mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/specs: Convert pci-testdev.txt to rst

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

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20230420160334.1048224-4-peter.maydell@linaro.org>
Reviewed-by: Michael S. Tsirkin <mst@redhat.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
This commit is contained in:
Peter Maydell 2023-04-20 17:03:34 +01:00 committed by Michael S. Tsirkin
parent 3669b594d8
commit 4d58309388
4 changed files with 41 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/specs/index.rst
View File

@ -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

2
docs/specs/pci-ids.rst
View File

@ -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

39
docs/specs/pci-testdev.rst Normal file
View File

@ -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.

31
docs/specs/pci-testdev.txt
View File

@ -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.