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