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