1 2Block layer support for Persistent Reservations 3=============================================== 4 5The Linux kernel supports a user space interface for simplified 6Persistent Reservations which map to block devices that support 7these (like SCSI). Persistent Reservations allow restricting 8access to block devices to specific initiators in a shared storage 9setup. 10 11This document gives a general overview of the support ioctl commands. 12For a more detailed reference please refer the the SCSI Primary 13Commands standard, specifically the section on Reservations and the 14"PERSISTENT RESERVE IN" and "PERSISTENT RESERVE OUT" commands. 15 16All implementations are expected to ensure the reservations survive 17a power loss and cover all connections in a multi path environment. 18These behaviors are optional in SPC but will be automatically applied 19by Linux. 20 21 22The 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 62The following ioctl are supported: 63---------------------------------- 64 651. IOC_PR_REGISTER 66 67This ioctl command registers a new reservation if the new_key argument 68is non-null. If no existing reservation exists old_key must be zero, 69if an existing reservation should be replaced old_key must contain 70the old reservation key. 71 72If the new_key argument is 0 it unregisters the existing reservation passed 73in old_key. 74 75 762. IOC_PR_RESERVE 77 78This ioctl command reserves the device and thus restricts access for other 79devices based on the type argument. The key argument must be the existing 80reservation key for the device as acquired by the IOC_PR_REGISTER, 81IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands. 82 83 843. IOC_PR_RELEASE 85 86This ioctl command releases the reservation specified by key and flags 87and thus removes any access restriction implied by it. 88 89 904. IOC_PR_PREEMPT 91 92This ioctl command releases the existing reservation referred to by 93old_key and replaces it with a new reservation of type for the 94reservation key new_key. 95 96 975. IOC_PR_PREEMPT_ABORT 98 99This ioctl command works like IOC_PR_PREEMPT except that it also aborts 100any outstanding command sent over a connection identified by old_key. 101 1026. IOC_PR_CLEAR 103 104This ioctl command unregisters both key and any other reservation key 105registered with the device and drops any existing reservation. 106 107 108Flags 109----- 110 111All 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 119For all unknown flags the kernel will return -EOPNOTSUPP. 120
