One Hat Cyber Team

Edit File: pr-helper.html

<!DOCTYPE html>

 <html class="no-js" lang="en" > 
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Persistent reservation helper protocol &mdash; QEMU qemu-kvm-6.2.0-53.module+el8.10.0+2055+8eb7870b.4 documentation</title>

</head>

<a href="../index.html" class="icon icon-home"> QEMU

</div>

<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <p class="caption"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../about/index.html">About QEMU</a></li>
<li class="toctree-l1"><a class="reference internal" href="../system/index.html">System Emulation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">User Mode Emulation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Tools</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">System Emulation Management and Interoperability</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="barrier.html">Barrier client protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="bitmaps.html">Dirty Bitmaps and Incremental Backup</a></li>
<li class="toctree-l2"><a class="reference internal" href="dbus.html">D-Bus</a></li>
<li class="toctree-l2"><a class="reference internal" href="dbus-vmstate.html">D-Bus VMState</a></li>
<li class="toctree-l2"><a class="reference internal" href="live-block-operations.html">Live Block Device Operations</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Persistent reservation helper protocol</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#connection-and-initialization">Connection and initialization</a></li>
<li class="toctree-l3"><a class="reference internal" href="#command-format">Command format</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="qemu-ga.html">QEMU Guest Agent</a></li>
<li class="toctree-l2"><a class="reference internal" href="qemu-ga-ref.html">QEMU Guest Agent Protocol Reference</a></li>
<li class="toctree-l2"><a class="reference internal" href="qemu-qmp-ref.html">QEMU QMP Reference Manual</a></li>
<li class="toctree-l2"><a class="reference internal" href="qemu-storage-daemon-qmp-ref.html">QEMU Storage Daemon QMP Reference Manual</a></li>
<li class="toctree-l2"><a class="reference internal" href="vhost-user.html">Vhost-user Protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="vhost-user-gpu.html">Vhost-user-gpu Protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="vhost-vdpa.html">Vhost-vdpa Protocol</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../specs/index.html">System Emulation Guest Hardware Specifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devel/index.html">Developer Information</a></li>
</ul>

</div>
      </div>
    </nav>

<ul class="wy-breadcrumbs">
    
      <li><a href="../index.html">Docs</a> &raquo;</li>
        
          <li><a href="index.html">System Emulation Management and Interoperability</a> &raquo;</li>
        
      <li>Persistent reservation helper protocol</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            
              <a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/interop/pr-helper.rst" class="fa fa-gitlab"> Edit on GitLab</a>
            
          
        
      </li>
    
  </ul>

<hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="persistent-reservation-helper-protocol">
<h1><a class="toc-backref" href="#id1">Persistent reservation helper protocol</a><a class="headerlink" href="#persistent-reservation-helper-protocol" title="Permalink to this headline">¶</a></h1>
<p>QEMU’s SCSI passthrough devices, <code class="docutils literal notranslate"><span class="pre">scsi-block</span></code> and <code class="docutils literal notranslate"><span class="pre">scsi-generic</span></code>,
can delegate implementation of persistent reservations to an external
(and typically privileged) program.  Persistent Reservations allow
restricting access to block devices to specific initiators in a shared
storage setup.</p>
<p>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>This document describes the socket protocol used between QEMU’s
<code class="docutils literal notranslate"><span class="pre">pr-manager-helper</span></code> object and the external program.</p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#persistent-reservation-helper-protocol" id="id1">Persistent reservation helper protocol</a><ul>
<li><a class="reference internal" href="#connection-and-initialization" id="id2">Connection and initialization</a></li>
<li><a class="reference internal" href="#command-format" id="id3">Command format</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="connection-and-initialization">
<h2><a class="toc-backref" href="#id2">Connection and initialization</a><a class="headerlink" href="#connection-and-initialization" title="Permalink to this headline">¶</a></h2>
<p>All data transmitted on the socket is big-endian.</p>
<p>After connecting to the helper program’s socket, the helper starts a simple
feature negotiation process by writing four bytes corresponding to
the features it exposes (<code class="docutils literal notranslate"><span class="pre">supported_features</span></code>).  QEMU reads it,
then writes four bytes corresponding to the desired features of the
helper program (<code class="docutils literal notranslate"><span class="pre">requested_features</span></code>).</p>
<p>If a bit is 1 in <code class="docutils literal notranslate"><span class="pre">requested_features</span></code> and 0 in <code class="docutils literal notranslate"><span class="pre">supported_features</span></code>,
the corresponding feature is not supported by the helper and the connection
is closed.  On the other hand, it is acceptable for a bit to be 0 in
<code class="docutils literal notranslate"><span class="pre">requested_features</span></code> and 1 in <code class="docutils literal notranslate"><span class="pre">supported_features</span></code>; in this case,
the helper will not enable the feature.</p>
<p>Right now no feature is defined, so the two parties always write four
zero bytes.</p>
</div>
<div class="section" id="command-format">
<h2><a class="toc-backref" href="#id3">Command format</a><a class="headerlink" href="#command-format" title="Permalink to this headline">¶</a></h2>
<p>It is invalid to send multiple commands concurrently on the same
socket.  It is however possible to connect multiple sockets to the
helper and send multiple commands to the helper for one or more
file descriptors.</p>
<p>A command consists of a request and a response.  A request consists
of a 16-byte SCSI CDB.  A file descriptor must be passed to the helper
together with the SCSI CDB using ancillary data.</p>
<p>The CDB has the following limitations:</p>
<ul class="simple">
<li>the command (stored in the first byte) must be one of 0x5E
(PERSISTENT RESERVE IN) or 0x5F (PERSISTENT RESERVE OUT).</li>
<li>the allocation length (stored in bytes 7-8 of the CDB for PERSISTENT
RESERVE IN) or parameter list length (stored in bytes 5-8 of the CDB
for PERSISTENT RESERVE OUT) is limited to 8 KiB.</li>
</ul>
<p>For PERSISTENT RESERVE OUT, the parameter list is sent right after the
CDB.  The length of the parameter list is taken from the CDB itself.</p>
<p>The helper’s reply has the following structure:</p>
<ul class="simple">
<li>4 bytes for the SCSI status</li>
<li>4 bytes for the payload size (nonzero only for PERSISTENT RESERVE IN
and only if the SCSI status is 0x00, i.e. GOOD)</li>
<li>96 bytes for the SCSI sense data</li>
<li>if the size is nonzero, the payload follows</li>
</ul>
<p>The sense data is always sent to keep the protocol simple, even though
it is only valid if the SCSI status is CHECK CONDITION (0x02).</p>
<p>The payload size is always less than or equal to the allocation length
specified in the CDB for the PERSISTENT RESERVE IN command.</p>
<p>If the protocol is violated, the helper closes the socket.</p>
</div>
</div>

</div>
           
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="qemu-ga.html" class="btn btn-neutral float-right" title="QEMU Guest Agent" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="live-block-operations.html" class="btn btn-neutral" title="Live Block Device Operations" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>

<hr/>

<div role="contentinfo">
    <p>
        &copy; Copyright 2021, The QEMU Project Developers.

</p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.

<p></p>

<p>This documentation is for QEMU version 6.2.0.</p>

<p><a href="../about/license.html">QEMU and this manual are released under the
GNU General Public License, version 2.</a></p>

</footer>

</div>
      </div>

</section>

</div>

</body>
</html>