<!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>Vector Extension Support for RISC-V Linux — 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="Concurrent Modification and Execution of Instructions (CMODX) for RISC-V Linux" href="cmodx.html" />
<link rel="prev" title="RISC-V Linux User ABI" href="uabi.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>
<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"><a class="reference internal" href="../../subsystem-apis.html">Subsystems</a></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 class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../index.html">CPU architectures</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../arc/index.html">ARC architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../arm/index.html">ARM Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../arm64/index.html">ARM64 Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../loongarch/index.html">LoongArch Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../m68k/index.html">m68k Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mips/index.html">MIPS-specific Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../nios2/index.html">Nios II Specific Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../openrisc/index.html">OpenRISC Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../parisc/index.html">PA-RISC Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../powerpc/index.html">powerpc</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">RISC-V architecture</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="acpi.html">ACPI on RISC-V</a></li>
<li class="toctree-l3"><a class="reference internal" href="boot.html">RISC-V Kernel Boot Requirements and Constraints</a></li>
<li class="toctree-l3"><a class="reference internal" href="boot-image-header.html">Boot image header in RISC-V Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="vm-layout.html">Virtual Memory Layout on RISC-V Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="hwprobe.html">RISC-V Hardware Probing Interface</a></li>
<li class="toctree-l3"><a class="reference internal" href="patch-acceptance.html">arch/riscv maintenance guidelines for developers</a></li>
<li class="toctree-l3"><a class="reference internal" href="uabi.html">RISC-V Linux User ABI</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Vector Extension Support for RISC-V Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="cmodx.html">Concurrent Modification and Execution of Instructions (CMODX) for RISC-V Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="features.html">Feature status on riscv architecture</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../s390/index.html">s390 Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sh/index.html">SuperH Interfaces Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sparc/index.html">Sparc Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../x86/index.html">x86-specific Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../xtensa/index.html">Xtensa Architecture</a></li>
</ul>
</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/arch/riscv/vector.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="vector-extension-support-for-risc-v-linux">
<h1>Vector Extension Support for RISC-V Linux<a class="headerlink" href="#vector-extension-support-for-risc-v-linux" title="Link to this heading">¶</a></h1>
<p>This document briefly outlines the interface provided to userspace by Linux in
order to support the use of the RISC-V Vector Extension.</p>
<section id="prctl-interface">
<h2>1. prctl() Interface<a class="headerlink" href="#prctl-interface" title="Link to this heading">¶</a></h2>
<p>Two new <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">prctl()</span></code> calls are added to allow programs to manage the enablement
status for the use of Vector in userspace. The intended usage guideline for
these interfaces is to give init systems a way to modify the availability of V
for processes running under its domain. Calling these interfaces is not
recommended in libraries routines because libraries should not override policies
configured from the parent process. Also, users must note that these interfaces
are not portable to non-Linux, nor non-RISC-V environments, so it is discourage
to use in a portable code. To get the availability of V in an ELF program,
please read <code class="xref c c-macro docutils literal notranslate"><span class="pre">COMPAT_HWCAP_ISA_V</span></code> bit of <code class="xref c c-macro docutils literal notranslate"><span class="pre">ELF_HWCAP</span></code> in the
auxiliary vector.</p>
<ul>
<li><p>prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)</p>
<blockquote>
<div><p>Sets the Vector enablement status of the calling thread, where the control
argument consists of two 2-bit enablement statuses and a bit for inheritance
mode. Other threads of the calling process are unaffected.</p>
<p>Enablement status is a tri-state value each occupying 2-bit of space in
the control argument:</p>
<ul class="simple">
<li><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">PR_RISCV_V_VSTATE_CTRL_DEFAULT</span></code>: Use the system-wide default
enablement status on execve(). The system-wide default setting can be
controlled via sysctl interface (see sysctl section below).</p></li>
<li><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">PR_RISCV_V_VSTATE_CTRL_ON</span></code>: Allow Vector to be run for the
thread.</p></li>
<li><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">PR_RISCV_V_VSTATE_CTRL_OFF</span></code>: Disallow Vector. Executing Vector
instructions under such condition will trap and casuse the termination of the thread.</p></li>
</ul>
<p>arg: The control argument is a 5-bit value consisting of 3 parts, and
accessed by 3 masks respectively.</p>
<p>The 3 masks, PR_RISCV_V_VSTATE_CTRL_CUR_MASK,
PR_RISCV_V_VSTATE_CTRL_NEXT_MASK, and PR_RISCV_V_VSTATE_CTRL_INHERIT
represents bit[1:0], bit[3:2], and bit[4]. bit[1:0] accounts for the
enablement status of current thread, and the setting at bit[3:2] takes place
at next execve(). bit[4] defines the inheritance mode of the setting in
bit[3:2].</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">PR_RISCV_V_VSTATE_CTRL_CUR_MASK</span></code>: bit[1:0]: Account for the
Vector enablement status for the calling thread. The calling thread is
not able to turn off Vector once it has been enabled. The <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">prctl()</span></code> call
fails with EPERM if the value in this mask is PR_RISCV_V_VSTATE_CTRL_OFF
but the current enablement status is not off. Setting
PR_RISCV_V_VSTATE_CTRL_DEFAULT here takes no effect but to set back
the original enablement status.</p></li>
<li><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">PR_RISCV_V_VSTATE_CTRL_NEXT_MASK</span></code>: bit[3:2]: Account for the
Vector enablement setting for the calling thread at the next execve()
system call. If PR_RISCV_V_VSTATE_CTRL_DEFAULT is used in this mask,
then the enablement status will be decided by the system-wide
enablement status when execve() happen.</p></li>
<li><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">PR_RISCV_V_VSTATE_CTRL_INHERIT</span></code>: bit[4]: the inheritance
mode for the setting at PR_RISCV_V_VSTATE_CTRL_NEXT_MASK. If the bit
is set then the following execve() will not clear the setting in both
PR_RISCV_V_VSTATE_CTRL_NEXT_MASK and PR_RISCV_V_VSTATE_CTRL_INHERIT.
This setting persists across changes in the system-wide default value.</p></li>
</ul>
</div></blockquote>
<dl class="simple">
<dt>Return value:</dt><dd><ul class="simple">
<li><p>0 on success;</p></li>
<li><p>EINVAL: Vector not supported, invalid enablement status for current or
next mask;</p></li>
<li><p>EPERM: Turning off Vector in PR_RISCV_V_VSTATE_CTRL_CUR_MASK if Vector
was enabled for the calling thread.</p></li>
</ul>
</dd>
<dt>On success:</dt><dd><ul class="simple">
<li><p>A valid setting for PR_RISCV_V_VSTATE_CTRL_CUR_MASK takes place
immediately. The enablement status specified in
PR_RISCV_V_VSTATE_CTRL_NEXT_MASK happens at the next execve() call, or
all following execve() calls if PR_RISCV_V_VSTATE_CTRL_INHERIT bit is
set.</p></li>
<li><p>Every successful call overwrites a previous setting for the calling
thread.</p></li>
</ul>
</dd>
</dl>
</div></blockquote>
</li>
<li><p>prctl(PR_RISCV_V_GET_CONTROL)</p>
<blockquote>
<div><p>Gets the same Vector enablement status for the calling thread. Setting for
next execve() call and the inheritance bit are all OR-ed together.</p>
<p>Note that ELF programs are able to get the availability of V for itself by
reading <code class="xref c c-macro docutils literal notranslate"><span class="pre">COMPAT_HWCAP_ISA_V</span></code> bit of <code class="xref c c-macro docutils literal notranslate"><span class="pre">ELF_HWCAP</span></code> in the
auxiliary vector.</p>
<dl class="simple">
<dt>Return value:</dt><dd><ul class="simple">
<li><p>a nonnegative value on success;</p></li>
<li><p>EINVAL: Vector not supported.</p></li>
</ul>
</dd>
</dl>
</div></blockquote>
</li>
</ul>
</section>
<section id="system-runtime-configuration-sysctl">
<h2>2. System runtime configuration (sysctl)<a class="headerlink" href="#system-runtime-configuration-sysctl" title="Link to this heading">¶</a></h2>
<p>To mitigate the ABI impact of expansion of the signal stack, a
policy mechanism is provided to the administrators, distro maintainers, and
developers to control the default Vector enablement status for userspace
processes in form of sysctl knob:</p>
<ul>
<li><p>/proc/sys/abi/riscv_v_default_allow</p>
<blockquote>
<div><p>Writing the text representation of 0 or 1 to this file sets the default
system enablement status for new starting userspace programs. Valid values
are:</p>
<ul class="simple">
<li><p>0: Do not allow Vector code to be executed as the default for new processes.</p></li>
<li><p>1: Allow Vector code to be executed as the default for new processes.</p></li>
</ul>
<p>Reading this file returns the current system default enablement status.</p>
<p>At every execve() call, a new enablement status of the new process is set to
the system default, unless:</p>
<blockquote>
<div><ul class="simple">
<li><p>PR_RISCV_V_VSTATE_CTRL_INHERIT is set for the calling process, and the
setting in PR_RISCV_V_VSTATE_CTRL_NEXT_MASK is not
PR_RISCV_V_VSTATE_CTRL_DEFAULT. Or,</p></li>
<li><p>The setting in PR_RISCV_V_VSTATE_CTRL_NEXT_MASK is not
PR_RISCV_V_VSTATE_CTRL_DEFAULT.</p></li>
</ul>
</div></blockquote>
<p>Modifying the system default enablement status does not affect the enablement
status of any existing process of thread that do not make an execve() call.</p>
</div></blockquote>
</li>
</ul>
</section>
<section id="vector-register-state-across-system-calls">
<h2>3. Vector Register State Across System Calls<a class="headerlink" href="#vector-register-state-across-system-calls" title="Link to this heading">¶</a></h2>
<p>As indicated by version 1.0 of the V extension [1], vector registers are
clobbered by system calls.</p>
<p>1: <a class="reference external" href="https://github.com/riscv/riscv-v-spec/blob/master/calling-convention.adoc">https://github.com/riscv/riscv-v-spec/blob/master/calling-convention.adoc</a></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/arch/riscv/vector.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>