^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Block layer support for Persistent Reservations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) The Linux kernel supports a user space interface for simplified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) Persistent Reservations which map to block devices that support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) these (like SCSI). Persistent Reservations allow restricting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) access to block devices to specific initiators in a shared storage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) setup.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) This document gives a general overview of the support ioctl commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) For a more detailed reference please refer to the SCSI Primary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) Commands standard, specifically the section on Reservations and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) "PERSISTENT RESERVE IN" and "PERSISTENT RESERVE OUT" commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) All implementations are expected to ensure the reservations survive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) a power loss and cover all connections in a multi path environment.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) These behaviors are optional in SPC but will be automatically applied
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) by Linux.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) The following types of reservations are supported:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) --------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) - PR_WRITE_EXCLUSIVE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) Only the initiator that owns the reservation can write to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) device. Any initiator can read from the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) - PR_EXCLUSIVE_ACCESS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) Only the initiator that owns the reservation can access the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) - PR_WRITE_EXCLUSIVE_REG_ONLY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Only initiators with a registered key can write to the device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Any initiator can read from the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) - PR_EXCLUSIVE_ACCESS_REG_ONLY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) Only initiators with a registered key can access the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) - PR_WRITE_EXCLUSIVE_ALL_REGS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) Only initiators with a registered key can write to the device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) Any initiator can read from the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) All initiators with a registered key are considered reservation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) holders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) Please reference the SPC spec on the meaning of a reservation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) holder if you want to use this type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) - PR_EXCLUSIVE_ACCESS_ALL_REGS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) Only initiators with a registered key can access the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) All initiators with a registered key are considered reservation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) holders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) Please reference the SPC spec on the meaning of a reservation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) holder if you want to use this type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) The following ioctl are supported:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) 1. IOC_PR_REGISTER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) ^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) This ioctl command registers a new reservation if the new_key argument
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) is non-null. If no existing reservation exists old_key must be zero,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) if an existing reservation should be replaced old_key must contain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) the old reservation key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) If the new_key argument is 0 it unregisters the existing reservation passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) in old_key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) 2. IOC_PR_RESERVE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) ^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) This ioctl command reserves the device and thus restricts access for other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) devices based on the type argument. The key argument must be the existing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) reservation key for the device as acquired by the IOC_PR_REGISTER,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) 3. IOC_PR_RELEASE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) ^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) This ioctl command releases the reservation specified by key and flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) and thus removes any access restriction implied by it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) 4. IOC_PR_PREEMPT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) ^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) This ioctl command releases the existing reservation referred to by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) old_key and replaces it with a new reservation of type for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) reservation key new_key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) 5. IOC_PR_PREEMPT_ABORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) ^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) This ioctl command works like IOC_PR_PREEMPT except that it also aborts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) any outstanding command sent over a connection identified by old_key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) 6. IOC_PR_CLEAR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) ^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) This ioctl command unregisters both key and any other reservation key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) registered with the device and drops any existing reservation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) Flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) -----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) All the ioctls have a flag field. Currently only one flag is supported:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) - PR_FL_IGNORE_KEY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) Ignore the existing reservation key. This is commonly supported for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) IOC_PR_REGISTER, and some implementation may support the flag for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) IOC_PR_RESERVE.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) For all unknown flags the kernel will return -EOPNOTSUPP.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags