1 /* SPDX-License-Identifier: GPL-2.0-only */
3 * User-mode machine state access
5 * Copyright (C) 2007 Red Hat, Inc. All rights reserved.
7 * Red Hat Author: Roland McGrath.
10 #ifndef _LINUX_REGSET_H
11 #define _LINUX_REGSET_H 1
13 #include <linux/compiler.h>
14 #include <linux/types.h>
15 #include <linux/bug.h>
16 #include <linux/uaccess.h>
25 static inline int membuf_zero(struct membuf *s, size_t size)
30 memset(s->p, 0, size);
37 static inline int membuf_write(struct membuf *s, const void *v, size_t size)
42 memcpy(s->p, v, size);
49 /* current s->p must be aligned for v; v must be a scalar */
50 #define membuf_store(s, v) \
52 struct membuf *__s = (s); \
54 typeof(v) __v = (v); \
55 size_t __size = sizeof(__v); \
56 if (unlikely(__size > __s->left)) { \
58 memcpy(__s->p, &__v, __size); \
60 *(typeof(__v + 0) *)__s->p = __v; \
63 __s->left -= __size; \
68 * user_regset_active_fn - type of @active function in &struct user_regset
69 * @target: thread being examined
70 * @regset: regset being examined
72 * Return -%ENODEV if not available on the hardware found.
73 * Return %0 if no interesting state in this thread.
74 * Return >%0 number of @size units of interesting state.
75 * Any get call fetching state beyond that number will
76 * see the default initialization state for this data,
77 * so a caller that knows what the default state is need
78 * not copy it all out.
79 * This call is optional; the pointer is %NULL if there
80 * is no inexpensive check to yield a value < @n.
82 typedef int user_regset_active_fn(struct task_struct *target,
83 const struct user_regset *regset);
85 typedef int user_regset_get2_fn(struct task_struct *target,
86 const struct user_regset *regset,
90 * user_regset_set_fn - type of @set function in &struct user_regset
91 * @target: thread being examined
92 * @regset: regset being examined
93 * @pos: offset into the regset data to access, in bytes
94 * @count: amount of data to copy, in bytes
95 * @kbuf: if not %NULL, a kernel-space pointer to copy from
96 * @ubuf: if @kbuf is %NULL, a user-space pointer to copy from
98 * Store register values. Return %0 on success; -%EIO or -%ENODEV
99 * are usual failure returns. The @pos and @count values are in
100 * bytes, but must be properly aligned. If @kbuf is non-null, that
101 * buffer is used and @ubuf is ignored. If @kbuf is %NULL, then
102 * ubuf gives a userland pointer to access directly, and an -%EFAULT
103 * return value is possible.
105 typedef int user_regset_set_fn(struct task_struct *target,
106 const struct user_regset *regset,
107 unsigned int pos, unsigned int count,
108 const void *kbuf, const void __user *ubuf);
111 * user_regset_writeback_fn - type of @writeback function in &struct user_regset
112 * @target: thread being examined
113 * @regset: regset being examined
114 * @immediate: zero if writeback at completion of next context switch is OK
116 * This call is optional; usually the pointer is %NULL. When
117 * provided, there is some user memory associated with this regset's
118 * hardware, such as memory backing cached register data on register
119 * window machines; the regset's data controls what user memory is
120 * used (e.g. via the stack pointer value).
122 * Write register data back to user memory. If the @immediate flag
123 * is nonzero, it must be written to the user memory so uaccess or
124 * access_process_vm() can see it when this call returns; if zero,
125 * then it must be written back by the time the task completes a
126 * context switch (as synchronized with wait_task_inactive()).
127 * Return %0 on success or if there was nothing to do, -%EFAULT for
128 * a memory problem (bad stack pointer or whatever), or -%EIO for a
131 typedef int user_regset_writeback_fn(struct task_struct *target,
132 const struct user_regset *regset,
136 * user_regset_get_size_fn - type of @get_size function in &struct user_regset
137 * @target: thread being examined
138 * @regset: regset being examined
140 * This call is optional; usually the pointer is %NULL.
142 * When provided, this function must return the current size of regset
143 * data, as observed by the @get function in &struct user_regset. The
144 * value returned must be a multiple of @size. The returned size is
145 * required to be valid only until the next time (if any) @regset is
146 * modified for @target.
148 * This function is intended for dynamically sized regsets. A regset
149 * that is statically sized does not need to implement it.
151 * This function should not be called directly: instead, callers should
152 * call regset_size() to determine the current size of a regset.
154 typedef unsigned int user_regset_get_size_fn(struct task_struct *target,
155 const struct user_regset *regset);
158 * struct user_regset - accessible thread CPU state
159 * @n: Number of slots (registers).
160 * @size: Size in bytes of a slot (register).
161 * @align: Required alignment, in bytes.
162 * @bias: Bias from natural indexing.
163 * @core_note_type: ELF note @n_type value used in core dumps.
164 * @get: Function to fetch values.
165 * @set: Function to store values.
166 * @active: Function to report if regset is active, or %NULL.
167 * @writeback: Function to write data back to user memory, or %NULL.
168 * @get_size: Function to return the regset's size, or %NULL.
170 * This data structure describes a machine resource we call a register set.
171 * This is part of the state of an individual thread, not necessarily
172 * actual CPU registers per se. A register set consists of a number of
173 * similar slots, given by @n. Each slot is @size bytes, and aligned to
174 * @align bytes (which is at least @size). For dynamically-sized
175 * regsets, @n must contain the maximum possible number of slots for the
176 * regset, and @get_size must point to a function that returns the
177 * current regset size.
179 * Callers that need to know only the current size of the regset and do
180 * not care about its internal structure should call regset_size()
181 * instead of inspecting @n or calling @get_size.
183 * For backward compatibility, the @get and @set methods must pad to, or
184 * accept, @n * @size bytes, even if the current regset size is smaller.
185 * The precise semantics of these operations depend on the regset being
188 * The functions to which &struct user_regset members point must be
189 * called only on the current thread or on a thread that is in
190 * %TASK_STOPPED or %TASK_TRACED state, that we are guaranteed will not
191 * be woken up and return to user mode, and that we have called
192 * wait_task_inactive() on. (The target thread always might wake up for
193 * SIGKILL while these functions are working, in which case that
194 * thread's user_regset state might be scrambled.)
196 * The @pos argument must be aligned according to @align; the @count
197 * argument must be a multiple of @size. These functions are not
198 * responsible for checking for invalid arguments.
200 * When there is a natural value to use as an index, @bias gives the
201 * difference between the natural index and the slot index for the
202 * register set. For example, x86 GDT segment descriptors form a regset;
203 * the segment selector produces a natural index, but only a subset of
204 * that index space is available as a regset (the TLS slots); subtracting
205 * @bias from a segment selector index value computes the regset slot.
207 * If nonzero, @core_note_type gives the n_type field (NT_* value)
208 * of the core file note in which this regset's data appears.
209 * NT_PRSTATUS is a special case in that the regset data starts at
210 * offsetof(struct elf_prstatus, pr_reg) into the note data; that is
211 * part of the per-machine ELF formats userland knows about. In
212 * other cases, the core file note contains exactly the whole regset
213 * (@n * @size) and nothing else. The core file note is normally
214 * omitted when there is an @active function and it returns zero.
217 user_regset_get2_fn *regset_get;
218 user_regset_set_fn *set;
219 user_regset_active_fn *active;
220 user_regset_writeback_fn *writeback;
221 user_regset_get_size_fn *get_size;
226 unsigned int core_note_type;
230 * struct user_regset_view - available regsets
231 * @name: Identifier, e.g. UTS_MACHINE string.
232 * @regsets: Array of @n regsets available in this view.
233 * @n: Number of elements in @regsets.
234 * @e_machine: ELF header @e_machine %EM_* value written in core dumps.
235 * @e_flags: ELF header @e_flags value written in core dumps.
236 * @ei_osabi: ELF header @e_ident[%EI_OSABI] value written in core dumps.
238 * A regset view is a collection of regsets (&struct user_regset,
239 * above). This describes all the state of a thread that can be seen
240 * from a given architecture/ABI environment. More than one view might
241 * refer to the same &struct user_regset, or more than one regset
242 * might refer to the same machine-specific state in the thread. For
243 * example, a 32-bit thread's state could be examined from the 32-bit
244 * view or from the 64-bit view. Either method reaches the same thread
245 * register state, doing appropriate widening or truncation.
247 struct user_regset_view {
249 const struct user_regset *regsets;
257 * This is documented here rather than at the definition sites because its
258 * implementation is machine-dependent but its interface is universal.
261 * task_user_regset_view - Return the process's native regset view.
262 * @tsk: a thread of the process in question
264 * Return the &struct user_regset_view that is native for the given process.
265 * For example, what it would access when it called ptrace().
266 * Throughout the life of the process, this only changes at exec.
268 const struct user_regset_view *task_user_regset_view(struct task_struct *tsk);
272 * These are helpers for writing regset get/set functions in arch code.
273 * Because @start_pos and @end_pos are always compile-time constants,
274 * these are inlined into very little code though they look large.
276 * Use one or more calls sequentially for each chunk of regset data stored
277 * contiguously in memory. Call with constants for @start_pos and @end_pos,
278 * giving the range of byte positions in the regset that data corresponds
279 * to; @end_pos can be -1 if this chunk is at the end of the regset layout.
280 * Each call updates the arguments to point past its chunk.
283 static inline int user_regset_copyout(unsigned int *pos, unsigned int *count,
285 void __user **ubuf, const void *data,
286 const int start_pos, const int end_pos)
290 BUG_ON(*pos < start_pos);
291 if (end_pos < 0 || *pos < end_pos) {
292 unsigned int copy = (end_pos < 0 ? *count
293 : min(*count, end_pos - *pos));
294 data += *pos - start_pos;
296 memcpy(*kbuf, data, copy);
298 } else if (__copy_to_user(*ubuf, data, copy))
308 static inline int user_regset_copyin(unsigned int *pos, unsigned int *count,
310 const void __user **ubuf, void *data,
311 const int start_pos, const int end_pos)
315 BUG_ON(*pos < start_pos);
316 if (end_pos < 0 || *pos < end_pos) {
317 unsigned int copy = (end_pos < 0 ? *count
318 : min(*count, end_pos - *pos));
319 data += *pos - start_pos;
321 memcpy(data, *kbuf, copy);
323 } else if (__copy_from_user(data, *ubuf, copy))
334 * These two parallel the two above, but for portions of a regset layout
335 * that always read as all-zero or for which writes are ignored.
337 static inline int user_regset_copyout_zero(unsigned int *pos,
339 void **kbuf, void __user **ubuf,
345 BUG_ON(*pos < start_pos);
346 if (end_pos < 0 || *pos < end_pos) {
347 unsigned int copy = (end_pos < 0 ? *count
348 : min(*count, end_pos - *pos));
350 memset(*kbuf, 0, copy);
352 } else if (clear_user(*ubuf, copy))
362 static inline int user_regset_copyin_ignore(unsigned int *pos,
365 const void __user **ubuf,
371 BUG_ON(*pos < start_pos);
372 if (end_pos < 0 || *pos < end_pos) {
373 unsigned int copy = (end_pos < 0 ? *count
374 : min(*count, end_pos - *pos));
385 extern int regset_get(struct task_struct *target,
386 const struct user_regset *regset,
387 unsigned int size, void *data);
389 extern int regset_get_alloc(struct task_struct *target,
390 const struct user_regset *regset,
394 extern int copy_regset_to_user(struct task_struct *target,
395 const struct user_regset_view *view,
396 unsigned int setno, unsigned int offset,
397 unsigned int size, void __user *data);
400 * copy_regset_from_user - store into thread's user_regset data from user memory
401 * @target: thread to be examined
402 * @view: &struct user_regset_view describing user thread machine state
403 * @setno: index in @view->regsets
404 * @offset: offset into the regset data, in bytes
405 * @size: amount of data to copy, in bytes
406 * @data: user-mode pointer to copy from
408 static inline int copy_regset_from_user(struct task_struct *target,
409 const struct user_regset_view *view,
411 unsigned int offset, unsigned int size,
412 const void __user *data)
414 const struct user_regset *regset = &view->regsets[setno];
419 if (!access_ok(data, size))
422 return regset->set(target, regset, offset, size, NULL, data);
426 * regset_size - determine the current size of a regset
427 * @target: thread to be examined
428 * @regset: regset to be examined
430 * Note that the returned size is valid only until the next time
431 * (if any) @regset is modified for @target.
433 static inline unsigned int regset_size(struct task_struct *target,
434 const struct user_regset *regset)
436 if (!regset->get_size)
437 return regset->n * regset->size;
439 return regset->get_size(target, regset);
442 #endif /* <linux/regset.h> */