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 to 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	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
57The following ioctl are supported:
58----------------------------------
59
601. IOC_PR_REGISTER
61^^^^^^^^^^^^^^^^^^
62
63This ioctl command registers a new reservation if the new_key argument
64is non-null.  If no existing reservation exists old_key must be zero,
65if an existing reservation should be replaced old_key must contain
66the old reservation key.
67
68If the new_key argument is 0 it unregisters the existing reservation passed
69in old_key.
70
71
722. IOC_PR_RESERVE
73^^^^^^^^^^^^^^^^^
74
75This ioctl command reserves the device and thus restricts access for other
76devices based on the type argument.  The key argument must be the existing
77reservation key for the device as acquired by the IOC_PR_REGISTER,
78IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands.
79
80
813. IOC_PR_RELEASE
82^^^^^^^^^^^^^^^^^
83
84This ioctl command releases the reservation specified by key and flags
85and thus removes any access restriction implied by it.
86
87
884. IOC_PR_PREEMPT
89^^^^^^^^^^^^^^^^^
90
91This ioctl command releases the existing reservation referred to by
92old_key and replaces it with a new reservation of type for the
93reservation key new_key.
94
95
965. IOC_PR_PREEMPT_ABORT
97^^^^^^^^^^^^^^^^^^^^^^^
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^^^^^^^^^^^^^^^
104
105This ioctl command unregisters both key and any other reservation key
106registered with the device and drops any existing reservation.
107
108
109Flags
110-----
111
112All 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
119For all unknown flags the kernel will return -EOPNOTSUPP.
120