aboutsummaryrefslogtreecommitdiffstats
path: root/docs/specs/vmw_pvscsi-spec.txt
diff options
context:
space:
mode:
authorTimos Ampelikiotis <t.ampelikiotis@virtualopensystems.com>2023-10-10 11:40:56 +0000
committerTimos Ampelikiotis <t.ampelikiotis@virtualopensystems.com>2023-10-10 11:40:56 +0000
commite02cda008591317b1625707ff8e115a4841aa889 (patch)
treeaee302e3cf8b59ec2d32ec481be3d1afddfc8968 /docs/specs/vmw_pvscsi-spec.txt
parentcc668e6b7e0ffd8c9d130513d12053cf5eda1d3b (diff)
Introduce Virtio-loopback epsilon release:
Epsilon release introduces a new compatibility layer which make virtio-loopback design to work with QEMU and rust-vmm vhost-user backend without require any changes. Signed-off-by: Timos Ampelikiotis <t.ampelikiotis@virtualopensystems.com> Change-Id: I52e57563e08a7d0bdc002f8e928ee61ba0c53dd9
Diffstat (limited to 'docs/specs/vmw_pvscsi-spec.txt')
-rw-r--r--docs/specs/vmw_pvscsi-spec.txt92
1 files changed, 92 insertions, 0 deletions
diff --git a/docs/specs/vmw_pvscsi-spec.txt b/docs/specs/vmw_pvscsi-spec.txt
new file mode 100644
index 000000000..49affb2a4
--- /dev/null
+++ b/docs/specs/vmw_pvscsi-spec.txt
@@ -0,0 +1,92 @@
+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.