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