[deliverable/linux.git] / Documentation / block / pr.txt


Block layer support for Persistent Reservations
===============================================

The Linux kernel supports a user space interface for simplified
Persistent Reservations which map to block devices that support
these (like SCSI). Persistent Reservations allow restricting
access to block devices to specific initiators in a shared storage
setup.

This document gives a general overview of the support ioctl commands.
For a more detailed reference please refer the the SCSI Primary
Commands standard, specifically the section on Reservations and the
"PERSISTENT RESERVE IN" and "PERSISTENT RESERVE OUT" commands.

All implementations are expected to ensure the reservations survive
a power loss and cover all connections in a multi path environment.
These behaviors are optional in SPC but will be automatically applied
by Linux.


The following types of reservations are supported:
--------------------------------------------------

 - PR_WRITE_EXCLUSIVE

	Only the initiator that owns the reservation can write to the
	device.  Any initiator can read from the device.

 - PR_EXCLUSIVE_ACCESS

	Only the initiator that owns the reservation can access the
	device.

 - PR_WRITE_EXCLUSIVE_REG_ONLY

	Only initiators with a registered key can write to the device,
	Any initiator can read from the device.

 - PR_EXCLUSIVE_ACCESS_REG_ONLY

	Only initiators with a registered key can access the device.

 - PR_WRITE_EXCLUSIVE_ALL_REGS

	Only initiators with a registered key can write to the device,
	Any initiator can read from the device.
	All initiators with a registered key are considered reservation
	holders.
	Please reference the SPC spec on the meaning of a reservation
	holder if you want to use this type. 

 - PR_EXCLUSIVE_ACCESS_ALL_REGS

	Only initiators with a registered key can access the device.
	All initiators with a registered key are considered reservation
	holders.
	Please reference the SPC spec on the meaning of a reservation
	holder if you want to use this type. 


The following ioctl are supported:
----------------------------------

1. IOC_PR_REGISTER

This ioctl command registers a new reservation if the new_key argument
is non-null.  If no existing reservation exists old_key must be zero,
if an existing reservation should be replaced old_key must contain
the old reservation key.

If the new_key argument is 0 it unregisters the existing reservation passed
in old_key.


2. IOC_PR_RESERVE

This ioctl command reserves the device and thus restricts access for other
devices based on the type argument.  The key argument must be the existing
reservation key for the device as acquired by the IOC_PR_REGISTER,
IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands.


3. IOC_PR_RELEASE

This ioctl command releases the reservation specified by key and flags
and thus removes any access restriction implied by it.


4. IOC_PR_PREEMPT

This ioctl command releases the existing reservation referred to by
old_key and replaces it with a a new reservation of type for the
reservation key new_key.


5. IOC_PR_PREEMPT_ABORT

This ioctl command works like IOC_PR_PREEMPT except that it also aborts
any outstanding command sent over a connection identified by old_key.

6. IOC_PR_CLEAR

This ioctl command unregisters both key and any other reservation key
registered with the device and drops any existing reservation.


Flags
-----

All the ioctls have a flag field.  Currently only one flag is supported:

 - PR_FL_IGNORE_KEY

	Ignore the existing reservation key.  This is commonly supported for
	IOC_PR_REGISTER, and some implementation may support the flag for
	IOC_PR_RESERVE.

For all unknown flags the kernel will return -EOPNOTSUPP.
Commit	Line	Data
bbd3e064 CH	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.