<!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>Infiniband Userspace Capabilities — 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="Userspace MAD access" href="user_mad.html" />
<link rel="prev" title="Tag matching logic" href="tag_matching.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 current"><a class="reference internal" href="../subsystem-apis.html#networking-interfaces">Networking interfaces</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../networking/index.html">Networking</a></li>
<li class="toctree-l3"><a class="reference internal" href="../netlabel/index.html">NetLabel</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="index.html">InfiniBand</a></li>
<li class="toctree-l3"><a class="reference internal" href="../isdn/index.html">ISDN</a></li>
<li class="toctree-l3"><a class="reference internal" href="../mhi/index.html">MHI</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#storage-interfaces">Storage interfaces</a></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/infiniband/ucaps.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="infiniband-userspace-capabilities">
<h1>Infiniband Userspace Capabilities<a class="headerlink" href="#infiniband-userspace-capabilities" title="Link to this heading">¶</a></h1>
<blockquote>
<div><p>User CAPabilities (UCAPs) provide fine-grained control over specific
firmware features in Infiniband (IB) devices. This approach offers
more granular capabilities than the existing Linux capabilities,
which may be too generic for certain FW features.</p>
<p>Each user capability is represented as a character device with root
read-write access. Root processes can grant users special privileges
by allowing access to these character devices (e.g., using chown).</p>
</div></blockquote>
<section id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h2>
<blockquote>
<div><p>UCAPs allow control over specific features of an IB device using file
descriptors of UCAP character devices. Here is how a user enables
specific features of an IB device:</p>
<blockquote>
<div><ul class="simple">
<li><p>A root process grants the user access to the UCAP files that
represents the capabilities (e.g., using chown).</p></li>
<li><p>The user opens the UCAP files, obtaining file descriptors.</p></li>
<li><p>When opening an IB device, include an array of the UCAP file
descriptors as an attribute.</p></li>
<li><p>The ib_uverbs driver recognizes the UCAP file descriptors and enables
the corresponding capabilities for the IB device.</p></li>
</ul>
</div></blockquote>
</div></blockquote>
</section>
<section id="creating-ucaps">
<h2>Creating UCAPs<a class="headerlink" href="#creating-ucaps" title="Link to this heading">¶</a></h2>
<blockquote>
<div><p>To create a new UCAP, drivers must first define a type in the
rdma_user_cap <code class="xref c c-enum broken_xref docutils literal notranslate"><span class="pre">enum</span> <span class="pre">in</span></code> rdma/ib_ucaps.h. The name of the UCAP character
device should be added to the ucap_names array in
drivers/infiniband/core/ucaps.c. Then, the driver can create the UCAP
character device by calling the ib_create_ucap API with the UCAP
type.</p>
<p>A reference count is stored for each UCAP to track creations and
removals of the UCAP device. If multiple creation calls are made with
the same type (e.g., for two IB devices), the UCAP character device
is created during the first call and subsequent calls increment the
reference count.</p>
<p>The UCAP character device is created under /dev/infiniband, and its
permissions are set to allow root read and write access only.</p>
</div></blockquote>
</section>
<section id="removing-ucaps">
<h2>Removing UCAPs<a class="headerlink" href="#removing-ucaps" title="Link to this heading">¶</a></h2>
<blockquote>
<div><p>Each removal decrements the reference count of the UCAP. The UCAP
character device is removed from the filesystem only when the
reference count is decreased to 0.</p>
</div></blockquote>
</section>
<section id="dev-and-sys-class-files">
<h2>/dev and /sys/class files<a class="headerlink" href="#dev-and-sys-class-files" title="Link to this heading">¶</a></h2>
<blockquote>
<div><p>The class:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>/sys/class/infiniband_ucaps
</pre></div>
</div>
<p>is created when the first UCAP character device is created.</p>
<p>The UCAP character device is created under /dev/infiniband.</p>
<p>For example, if mlx5_ib adds the rdma_user_cap
RDMA_UCAP_MLX5_CTRL_LOCAL with name “mlx5_perm_ctrl_local”, this will
create the device node:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>/dev/infiniband/mlx5_perm_ctrl_local
</pre></div>
</div>
</div></blockquote>
</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/infiniband/ucaps.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>