Documentation/riscv/vector.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =========================================
   4 Vector Extension Support for RISC-V Linux
   5 =========================================
   6
   7 This document briefly outlines the interface provided to userspace by Linux in
   8 order to support the use of the RISC-V Vector Extension.
   9
  10 1.  prctl() Interface
  11 ---------------------
  12
  13 Two new prctl() calls are added to allow programs to manage the enablement
  14 status for the use of Vector in userspace. The intended usage guideline for
  15 these interfaces is to give init systems a way to modify the availability of V
  16 for processes running under its domain. Calling these interfaces is not
  17 recommended in libraries routines because libraries should not override policies
  18 configured from the parant process. Also, users must noted that these interfaces
  19 are not portable to non-Linux, nor non-RISC-V environments, so it is discourage
  20 to use in a portable code. To get the availability of V in an ELF program,
  21 please read :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in the
  22 auxiliary vector.
  23
  24 * prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)
  25
  26     Sets the Vector enablement status of the calling thread, where the control
  27     argument consists of two 2-bit enablement statuses and a bit for inheritance
  28     mode. Other threads of the calling process are unaffected.
  29
  30     Enablement status is a tri-state value each occupying 2-bit of space in
  31     the control argument:
  32
  33     * :c:macro:`PR_RISCV_V_VSTATE_CTRL_DEFAULT`: Use the system-wide default
  34       enablement status on execve(). The system-wide default setting can be
  35       controlled via sysctl interface (see sysctl section below).
  36
  37     * :c:macro:`PR_RISCV_V_VSTATE_CTRL_ON`: Allow Vector to be run for the
  38       thread.
  39
  40     * :c:macro:`PR_RISCV_V_VSTATE_CTRL_OFF`: Disallow Vector. Executing Vector
  41       instructions under such condition will trap and casuse the termination of the thread.
  42
  43     arg: The control argument is a 5-bit value consisting of 3 parts, and
  44     accessed by 3 masks respectively.
  45
  46     The 3 masks, PR_RISCV_V_VSTATE_CTRL_CUR_MASK,
  47     PR_RISCV_V_VSTATE_CTRL_NEXT_MASK, and PR_RISCV_V_VSTATE_CTRL_INHERIT
  48     represents bit[1:0], bit[3:2], and bit[4]. bit[1:0] accounts for the
  49     enablement status of current thread, and the setting at bit[3:2] takes place
  50     at next execve(). bit[4] defines the inheritance mode of the setting in
  51     bit[3:2].
  52
  53         * :c:macro:`PR_RISCV_V_VSTATE_CTRL_CUR_MASK`: bit[1:0]: Account for the
  54           Vector enablement status for the calling thread. The calling thread is
  55           not able to turn off Vector once it has been enabled. The prctl() call
  56           fails with EPERM if the value in this mask is PR_RISCV_V_VSTATE_CTRL_OFF
  57           but the current enablement status is not off. Setting
  58           PR_RISCV_V_VSTATE_CTRL_DEFAULT here takes no effect but to set back
  59           the original enablement status.
  60
  61         * :c:macro:`PR_RISCV_V_VSTATE_CTRL_NEXT_MASK`: bit[3:2]: Account for the
  62           Vector enablement setting for the calling thread at the next execve()
  63           system call. If PR_RISCV_V_VSTATE_CTRL_DEFAULT is used in this mask,
  64           then the enablement status will be decided by the system-wide
  65           enablement status when execve() happen.
  66
  67         * :c:macro:`PR_RISCV_V_VSTATE_CTRL_INHERIT`: bit[4]: the inheritance
  68           mode for the setting at PR_RISCV_V_VSTATE_CTRL_NEXT_MASK. If the bit
  69           is set then the following execve() will not clear the setting in both
  70           PR_RISCV_V_VSTATE_CTRL_NEXT_MASK and PR_RISCV_V_VSTATE_CTRL_INHERIT.
  71           This setting persists across changes in the system-wide default value.
  72
  73     Return value:
  74         * 0 on success;
  75         * EINVAL: Vector not supported, invalid enablement status for current or
  76           next mask;
  77         * EPERM: Turning off Vector in PR_RISCV_V_VSTATE_CTRL_CUR_MASK if Vector
  78           was enabled for the calling thread.
  79
  80     On success:
  81         * A valid setting for PR_RISCV_V_VSTATE_CTRL_CUR_MASK takes place
  82           immediately. The enablement status specified in
  83           PR_RISCV_V_VSTATE_CTRL_NEXT_MASK happens at the next execve() call, or
  84           all following execve() calls if PR_RISCV_V_VSTATE_CTRL_INHERIT bit is
  85           set.
  86         * Every successful call overwrites a previous setting for the calling
  87           thread.
  88
  89 * prctl(PR_RISCV_V_GET_CONTROL)
  90
  91     Gets the same Vector enablement status for the calling thread. Setting for
  92     next execve() call and the inheritance bit are all OR-ed together.
  93
  94     Note that ELF programs are able to get the availability of V for itself by
  95     reading :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in the
  96     auxiliary vector.
  97
  98     Return value:
  99         * a nonnegative value on success;
 100         * EINVAL: Vector not supported.
 101
 102 2.  System runtime configuration (sysctl)
 103 -----------------------------------------
 104
 105 To mitigate the ABI impact of expansion of the signal stack, a
 106 policy mechanism is provided to the administrators, distro maintainers, and
 107 developers to control the default Vector enablement status for userspace
 108 processes in form of sysctl knob:
 109
 110 * /proc/sys/abi/riscv_v_default_allow
 111
 112     Writing the text representation of 0 or 1 to this file sets the default
 113     system enablement status for new starting userspace programs. Valid values
 114     are:
 115
 116     * 0: Do not allow Vector code to be executed as the default for new processes.
 117     * 1: Allow Vector code to be executed as the default for new processes.
 118
 119     Reading this file returns the current system default enablement status.
 120
 121     At every execve() call, a new enablement status of the new process is set to
 122     the system default, unless:
 123
 124       * PR_RISCV_V_VSTATE_CTRL_INHERIT is set for the calling process, and the
 125         setting in PR_RISCV_V_VSTATE_CTRL_NEXT_MASK is not
 126         PR_RISCV_V_VSTATE_CTRL_DEFAULT. Or,
 127
 128       * The setting in PR_RISCV_V_VSTATE_CTRL_NEXT_MASK is not
 129         PR_RISCV_V_VSTATE_CTRL_DEFAULT.
 130
 131     Modifying the system default enablement status does not affect the enablement
 132     status of any existing process of thread that do not make an execve() call.
 133
 134 3.  Vector Register State Across System Calls
 135 ---------------------------------------------
 136
 137 As indicated by version 1.0 of the V extension [1], vector registers are
 138 clobbered by system calls.
 139
 140 1: https://github.com/riscv/riscv-v-spec/blob/master/calling-convention.adoc