Merge tag 'bug-for-3.4' of git://git.kernel.org/pub/scm/linux/kernel/git/paulg/linux
[linux-2.6.git] / include / linux / regset.h
1 /*
2  * User-mode machine state access
3  *
4  * Copyright (C) 2007 Red Hat, Inc.  All rights reserved.
5  *
6  * This copyrighted material is made available to anyone wishing to use,
7  * modify, copy, or redistribute it subject to the terms and conditions
8  * of the GNU General Public License v.2.
9  *
10  * Red Hat Author: Roland McGrath.
11  */
12
13 #ifndef _LINUX_REGSET_H
14 #define _LINUX_REGSET_H 1
15
16 #include <linux/compiler.h>
17 #include <linux/types.h>
18 #include <linux/bug.h>
19 #include <linux/uaccess.h>
20 struct task_struct;
21 struct user_regset;
22
23
24 /**
25  * user_regset_active_fn - type of @active function in &struct user_regset
26  * @target:     thread being examined
27  * @regset:     regset being examined
28  *
29  * Return -%ENODEV if not available on the hardware found.
30  * Return %0 if no interesting state in this thread.
31  * Return >%0 number of @size units of interesting state.
32  * Any get call fetching state beyond that number will
33  * see the default initialization state for this data,
34  * so a caller that knows what the default state is need
35  * not copy it all out.
36  * This call is optional; the pointer is %NULL if there
37  * is no inexpensive check to yield a value < @n.
38  */
39 typedef int user_regset_active_fn(struct task_struct *target,
40                                   const struct user_regset *regset);
41
42 /**
43  * user_regset_get_fn - type of @get function in &struct user_regset
44  * @target:     thread being examined
45  * @regset:     regset being examined
46  * @pos:        offset into the regset data to access, in bytes
47  * @count:      amount of data to copy, in bytes
48  * @kbuf:       if not %NULL, a kernel-space pointer to copy into
49  * @ubuf:       if @kbuf is %NULL, a user-space pointer to copy into
50  *
51  * Fetch register values.  Return %0 on success; -%EIO or -%ENODEV
52  * are usual failure returns.  The @pos and @count values are in
53  * bytes, but must be properly aligned.  If @kbuf is non-null, that
54  * buffer is used and @ubuf is ignored.  If @kbuf is %NULL, then
55  * ubuf gives a userland pointer to access directly, and an -%EFAULT
56  * return value is possible.
57  */
58 typedef int user_regset_get_fn(struct task_struct *target,
59                                const struct user_regset *regset,
60                                unsigned int pos, unsigned int count,
61                                void *kbuf, void __user *ubuf);
62
63 /**
64  * user_regset_set_fn - type of @set function in &struct user_regset
65  * @target:     thread being examined
66  * @regset:     regset being examined
67  * @pos:        offset into the regset data to access, in bytes
68  * @count:      amount of data to copy, in bytes
69  * @kbuf:       if not %NULL, a kernel-space pointer to copy from
70  * @ubuf:       if @kbuf is %NULL, a user-space pointer to copy from
71  *
72  * Store register values.  Return %0 on success; -%EIO or -%ENODEV
73  * are usual failure returns.  The @pos and @count values are in
74  * bytes, but must be properly aligned.  If @kbuf is non-null, that
75  * buffer is used and @ubuf is ignored.  If @kbuf is %NULL, then
76  * ubuf gives a userland pointer to access directly, and an -%EFAULT
77  * return value is possible.
78  */
79 typedef int user_regset_set_fn(struct task_struct *target,
80                                const struct user_regset *regset,
81                                unsigned int pos, unsigned int count,
82                                const void *kbuf, const void __user *ubuf);
83
84 /**
85  * user_regset_writeback_fn - type of @writeback function in &struct user_regset
86  * @target:     thread being examined
87  * @regset:     regset being examined
88  * @immediate:  zero if writeback at completion of next context switch is OK
89  *
90  * This call is optional; usually the pointer is %NULL.  When
91  * provided, there is some user memory associated with this regset's
92  * hardware, such as memory backing cached register data on register
93  * window machines; the regset's data controls what user memory is
94  * used (e.g. via the stack pointer value).
95  *
96  * Write register data back to user memory.  If the @immediate flag
97  * is nonzero, it must be written to the user memory so uaccess or
98  * access_process_vm() can see it when this call returns; if zero,
99  * then it must be written back by the time the task completes a
100  * context switch (as synchronized with wait_task_inactive()).
101  * Return %0 on success or if there was nothing to do, -%EFAULT for
102  * a memory problem (bad stack pointer or whatever), or -%EIO for a
103  * hardware problem.
104  */
105 typedef int user_regset_writeback_fn(struct task_struct *target,
106                                      const struct user_regset *regset,
107                                      int immediate);
108
109 /**
110  * struct user_regset - accessible thread CPU state
111  * @n:                  Number of slots (registers).
112  * @size:               Size in bytes of a slot (register).
113  * @align:              Required alignment, in bytes.
114  * @bias:               Bias from natural indexing.
115  * @core_note_type:     ELF note @n_type value used in core dumps.
116  * @get:                Function to fetch values.
117  * @set:                Function to store values.
118  * @active:             Function to report if regset is active, or %NULL.
119  * @writeback:          Function to write data back to user memory, or %NULL.
120  *
121  * This data structure describes a machine resource we call a register set.
122  * This is part of the state of an individual thread, not necessarily
123  * actual CPU registers per se.  A register set consists of a number of
124  * similar slots, given by @n.  Each slot is @size bytes, and aligned to
125  * @align bytes (which is at least @size).
126  *
127  * These functions must be called only on the current thread or on a
128  * thread that is in %TASK_STOPPED or %TASK_TRACED state, that we are
129  * guaranteed will not be woken up and return to user mode, and that we
130  * have called wait_task_inactive() on.  (The target thread always might
131  * wake up for SIGKILL while these functions are working, in which case
132  * that thread's user_regset state might be scrambled.)
133  *
134  * The @pos argument must be aligned according to @align; the @count
135  * argument must be a multiple of @size.  These functions are not
136  * responsible for checking for invalid arguments.
137  *
138  * When there is a natural value to use as an index, @bias gives the
139  * difference between the natural index and the slot index for the
140  * register set.  For example, x86 GDT segment descriptors form a regset;
141  * the segment selector produces a natural index, but only a subset of
142  * that index space is available as a regset (the TLS slots); subtracting
143  * @bias from a segment selector index value computes the regset slot.
144  *
145  * If nonzero, @core_note_type gives the n_type field (NT_* value)
146  * of the core file note in which this regset's data appears.
147  * NT_PRSTATUS is a special case in that the regset data starts at
148  * offsetof(struct elf_prstatus, pr_reg) into the note data; that is
149  * part of the per-machine ELF formats userland knows about.  In
150  * other cases, the core file note contains exactly the whole regset
151  * (@n * @size) and nothing else.  The core file note is normally
152  * omitted when there is an @active function and it returns zero.
153  */
154 struct user_regset {
155         user_regset_get_fn              *get;
156         user_regset_set_fn              *set;
157         user_regset_active_fn           *active;
158         user_regset_writeback_fn        *writeback;
159         unsigned int                    n;
160         unsigned int                    size;
161         unsigned int                    align;
162         unsigned int                    bias;
163         unsigned int                    core_note_type;
164 };
165
166 /**
167  * struct user_regset_view - available regsets
168  * @name:       Identifier, e.g. UTS_MACHINE string.
169  * @regsets:    Array of @n regsets available in this view.
170  * @n:          Number of elements in @regsets.
171  * @e_machine:  ELF header @e_machine %EM_* value written in core dumps.
172  * @e_flags:    ELF header @e_flags value written in core dumps.
173  * @ei_osabi:   ELF header @e_ident[%EI_OSABI] value written in core dumps.
174  *
175  * A regset view is a collection of regsets (&struct user_regset,
176  * above).  This describes all the state of a thread that can be seen
177  * from a given architecture/ABI environment.  More than one view might
178  * refer to the same &struct user_regset, or more than one regset
179  * might refer to the same machine-specific state in the thread.  For
180  * example, a 32-bit thread's state could be examined from the 32-bit
181  * view or from the 64-bit view.  Either method reaches the same thread
182  * register state, doing appropriate widening or truncation.
183  */
184 struct user_regset_view {
185         const char *name;
186         const struct user_regset *regsets;
187         unsigned int n;
188         u32 e_flags;
189         u16 e_machine;
190         u8 ei_osabi;
191 };
192
193 /*
194  * This is documented here rather than at the definition sites because its
195  * implementation is machine-dependent but its interface is universal.
196  */
197 /**
198  * task_user_regset_view - Return the process's native regset view.
199  * @tsk: a thread of the process in question
200  *
201  * Return the &struct user_regset_view that is native for the given process.
202  * For example, what it would access when it called ptrace().
203  * Throughout the life of the process, this only changes at exec.
204  */
205 const struct user_regset_view *task_user_regset_view(struct task_struct *tsk);
206
207
208 /*
209  * These are helpers for writing regset get/set functions in arch code.
210  * Because @start_pos and @end_pos are always compile-time constants,
211  * these are inlined into very little code though they look large.
212  *
213  * Use one or more calls sequentially for each chunk of regset data stored
214  * contiguously in memory.  Call with constants for @start_pos and @end_pos,
215  * giving the range of byte positions in the regset that data corresponds
216  * to; @end_pos can be -1 if this chunk is at the end of the regset layout.
217  * Each call updates the arguments to point past its chunk.
218  */
219
220 static inline int user_regset_copyout(unsigned int *pos, unsigned int *count,
221                                       void **kbuf,
222                                       void __user **ubuf, const void *data,
223                                       const int start_pos, const int end_pos)
224 {
225         if (*count == 0)
226                 return 0;
227         BUG_ON(*pos < start_pos);
228         if (end_pos < 0 || *pos < end_pos) {
229                 unsigned int copy = (end_pos < 0 ? *count
230                                      : min(*count, end_pos - *pos));
231                 data += *pos - start_pos;
232                 if (*kbuf) {
233                         memcpy(*kbuf, data, copy);
234                         *kbuf += copy;
235                 } else if (__copy_to_user(*ubuf, data, copy))
236                         return -EFAULT;
237                 else
238                         *ubuf += copy;
239                 *pos += copy;
240                 *count -= copy;
241         }
242         return 0;
243 }
244
245 static inline int user_regset_copyin(unsigned int *pos, unsigned int *count,
246                                      const void **kbuf,
247                                      const void __user **ubuf, void *data,
248                                      const int start_pos, const int end_pos)
249 {
250         if (*count == 0)
251                 return 0;
252         BUG_ON(*pos < start_pos);
253         if (end_pos < 0 || *pos < end_pos) {
254                 unsigned int copy = (end_pos < 0 ? *count
255                                      : min(*count, end_pos - *pos));
256                 data += *pos - start_pos;
257                 if (*kbuf) {
258                         memcpy(data, *kbuf, copy);
259                         *kbuf += copy;
260                 } else if (__copy_from_user(data, *ubuf, copy))
261                         return -EFAULT;
262                 else
263                         *ubuf += copy;
264                 *pos += copy;
265                 *count -= copy;
266         }
267         return 0;
268 }
269
270 /*
271  * These two parallel the two above, but for portions of a regset layout
272  * that always read as all-zero or for which writes are ignored.
273  */
274 static inline int user_regset_copyout_zero(unsigned int *pos,
275                                            unsigned int *count,
276                                            void **kbuf, void __user **ubuf,
277                                            const int start_pos,
278                                            const int end_pos)
279 {
280         if (*count == 0)
281                 return 0;
282         BUG_ON(*pos < start_pos);
283         if (end_pos < 0 || *pos < end_pos) {
284                 unsigned int copy = (end_pos < 0 ? *count
285                                      : min(*count, end_pos - *pos));
286                 if (*kbuf) {
287                         memset(*kbuf, 0, copy);
288                         *kbuf += copy;
289                 } else if (__clear_user(*ubuf, copy))
290                         return -EFAULT;
291                 else
292                         *ubuf += copy;
293                 *pos += copy;
294                 *count -= copy;
295         }
296         return 0;
297 }
298
299 static inline int user_regset_copyin_ignore(unsigned int *pos,
300                                             unsigned int *count,
301                                             const void **kbuf,
302                                             const void __user **ubuf,
303                                             const int start_pos,
304                                             const int end_pos)
305 {
306         if (*count == 0)
307                 return 0;
308         BUG_ON(*pos < start_pos);
309         if (end_pos < 0 || *pos < end_pos) {
310                 unsigned int copy = (end_pos < 0 ? *count
311                                      : min(*count, end_pos - *pos));
312                 if (*kbuf)
313                         *kbuf += copy;
314                 else
315                         *ubuf += copy;
316                 *pos += copy;
317                 *count -= copy;
318         }
319         return 0;
320 }
321
322 /**
323  * copy_regset_to_user - fetch a thread's user_regset data into user memory
324  * @target:     thread to be examined
325  * @view:       &struct user_regset_view describing user thread machine state
326  * @setno:      index in @view->regsets
327  * @offset:     offset into the regset data, in bytes
328  * @size:       amount of data to copy, in bytes
329  * @data:       user-mode pointer to copy into
330  */
331 static inline int copy_regset_to_user(struct task_struct *target,
332                                       const struct user_regset_view *view,
333                                       unsigned int setno,
334                                       unsigned int offset, unsigned int size,
335                                       void __user *data)
336 {
337         const struct user_regset *regset = &view->regsets[setno];
338
339         if (!regset->get)
340                 return -EOPNOTSUPP;
341
342         if (!access_ok(VERIFY_WRITE, data, size))
343                 return -EFAULT;
344
345         return regset->get(target, regset, offset, size, NULL, data);
346 }
347
348 /**
349  * copy_regset_from_user - store into thread's user_regset data from user memory
350  * @target:     thread to be examined
351  * @view:       &struct user_regset_view describing user thread machine state
352  * @setno:      index in @view->regsets
353  * @offset:     offset into the regset data, in bytes
354  * @size:       amount of data to copy, in bytes
355  * @data:       user-mode pointer to copy from
356  */
357 static inline int copy_regset_from_user(struct task_struct *target,
358                                         const struct user_regset_view *view,
359                                         unsigned int setno,
360                                         unsigned int offset, unsigned int size,
361                                         const void __user *data)
362 {
363         const struct user_regset *regset = &view->regsets[setno];
364
365         if (!regset->set)
366                 return -EOPNOTSUPP;
367
368         if (!access_ok(VERIFY_READ, data, size))
369                 return -EFAULT;
370
371         return regset->set(target, regset, offset, size, NULL, data);
372 }
373
374
375 #endif  /* <linux/regset.h> */