docs/specs/vmw_pvscsi-spec.txt

   1 General Description
   2 ===================
   3
   4 This document describes VMWare PVSCSI device interface specification.
   5 Created by Dmitry Fleytman (dmitry@daynix.com), Daynix Computing LTD.
   6 Based on source code of PVSCSI Linux driver from kernel 3.0.4
   7
   8 PVSCSI Device Interface Overview
   9 ================================
  10
  11 The interface is based on memory area shared between hypervisor and VM.
  12 Memory area is obtained by driver as device IO memory resource of
  13 PVSCSI_MEM_SPACE_SIZE length.
  14 The shared memory consists of registers area and rings area.
  15 The registers area is used to raise hypervisor interrupts and issue device
  16 commands. The rings area is used to transfer data descriptors and SCSI
  17 commands from VM to hypervisor and to transfer messages produced by
  18 hypervisor to VM. Data itself is transferred via virtual scatter-gather DMA.
  19
  20 PVSCSI Device Registers
  21 =======================
  22
  23 The length of the registers area is 1 page (PVSCSI_MEM_SPACE_COMMAND_NUM_PAGES).
  24 The structure of the registers area is described by the PVSCSIRegOffset enum.
  25 There are registers to issue device command (with optional short data),
  26 issue device interrupt, control interrupts masking.
  27
  28 PVSCSI Device Rings
  29 ===================
  30
  31 There 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.
  40 There is a control area (struct PVSCSIRingsState *rings_state) used to control
  41 rings operation.
  42
  43 PVSCSI Device to Host Interrupts
  44 ================================
  45 There 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
  53 Interrupts are controlled via PVSCSI_REG_OFFSET_INTR_MASK register
  54 Bit set means interrupt enabled, bit cleared - disabled
  55
  56 Interrupt modes supported are legacy, MSI and MSI-X
  57 In case of legacy interrupts, register PVSCSI_REG_OFFSET_INTR_STATUS
  58 is used to check which interrupt has arrived.  Interrupts are
  59 acknowledged when the corresponding bit is written to the interrupt
  60 status register.
  61
  62 PVSCSI Device Operation Sequences
  63 =================================
  64
  65 1. 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
  77 2. 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
  82 3. 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
  87 4. Abort command
  88     a. Issue PVSCSI_CMD_ABORT_CMD command;
  89
  90 5. Request completion processing
  91     a. Upon completion interrupt arrival process completion
  92        and message (if enabled) rings.