<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Block layer support for Persistent Reservations — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=3918102e" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Block layer statistics in /sys/block/<dev>/stat" href="stat.html" />
<link rel="prev" title="Null block device driver" href="null_blk.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/index.html">All development-process docs</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../subsystem-apis.html">Subsystems</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#core-subsystems">Core subsystems</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#human-interfaces">Human interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#networking-interfaces">Networking interfaces</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../subsystem-apis.html#storage-interfaces">Storage interfaces</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../filesystems/index.html">Filesystems in the Linux kernel</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="index.html">Block</a></li>
<li class="toctree-l3"><a class="reference internal" href="../cdrom/index.html">CD-ROM</a></li>
<li class="toctree-l3"><a class="reference internal" href="../scsi/index.html">SCSI Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../target/index.html">TCM Virtual Device</a></li>
<li class="toctree-l3"><a class="reference internal" href="../nvme/index.html">NVMe Subsystem</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#other-subsystems">Other subsystems</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/block/pr.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="block-layer-support-for-persistent-reservations">
<h1>Block layer support for Persistent Reservations<a class="headerlink" href="#block-layer-support-for-persistent-reservations" title="Link to this heading">¶</a></h1>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<section id="the-following-types-of-reservations-are-supported">
<h2>The following types of reservations are supported:<a class="headerlink" href="#the-following-types-of-reservations-are-supported" title="Link to this heading">¶</a></h2>
<blockquote>
<div><ul>
<li><dl class="simple">
<dt>PR_WRITE_EXCLUSIVE</dt><dd><p>Only the initiator that owns the reservation can write to the
device. Any initiator can read from the device.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>PR_EXCLUSIVE_ACCESS</dt><dd><p>Only the initiator that owns the reservation can access the
device.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>PR_WRITE_EXCLUSIVE_REG_ONLY</dt><dd><p>Only initiators with a registered key can write to the device,
Any initiator can read from the device.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>PR_EXCLUSIVE_ACCESS_REG_ONLY</dt><dd><p>Only initiators with a registered key can access the device.</p>
</dd>
</dl>
</li>
<li><p>PR_WRITE_EXCLUSIVE_ALL_REGS</p>
<blockquote>
<div><p>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.</p>
</div></blockquote>
</li>
<li><dl class="simple">
<dt>PR_EXCLUSIVE_ACCESS_ALL_REGS</dt><dd><p>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.</p>
</dd>
</dl>
</li>
</ul>
</div></blockquote>
</section>
<section id="the-following-ioctl-are-supported">
<h2>The following ioctl are supported:<a class="headerlink" href="#the-following-ioctl-are-supported" title="Link to this heading">¶</a></h2>
<section id="ioc-pr-register">
<h3>1. IOC_PR_REGISTER<a class="headerlink" href="#ioc-pr-register" title="Link to this heading">¶</a></h3>
<p>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.</p>
<p>If the new_key argument is 0 it unregisters the existing reservation passed
in old_key.</p>
</section>
<section id="ioc-pr-reserve">
<h3>2. IOC_PR_RESERVE<a class="headerlink" href="#ioc-pr-reserve" title="Link to this heading">¶</a></h3>
<p>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.</p>
</section>
<section id="ioc-pr-release">
<h3>3. IOC_PR_RELEASE<a class="headerlink" href="#ioc-pr-release" title="Link to this heading">¶</a></h3>
<p>This ioctl command releases the reservation specified by key and flags
and thus removes any access restriction implied by it.</p>
</section>
<section id="ioc-pr-preempt">
<h3>4. IOC_PR_PREEMPT<a class="headerlink" href="#ioc-pr-preempt" title="Link to this heading">¶</a></h3>
<p>This ioctl command releases the existing reservation referred to by
old_key and replaces it with a new reservation of type for the
reservation key new_key.</p>
</section>
<section id="ioc-pr-preempt-abort">
<h3>5. IOC_PR_PREEMPT_ABORT<a class="headerlink" href="#ioc-pr-preempt-abort" title="Link to this heading">¶</a></h3>
<p>This ioctl command works like IOC_PR_PREEMPT except that it also aborts
any outstanding command sent over a connection identified by old_key.</p>
</section>
<section id="ioc-pr-clear">
<h3>6. IOC_PR_CLEAR<a class="headerlink" href="#ioc-pr-clear" title="Link to this heading">¶</a></h3>
<p>This ioctl command unregisters both key and any other reservation key
registered with the device and drops any existing reservation.</p>
</section>
</section>
<section id="flags">
<h2>Flags<a class="headerlink" href="#flags" title="Link to this heading">¶</a></h2>
<p>All the ioctls have a flag field. Currently only one flag is supported:</p>
<blockquote>
<div><ul class="simple">
<li><dl class="simple">
<dt>PR_FL_IGNORE_KEY</dt><dd><p>Ignore the existing reservation key. This is commonly supported for
IOC_PR_REGISTER, and some implementation may support the flag for
IOC_PR_RESERVE.</p>
</dd>
</dl>
</li>
</ul>
</div></blockquote>
<p>For all unknown flags the kernel will return -EOPNOTSUPP.</p>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../_sources/block/pr.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>