Documentation/block/pr.rst

Source file repositories/reference/linux-study-clean/Documentation/block/pr.rst

File Facts

System
Linux kernel
Corpus path
Documentation/block/pr.rst
Extension
.rst
Size
3846 bytes
Lines
120
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

===============================================
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 to 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.

Annotation

Implementation Notes