1.. SPDX-License-Identifier: GPL-2.0-or-later 2 3========================================== 4DEXCR (Dynamic Execution Control Register) 5========================================== 6 7Overview 8======== 9 10The DEXCR is a privileged special purpose register (SPR) introduced in 11PowerPC ISA 3.1B (Power10) that allows per-cpu control over several dynamic 12execution behaviours. These behaviours include speculation (e.g., indirect 13branch target prediction) and enabling return-oriented programming (ROP) 14protection instructions. 15 16The execution control is exposed in hardware as up to 32 bits ('aspects') in 17the DEXCR. Each aspect controls a certain behaviour, and can be set or cleared 18to enable/disable the aspect. There are several variants of the DEXCR for 19different purposes: 20 21DEXCR 22 A privileged SPR that can control aspects for userspace and kernel space 23HDEXCR 24 A hypervisor-privileged SPR that can control aspects for the hypervisor and 25 enforce aspects for the kernel and userspace. 26UDEXCR 27 An optional ultravisor-privileged SPR that can control aspects for the ultravisor. 28 29Userspace can examine the current DEXCR state using a dedicated SPR that 30provides a non-privileged read-only view of the userspace DEXCR aspects. 31There is also an SPR that provides a read-only view of the hypervisor enforced 32aspects, which ORed with the userspace DEXCR view gives the effective DEXCR 33state for a process. 34 35 36Configuration 37============= 38 39prctl 40----- 41 42A process can control its own userspace DEXCR value using the 43``PR_PPC_GET_DEXCR`` and ``PR_PPC_SET_DEXCR`` pair of 44:manpage:`prctl(2)` commands. These calls have the form:: 45 46 prctl(PR_PPC_GET_DEXCR, unsigned long which, 0, 0, 0); 47 prctl(PR_PPC_SET_DEXCR, unsigned long which, unsigned long ctrl, 0, 0); 48 49The possible 'which' and 'ctrl' values are as follows. Note there is no relation 50between the 'which' value and the DEXCR aspect's index. 51 52.. flat-table:: 53 :header-rows: 1 54 :widths: 2 7 1 55 56 * - ``prctl()`` which 57 - Aspect name 58 - Aspect index 59 60 * - ``PR_PPC_DEXCR_SBHE`` 61 - Speculative Branch Hint Enable (SBHE) 62 - 0 63 64 * - ``PR_PPC_DEXCR_IBRTPD`` 65 - Indirect Branch Recurrent Target Prediction Disable (IBRTPD) 66 - 3 67 68 * - ``PR_PPC_DEXCR_SRAPD`` 69 - Subroutine Return Address Prediction Disable (SRAPD) 70 - 4 71 72 * - ``PR_PPC_DEXCR_NPHIE`` 73 - Non-Privileged Hash Instruction Enable (NPHIE) 74 - 5 75 76.. flat-table:: 77 :header-rows: 1 78 :widths: 2 8 79 80 * - ``prctl()`` ctrl 81 - Meaning 82 83 * - ``PR_PPC_DEXCR_CTRL_EDITABLE`` 84 - This aspect can be configured with PR_PPC_SET_DEXCR (get only) 85 86 * - ``PR_PPC_DEXCR_CTRL_SET`` 87 - This aspect is set / set this aspect 88 89 * - ``PR_PPC_DEXCR_CTRL_CLEAR`` 90 - This aspect is clear / clear this aspect 91 92 * - ``PR_PPC_DEXCR_CTRL_SET_ONEXEC`` 93 - This aspect will be set after exec / set this aspect after exec 94 95 * - ``PR_PPC_DEXCR_CTRL_CLEAR_ONEXEC`` 96 - This aspect will be clear after exec / clear this aspect after exec 97 98Note that 99 100* which is a plain value, not a bitmask. Aspects must be worked with individually. 101 102* ctrl is a bitmask. ``PR_PPC_GET_DEXCR`` returns both the current and onexec 103 configuration. For example, ``PR_PPC_GET_DEXCR`` may return 104 ``PR_PPC_DEXCR_CTRL_EDITABLE | PR_PPC_DEXCR_CTRL_SET | 105 PR_PPC_DEXCR_CTRL_CLEAR_ONEXEC``. This would indicate the aspect is currently 106 set, it will be cleared when you run exec, and you can change this with the 107 ``PR_PPC_SET_DEXCR`` prctl. 108 109* The set/clear terminology refers to setting/clearing the bit in the DEXCR. 110 For example:: 111 112 prctl(PR_PPC_SET_DEXCR, PR_PPC_DEXCR_IBRTPD, PR_PPC_DEXCR_CTRL_SET, 0, 0); 113 114 will set the IBRTPD aspect bit in the DEXCR, causing indirect branch prediction 115 to be disabled. 116 117* The status returned by ``PR_PPC_GET_DEXCR`` represents what value the process 118 would like applied. It does not include any alternative overrides, such as if 119 the hypervisor is enforcing the aspect be set. To see the true DEXCR state 120 software should read the appropriate SPRs directly. 121 122* The aspect state when starting a process is copied from the parent's state on 123 :manpage:`fork(2)`. The state is reset to a fixed value on 124 :manpage:`execve(2)`. The PR_PPC_SET_DEXCR prctl() can control both of these 125 values. 126 127* The ``*_ONEXEC`` controls do not change the current process's DEXCR. 128 129Use ``PR_PPC_SET_DEXCR`` with one of ``PR_PPC_DEXCR_CTRL_SET`` or 130``PR_PPC_DEXCR_CTRL_CLEAR`` to edit a given aspect. 131 132Common error codes for both getting and setting the DEXCR are as follows: 133 134.. flat-table:: 135 :header-rows: 1 136 :widths: 2 8 137 138 * - Error 139 - Meaning 140 141 * - ``EINVAL`` 142 - The DEXCR is not supported by the kernel. 143 144 * - ``ENODEV`` 145 - The aspect is not recognised by the kernel or not supported by the 146 hardware. 147 148``PR_PPC_SET_DEXCR`` may also report the following error codes: 149 150.. flat-table:: 151 :header-rows: 1 152 :widths: 2 8 153 154 * - Error 155 - Meaning 156 157 * - ``EINVAL`` 158 - The ctrl value contains unrecognised flags. 159 160 * - ``EINVAL`` 161 - The ctrl value contains mutually conflicting flags (e.g., 162 ``PR_PPC_DEXCR_CTRL_SET | PR_PPC_DEXCR_CTRL_CLEAR``) 163 164 * - ``EPERM`` 165 - This aspect cannot be modified with prctl() (check for the 166 PR_PPC_DEXCR_CTRL_EDITABLE flag with PR_PPC_GET_DEXCR). 167 168 * - ``EPERM`` 169 - The process does not have sufficient privilege to perform the operation. 170 For example, clearing NPHIE on exec is a privileged operation (a process 171 can still clear its own NPHIE aspect without privileges). 172 173This interface allows a process to control its own DEXCR aspects, and also set 174the initial DEXCR value for any children in its process tree (up to the next 175child to use an ``*_ONEXEC`` control). This allows fine-grained control over the 176default value of the DEXCR, for example allowing containers to run with different 177default values. 178 179 180coredump and ptrace 181=================== 182 183The userspace values of the DEXCR and HDEXCR (in this order) are exposed under 184``NT_PPC_DEXCR``. These are each 64 bits and readonly, and are intended to 185assist with core dumps. The DEXCR may be made writable in future. The top 32 186bits of both registers (corresponding to the non-userspace bits) are masked off. 187 188If the kernel config ``CONFIG_CHECKPOINT_RESTORE`` is enabled, then 189``NT_PPC_HASHKEYR`` is available and exposes the HASHKEYR value of the process 190for reading and writing. This is a tradeoff between increased security and 191checkpoint/restore support: a process should normally have no need to know its 192secret key, but restoring a process requires setting its original key. The key 193therefore appears in core dumps, and an attacker may be able to retrieve it from 194a coredump and effectively bypass ROP protection on any threads that share this 195key (potentially all threads from the same parent that have not run ``exec()``). 196