* [PATCH 1/3] docs/specs/pci-ids: Convert from txt to rST
2023-04-20 16:03 [PATCH 0/3] docs/specs: Convert some PCI specs docs to rST Peter Maydell
@ 2023-04-20 16:03 ` Peter Maydell
2023-04-20 16:03 ` [PATCH 2/3] docs/specs: Convert pci-serial.txt to rst Peter Maydell
2023-04-20 16:03 ` [PATCH 3/3] docs/specs: Convert pci-testdev.txt " Peter Maydell
2 siblings, 0 replies; 5+ messages in thread
From: Peter Maydell @ 2023-04-20 16:03 UTC (permalink / raw)
To: qemu-devel; +Cc: Michael S. Tsirkin, Marcel Apfelbaum
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
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 2/3] docs/specs: Convert pci-serial.txt to rst
2023-04-20 16:03 [PATCH 0/3] docs/specs: Convert some PCI specs docs to rST Peter Maydell
2023-04-20 16:03 ` [PATCH 1/3] docs/specs/pci-ids: Convert from txt " Peter Maydell
@ 2023-04-20 16:03 ` Peter Maydell
2023-04-21 6:40 ` Philippe Mathieu-Daudé
2023-04-20 16:03 ` [PATCH 3/3] docs/specs: Convert pci-testdev.txt " Peter Maydell
2 siblings, 1 reply; 5+ messages in thread
From: Peter Maydell @ 2023-04-20 16:03 UTC (permalink / raw)
To: qemu-devel; +Cc: Michael S. Tsirkin, Marcel Apfelbaum
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
^ permalink raw reply related [flat|nested] 5+ messages in thread* Re: [PATCH 2/3] docs/specs: Convert pci-serial.txt to rst
2023-04-20 16:03 ` [PATCH 2/3] docs/specs: Convert pci-serial.txt to rst Peter Maydell
@ 2023-04-21 6:40 ` Philippe Mathieu-Daudé
0 siblings, 0 replies; 5+ messages in thread
From: Philippe Mathieu-Daudé @ 2023-04-21 6:40 UTC (permalink / raw)
To: Peter Maydell, qemu-devel; +Cc: Michael S. Tsirkin, Marcel Apfelbaum
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>
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH 3/3] docs/specs: Convert pci-testdev.txt to rst
2023-04-20 16:03 [PATCH 0/3] docs/specs: Convert some PCI specs docs to rST Peter Maydell
2023-04-20 16:03 ` [PATCH 1/3] docs/specs/pci-ids: Convert from txt " Peter Maydell
2023-04-20 16:03 ` [PATCH 2/3] docs/specs: Convert pci-serial.txt to rst Peter Maydell
@ 2023-04-20 16:03 ` Peter Maydell
2 siblings, 0 replies; 5+ messages in thread
From: Peter Maydell @ 2023-04-20 16:03 UTC (permalink / raw)
To: qemu-devel; +Cc: Michael S. Tsirkin, Marcel Apfelbaum
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
^ permalink raw reply related [flat|nested] 5+ messages in thread