Re: [PATCH] docs/can: convert to restructuredText

2022-01-13 Thread Peter Maydell 
On Thu, 13 Jan 2022 at 15:26, Lucas Ramage
 wrote:
>
> Hi Peter,
>
> Thanks for that.
>
> The next on the list is docs/ccid.txt, should this go in the same "Device 
> Emulation / Emulated Devices" section? It mentions USB at the top.


Yes, please.

thanks
-- PMM

Re: [PATCH] docs/can: convert to restructuredText

2022-01-13 Thread Lucas Ramage 
Hi Peter,

Thanks for that.

The next on the list is docs/ccid.txt, should this go in the same "Device 
Emulation / Emulated Devices" section? It mentions USB at the top.

Regards,

‐‐‐ Original Message ‐‐‐

On Thursday, January 13th, 2022 at 6:37 AM, Peter Maydell 
 wrote:

> On Wed, 5 Jan 2022 at 20:56, oxr...@gmx.us wrote:
>
> > From: Lucas Ramage lucas.ram...@infinite-omicron.com
> >
> > Buglink: https://gitlab.com/qemu-project/qemu/-/issues/527
> >
> > Signed-off-by: Lucas Ramage lucas.ram...@infinite-omicron.com
> > -
> >
> > docs/{can.txt => system/can.rst} | 92 ++--
> >
> > docs/system/index.rst | 1 +
> >
> > 2 files changed, 42 insertions(+), 51 deletions(-)
> >
> > rename docs/{can.txt => system/can.rst} (68%)
>
> Hi Lucas; thanks for this docs-conversion patch. It looks
>
> good to me, except that I think that rather than putting
>
> the new document in the top-level index of the system manual
>
> it would fit better in the "Device Emulation / Emulated Devices"
>
> subsection, where we already document things like USB devices.
>
> Rather than ask you to respin the patch again for what is
>
> basically just a "git mv", I'm going to take this patch via
>
> my target-arm tree and make that change there.
>
> Thanks
>
> -- PMM

Re: [PATCH] docs/can: convert to restructuredText

2022-01-13 Thread Peter Maydell 
On Wed, 5 Jan 2022 at 20:56,  wrote:
>
> From: Lucas Ramage 
>
> Buglink: https://gitlab.com/qemu-project/qemu/-/issues/527
> Signed-off-by: Lucas Ramage 
> ---
>  docs/{can.txt => system/can.rst} | 92 ++--
>  docs/system/index.rst|  1 +
>  2 files changed, 42 insertions(+), 51 deletions(-)
>  rename docs/{can.txt => system/can.rst} (68%)

Hi Lucas; thanks for this docs-conversion patch. It looks
good to me, except that I think that rather than putting
the new document in the top-level index of the system manual
it would fit better in the "Device Emulation / Emulated Devices"
subsection, where we already document things like USB devices.

Rather than ask you to respin the patch again for what is
basically just a "git mv", I'm going to take this patch via
my target-arm tree and make that change there.

Thanks
-- PMM

Re: [PATCH] docs/can: convert to restructuredText

2022-01-07 Thread Lucas Ramage 
Hi Thomas,

Not sure if you saw my latest patch, but I fixed all of the warnings already.

I also updated the references at the bottom to use inline web links.

Regards,

‐‐‐ Original Message ‐‐‐

On Friday, January 7th, 2022 at 2:19 AM, Thomas Huth  wrote:

> On 05/01/2022 20.52, Lucas Ramage wrote:
>
> > Hi Thomas,
> >
> > I intentionally sent the email via my gmx address. But I want my commit 
> > under the infinite-omicron email address.
> >
> > I had a few warnings on my end, but it builds fine with Sphinx v3.4.3 on 
> > Debian Bullseye. I can clean up the warnings in the new patch.
>
> Yes, please do so. If you add "--enable-werror" to your "configure" options,
>
> the warnings should be turned into errors as well - and that's what we do in
>
> our CI, so the warnings have to be fixed first before this patch can be
>
> included.
>
> Thanks,
>
> Thomas

Re: [PATCH] docs/can: convert to restructuredText

2022-01-06 Thread Thomas Huth 

On 05/01/2022 20.52, Lucas Ramage wrote:

Hi Thomas,

I intentionally sent the email via my gmx address. But I want my commit under 
the infinite-omicron email address.

I had a few warnings on my end, but it builds fine with Sphinx v3.4.3 on Debian 
Bullseye. I can clean up the warnings in the new patch.


Yes, please do so. If you add "--enable-werror" to your "configure" options, 
the warnings should be turned into errors as well - and that's what we do in 
our CI, so the warnings have to be fixed first before this patch can be 
included.


 Thanks,
  Thomas

Re: [PATCH] docs/can: convert to restructuredText

2022-01-05 Thread Lucas Ramage 
Hi Thomas,

I intentionally sent the email via my gmx address. But I want my commit under 
the infinite-omicron email address.

I had a few warnings on my end, but it builds fine with Sphinx v3.4.3 on Debian 
Bullseye. I can clean up the warnings in the new patch.

Yeah, it renders fine.

Let me submit a new patch for the rest of these changes too.

Regards,

‐‐‐ Original Message ‐‐‐

On Wednesday, January 5th, 2022 at 4:11 AM, Thomas Huth  
wrote:

> On 17/12/2021 22.21, oxr...@gmx.us wrote:
>
> > From: Lucas Ramage lucas.ram...@infinite-omicron.com
>
> Hi!
>
> Thanks for your patch! This looks like a good idea, but I think there are
>
> some minor issues which should be fixed...
>
> First: Please check your mailer setup. The mail has been sent via @gmx.us,
>
> but the Signed-off-by uses @infinite-omicron.com ... not a big issue, I
>
> guess, but it might be better to use the same address for both.
>
> Second, it does not work here, at least not with Sphinx 1.7 which I have
>
> installed on my system:
>
> docs/can.rst:39:Enumerated list ends without a blank line;
>
> unexpected unindent.
>
> Does this render correctly on your system?
>
> Also there are paragraphs in this file which should be clearly marked as
>
> pre-formatted text (use "::" for those), e.g.:
>
> diff --git a/docs/can.rst b/docs/can.rst
>
> --- a/docs/can.rst
>
> +++ b/docs/can.rst
>
> @@ -122,7 +125,7 @@ is setup according to the previous SJA1000 section.
>
> -device ctucan_pci,canbus0=canbus0-bus,canbus1=canbus0-bus \
>
> -nographic
>
> -Setup of CTU CAN FD controller in a guest Linux system
>
> +Setup of CTU CAN FD controller in a guest Linux system::
>
> insmod ctucanfd.ko || modprobe ctucanfd
>
> insmod ctucanfd_pci.ko || modprobe ctucanfd_pci
>
> > Bug: https://gitlab.com/qemu-project/qemu/-/issues/527
>
> Please use "Buglink:" instead, it's more common in the QEMU project.
>
> > Signed-off-by: Lucas Ramage lucas.ram...@infinite-omicron.com
> > -
> >
> > docs/{can.txt => can.rst} | 14 ++
>
> While you're at it, I think this file should be moved into one of the
>
> subfolders as well, likely docs/system/ I guess.
>
> > docs/index.rst | 1 +
> >
> > 2 files changed, 7 insertions(+), 8 deletions(-)
> >
> > rename docs/{can.txt => can.rst} (97%)
> >
> > diff --git a/docs/can.txt b/docs/can.rst
> >
> > similarity index 97%
> >
> > rename from docs/can.txt
> >
> > rename to docs/can.rst
> >
> > index 0d310237df..995134d079 100644
> >
> > --- a/docs/can.txt
> >
> > +++ b/docs/can.rst
>
> [...]
>
> > @@ -196,3 +193,4 @@ Links to other resources
> >
> > http://canbus.pages.fel.cvut.cz/ctucanfd_ip_core/driver_doc/ctucanfd-driver.html
> >
> > (11) Integration with PCIe interfacing for Intel/Altera Cyclone IV based 
> > board
> >
> > https://gitlab.fel.cvut.cz/canbus/pcie-ctu_can_fd
> >
> > +
>
> This look like an unnecessary addition of an empty line.
>
> > diff --git a/docs/index.rst b/docs/index.rst
> >
> > index 0b9ee9901d..beb868ca7f 100644
> >
> > --- a/docs/index.rst
> >
> > +++ b/docs/index.rst
> >
> > @@ -18,3 +18,4 @@ Welcome to QEMU's documentation!
> >
> > interop/index
> >
> > specs/index
> >
> > devel/index
> >
> > -   can
> >
> > --
> >
> > 2.32.0
>
> Thomas

[PATCH] docs/can: convert to restructuredText

2022-01-05 Thread oxr463 
From: Lucas Ramage 

Buglink: https://gitlab.com/qemu-project/qemu/-/issues/527
Signed-off-by: Lucas Ramage 
---
 docs/{can.txt => system/can.rst} | 92 ++--
 docs/system/index.rst|  1 +
 2 files changed, 42 insertions(+), 51 deletions(-)
 rename docs/{can.txt => system/can.rst} (68%)

diff --git a/docs/can.txt b/docs/system/can.rst
similarity index 68%
rename from docs/can.txt
rename to docs/system/can.rst
index 0d310237df..198522eaa4 100644
--- a/docs/can.txt
+++ b/docs/system/can.rst
@@ -1,6 +1,5 @@
-QEMU CAN bus emulation support
-==
-
+CAN Bus Emulation Support
+=
 The CAN bus emulation provides mechanism to connect multiple
 emulated CAN controller chips together by one or multiple CAN busses
 (the controller device "canbus"  parameter). The individual busses
@@ -32,34 +31,39 @@ emulated environment for testing and RTEMS GSoC slot has 
been donated
 to work on CAN hardware emulation on QEMU.

 Examples how to use CAN emulation for SJA1000 based boards
-==
-
+--
 When QEMU with CAN PCI support is compiled then one of the next
 CAN boards can be selected

- (1) CAN bus Kvaser PCI CAN-S (single SJA1000 channel) boad. QEMU startup 
options
+(1) CAN bus Kvaser PCI CAN-S (single SJA1000 channel) boad. QEMU startup 
options::
+
 -object can-bus,id=canbus0
 -device kvaser_pci,canbus=canbus0
-Add "can-host-socketcan" object to connect device to host system CAN bus
+
+Add "can-host-socketcan" object to connect device to host system CAN bus::
+
 -object can-host-socketcan,id=canhost0,if=can0,canbus=canbus0

- (2) CAN bus PCM-3680I PCI (dual SJA1000 channel) emulation
+(2) CAN bus PCM-3680I PCI (dual SJA1000 channel) emulation::
+
 -object can-bus,id=canbus0
 -device pcm3680_pci,canbus0=canbus0,canbus1=canbus0

- another example:
+Another example::
+
 -object can-bus,id=canbus0
 -object can-bus,id=canbus1
 -device pcm3680_pci,canbus0=canbus0,canbus1=canbus1

- (3) CAN bus MIOe-3680 PCI (dual SJA1000 channel) emulation
--device mioe3680_pci,canbus0=canbus0
+(3) CAN bus MIOe-3680 PCI (dual SJA1000 channel) emulation::

+-device mioe3680_pci,canbus0=canbus0

 The ''kvaser_pci'' board/device model is compatible with and has been tested 
with
-''kvaser_pci'' driver included in mainline Linux kernel.
+the ''kvaser_pci'' driver included in mainline Linux kernel.
 The tested setup was Linux 4.9 kernel on the host and guest side.
-Example for qemu-system-x86_64:
+
+Example for qemu-system-x86_64::

 qemu-system-x86_64 -accel kvm -kernel /boot/vmlinuz-4.9.0-4-amd64 \
   -initrd ramdisk.cpio \
@@ -69,7 +73,7 @@ Example for qemu-system-x86_64:
   -device kvaser_pci,canbus=canbus0 \
   -nographic -append "console=ttyS0"

-Example for qemu-system-arm:
+Example for qemu-system-arm::

 qemu-system-arm -cpu arm1176 -m 256 -M versatilepb \
   -kernel kernel-qemu-arm1176-versatilepb \
@@ -84,24 +88,23 @@ Example for qemu-system-arm:
 The CAN interface of the host system has to be configured for proper
 bitrate and set up. Configuration is not propagated from emulated
 devices through bus to the physical host device. Example configuration
-for 1 Mbit/s
+for 1 Mbit/s::

   ip link set can0 type can bitrate 100
   ip link set can0 up

 Virtual (host local only) can interface can be used on the host
-side instead of physical interface
+side instead of physical interface::

   ip link add dev can0 type vcan

 The CAN interface on the host side can be used to analyze CAN
-traffic with "candump" command which is included in "can-utils".
+traffic with "candump" command which is included in "can-utils"::

   candump can0

 CTU CAN FD support examples
-===
-
+---
 This open-source core provides CAN FD support. CAN FD drames are
 delivered even to the host systems when SocketCAN interface is found
 CAN FD capable.
@@ -113,7 +116,7 @@ on the board.
 Example how to connect the canbus0-bus (virtual wire) to the host
 Linux system (SocketCAN used) and to both CTU CAN FD cores emulated
 on the corresponding PCI card expects that host system CAN bus
-is setup according to the previous SJA1000 section.
+is setup according to the previous SJA1000 section::

   qemu-system-x86_64 -enable-kvm -kernel /boot/vmlinuz-4.19.52+ \
   -initrd ramdisk.cpio \
@@ -125,7 +128,7 @@ is setup according to the previous SJA1000 section.
   -device ctucan_pci,canbus0=canbus0-bus,canbus1=canbus0-bus \
   -nographic

-Setup of CTU CAN FD controller in a guest Linux system
+Setup of CTU CAN FD controller in a guest Linux system::

   insmod ctucanfd.ko || modprobe ctucanfd
   insmod ctucanfd_pci.ko || modprobe ctucanfd_pci
@@ -150,19 +153,19 @@ Setup of CTU CAN FD controller in a guest Linux system
 /bin/ip link set $ifc up
   done

-The

Re: [PATCH] docs/can: convert to restructuredText

2022-01-05 Thread Thomas Huth 

On 17/12/2021 22.21, oxr...@gmx.us wrote:

From: Lucas Ramage 


 Hi!

Thanks for your patch! This looks like a good idea, but I think there are 
some minor issues which should be fixed...


First: Please check your mailer setup. The mail has been sent via @gmx.us, 
but the Signed-off-by uses @infinite-omicron.com ... not a big issue, I 
guess, but it might be better to use the same address for both.


Second, it does not work here, at least not with Sphinx 1.7 which I have 
installed on my system:


 docs/can.rst:39:Enumerated list ends without a blank line;
 unexpected unindent.

Does this render correctly on your system?

Also there are paragraphs in this file which should be clearly marked as 
pre-formatted text (use "::" for those), e.g.:


diff --git a/docs/can.rst b/docs/can.rst
--- a/docs/can.rst
+++ b/docs/can.rst
@@ -122,7 +125,7 @@ is setup according to the previous SJA1000 section.
 -device ctucan_pci,canbus0=canbus0-bus,canbus1=canbus0-bus \
 -nographic

-Setup of CTU CAN FD controller in a guest Linux system
+Setup of CTU CAN FD controller in a guest Linux system::

   insmod ctucanfd.ko || modprobe ctucanfd
   insmod ctucanfd_pci.ko || modprobe ctucanfd_pci


Bug: https://gitlab.com/qemu-project/qemu/-/issues/527


Please use "Buglink:" instead, it's more common in the QEMU project.


Signed-off-by: Lucas Ramage 
---
  docs/{can.txt => can.rst} | 14 ++


While you're at it, I think this file should be moved into one of the 
subfolders as well, likely docs/system/ I guess.



  docs/index.rst|  1 +
  2 files changed, 7 insertions(+), 8 deletions(-)
  rename docs/{can.txt => can.rst} (97%)

diff --git a/docs/can.txt b/docs/can.rst
similarity index 97%
rename from docs/can.txt
rename to docs/can.rst
index 0d310237df..995134d079 100644
--- a/docs/can.txt
+++ b/docs/can.rst

[...]

@@ -196,3 +193,4 @@ Links to other resources
   
http://canbus.pages.fel.cvut.cz/ctucanfd_ip_core/driver_doc/ctucanfd-driver.html
   (11) Integration with PCIe interfacing for Intel/Altera Cyclone IV based 
board
   https://gitlab.fel.cvut.cz/canbus/pcie-ctu_can_fd
+


This look like an unnecessary addition of an empty line.


diff --git a/docs/index.rst b/docs/index.rst
index 0b9ee9901d..beb868ca7f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,3 +18,4 @@ Welcome to QEMU's documentation!
 interop/index
 specs/index
 devel/index
+   can
--
2.32.0




 Thomas

[PATCH] docs/can: convert to restructuredText

2021-12-17 Thread oxr463 
From: Lucas Ramage 

Bug: https://gitlab.com/qemu-project/qemu/-/issues/527
Signed-off-by: Lucas Ramage 
---
 docs/{can.txt => can.rst} | 14 ++
 docs/index.rst|  1 +
 2 files changed, 7 insertions(+), 8 deletions(-)
 rename docs/{can.txt => can.rst} (97%)

diff --git a/docs/can.txt b/docs/can.rst
similarity index 97%
rename from docs/can.txt
rename to docs/can.rst
index 0d310237df..995134d079 100644
--- a/docs/can.txt
+++ b/docs/can.rst
@@ -1,6 +1,5 @@
-QEMU CAN bus emulation support
-==
-
+CAN Bus Emulation Support
+=
 The CAN bus emulation provides mechanism to connect multiple
 emulated CAN controller chips together by one or multiple CAN busses
 (the controller device "canbus"  parameter). The individual busses
@@ -32,8 +31,7 @@ emulated environment for testing and RTEMS GSoC slot has been 
donated
 to work on CAN hardware emulation on QEMU.

 Examples how to use CAN emulation for SJA1000 based boards
-==
-
+--
 When QEMU with CAN PCI support is compiled then one of the next
 CAN boards can be selected

@@ -100,8 +98,7 @@ traffic with "candump" command which is included in 
"can-utils".
   candump can0

 CTU CAN FD support examples
-===
-
+---
 This open-source core provides CAN FD support. CAN FD drames are
 delivered even to the host systems when SocketCAN interface is found
 CAN FD capable.
@@ -170,7 +167,7 @@ The test can be run viceversa, generate messages in the 
guest system and capture
 in the host one and much more combinations.

 Links to other resources
-
+

  (1) CAN related projects at Czech Technical University, Faculty of Electrical 
Engineering
  http://canbus.pages.fel.cvut.cz/
@@ -196,3 +193,4 @@ Links to other resources
  
http://canbus.pages.fel.cvut.cz/ctucanfd_ip_core/driver_doc/ctucanfd-driver.html
  (11) Integration with PCIe interfacing for Intel/Altera Cyclone IV based board
  https://gitlab.fel.cvut.cz/canbus/pcie-ctu_can_fd
+
diff --git a/docs/index.rst b/docs/index.rst
index 0b9ee9901d..beb868ca7f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,3 +18,4 @@ Welcome to QEMU's documentation!
interop/index
specs/index
devel/index
+   can
--
2.32.0