root / docs / specs / vmw_pvscsi-spec.txt @ 881d588a
History | View | Annotate | Download (3.6 kB)
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. |