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