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