docs/specs/vmw_pvscsi-spec: Convert to rST

Convert the docs/specs/vmw_pvscsi-spec.txt file to rST format.
This conversion includes some minor wordsmithing of the text
to fix some grammar nits.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Thomas Huth <thuth@redhat.com>
Message-id: 20230927151205.70930-2-peter.maydell@linaro.org

3 files changed, 116 insertions, 92 deletions

diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index e58be38c41..d23efbe248 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -24,3 +24,4 @@ guest hardware that is specific to QEMU.
    acpi_erst
    sev-guest-firmware
    fw_cfg
+   vmw_pvscsi-spec
diff --git a/docs/specs/vmw_pvscsi-spec.rst b/docs/specs/vmw_pvscsi-spec.rst
new file mode 100644
index 0000000000..b6f434a418
--- /dev/null
+++ b/docs/specs/vmw_pvscsi-spec.rst
@@ -0,0 +1,115 @@
+==============================
+VMWare PVSCSI Device Interface
+==============================
+
+..
+   Created by Dmitry Fleytman (dmitry@daynix.com), Daynix Computing LTD.
+
+This document describes the VMWare PVSCSI device interface specification,
+based on the source code of the PVSCSI Linux driver from kernel 3.0.4.
+
+Overview
+========
+
+The interface is based on a memory area shared between hypervisor and VM.
+The memory area is obtained by driver as a device IO memory resource of
+``PVSCSI_MEM_SPACE_SIZE`` length.
+The shared memory consists of a registers area and a rings area.
+The registers area is used to raise hypervisor interrupts and issue device
+commands. The rings area is used to transfer data descriptors and SCSI
+commands from VM to hypervisor and to transfer messages produced by
+hypervisor to VM. Data itself is transferred via virtual scatter-gather DMA.
+
+PVSCSI Device Registers
+=======================
+
+The length of the registers area is 1 page
+(``PVSCSI_MEM_SPACE_COMMAND_NUM_PAGES``).  The structure of the
+registers area is described by the ``PVSCSIRegOffset`` enum.  There
+are registers to issue device commands (with optional short data),
+issue device interrupts, and control interrupt masking.
+
+PVSCSI Device Rings
+===================
+
+There are three rings in shared memory:
+
+Request ring (``struct PVSCSIRingReqDesc *req_ring``)
+    ring for OS to device requests
+
+Completion ring (``struct PVSCSIRingCmpDesc *cmp_ring``)
+    ring for device request completions
+
+Message ring (``struct PVSCSIRingMsgDesc *msg_ring``)
+    ring for messages from device. This ring is optional and the
+    guest might not configure it.
+
+There is a control area (``struct PVSCSIRingsState *rings_state``)
+used to control rings operation.
+
+PVSCSI Device to Host Interrupts
+================================
+
+The following interrupt types are supported by the PVSCSI device:
+
+Completion interrupts (completion ring notifications):
+
+- ``PVSCSI_INTR_CMPL_0``
+- ``PVSCSI_INTR_CMPL_1``
+
+Message interrupts (message ring notifications):
+
+- ``PVSCSI_INTR_MSG_0``
+- ``PVSCSI_INTR_MSG_1``
+
+Interrupts are controlled via the ``PVSCSI_REG_OFFSET_INTR_MASK``
+register.  If a bit is set it means the interrupt is enabled, and if
+it is clear then the interrupt is disabled.
+
+The interrupt modes supported are legacy, MSI and MSI-X.
+In the case of legacy interrupts, the ``PVSCSI_REG_OFFSET_INTR_STATUS``
+register is used to check which interrupt has arrived.  Interrupts are
+acknowledged when the corresponding bit is written to the interrupt
+status register.
+
+PVSCSI Device Operation Sequences
+=================================
+
+Startup sequence
+----------------
+
+a. Issue ``PVSCSI_CMD_ADAPTER_RESET`` command
+b. Windows driver reads interrupt status register here
+c. Issue ``PVSCSI_CMD_SETUP_MSG_RING`` command with no additional data,
+   check status and disable device messages if error returned
+   (Omitted if device messages disabled by driver configuration)
+d. Issue ``PVSCSI_CMD_SETUP_RINGS`` command, provide rings configuration
+   as ``struct PVSCSICmdDescSetupRings``
+e. Issue ``PVSCSI_CMD_SETUP_MSG_RING`` command again, provide
+   rings configuration as ``struct PVSCSICmdDescSetupMsgRing``
+f. Unmask completion and message (if device messages enabled) interrupts
+
+Shutdown sequence
+-----------------
+
+a. Mask interrupts
+b. Flush request ring using ``PVSCSI_REG_OFFSET_KICK_NON_RW_IO``
+c. Issue ``PVSCSI_CMD_ADAPTER_RESET`` command
+
+Send request
+------------
+
+a. Fill next free request ring descriptor
+b. Issue ``PVSCSI_REG_OFFSET_KICK_RW_IO`` for R/W operations
+   or ``PVSCSI_REG_OFFSET_KICK_NON_RW_IO`` for other operations
+
+Abort command
+-------------
+
+a. Issue ``PVSCSI_CMD_ABORT_CMD`` command
+
+Request completion processing
+-----------------------------
+
+a. Upon completion interrupt arrival process completion
+   and message (if enabled) rings
diff --git a/docs/specs/vmw_pvscsi-spec.txt b/docs/specs/vmw_pvscsi-spec.txt
deleted file mode 100644
index 49affb2a42..0000000000
--- a/docs/specs/vmw_pvscsi-spec.txt
+++ /dev/null
@@ -1,92 +0,0 @@
-General Description
-===================
-
-This document describes VMWare PVSCSI device interface specification.
-Created by Dmitry Fleytman (dmitry@daynix.com), Daynix Computing LTD.
-Based on source code of PVSCSI Linux driver from kernel 3.0.4
-
-PVSCSI Device Interface Overview
-================================
-
-The interface is based on memory area shared between hypervisor and VM.
-Memory area is obtained by driver as device IO memory resource of
-PVSCSI_MEM_SPACE_SIZE length.
-The shared memory consists of registers area and rings area.
-The registers area is used to raise hypervisor interrupts and issue device
-commands. The rings area is used to transfer data descriptors and SCSI
-commands from VM to hypervisor and to transfer messages produced by
-hypervisor to VM. Data itself is transferred via virtual scatter-gather DMA.
-
-PVSCSI Device Registers
-=======================
-
-The length of the registers area is 1 page (PVSCSI_MEM_SPACE_COMMAND_NUM_PAGES).
-The structure of the registers area is described by the PVSCSIRegOffset enum.
-There are registers to issue device command (with optional short data),
-issue device interrupt, control interrupts masking.
-
-PVSCSI Device Rings
-===================
-
-There are three rings in shared memory:
-
-    1. Request ring (struct PVSCSIRingReqDesc *req_ring)
-        - ring for OS to device requests
-    2. Completion ring (struct PVSCSIRingCmpDesc *cmp_ring)
-        - ring for device request completions
-    3. Message ring (struct PVSCSIRingMsgDesc *msg_ring)
-        - ring for messages from device.
-       This ring is optional and the guest might not configure it.
-There is a control area (struct PVSCSIRingsState *rings_state) used to control
-rings operation.
-
-PVSCSI Device to Host Interrupts
-================================
-There are following interrupt types supported by PVSCSI device:
-    1. Completion interrupts (completion ring notifications):
-        PVSCSI_INTR_CMPL_0
-        PVSCSI_INTR_CMPL_1
-    2. Message interrupts (message ring notifications):
-        PVSCSI_INTR_MSG_0
-        PVSCSI_INTR_MSG_1
-
-Interrupts are controlled via PVSCSI_REG_OFFSET_INTR_MASK register
-Bit set means interrupt enabled, bit cleared - disabled
-
-Interrupt modes supported are legacy, MSI and MSI-X
-In case of legacy interrupts, register PVSCSI_REG_OFFSET_INTR_STATUS
-is used to check which interrupt has arrived.  Interrupts are
-acknowledged when the corresponding bit is written to the interrupt
-status register.
-
-PVSCSI Device Operation Sequences
-=================================
-
-1. Startup sequence:
-    a. Issue PVSCSI_CMD_ADAPTER_RESET command;
-    aa. Windows driver reads interrupt status register here;
-    b. Issue PVSCSI_CMD_SETUP_MSG_RING command with no additional data,
-       check status and disable device messages if error returned;
-       (Omitted if device messages disabled by driver configuration)
-    c. Issue PVSCSI_CMD_SETUP_RINGS command, provide rings configuration
-       as struct PVSCSICmdDescSetupRings;
-    d. Issue PVSCSI_CMD_SETUP_MSG_RING command again, provide
-       rings configuration as struct PVSCSICmdDescSetupMsgRing;
-    e. Unmask completion and message (if device messages enabled) interrupts.
-
-2. Shutdown sequences
-    a. Mask interrupts;
-    b. Flush request ring using PVSCSI_REG_OFFSET_KICK_NON_RW_IO;
-    c. Issue PVSCSI_CMD_ADAPTER_RESET command.
-
-3. Send request
-    a. Fill next free request ring descriptor;
-    b. Issue PVSCSI_REG_OFFSET_KICK_RW_IO for R/W operations;
-       or PVSCSI_REG_OFFSET_KICK_NON_RW_IO for other operations.
-
-4. Abort command
-    a. Issue PVSCSI_CMD_ABORT_CMD command;
-
-5. Request completion processing
-    a. Upon completion interrupt arrival process completion
-       and message (if enabled) rings.