docs/interop/pr-helper.rst

   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.