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