@@ -36,8 +36,145 @@ state for a process.
3636Configuration
3737=============
3838
39- The DEXCR is currently unconfigurable. All threads are run with the
40- NPHIE aspect enabled.
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.
41178
42179
43180coredump and ptrace
0 commit comments