| 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 | |
| 13 | For a more detailed reference please refer to the SCSI Primary |
| 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. |