| Christoph Hellwig | bbd3e06 | 2015-10-15 14:10:48 +0200 | [diff] [blame] | 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 the 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 | |
| 27 | Only the initiator that owns the reservation can write to the |
| 28 | device. Any initiator can read from the device. |
| 29 | |
| 30 | - PR_EXCLUSIVE_ACCESS |
| 31 | |
| 32 | Only the initiator that owns the reservation can access the |
| 33 | device. |
| 34 | |
| 35 | - PR_WRITE_EXCLUSIVE_REG_ONLY |
| 36 | |
| 37 | Only initiators with a registered key can write to the device, |
| 38 | Any initiator can read from the device. |
| 39 | |
| 40 | - PR_EXCLUSIVE_ACCESS_REG_ONLY |
| 41 | |
| 42 | Only initiators with a registered key can access the device. |
| 43 | |
| 44 | - PR_WRITE_EXCLUSIVE_ALL_REGS |
| 45 | |
| 46 | Only initiators with a registered key can write to the device, |
| 47 | Any initiator can read from the device. |
| 48 | All initiators with a registered key are considered reservation |
| 49 | holders. |
| 50 | Please reference the SPC spec on the meaning of a reservation |
| 51 | holder if you want to use this type. |
| 52 | |
| 53 | - PR_EXCLUSIVE_ACCESS_ALL_REGS |
| 54 | |
| 55 | Only initiators with a registered key can access the device. |
| 56 | All initiators with a registered key are considered reservation |
| 57 | holders. |
| 58 | Please reference the SPC spec on the meaning of a reservation |
| 59 | holder if you want to use this type. |
| 60 | |
| 61 | |
| 62 | The following ioctl are supported: |
| 63 | ---------------------------------- |
| 64 | |
| 65 | 1. IOC_PR_REGISTER |
| 66 | |
| 67 | This ioctl command registers a new reservation if the new_key argument |
| 68 | is non-null. If no existing reservation exists old_key must be zero, |
| 69 | if an existing reservation should be replaced old_key must contain |
| 70 | the old reservation key. |
| 71 | |
| 72 | If the new_key argument is 0 it unregisters the existing reservation passed |
| 73 | in old_key. |
| 74 | |
| 75 | |
| 76 | 2. IOC_PR_RESERVE |
| 77 | |
| 78 | This ioctl command reserves the device and thus restricts access for other |
| 79 | devices based on the type argument. The key argument must be the existing |
| 80 | reservation key for the device as acquired by the IOC_PR_REGISTER, |
| 81 | IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands. |
| 82 | |
| 83 | |
| 84 | 3. IOC_PR_RELEASE |
| 85 | |
| 86 | This ioctl command releases the reservation specified by key and flags |
| 87 | and thus removes any access restriction implied by it. |
| 88 | |
| 89 | |
| 90 | 4. IOC_PR_PREEMPT |
| 91 | |
| 92 | This ioctl command releases the existing reservation referred to by |
| 93 | old_key and replaces it with a a new reservation of type for the |
| 94 | reservation key new_key. |
| 95 | |
| 96 | |
| 97 | 5. IOC_PR_PREEMPT_ABORT |
| 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 | This ioctl command unregisters both key and any other reservation key |
| 105 | registered with the device and drops any existing reservation. |
| 106 | |
| 107 | |
| 108 | Flags |
| 109 | ----- |
| 110 | |
| 111 | All the ioctls have a flag field. Currently only one flag is supported: |
| 112 | |
| 113 | - PR_FL_IGNORE_KEY |
| 114 | |
| 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. |