0001 ===============================================
0002 Block layer support for Persistent Reservations
0003 ===============================================
0004
0005 The Linux kernel supports a user space interface for simplified
0006 Persistent Reservations which map to block devices that support
0007 these (like SCSI). Persistent Reservations allow restricting
0008 access to block devices to specific initiators in a shared storage
0009 setup.
0010
0011 This document gives a general overview of the support ioctl commands.
0012 For a more detailed reference please refer to the SCSI Primary
0013 Commands standard, specifically the section on Reservations and the
0014 "PERSISTENT RESERVE IN" and "PERSISTENT RESERVE OUT" commands.
0015
0016 All implementations are expected to ensure the reservations survive
0017 a power loss and cover all connections in a multi path environment.
0018 These behaviors are optional in SPC but will be automatically applied
0019 by Linux.
0020
0021
0022 The following types of reservations are supported:
0023 --------------------------------------------------
0024
0025 - PR_WRITE_EXCLUSIVE
0026 Only the initiator that owns the reservation can write to the
0027 device. Any initiator can read from the device.
0028
0029 - PR_EXCLUSIVE_ACCESS
0030 Only the initiator that owns the reservation can access the
0031 device.
0032
0033 - PR_WRITE_EXCLUSIVE_REG_ONLY
0034 Only initiators with a registered key can write to the device,
0035 Any initiator can read from the device.
0036
0037 - PR_EXCLUSIVE_ACCESS_REG_ONLY
0038 Only initiators with a registered key can access the device.
0039
0040 - PR_WRITE_EXCLUSIVE_ALL_REGS
0041
0042 Only initiators with a registered key can write to the device,
0043 Any initiator can read from the device.
0044 All initiators with a registered key are considered reservation
0045 holders.
0046 Please reference the SPC spec on the meaning of a reservation
0047 holder if you want to use this type.
0048
0049 - PR_EXCLUSIVE_ACCESS_ALL_REGS
0050 Only initiators with a registered key can access the device.
0051 All initiators with a registered key are considered reservation
0052 holders.
0053 Please reference the SPC spec on the meaning of a reservation
0054 holder if you want to use this type.
0055
0056
0057 The following ioctl are supported:
0058 ----------------------------------
0059
0060 1. IOC_PR_REGISTER
0061 ^^^^^^^^^^^^^^^^^^
0062
0063 This ioctl command registers a new reservation if the new_key argument
0064 is non-null. If no existing reservation exists old_key must be zero,
0065 if an existing reservation should be replaced old_key must contain
0066 the old reservation key.
0067
0068 If the new_key argument is 0 it unregisters the existing reservation passed
0069 in old_key.
0070
0071
0072 2. IOC_PR_RESERVE
0073 ^^^^^^^^^^^^^^^^^
0074
0075 This ioctl command reserves the device and thus restricts access for other
0076 devices based on the type argument. The key argument must be the existing
0077 reservation key for the device as acquired by the IOC_PR_REGISTER,
0078 IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands.
0079
0080
0081 3. IOC_PR_RELEASE
0082 ^^^^^^^^^^^^^^^^^
0083
0084 This ioctl command releases the reservation specified by key and flags
0085 and thus removes any access restriction implied by it.
0086
0087
0088 4. IOC_PR_PREEMPT
0089 ^^^^^^^^^^^^^^^^^
0090
0091 This ioctl command releases the existing reservation referred to by
0092 old_key and replaces it with a new reservation of type for the
0093 reservation key new_key.
0094
0095
0096 5. IOC_PR_PREEMPT_ABORT
0097 ^^^^^^^^^^^^^^^^^^^^^^^
0098
0099 This ioctl command works like IOC_PR_PREEMPT except that it also aborts
0100 any outstanding command sent over a connection identified by old_key.
0101
0102 6. IOC_PR_CLEAR
0103 ^^^^^^^^^^^^^^^
0104
0105 This ioctl command unregisters both key and any other reservation key
0106 registered with the device and drops any existing reservation.
0107
0108
0109 Flags
0110 -----
0111
0112 All the ioctls have a flag field. Currently only one flag is supported:
0113
0114 - PR_FL_IGNORE_KEY
0115 Ignore the existing reservation key. This is commonly supported for
0116 IOC_PR_REGISTER, and some implementation may support the flag for
0117 IOC_PR_RESERVE.
0118
0119 For all unknown flags the kernel will return -EOPNOTSUPP.
