[PATCH 0/3] docs/specs: Convert some PCI specs docs to rST

[PATCH 0/3] docs/specs: Convert some PCI specs docs to rST

[Peter Maydell]

This series converts a few small and simple PCI related
documents in the docs/specs/ directory from plain text
to rST: pci-ids.txt, pci-serial.txt and pci-testdev.txt.

Peter Maydell (3):
  docs/specs/pci-ids: Convert from txt to rST
  docs/specs: Convert pci-serial.txt to rst
  docs/specs: Convert pci-testdev.txt to rst

 docs/specs/index.rst       |  3 ++
 docs/specs/pci-ids.rst     | 98 ++++++++++++++++++++++++++++++++++++++
 docs/specs/pci-ids.txt     | 70 ---------------------------
 docs/specs/pci-serial.rst  | 37 ++++++++++++++
 docs/specs/pci-serial.txt  | 34 -------------
 docs/specs/pci-testdev.rst | 39 +++++++++++++++
 docs/specs/pci-testdev.txt | 31 ------------
 hw/char/serial-pci-multi.c |  2 +-
 hw/char/serial-pci.c       |  2 +-
 9 files changed, 179 insertions(+), 137 deletions(-)
 create mode 100644 docs/specs/pci-ids.rst
 delete mode 100644 docs/specs/pci-ids.txt
 create mode 100644 docs/specs/pci-serial.rst
 delete mode 100644 docs/specs/pci-serial.txt
 create mode 100644 docs/specs/pci-testdev.rst
 delete mode 100644 docs/specs/pci-testdev.txt

-- 
2.34.1

[PATCH 1/3] docs/specs/pci-ids: Convert from txt to rST

[Peter Maydell]

Convert the pci-ids document from plain text to reStructuredText.

I opted to use definition-lists here because rST tables are
super-clunky, and actually formatting these as tables didn't
seem necessary.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/specs/index.rst   |  1 +
 docs/specs/pci-ids.rst | 98 ++++++++++++++++++++++++++++++++++++++++++
 docs/specs/pci-ids.txt | 70 ------------------------------
 3 files changed, 99 insertions(+), 70 deletions(-)
 create mode 100644 docs/specs/pci-ids.rst
 delete mode 100644 docs/specs/pci-ids.txt

diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index a58d9311cb3..8aa0fcb77a9 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -8,6 +8,7 @@ guest hardware that is specific to QEMU.
 .. toctree::
    :maxdepth: 2
 
+   pci-ids
    ppc-xive
    ppc-spapr-xive
    ppc-spapr-numa
diff --git a/docs/specs/pci-ids.rst b/docs/specs/pci-ids.rst
new file mode 100644
index 00000000000..e1cf022006b
--- /dev/null
+++ b/docs/specs/pci-ids.rst
@@ -0,0 +1,98 @@
+================
+PCI IDs for QEMU
+================
+
+Red Hat, Inc. donates a part of its device ID range to QEMU, to be used for
+virtual devices.  The vendor IDs are 1af4 (formerly Qumranet ID) and 1b36.
+
+Contact Gerd Hoffmann <kraxel@redhat.com> to get a device ID assigned
+for your devices.
+
+1af4 vendor ID
+--------------
+
+The 1000 -> 10ff device ID range is used as follows for virtio-pci devices.
+Note that this allocation is separate from the virtio device IDs, which are
+maintained as part of the virtio specification.
+
+1af4:1000
+  network device (legacy)
+1af4:1001
+  block device (legacy)
+1af4:1002
+  balloon device (legacy)
+1af4:1003
+  console device (legacy)
+1af4:1004
+  SCSI host bus adapter device (legacy)
+1af4:1005
+  entropy generator device (legacy)
+1af4:1009
+  9p filesystem device (legacy)
+1af4:1012
+  vsock device (bug compatibility)
+
+1af4:1040 to 1af4:10ef
+  ID range for modern virtio devices.  The PCI device
+  ID is calculated from the virtio device ID by adding the
+  0x1040 offset.  The virtio IDs are defined in the virtio
+  specification.  The Linux kernel has a header file with
+  defines for all virtio IDs (``linux/virtio_ids.h``); QEMU has a
+  copy in ``include/standard-headers/``.
+
+1af4:10f0 to 1a4f:10ff
+  Available for experimental usage without registration.  Must get
+  official ID when the code leaves the test lab (i.e. when seeking
+  upstream merge or shipping a distro/product) to avoid conflicts.
+
+1af4:1100
+  Used as PCI Subsystem ID for existing hardware devices emulated
+  by QEMU.
+
+1af4:1110
+  ivshmem device (shared memory, ``docs/specs/ivshmem-spec.txt``)
+
+All other device IDs are reserved.
+
+1b36 vendor ID
+--------------
+
+The 0000 -> 00ff device ID range is used as follows for QEMU-specific
+PCI devices (other than virtio):
+
+1b36:0001
+  PCI-PCI bridge
+1b36:0002
+  PCI serial port (16550A) adapter (``docs/specs/pci-serial.txt``)
+1b36:0003
+  PCI Dual-port 16550A adapter (``docs/specs/pci-serial.txt``)
+1b36:0004
+  PCI Quad-port 16550A adapter (``docs/specs/pci-serial.txt``)
+1b36:0005
+  PCI test device (``docs/specs/pci-testdev.txt``)
+1b36:0006
+  PCI Rocker Ethernet switch device
+1b36:0007
+  PCI SD Card Host Controller Interface (SDHCI)
+1b36:0008
+  PCIe host bridge
+1b36:0009
+  PCI Expander Bridge (-device pxb)
+1b36:000a
+  PCI-PCI bridge (multiseat)
+1b36:000b
+  PCIe Expander Bridge (-device pxb-pcie)
+1b36:000d
+  PCI xhci usb host adapter
+1b36:000f
+  mdpy (mdev sample device), ``linux/samples/vfio-mdev/mdpy.c``
+1b36:0010
+  PCIe NVMe device (``-device nvme``)
+1b36:0011
+  PCI PVPanic device (``-device pvpanic-pci``)
+1b36:0012
+  PCI ACPI ERST device (``-device acpi-erst``)
+
+All these devices are documented in :doc:`index`.
+
+The 0100 device ID is used for the QXL video card device.
diff --git a/docs/specs/pci-ids.txt b/docs/specs/pci-ids.txt
deleted file mode 100644
index e463c4cb3a2..00000000000
--- a/docs/specs/pci-ids.txt
+++ /dev/null
@@ -1,70 +0,0 @@
-
-PCI IDs for qemu
-================
-
-Red Hat, Inc. donates a part of its device ID range to qemu, to be used for
-virtual devices.  The vendor IDs are 1af4 (formerly Qumranet ID) and 1b36.
-
-Contact Gerd Hoffmann <kraxel@redhat.com> to get a device ID assigned
-for your devices.
-
-1af4 vendor ID
---------------
-
-The 1000 -> 10ff device ID range is used as follows for virtio-pci devices.
-Note that this allocation separate from the virtio device IDs, which are
-maintained as part of the virtio specification.
-
-1af4:1000  network device (legacy)
-1af4:1001  block device (legacy)
-1af4:1002  balloon device (legacy)
-1af4:1003  console device (legacy)
-1af4:1004  SCSI host bus adapter device (legacy)
-1af4:1005  entropy generator device (legacy)
-1af4:1009  9p filesystem device (legacy)
-1af4:1012  vsock device (bug compatibility)
-
-1af4:1040  Start of ID range for modern virtio devices.  The PCI device
-   to      ID is calculated from the virtio device ID by adding the
-1af4:10ef  0x1040 offset.  The virtio IDs are defined in the virtio
-           specification.  The Linux kernel has a header file with
-           defines for all virtio IDs (linux/virtio_ids.h), qemu has a
-           copy in include/standard-headers/.
-
-1af4:10f0  Available for experimental usage without registration.  Must get
-   to      official ID when the code leaves the test lab (i.e. when seeking
-1af4:10ff  upstream merge or shipping a distro/product) to avoid conflicts.
-
-1af4:1100  Used as PCI Subsystem ID for existing hardware devices emulated
-           by qemu.
-
-1af4:1110  ivshmem device (shared memory, docs/specs/ivshmem-spec.txt)
-
-All other device IDs are reserved.
-
-1b36 vendor ID
---------------
-
-The 0000 -> 00ff device ID range is used as follows for QEMU-specific
-PCI devices (other than virtio):
-
-1b36:0001  PCI-PCI bridge
-1b36:0002  PCI serial port (16550A) adapter (docs/specs/pci-serial.txt)
-1b36:0003  PCI Dual-port 16550A adapter (docs/specs/pci-serial.txt)
-1b36:0004  PCI Quad-port 16550A adapter (docs/specs/pci-serial.txt)
-1b36:0005  PCI test device (docs/specs/pci-testdev.txt)
-1b36:0006  PCI Rocker Ethernet switch device
-1b36:0007  PCI SD Card Host Controller Interface (SDHCI)
-1b36:0008  PCIe host bridge
-1b36:0009  PCI Expander Bridge (-device pxb)
-1b36:000a  PCI-PCI bridge (multiseat)
-1b36:000b  PCIe Expander Bridge (-device pxb-pcie)
-1b36:000d  PCI xhci usb host adapter
-1b36:000f  mdpy (mdev sample device), linux/samples/vfio-mdev/mdpy.c
-1b36:0010  PCIe NVMe device (-device nvme)
-1b36:0011  PCI PVPanic device (-device pvpanic-pci)
-1b36:0012  PCI ACPI ERST device (-device acpi-erst)
-
-All these devices are documented in docs/specs.
-
-The 0100 device ID is used for the QXL video card device.
-- 
2.34.1

[PATCH 2/3] docs/specs: Convert pci-serial.txt to rst

[Peter Maydell]

Convert pci-serial.txt to reStructuredText. This includes
some wordsmithing, and the correction of the docs to note
that the Windows inf file includes 2x and 4x support
(as it has done since commit dc9528fdf9f61 in 2014).

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/specs/index.rst       |  1 +
 docs/specs/pci-ids.rst     |  6 +++---
 docs/specs/pci-serial.rst  | 37 +++++++++++++++++++++++++++++++++++++
 docs/specs/pci-serial.txt  | 34 ----------------------------------
 hw/char/serial-pci-multi.c |  2 +-
 hw/char/serial-pci.c       |  2 +-
 6 files changed, 43 insertions(+), 39 deletions(-)
 create mode 100644 docs/specs/pci-serial.rst
 delete mode 100644 docs/specs/pci-serial.txt

diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index 8aa0fcb77a9..dfa136073c7 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -9,6 +9,7 @@ guest hardware that is specific to QEMU.
    :maxdepth: 2
 
    pci-ids
+   pci-serial
    ppc-xive
    ppc-spapr-xive
    ppc-spapr-numa
diff --git a/docs/specs/pci-ids.rst b/docs/specs/pci-ids.rst
index e1cf022006b..7bc7168fb6a 100644
--- a/docs/specs/pci-ids.rst
+++ b/docs/specs/pci-ids.rst
@@ -63,11 +63,11 @@ PCI devices (other than virtio):
 1b36:0001
   PCI-PCI bridge
 1b36:0002
-  PCI serial port (16550A) adapter (``docs/specs/pci-serial.txt``)
+  PCI serial port (16550A) adapter (:doc:`pci-serial`)
 1b36:0003
-  PCI Dual-port 16550A adapter (``docs/specs/pci-serial.txt``)
+  PCI Dual-port 16550A adapter (:doc:`pci-serial`)
 1b36:0004
-  PCI Quad-port 16550A adapter (``docs/specs/pci-serial.txt``)
+  PCI Quad-port 16550A adapter (:doc:`pci-serial`)
 1b36:0005
   PCI test device (``docs/specs/pci-testdev.txt``)
 1b36:0006
diff --git a/docs/specs/pci-serial.rst b/docs/specs/pci-serial.rst
new file mode 100644
index 00000000000..8d916a36697
--- /dev/null
+++ b/docs/specs/pci-serial.rst
@@ -0,0 +1,37 @@
+=======================
+QEMU PCI serial devices
+=======================
+
+QEMU implements some PCI serial devices which are simple PCI
+wrappers around one or more 16550 UARTs.
+
+There is one single-port variant and two multiport-variants.  Linux
+guests work out-of-the box with all cards.  There is a Windows inf file
+(``docs/qemupciserial.inf``) to set up the cards in Windows guests.
+
+
+Single-port card
+----------------
+
+Name:
+  ``pci-serial``
+PCI ID:
+  1b36:0002
+PCI Region 0:
+   IO bar, 8 bytes long, with the 16550 UART mapped to it.
+Interrupt:
+   Wired to pin A.
+
+
+Multiport cards
+---------------
+
+Name:
+  ``pci-serial-2x``, ``pci-serial-4x``
+PCI ID:
+  1b36:0003 (``-2x``) and 1b36:0004 (``-4x``)
+PCI Region 0:
+   IO bar, with two or four 16550 UARTs mapped after each other.
+   The first is at offset 0, the second at offset 8, and so on.
+Interrupt:
+   Wired to pin A.
diff --git a/docs/specs/pci-serial.txt b/docs/specs/pci-serial.txt
deleted file mode 100644
index 66c761f2b40..00000000000
--- a/docs/specs/pci-serial.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-
-QEMU pci serial devices
-=======================
-
-There is one single-port variant and two muliport-variants.  Linux
-guests out-of-the box with all cards.  There is a Windows inf file
-(docs/qemupciserial.inf) to setup the single-port card in Windows
-guests.
-
-
-single-port card
-----------------
-
-Name:   pci-serial
-PCI ID: 1b36:0002
-
-PCI Region 0:
-   IO bar, 8 bytes long, with the 16550 uart mapped to it.
-   Interrupt is wired to pin A.
-
-
-multiport cards
----------------
-
-Name:   pci-serial-2x
-PCI ID: 1b36:0003
-
-Name:   pci-serial-4x
-PCI ID: 1b36:0004
-
-PCI Region 0:
-   IO bar, with two/four 16550 uart mapped after each other.
-   The first is at offset 0, second at offset 8, ...
-   Interrupt is wired to pin A.
diff --git a/hw/char/serial-pci-multi.c b/hw/char/serial-pci-multi.c
index f18b8dcce5f..5d65c534cb5 100644
--- a/hw/char/serial-pci-multi.c
+++ b/hw/char/serial-pci-multi.c
@@ -25,7 +25,7 @@
  * THE SOFTWARE.
  */
 
-/* see docs/specs/pci-serial.txt */
+/* see docs/specs/pci-serial.rst */
 
 #include "qemu/osdep.h"
 #include "qapi/error.h"
diff --git a/hw/char/serial-pci.c b/hw/char/serial-pci.c
index 801b769abab..087da3059a4 100644
--- a/hw/char/serial-pci.c
+++ b/hw/char/serial-pci.c
@@ -23,7 +23,7 @@
  * THE SOFTWARE.
  */
 
-/* see docs/specs/pci-serial.txt */
+/* see docs/specs/pci-serial.rst */
 
 #include "qemu/osdep.h"
 #include "qapi/error.h"
-- 
2.34.1

[PATCH 3/3] docs/specs: Convert pci-testdev.txt to rst

[Peter Maydell]

Convert pci-testdev.txt to reStructuredText. Includes
some minor wordsmithing.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/specs/index.rst       |  1 +
 docs/specs/pci-ids.rst     |  2 +-
 docs/specs/pci-testdev.rst | 39 ++++++++++++++++++++++++++++++++++++++
 docs/specs/pci-testdev.txt | 31 ------------------------------
 4 files changed, 41 insertions(+), 32 deletions(-)
 create mode 100644 docs/specs/pci-testdev.rst
 delete mode 100644 docs/specs/pci-testdev.txt

diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index dfa136073c7..e58be38c41c 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -10,6 +10,7 @@ guest hardware that is specific to QEMU.
 
    pci-ids
    pci-serial
+   pci-testdev
    ppc-xive
    ppc-spapr-xive
    ppc-spapr-numa
diff --git a/docs/specs/pci-ids.rst b/docs/specs/pci-ids.rst
index 7bc7168fb6a..e302bea484e 100644
--- a/docs/specs/pci-ids.rst
+++ b/docs/specs/pci-ids.rst
@@ -69,7 +69,7 @@ PCI devices (other than virtio):
 1b36:0004
   PCI Quad-port 16550A adapter (:doc:`pci-serial`)
 1b36:0005
-  PCI test device (``docs/specs/pci-testdev.txt``)
+  PCI test device (:doc:`pci-testdev`)
 1b36:0006
   PCI Rocker Ethernet switch device
 1b36:0007
diff --git a/docs/specs/pci-testdev.rst b/docs/specs/pci-testdev.rst
new file mode 100644
index 00000000000..4b6d36543b7
--- /dev/null
+++ b/docs/specs/pci-testdev.rst
@@ -0,0 +1,39 @@
+====================
+QEMU PCI test device
+====================
+
+``pci-testdev`` is a device used for testing low level IO.
+
+The device implements up to three BARs: BAR0, BAR1 and BAR2.
+Each of BAR 0+1 can be memory or IO. Guests must detect
+BAR types and act accordingly.
+
+BAR 0+1 size is up to 4K bytes each.
+BAR 0+1 starts with the following header:
+
+.. code-block:: c
+
+  typedef struct PCITestDevHdr {
+      uint8_t test;        /* write-only, starts a given test number */
+      uint8_t width_type;  /*
+                            * read-only, type and width of access for a given test.
+                            * 1,2,4 for byte,word or long write.
+                            * any other value if test not supported on this BAR
+                            */
+      uint8_t pad0[2];
+      uint32_t offset;     /* read-only, offset in this BAR for a given test */
+      uint32_t data;       /* read-only, data to use for a given test */
+      uint32_t count;      /* for debugging. number of writes detected. */
+      uint8_t name[];      /* for debugging. 0-terminated ASCII string. */
+  } PCITestDevHdr;
+
+All registers are little endian.
+
+The device is expected to always implement tests 0 to N on each BAR, and to add new
+tests with higher numbers.  In this way a guest can scan test numbers until it
+detects an access type that it does not support on this BAR, then stop.
+
+BAR2 is a 64bit memory BAR, without backing storage.  It is disabled
+by default and can be enabled using the ``membar=<size>`` property.  This
+can be used to test whether guests handle PCI BARs of a specific
+(possibly quite large) size correctly.
diff --git a/docs/specs/pci-testdev.txt b/docs/specs/pci-testdev.txt
deleted file mode 100644
index 4280a1e73c5..00000000000
--- a/docs/specs/pci-testdev.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-pci-test is a device used for testing low level IO
-
-device implements up to three BARs: BAR0, BAR1 and BAR2.
-Each of BAR 0+1 can be memory or IO. Guests must detect
-BAR types and act accordingly.
-
-BAR 0+1 size is up to 4K bytes each.
-BAR 0+1 starts with the following header:
-
-typedef struct PCITestDevHdr {
-    uint8_t test;  <- write-only, starts a given test number
-    uint8_t width_type; <- read-only, type and width of access for a given test.
-                           1,2,4 for byte,word or long write.
-                           any other value if test not supported on this BAR
-    uint8_t pad0[2];
-    uint32_t offset; <- read-only, offset in this BAR for a given test
-    uint32_t data;    <- read-only, data to use for a given test
-    uint32_t count;  <- for debugging. number of writes detected.
-    uint8_t name[]; <- for debugging. 0-terminated ASCII string.
-} PCITestDevHdr;
-
-All registers are little endian.
-
-device is expected to always implement tests 0 to N on each BAR, and to add new
-tests with higher numbers.  In this way a guest can scan test numbers until it
-detects an access type that it does not support on this BAR, then stop.
-
-BAR2 is a 64bit memory bar, without backing storage.  It is disabled
-by default and can be enabled using the membar=<size> property.  This
-can be used to test whether guests handle pci bars of a specific
-(possibly quite large) size correctly.
-- 
2.34.1

Re: [PATCH 2/3] docs/specs: Convert pci-serial.txt to rst

[Philippe Mathieu-Daudé]

On 20/4/23 18:03, Peter Maydell wrote:
> Convert pci-serial.txt to reStructuredText. This includes
> some wordsmithing, and the correction of the docs to note
> that the Windows inf file includes 2x and 4x support
> (as it has done since commit dc9528fdf9f61 in 2014).
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>   docs/specs/index.rst       |  1 +
>   docs/specs/pci-ids.rst     |  6 +++---
>   docs/specs/pci-serial.rst  | 37 +++++++++++++++++++++++++++++++++++++
>   docs/specs/pci-serial.txt  | 34 ----------------------------------
>   hw/char/serial-pci-multi.c |  2 +-
>   hw/char/serial-pci.c       |  2 +-
>   6 files changed, 43 insertions(+), 39 deletions(-)
>   create mode 100644 docs/specs/pci-serial.rst
>   delete mode 100644 docs/specs/pci-serial.txt

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>