1 .. SPDX-License-Identifier: GPL-2.0-or-later
2
3 ==========================================
4 DEXCR (Dynamic Execution Control Register)
5 ==========================================
6
7 Overview
8 ========
9
10 The DEXCR is a privileged special purpose register (SPR) introduced in
11 PowerPC ISA 3.1B (Power10) that allows per-cpu control over several dynamic
12 execution behaviours. These behaviours include speculation (e.g., indirect
13 branch target prediction) and enabling return-oriented programming (ROP)
14 protection instructions.
15
16 The execution control is exposed in hardware as up to 32 bits ('aspects') in
17 the DEXCR. Each aspect controls a certain behaviour, and can be set or cleared
18 to enable/disable the aspect. There are several variants of the DEXCR for
19 different purposes:
20
21 DEXCR
22 A privileged SPR that can control aspects for userspace and kernel space
23 HDEXCR
24 A hypervisor-privileged SPR that can control aspects for the hypervisor and
25 enforce aspects for the kernel and userspace.
26 UDEXCR
27 An optional ultravisor-privileged SPR that can control aspects for the ultravisor.
28
29 Userspace can examine the current DEXCR state using a dedicated SPR that
30 provides a non-privileged read-only view of the userspace DEXCR aspects.
31 There is also an SPR that provides a read-only view of the hypervisor enforced
32 aspects, which ORed with the userspace DEXCR view gives the effective DEXCR
33 state for a process.
34
35
36 Configuration
37 =============
38
39 prctl
40 -----
41
42 A 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
49 The possible 'which' and 'ctrl' values are as follows. Note there is no relation
50 between 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
98 Note 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
129 Use ``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
132 Common 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
173 This interface allows a process to control its own DEXCR aspects, and also set
174 the initial DEXCR value for any children in its process tree (up to the next
175 child to use an ``*_ONEXEC`` control). This allows fine-grained control over the
176 default value of the DEXCR, for example allowing containers to run with different
177 default values.
178
179
180 coredump and ptrace
181 ===================
182
183 The 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
185 assist with core dumps. The DEXCR may be made writable in future. The top 32
186 bits of both registers (corresponding to the non-userspace bits) are masked off.
187
188 If the kernel config ``CONFIG_CHECKPOINT_RESTORE`` is enabled, then
189 ``NT_PPC_HASHKEYR`` is available and exposes the HASHKEYR value of the process
190 for reading and writing. This is a tradeoff between increased security and
191 checkpoint/restore support: a process should normally have no need to know its
192 secret key, but restoring a process requires setting its original key. The key
193 therefore appears in core dumps, and an attacker may be able to retrieve it from
194 a coredump and effectively bypass ROP protection on any threads that share this
195 key (potentially all threads from the same parent that have not run ``exec()``).
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.