1============================== 2VMWare PVSCSI Device Interface 3============================== 4 5.. 6 Created by Dmitry Fleytman (dmitry@daynix.com), Daynix Computing LTD. 7 8This document describes the VMWare PVSCSI device interface specification, 9based on the source code of the PVSCSI Linux driver from kernel 3.0.4. 10 11Overview 12======== 13 14The interface is based on a memory area shared between hypervisor and VM. 15The memory area is obtained by driver as a device IO memory resource of 16``PVSCSI_MEM_SPACE_SIZE`` length. 17The shared memory consists of a registers area and a rings area. 18The registers area is used to raise hypervisor interrupts and issue device 19commands. The rings area is used to transfer data descriptors and SCSI 20commands from VM to hypervisor and to transfer messages produced by 21hypervisor to VM. Data itself is transferred via virtual scatter-gather DMA. 22 23PVSCSI Device Registers 24======================= 25 26The length of the registers area is 1 page 27(``PVSCSI_MEM_SPACE_COMMAND_NUM_PAGES``). The structure of the 28registers area is described by the ``PVSCSIRegOffset`` enum. There 29are registers to issue device commands (with optional short data), 30issue device interrupts, and control interrupt masking. 31 32PVSCSI Device Rings 33=================== 34 35There are three rings in shared memory: 36 37Request ring (``struct PVSCSIRingReqDesc *req_ring``) 38 ring for OS to device requests 39 40Completion ring (``struct PVSCSIRingCmpDesc *cmp_ring``) 41 ring for device request completions 42 43Message ring (``struct PVSCSIRingMsgDesc *msg_ring``) 44 ring for messages from device. This ring is optional and the 45 guest might not configure it. 46 47There is a control area (``struct PVSCSIRingsState *rings_state``) 48used to control rings operation. 49 50PVSCSI Device to Host Interrupts 51================================ 52 53The following interrupt types are supported by the PVSCSI device: 54 55Completion interrupts (completion ring notifications): 56 57- ``PVSCSI_INTR_CMPL_0`` 58- ``PVSCSI_INTR_CMPL_1`` 59 60Message interrupts (message ring notifications): 61 62- ``PVSCSI_INTR_MSG_0`` 63- ``PVSCSI_INTR_MSG_1`` 64 65Interrupts are controlled via the ``PVSCSI_REG_OFFSET_INTR_MASK`` 66register. If a bit is set it means the interrupt is enabled, and if 67it is clear then the interrupt is disabled. 68 69The interrupt modes supported are legacy, MSI and MSI-X. 70In the case of legacy interrupts, the ``PVSCSI_REG_OFFSET_INTR_STATUS`` 71register is used to check which interrupt has arrived. Interrupts are 72acknowledged when the corresponding bit is written to the interrupt 73status register. 74 75PVSCSI Device Operation Sequences 76================================= 77 78Startup sequence 79---------------- 80 81a. Issue ``PVSCSI_CMD_ADAPTER_RESET`` command 82b. Windows driver reads interrupt status register here 83c. Issue ``PVSCSI_CMD_SETUP_MSG_RING`` command with no additional data, 84 check status and disable device messages if error returned 85 (Omitted if device messages disabled by driver configuration) 86d. Issue ``PVSCSI_CMD_SETUP_RINGS`` command, provide rings configuration 87 as ``struct PVSCSICmdDescSetupRings`` 88e. Issue ``PVSCSI_CMD_SETUP_MSG_RING`` command again, provide 89 rings configuration as ``struct PVSCSICmdDescSetupMsgRing`` 90f. Unmask completion and message (if device messages enabled) interrupts 91 92Shutdown sequence 93----------------- 94 95a. Mask interrupts 96b. Flush request ring using ``PVSCSI_REG_OFFSET_KICK_NON_RW_IO`` 97c. Issue ``PVSCSI_CMD_ADAPTER_RESET`` command 98 99Send request 100------------ 101 102a. Fill next free request ring descriptor 103b. Issue ``PVSCSI_REG_OFFSET_KICK_RW_IO`` for R/W operations 104 or ``PVSCSI_REG_OFFSET_KICK_NON_RW_IO`` for other operations 105 106Abort command 107------------- 108 109a. Issue ``PVSCSI_CMD_ABORT_CMD`` command 110 111Request completion processing 112----------------------------- 113 114a. Upon completion interrupt arrival process completion 115 and message (if enabled) rings 116