]>
Commit | Line | Data |
---|---|---|
b855f8d1 PB |
1 | .. |
2 | ||
3 | ====================================== | |
4 | Persistent reservation helper protocol | |
5 | ====================================== | |
6 | ||
7 | QEMU's SCSI passthrough devices, ``scsi-block`` and ``scsi-generic``, | |
8 | can delegate implementation of persistent reservations to an external | |
9 | (and typically privileged) program. Persistent Reservations allow | |
10 | restricting access to block devices to specific initiators in a shared | |
11 | storage setup. | |
12 | ||
df59feb1 | 13 | For a more detailed reference please refer to the SCSI Primary |
b855f8d1 PB |
14 | Commands standard, specifically the section on Reservations and the |
15 | "PERSISTENT RESERVE IN" and "PERSISTENT RESERVE OUT" commands. | |
16 | ||
17 | This document describes the socket protocol used between QEMU's | |
18 | ``pr-manager-helper`` object and the external program. | |
19 | ||
20 | .. contents:: | |
21 | ||
22 | Connection and initialization | |
23 | ----------------------------- | |
24 | ||
25 | All data transmitted on the socket is big-endian. | |
26 | ||
27 | After connecting to the helper program's socket, the helper starts a simple | |
28 | feature negotiation process by writing four bytes corresponding to | |
29 | the features it exposes (``supported_features``). QEMU reads it, | |
30 | then writes four bytes corresponding to the desired features of the | |
31 | helper program (``requested_features``). | |
32 | ||
33 | If a bit is 1 in ``requested_features`` and 0 in ``supported_features``, | |
34 | the corresponding feature is not supported by the helper and the connection | |
35 | is closed. On the other hand, it is acceptable for a bit to be 0 in | |
36 | ``requested_features`` and 1 in ``supported_features``; in this case, | |
37 | the helper will not enable the feature. | |
38 | ||
39 | Right now no feature is defined, so the two parties always write four | |
40 | zero bytes. | |
41 | ||
42 | Command format | |
43 | -------------- | |
44 | ||
45 | It is invalid to send multiple commands concurrently on the same | |
46 | socket. It is however possible to connect multiple sockets to the | |
47 | helper and send multiple commands to the helper for one or more | |
48 | file descriptors. | |
49 | ||
50 | A command consists of a request and a response. A request consists | |
51 | of a 16-byte SCSI CDB. A file descriptor must be passed to the helper | |
52 | together with the SCSI CDB using ancillary data. | |
53 | ||
54 | The CDB has the following limitations: | |
55 | ||
56 | - the command (stored in the first byte) must be one of 0x5E | |
57 | (PERSISTENT RESERVE IN) or 0x5F (PERSISTENT RESERVE OUT). | |
58 | ||
59 | - the allocation length (stored in bytes 7-8 of the CDB for PERSISTENT | |
60 | RESERVE IN) or parameter list length (stored in bytes 5-8 of the CDB | |
61 | for PERSISTENT RESERVE OUT) is limited to 8 KiB. | |
62 | ||
63 | For PERSISTENT RESERVE OUT, the parameter list is sent right after the | |
64 | CDB. The length of the parameter list is taken from the CDB itself. | |
65 | ||
66 | The helper's reply has the following structure: | |
67 | ||
68 | - 4 bytes for the SCSI status | |
69 | ||
70 | - 4 bytes for the payload size (nonzero only for PERSISTENT RESERVE IN | |
71 | and only if the SCSI status is 0x00, i.e. GOOD) | |
72 | ||
73 | - 96 bytes for the SCSI sense data | |
74 | ||
75 | - if the size is nonzero, the payload follows | |
76 | ||
77 | The sense data is always sent to keep the protocol simple, even though | |
78 | it is only valid if the SCSI status is CHECK CONDITION (0x02). | |
79 | ||
80 | The payload size is always less than or equal to the allocation length | |
81 | specified in the CDB for the PERSISTENT RESERVE IN command. | |
82 | ||
83 | If the protocol is violated, the helper closes the socket. |