4 * Copyright (C) 2006, 2007 Red Hat, Inc. All rights reserved.
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.
10 * Red Hat Author: Roland McGrath.
12 * This file defines hook entry points called by core code where
13 * user tracing/debugging support might need to do something.
14 * These entry points are called tracehook_*. Each hook declared below
15 * has a detailed comment giving the context (locking et al) from
16 * which it is called, and the meaning of its return value (if any).
18 * We also declare here tracehook_* functions providing access to low-level
19 * interrogation and control of threads. These functions must be called
20 * on either the current thread or on a quiescent thread. We say a
21 * thread is "quiescent" if it is in TASK_STOPPED or TASK_TRACED state,
22 * we are guaranteed it will not be woken up and return to user mode, and
23 * we have called wait_task_inactive on it.
26 #ifndef _LINUX_TRACEHOOK_H
27 #define _LINUX_TRACEHOOK_H 1
29 #include <linux/sched.h>
30 #include <linux/uaccess.h>
31 #include <linux/utrace.h>
37 * The machine-specific asm/tracehook.h file is responsible for declaring
38 * the following entry points. These can be called only on a quiescent thread,
39 * or the current thread when it is about to return to user mode.
41 * Single-step control. When enabled, the next instruction or syscall exit
42 * produces a SIGTRAP. Enabling or disabling redundantly is harmless.
44 * void tracehook_enable_single_step(struct task_struct *tsk);
45 * void tracehook_disable_single_step(struct task_struct *tsk);
46 * int tracehook_single_step_enabled(struct task_struct *tsk);
48 * If those calls are defined, #define ARCH_HAS_SINGLE_STEP to nonzero.
49 * Do not #define it if these calls are never available in this kernel config.
50 * If defined, the value of ARCH_HAS_SINGLE_STEP can be constant or variable.
51 * It should evaluate to nonzero if the hardware is able to support
52 * tracehook_enable_single_step. If it's a variable expression, it
53 * should be one that can be evaluated in modules, i.e. uses exported symbols.
55 * Block-step control (trap on control transfer), when available.
56 * tracehook_disable_block_step will be called after tracehook_enable_single_step.
57 * When enabled, the next jump, or other control transfer or syscall exit,
58 * produces a SIGTRAP. Enabling or disabling redundantly is harmless.
60 * void tracehook_enable_block_step(struct task_struct *tsk);
61 * void tracehook_disable_block_step(struct task_struct *tsk);
62 * int tracehook_block_step_enabled(struct task_struct *tsk);
64 * If those calls are defined, #define ARCH_HAS_BLOCK_STEP to nonzero.
65 * Do not #define it if these calls are never available in this kernel config.
66 * If defined, the value of ARCH_HAS_BLOCK_STEP can be constant or variable.
67 * It should evaluate to nonzero if the hardware is able to support
68 * tracehook_enable_block_step. If it's a variable expression, it
69 * should be one that can be evaluated in modules, i.e. uses exported symbols.
71 * Control system call tracing. When enabled a syscall entry or exit
72 * produces a call to tracehook_report_syscall, below.
74 * void tracehook_enable_syscall_trace(struct task_struct *tsk);
75 * void tracehook_disable_syscall_trace(struct task_struct *tsk);
77 * When stopped in tracehook_report_syscall for syscall entry,
78 * abort the syscall so no kernel function is called.
79 * If the register state was not otherwise updated before,
80 * this produces an -ENOSYS error return as for an invalid syscall number.
82 * void tracehook_abort_syscall(struct pt_regs *regs);
84 * Return the regset view (see below) that is native for the given process.
85 * For example, what it would access when it called ptrace.
86 * Throughout the life of the process, this only changes at exec.
88 * const struct utrace_regset_view *utrace_native_view(struct task_struct *);
94 * This data structure describes a machine resource we call a register set.
95 * This is part of the state of an individual thread, not necessarily
96 * actual CPU registers per se. A register set consists of a number of
97 * similar slots, given by ->n. Each slot is ->size bytes, and aligned to
98 * ->align bytes (which is at least ->size).
100 * As described above, these entry points can be called on the current
101 * thread or on a quiescent thread. The pos argument must be aligned
102 * according to ->align; the count argument must be a multiple of ->size.
103 * These functions are not responsible for checking for invalid arguments.
105 * When there is a natural value to use as an index, ->bias gives the
106 * difference between the natural index and the slot index for the
107 * register set. For example, x86 GDT segment descriptors form a regset;
108 * the segment selector produces a natural index, but only a subset of
109 * that index space is available as a regset (the TLS slots); subtracting
110 * ->bias from a segment selector index value computes the regset slot.
112 struct utrace_regset {
113 unsigned int n; /* Number of slots (registers). */
114 unsigned int size; /* Size in bytes of a slot (register). */
115 unsigned int align; /* Required alignment, in bytes. */
116 unsigned int bias; /* Bias from natural indexing. */
119 * Return -ENODEV if not available on the hardware found.
120 * Return 0 if no interesting state in this thread.
121 * Return >0 number of ->size units of interesting state.
122 * Any get call fetching state beyond that number will
123 * see the default initialization state for this data,
124 * so a caller that knows that the default state is need
125 * not copy it all out.
126 * This call is optional; the pointer is NULL if there
127 * so no inexpensive check to yield a value < .n.
129 int (*active)(struct task_struct *, const struct utrace_regset *);
132 * Fetch and store register values. Return 0 on success; -EIO or
133 * -ENODEV are usual failure returns. The pos and count values are
134 * in bytes, but must be properly aligned. If kbuf is non-null,
135 * that buffer is used and ubuf is ignored. If kbuf is NULL, then
136 * ubuf gives a userland pointer to access directly, and an -EFAULT
137 * return value is possible.
139 int (*get)(struct task_struct *, const struct utrace_regset *,
140 unsigned int pos, unsigned int count,
141 void *kbuf, void __user *ubuf);
142 int (*set)(struct task_struct *, const struct utrace_regset *,
143 unsigned int pos, unsigned int count,
144 const void *kbuf, const void __user *ubuf);
147 * This call is optional; usually the pointer is NULL.
148 * When provided, there is some user memory associated
149 * with this regset's hardware, such as memory backing
150 * cached register data on register window machines; the
151 * regset's data controls what user memory is used
152 * (e.g. via the stack pointer value).
154 * Write register data back to user memory. If the
155 * immediate flag is nonzero, it must be written to the
156 * user memory so uaccess/access_process_vm can see it
157 * when this call returns; if zero, then it must be
158 * written back by the time the task completes a context
159 * switch (as synchronized with wait_task_inactive).
160 * Return 0 on success or if there was nothing to do,
161 * -EFAULT for a memory problem (bad stack pointer or
162 * whatever), or -EIO for a hardware problem.
164 int (*writeback)(struct task_struct *, const struct utrace_regset *,
169 * A regset view is a collection of regsets (struct utrace_regset, above).
170 * This describes all the state of a thread that can be seen from a given
171 * architecture/ABI environment. More than one view might refer to the
172 * same utrace_regset, or more than one regset might refer to the same
173 * machine-specific state in the thread. For example, a 32-bit thread's
174 * state could be examined from the 32-bit view or from the 64-bit view.
175 * Either method reaches the same thread register state, doing appropriate
176 * widening or truncation.
178 struct utrace_regset_view {
179 const char *name; /* Identifier, e.g. ELF_PLATFORM string. */
181 const struct utrace_regset *regsets;
185 * EM_* value for which this is the native view, if any.
192 * These two are helpers for writing regset get/set functions in arch code.
193 * Use one or more calls sequentially for each chunk of regset data stored
194 * contiguously in memory. Call with constants for start_pos and end_pos,
195 * giving the range of byte positions in the regset that data corresponds
196 * to; end_pos can be -1 if this chunk is at the end of the regset layout.
197 * Each call updates the arguments to point past its chunk.
201 utrace_regset_copyout(unsigned int *pos, unsigned int *count,
202 void **kbuf, void __user **ubuf,
203 const void *data, int start_pos, int end_pos)
207 BUG_ON(*pos < start_pos);
208 if (end_pos < 0 || *pos < end_pos) {
209 unsigned int copy = (end_pos < 0 ? *count
210 : min(*count, end_pos - *pos));
211 data += *pos - start_pos;
213 memcpy(*kbuf, data, copy);
216 else if (copy_to_user(*ubuf, data, copy))
227 utrace_regset_copyin(unsigned int *pos, unsigned int *count,
228 const void **kbuf, const void __user **ubuf,
229 void *data, int start_pos, int end_pos)
233 BUG_ON(*pos < start_pos);
234 if (end_pos < 0 || *pos < end_pos) {
235 unsigned int copy = (end_pos < 0 ? *count
236 : min(*count, end_pos - *pos));
237 data += *pos - start_pos;
239 memcpy(data, *kbuf, copy);
242 else if (copy_from_user(data, *ubuf, copy))
253 * These two parallel the two above, but for portions of a regset layout
254 * that always read as all-zero or for which writes are ignored.
257 utrace_regset_copyout_zero(unsigned int *pos, unsigned int *count,
258 void **kbuf, void __user **ubuf,
259 int start_pos, int end_pos)
263 BUG_ON(*pos < start_pos);
264 if (end_pos < 0 || *pos < end_pos) {
265 unsigned int copy = (end_pos < 0 ? *count
266 : min(*count, end_pos - *pos));
268 memset(*kbuf, 0, copy);
271 else if (clear_user(*ubuf, copy))
282 utrace_regset_copyin_ignore(unsigned int *pos, unsigned int *count,
283 const void **kbuf, const void __user **ubuf,
284 int start_pos, int end_pos)
288 BUG_ON(*pos < start_pos);
289 if (end_pos < 0 || *pos < end_pos) {
290 unsigned int copy = (end_pos < 0 ? *count
291 : min(*count, end_pos - *pos));
307 *** Following are entry points from core code, where the user debugging
308 *** support can affect the normal behavior. The locking situation is
309 *** described for each call.
315 * Called in copy_process when setting up the copied task_struct,
316 * with tasklist_lock held for writing.
318 static inline void tracehook_init_task(struct task_struct *child)
320 utrace_init_task(child);
324 * Called from release_task, no locks held.
325 * After this, there should be no tracing entanglements.
327 static inline void tracehook_release_task(struct task_struct *p)
330 if (tsk_utrace_struct(p) != NULL)
331 utrace_release_task(p);
335 * Return nonzero to trigger a BUG_ON crash in release_task.
336 * This should verify that there is no tracing-related state
337 * still affecting the task_struct about to be released.
338 * Called with tasklist_lock held for writing.
340 static inline int tracehook_check_released(struct task_struct *p)
342 return unlikely(tsk_utrace_struct(p) != NULL);
346 * do_notify_parent_cldstop calls this when it's about to generate a SIGCHLD
347 * for a job control stop. Return nonzero to prevent that signal generation.
348 * Called with tasklist_lock held for reading, sometimes with irqs disabled.
350 static inline int tracehook_notify_cldstop(struct task_struct *tsk,
351 const siginfo_t *info)
353 return (tsk_utrace_flags(tsk) & UTRACE_ACTION_NOREAP);
357 * exit_notify calls this with tasklist_lock held for writing.
358 * Return nonzero to prevent any normal SIGCHLD generation for this
359 * thread's death (i.e. when it is not ignored and its thread group is
360 * empty). This call must set *noreap to 0, or to 1 to force this thread
361 * to become a zombie when it would normally reap itself.
362 * The *death_cookie is passed to tracehook_report_death (below).
364 static inline int tracehook_notify_death(struct task_struct *tsk,
365 int *noreap, void **death_cookie)
367 *death_cookie = tsk_utrace_struct(tsk);
368 if (tsk_utrace_flags(tsk) & UTRACE_ACTION_NOREAP) {
377 * Return zero iff tracing doesn't care to examine this fatal signal,
378 * so it can short-circuit normal delivery directly to a group exit.
379 * Called with tsk->sighand->siglock held.
381 static inline int tracehook_consider_fatal_signal(struct task_struct *tsk,
384 return (tsk_utrace_flags(tsk) & (UTRACE_EVENT(SIGNAL_TERM)
385 | UTRACE_EVENT(SIGNAL_CORE)));
389 * Return zero iff tracing doesn't care to examine this ignored signal,
390 * so it can short-circuit normal delivery and never even get queued.
391 * Either the handler is SIG_DFL and sig's default is ignore, or it's SIG_IGN.
392 * Called with tsk->sighand->siglock held.
394 static inline int tracehook_consider_ignored_signal(struct task_struct *tsk,
395 int sig, void *handler)
397 return (tsk_utrace_flags(tsk) & UTRACE_EVENT(SIGNAL_IGN));
402 * Called with the siglock held when computing tsk's signal_pending flag.
403 * Return nonzero to force the signal_pending flag on, so that
404 * tracehook_induce_signal will be called before the next return to user mode.
406 static inline int tracehook_induce_sigpending(struct task_struct *tsk)
408 return unlikely(tsk_utrace_flags(tsk) & UTRACE_ACTION_QUIESCE);
412 * Called with the siglock held before dequeuing pending signals.
413 * Return zero to check for a real pending signal normally.
414 * Return -1 after releasing the siglock to repeat the check.
415 * Return a signal number to induce an artifical signal delivery,
416 * setting *info and *return_ka to specify its details and behavior.
418 static inline int tracehook_get_signal(struct task_struct *tsk,
419 struct pt_regs *regs,
421 struct k_sigaction *return_ka)
423 if (unlikely(tsk_utrace_flags(tsk)))
424 return utrace_get_signal(tsk, regs, info, return_ka);
429 * Called with no locks held when about to stop for job control;
430 * we are already in TASK_STOPPED state, about to call schedule.
431 * Return zero if the normal SIGCHLD should be generated, which
432 * will happen if last_one is true meaning this is the last thread
433 * in the thread group to stop.
435 static inline int tracehook_finish_stop(int last_one)
437 if (tsk_utrace_flags(current) & UTRACE_EVENT(JCTL))
438 return utrace_report_jctl(CLD_STOPPED);
444 * Return nonzero if the child's parent (current) should be prevented
445 * from seeing its child in TASK_STOPPED state when it waits with WSTOPPED.
446 * Called with tasklist_lock held for reading.
448 static inline int tracehook_inhibit_wait_stopped(struct task_struct *child)
450 return (tsk_utrace_flags(child) & UTRACE_ACTION_NOREAP);
454 * Return nonzero if the child's parent (current) should be prevented
455 * from seeing its child in TASK_ZOMBIE state when it waits with WEXITED.
456 * Called with tasklist_lock held for reading.
458 static inline int tracehook_inhibit_wait_zombie(struct task_struct *child)
460 return (tsk_utrace_flags(child) & UTRACE_ACTION_NOREAP);
464 * Return nonzero if the child's parent (current) should be prevented
465 * from seeing its child resuming after job stop when it waits with WCONTINUED.
466 * Called with tasklist_lock held for reading.
468 static inline int tracehook_inhibit_wait_continued(struct task_struct *child)
470 return (tsk_utrace_flags(child) & UTRACE_ACTION_NOREAP);
475 * Return LSM_UNSAFE_* bits applied to an exec because of tracing.
476 * Called with task_lock(tsk) held.
478 static inline int tracehook_unsafe_exec(struct task_struct *tsk)
480 if (tsk_utrace_flags(tsk))
481 return utrace_unsafe_exec(tsk);
486 * Return the task_struct for the task using ptrace on this one, or NULL.
487 * Must be called with rcu_read_lock held to keep the returned struct alive.
489 * At exec time, this may be called with task_lock(p) still held from when
490 * tracehook_unsafe_exec was just called.
492 * The value is also used to display after "TracerPid:" in /proc/PID/status,
493 * where it is called with only rcu_read_lock held.
495 static inline struct task_struct *tracehook_tracer_task(struct task_struct *p)
497 if (tsk_utrace_flags(p))
498 return utrace_tracer_task(p);
503 * Return nonzero if the current task should be allowed to use
504 * access_process_vm on the given task.
506 static inline int tracehook_allow_access_process_vm(struct task_struct *tsk)
510 if (tsk_utrace_flags(tsk))
511 return utrace_allow_access_process_vm(tsk);
518 *** Following decelarations are hook stubs where core code reports
519 *** events. These are called without locks, from the thread having the
520 *** event. In all tracehook_report_* calls, no locks are held and the thread
521 *** is in a state close to returning to user mode with little baggage to
522 *** unwind, except as noted below for tracehook_report_clone. It is generally
523 *** OK to block in these places if you want the user thread to be suspended.
528 * Thread has just become a zombie (exit_state==TASK_ZOMBIE) or is about to
529 * self-reap (exit_state==EXIT_DEAD). If normal reaping is not inhibited,
530 * tsk->exit_state might be changing in parallel. The death_cookie was
531 * passed back by tracehook_notify_death (above).
533 static inline void tracehook_report_death(struct task_struct *tsk,
534 int exit_state, void *death_cookie)
537 if (tsk_utrace_flags(tsk) & (UTRACE_EVENT(DEATH)
538 | UTRACE_ACTION_QUIESCE))
539 utrace_report_death(tsk, death_cookie);
543 * This is called when tracehook_inhibit_wait_zombie(p) returned true
544 * and a previously delayed group_leader is now eligible for reaping.
545 * It's called from release_task, with no locks held, and p is not current.
547 static inline void tracehook_report_delayed_group_leader(struct task_struct *p)
549 utrace_report_delayed_group_leader(p);
553 * exec completed, we are shortly going to return to user mode.
554 * The freshly initialized register state can be seen and changed here.
556 static inline void tracehook_report_exec(struct linux_binprm *bprm,
557 struct pt_regs *regs)
559 if (tsk_utrace_flags(current) & UTRACE_EVENT(EXEC))
560 utrace_report_exec(bprm, regs);
564 * Called from do_exit, we are about to exit. The code returned to the
565 * parent for wait can be changed here.
567 static inline void tracehook_report_exit(long *exit_code)
569 if (tsk_utrace_flags(current) & UTRACE_EVENT(EXIT))
570 utrace_report_exit(exit_code);
574 * Called after a child is set up, but before it has been started or
575 * been given its CLONE_STOPPED initial stop. (See also tracehook_init_task.)
576 * This is not a good place to block, because the child has not started yet.
577 * Suspend the child here if desired, and block in clone_complete (below).
578 * This must prevent the child from self-reaping if clone_complete uses
579 * the task_struct pointer; otherwise it might have died and been released
580 * by the time tracehook_report_clone_complete is called.
582 static inline void tracehook_report_clone(unsigned long clone_flags,
583 struct task_struct *child)
585 if (tsk_utrace_flags(current) & UTRACE_EVENT(CLONE))
586 utrace_report_clone(clone_flags, child);
590 * Called after the child has started running, shortly after
591 * tracehook_report_clone. This is just before the clone/fork syscall returns,
592 * or blocks for vfork child completion if (clone_flags & CLONE_VFORK).
593 * The child pointer may be invalid if a self-reaping child died and
594 * tracehook_report_clone took no action to prevent it from self-reaping.
596 static inline void tracehook_report_clone_complete(unsigned long clone_flags,
598 struct task_struct *child)
600 if (tsk_utrace_flags(current) & UTRACE_ACTION_QUIESCE)
601 utrace_quiescent(current, NULL);
605 * Called after a CLONE_VFORK parent has waited for the child to complete.
606 * The clone/vfork system call will return immediately after this.
607 * The child pointer may be invalid if a self-reaping child died and
608 * tracehook_report_clone took no action to prevent it from self-reaping.
610 static inline void tracehook_report_vfork_done(struct task_struct *child,
613 if (tsk_utrace_flags(current) & UTRACE_EVENT(VFORK_DONE))
614 utrace_report_vfork_done(child_pid);
618 * Called for system call entry or exit.
620 static inline void tracehook_report_syscall(struct pt_regs *regs, int is_exit)
622 if (tsk_utrace_flags(current) & (is_exit ? UTRACE_EVENT(SYSCALL_EXIT)
623 : UTRACE_EVENT(SYSCALL_ENTRY)))
624 utrace_report_syscall(regs, is_exit);
628 * Called after system call exit if single/block-stepped into the syscall.
630 static inline void tracehook_report_syscall_step(struct pt_regs *regs)
635 * Called when a signal handler has been set up.
636 * Register and stack state reflects the user handler about to run.
637 * Signal mask changes have already been made.
639 static inline void tracehook_report_handle_signal(int sig,
640 const struct k_sigaction *ka,
641 const sigset_t *oldset,
642 struct pt_regs *regs)
644 struct task_struct *tsk = current;
645 if ((tsk_utrace_flags(tsk) & UTRACE_EVENT_SIGNAL_ALL)
646 && (tsk_utrace_flags(tsk) & (UTRACE_ACTION_SINGLESTEP
647 | UTRACE_ACTION_BLOCKSTEP)))
648 utrace_signal_handler_singlestep(tsk, regs);
652 #endif /* <linux/tracehook.h> */