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