4 * This file defines hook entry points called by core code where
5 * user tracing/debugging support might need to do something.
6 * These entry points are called tracehook_*. Each hook declared below
7 * has a detailed comment giving the context (locking et al) from
8 * which it is called, and the meaning of its return value (if any).
10 * We also declare here tracehook_* functions providing access to low-level
11 * interrogation and control of threads. These functions must be called
12 * on either the current thread or on a quiescent thread. We say a
13 * thread is "quiescent" if it is in TASK_STOPPED or TASK_TRACED state,
14 * we are guaranteed it will not be woken up and return to user mode, and
15 * we have called wait_task_inactive on it.
18 #ifndef _LINUX_TRACEHOOK_H
19 #define _LINUX_TRACEHOOK_H 1
21 #include <linux/sched.h>
22 #include <linux/uaccess.h>
28 * The machine-specific asm/tracehook.h file is responsible for declaring
29 * the following entry points. These can be called only on a quiescent thread,
30 * or the current thread when it is about to return to user mode.
32 * Single-step control. When enabled, the next instruction or syscall exit
33 * produces a SIGTRAP. Enabling or disabling redundantly is harmless.
35 * void tracehook_enable_single_step(struct task_struct *tsk);
36 * void tracehook_disable_single_step(struct task_struct *tsk);
37 * int tracehook_single_step_enabled(struct task_struct *tsk);
39 * If those calls are defined, #define ARCH_HAS_SINGLE_STEP to nonzero.
40 * Do not #define it if these calls are never available in this kernel config.
41 * If defined, the value of ARCH_HAS_SINGLE_STEP can be constant or variable.
42 * It should evaluate to nonzero if the hardware is able to support
43 * tracehook_enable_single_step. If it's a variable expression, it
44 * should be one that can be evaluated in modules, i.e. uses exported symbols.
46 * Block-step control (trap on control transfer), when available.
47 * tracehook_disable_block_step will be called after tracehook_enable_single_step.
48 * When enabled, the next jump, or other control transfer or syscall exit,
49 * produces a SIGTRAP. Enabling or disabling redundantly is harmless.
51 * void tracehook_enable_block_step(struct task_struct *tsk);
52 * void tracehook_disable_block_step(struct task_struct *tsk);
53 * int tracehook_block_step_enabled(struct task_struct *tsk);
55 * If those calls are defined, #define ARCH_HAS_BLOCK_STEP to nonzero.
56 * Do not #define it if these calls are never available in this kernel config.
57 * If defined, the value of ARCH_HAS_BLOCK_STEP can be constant or variable.
58 * It should evaluate to nonzero if the hardware is able to support
59 * tracehook_enable_block_step. If it's a variable expression, it
60 * should be one that can be evaluated in modules, i.e. uses exported symbols.
62 * Control system call tracing. When enabled a syscall entry or exit
63 * produces a call to tracehook_report_syscall, below.
65 * void tracehook_enable_syscall_trace(struct task_struct *tsk);
66 * void tracehook_disable_syscall_trace(struct task_struct *tsk);
68 * When stopped in tracehook_report_syscall for syscall entry,
69 * abort the syscall so no kernel function is called.
70 * If the register state was not otherwise updated before,
71 * this produces an -ENOSYS error return as for an invalid syscall number.
73 * void tracehook_abort_syscall(struct pt_regs *regs);
75 * Return the regset view (see below) that is native for the given process.
76 * For example, what it would access when it called ptrace.
77 * Throughout the life of the process, this only changes at exec.
79 * const struct utrace_regset_view *utrace_native_view(struct task_struct *);
85 * This data structure describes a machine resource we call a register set.
86 * This is part of the state of an individual thread, not necessarily
87 * actual CPU registers per se. A register set consists of a number of
88 * similar slots, given by ->n. Each slot is ->size bytes, and aligned to
89 * ->align bytes (which is at least ->size).
91 * As described above, these entry points can be called on the current
92 * thread or on a quiescent thread. The pos argument must be aligned
93 * according to ->align; the count argument must be a multiple of ->size.
94 * These functions are not responsible for checking for invalid arguments.
96 * When there is a natural value to use as an index, ->bias gives the
97 * difference between the natural index and the slot index for the
98 * register set. For example, x86 GDT segment descriptors form a regset;
99 * the segment selector produces a natural index, but only a subset of
100 * that index space is available as a regset (the TLS slots); subtracting
101 * ->bias from a segment selector index value computes the regset slot.
103 struct utrace_regset {
104 unsigned int n; /* Number of slots (registers). */
105 unsigned int size; /* Size in bytes of a slot (register). */
106 unsigned int align; /* Required alignment, in bytes. */
107 unsigned int bias; /* Bias from natural indexing. */
110 * Return -ENODEV if not available on the hardware found.
111 * Return 0 if no interesting state in this thread.
112 * Return >0 number of ->size units of interesting state.
113 * Any get call fetching state beyond that number will
114 * see the default initialization state for this data,
115 * so a caller that knows that the default state is need
116 * not copy it all out.
117 * This call is optional; the pointer is NULL if there
118 * so no inexpensive check to yield a value < .n.
120 int (*active)(struct task_struct *, const struct utrace_regset *);
123 * Fetch and store register values. Return 0 on success; -EIO or
124 * -ENODEV are usual failure returns. The pos and count values are
125 * in bytes, but must be properly aligned. If kbuf is non-null,
126 * that buffer is used and ubuf is ignored. If kbuf is NULL, then
127 * ubuf gives a userland pointer to access directly, and an -EFAULT
128 * return value is possible.
130 int (*get)(struct task_struct *, const struct utrace_regset *,
131 unsigned int pos, unsigned int count,
132 void *kbuf, void __user *ubuf);
133 int (*set)(struct task_struct *, const struct utrace_regset *,
134 unsigned int pos, unsigned int count,
135 const void *kbuf, const void __user *ubuf);
138 * This call is optional; usually the pointer is NULL.
139 * When provided, there is some user memory associated
140 * with this regset's hardware, such as memory backing
141 * cached register data on register window machines; the
142 * regset's data controls what user memory is used
143 * (e.g. via the stack pointer value).
145 * Write register data back to user memory. If the
146 * immediate flag is nonzero, it must be written to the
147 * user memory so uaccess/access_process_vm can see it
148 * when this call returns; if zero, then it must be
149 * written back by the time the task completes a context
150 * switch (as synchronized with wait_task_inactive).
151 * Return 0 on success or if there was nothing to do,
152 * -EFAULT for a memory problem (bad stack pointer or
153 * whatever), or -EIO for a hardware problem.
155 int (*writeback)(struct task_struct *, const struct utrace_regset *,
160 * A regset view is a collection of regsets (struct utrace_regset, above).
161 * This describes all the state of a thread that can be seen from a given
162 * architecture/ABI environment. More than one view might refer to the
163 * same utrace_regset, or more than one regset might refer to the same
164 * machine-specific state in the thread. For example, a 32-bit thread's
165 * state could be examined from the 32-bit view or from the 64-bit view.
166 * Either method reaches the same thread register state, doing appropriate
167 * widening or truncation.
169 struct utrace_regset_view {
170 const char *name; /* Identifier, e.g. ELF_PLATFORM string. */
172 const struct utrace_regset *regsets;
176 * EM_* value for which this is the native view, if any.
183 * These two are helpers for writing regset get/set functions in arch code.
184 * Use one or more calls sequentially for each chunk of regset data stored
185 * contiguously in memory. Call with constants for start_pos and end_pos,
186 * giving the range of byte positions in the regset that data corresponds
187 * to; end_pos can be -1 if this chunk is at the end of the regset layout.
188 * Each call updates the arguments to point past its chunk.
192 utrace_regset_copyout(unsigned int *pos, unsigned int *count,
193 void **kbuf, void __user **ubuf,
194 const void *data, int start_pos, int end_pos)
198 BUG_ON(*pos < start_pos);
199 if (end_pos < 0 || *pos < end_pos) {
200 unsigned int copy = (end_pos < 0 ? *count
201 : min(*count, end_pos - *pos));
202 data += *pos - start_pos;
204 memcpy(*kbuf, data, copy);
207 else if (copy_to_user(*ubuf, data, copy))
218 utrace_regset_copyin(unsigned int *pos, unsigned int *count,
219 const void **kbuf, const void __user **ubuf,
220 void *data, int start_pos, int end_pos)
224 BUG_ON(*pos < start_pos);
225 if (end_pos < 0 || *pos < end_pos) {
226 unsigned int copy = (end_pos < 0 ? *count
227 : min(*count, end_pos - *pos));
228 data += *pos - start_pos;
230 memcpy(data, *kbuf, copy);
233 else if (copy_from_user(data, *ubuf, copy))
244 * These two parallel the two above, but for portions of a regset layout
245 * that always read as all-zero or for which writes are ignored.
248 utrace_regset_copyout_zero(unsigned int *pos, unsigned int *count,
249 void **kbuf, void __user **ubuf,
250 int start_pos, int end_pos)
254 BUG_ON(*pos < start_pos);
255 if (end_pos < 0 || *pos < end_pos) {
256 unsigned int copy = (end_pos < 0 ? *count
257 : min(*count, end_pos - *pos));
259 memset(*kbuf, 0, copy);
262 else if (clear_user(*ubuf, copy))
273 utrace_regset_copyin_ignore(unsigned int *pos, unsigned int *count,
274 const void **kbuf, const void __user **ubuf,
275 int start_pos, int end_pos)
279 BUG_ON(*pos < start_pos);
280 if (end_pos < 0 || *pos < end_pos) {
281 unsigned int copy = (end_pos < 0 ? *count
282 : min(*count, end_pos - *pos));
298 *** Following are entry points from core code, where the user debugging
299 *** support can affect the normal behavior. The locking situation is
300 *** described for each call.
305 #include <linux/utrace.h>
310 * Called in copy_process when setting up the copied task_struct,
311 * with tasklist_lock held for writing.
313 static inline void tracehook_init_task(struct task_struct *child)
316 child->utrace_flags = 0;
317 child->utrace = NULL;
322 * Called from release_task, no locks held.
323 * After this, there should be no tracing entanglements.
325 static inline void tracehook_release_task(struct task_struct *p)
329 if (p->utrace != NULL)
330 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)
343 return unlikely(p->utrace != NULL);
349 * do_notify_parent_cldstop calls this when it's about to generate a SIGCHLD
350 * for a job control stop. Return nonzero to prevent that signal generation.
351 * Called with tasklist_lock held for reading, sometimes with irqs disabled.
353 static inline int tracehook_notify_cldstop(struct task_struct *tsk,
354 const siginfo_t *info)
357 if (tsk->utrace_flags & UTRACE_ACTION_NOREAP)
364 * exit_notify calls this with tasklist_lock held for writing.
365 * Return nonzero to prevent any normal SIGCHLD generation for this
366 * thread's death (i.e. when it is not ignored and its thread group is
367 * empty). This call must set *noreap to 0, or to 1 to force this thread
368 * to become a zombie when it would normally reap itself.
369 * The *death_cookie is passed to tracehook_report_death (below).
371 static inline int tracehook_notify_death(struct task_struct *tsk,
372 int *noreap, void **death_cookie)
374 *death_cookie = NULL;
376 *death_cookie = tsk->utrace;
377 if (tsk->utrace_flags & UTRACE_ACTION_NOREAP) {
387 * Return zero iff tracing doesn't care to examine this fatal signal,
388 * so it can short-circuit normal delivery directly to a group exit.
389 * Called with tsk->sighand->siglock held.
391 static inline int tracehook_consider_fatal_signal(struct task_struct *tsk,
395 return (tsk->utrace_flags & (UTRACE_EVENT(SIGNAL_TERM)
396 | UTRACE_EVENT(SIGNAL_CORE)));
402 * Return zero iff tracing doesn't care to examine this ignored signal,
403 * so it can short-circuit normal delivery and never even get queued.
404 * Either the handler is SIG_DFL and sig's default is ignore, or it's SIG_IGN.
405 * Called with tsk->sighand->siglock held.
407 static inline int tracehook_consider_ignored_signal(struct task_struct *tsk,
408 int sig, void *handler)
411 return (tsk->utrace_flags & UTRACE_EVENT(SIGNAL_IGN));
418 * Called with the siglock held when computing tsk's signal_pending flag.
419 * Return nonzero to force the signal_pending flag on, so that
420 * tracehook_induce_signal will be called before the next return to user mode.
422 static inline int tracehook_induce_sigpending(struct task_struct *tsk)
425 return unlikely(tsk->utrace_flags & UTRACE_ACTION_QUIESCE);
431 * Called with the siglock held before dequeuing pending signals.
432 * Return zero to check for a real pending signal normally.
433 * Return -1 after releasing the siglock to repeat the check.
434 * Return a signal number to induce an artifical signal delivery,
435 * setting *info and *return_ka to specify its details and behavior.
437 static inline int tracehook_get_signal(struct task_struct *tsk,
438 struct pt_regs *regs,
440 struct k_sigaction *return_ka)
443 if (unlikely(tsk->utrace_flags))
444 return utrace_get_signal(tsk, regs, info, return_ka);
450 * Called with no locks held when about to stop for job control;
451 * we are already in TASK_STOPPED state, about to call schedule.
452 * Return zero if the normal SIGCHLD should be generated, which
453 * will happen if last_one is true meaning this is the last thread
454 * in the thread group to stop.
456 static inline int tracehook_finish_stop(int last_one)
459 if (current->utrace_flags & UTRACE_EVENT(JCTL))
460 return utrace_report_jctl(CLD_STOPPED);
467 * Called with tasklist_lock held for reading, for an event notification stop.
468 * We are already in TASK_TRACED. Return zero to go back to running,
469 * or nonzero to actually stop until resumed.
471 static inline int tracehook_stop_now(void)
478 * Return nonzero if the child's parent (current) should be prevented
479 * from seeing its child in TASK_STOPPED state when it waits with WSTOPPED.
480 * Called with tasklist_lock held for reading.
482 static inline int tracehook_inhibit_wait_stopped(struct task_struct *child)
485 return (child->utrace_flags & UTRACE_ACTION_NOREAP);
491 * Return nonzero if the child's parent (current) should be prevented
492 * from seeing its child in TASK_ZOMBIE state when it waits with WEXITED.
493 * Called with tasklist_lock held for reading.
495 static inline int tracehook_inhibit_wait_zombie(struct task_struct *child)
498 return (child->utrace_flags & UTRACE_ACTION_NOREAP);
504 * Return nonzero if the child's parent (current) should be prevented
505 * from seeing its child resuming after job stop when it waits with WCONTINUED.
506 * Called with tasklist_lock held for reading.
508 static inline int tracehook_inhibit_wait_continued(struct task_struct *child)
511 return (child->utrace_flags & UTRACE_ACTION_NOREAP);
518 * Return LSM_UNSAFE_* bits applied to an exec because of tracing.
519 * Called with task_lock(tsk) held.
521 static inline int tracehook_unsafe_exec(struct task_struct *tsk)
524 if (tsk->utrace_flags)
525 return utrace_unsafe_exec(tsk);
531 * Return the task_struct for the task using ptrace on this one, or NULL.
532 * Must be called with rcu_read_lock held to keep the returned struct alive.
534 * At exec time, this may be called with task_lock(p) still held from when
535 * tracehook_unsafe_exec was just called.
537 * The value is also used to display after "TracerPid:" in /proc/PID/status,
538 * where it is called with only rcu_read_lock held.
540 static inline struct task_struct *tracehook_tracer_task(struct task_struct *p)
544 return utrace_tracer_task(p);
550 * Return nonzero if the current task should be allowed to use
551 * access_process_vm on the given task.
553 static inline int tracehook_allow_access_process_vm(struct task_struct *tsk)
558 if (tsk->utrace_flags)
559 return utrace_allow_access_process_vm(tsk);
567 *** Following decelarations are hook stubs where core code reports
568 *** events. These are called without locks, from the thread having the
569 *** event. In all tracehook_report_* calls, no locks are held and the thread
570 *** is in a state close to returning to user mode with little baggage to
571 *** unwind, except as noted below for tracehook_report_clone. It is generally
572 *** OK to block in these places if you want the user thread to be suspended.
577 * Thread has just become a zombie (exit_state==TASK_ZOMBIE) or is about to
578 * self-reap (exit_state==EXIT_DEAD). If normal reaping is not inhibited,
579 * tsk->exit_state might be changing in parallel. The death_cookie was
580 * passed back by tracehook_notify_death (above).
582 static inline void tracehook_report_death(struct task_struct *tsk,
583 int exit_state, void *death_cookie)
587 if (tsk->utrace_flags & (UTRACE_EVENT(DEATH) | UTRACE_ACTION_QUIESCE))
588 utrace_report_death(tsk, death_cookie);
593 * exec completed, we are shortly going to return to user mode.
594 * The freshly initialized register state can be seen and changed here.
596 static inline void tracehook_report_exec(struct linux_binprm *bprm,
597 struct pt_regs *regs)
600 if (current->utrace_flags & UTRACE_EVENT(EXEC))
601 utrace_report_exec(bprm, regs);
606 * Called from do_exit, we are about to exit. The code returned to the
607 * parent for wait can be changed here.
609 static inline void tracehook_report_exit(long *exit_code)
612 if (current->utrace_flags & UTRACE_EVENT(EXIT))
613 utrace_report_exit(exit_code);
618 * Called after a child is set up, but before it has been started or
619 * been given its CLONE_STOPPED initial stop. (See also tracehook_init_task.)
620 * This is not a good place to block, because the child has not started yet.
621 * Suspend the child here if desired, and block in clone_complete (below).
622 * This must prevent the child from self-reaping if clone_complete uses
623 * the task_struct pointer; otherwise it might have died and been released
624 * by the time tracehook_report_clone_complete is called.
626 static inline void tracehook_report_clone(unsigned long clone_flags,
627 struct task_struct *child)
630 if (current->utrace_flags & UTRACE_EVENT(CLONE))
631 utrace_report_clone(clone_flags, child);
636 * Called after the child has started running, shortly after
637 * tracehook_report_clone. This is just before the clone/fork syscall
638 * returns, or blocks for vfork child completion if (clone_flags &
639 * CLONE_VFORK). The child pointer may be invalid if a self-reaping
640 * child died and tracehook_report_clone took no action to prevent it
643 static inline void tracehook_report_clone_complete(unsigned long clone_flags,
645 struct task_struct *child)
648 if (current->utrace_flags & UTRACE_ACTION_QUIESCE)
649 utrace_quiescent(current, NULL);
654 * Called after a CLONE_VFORK parent has waited for the child to complete.
655 * The clone/vfork system call will return immediately after this.
656 * The child pointer may be invalid if a self-reaping child died and
657 * tracehook_report_clone took no action to prevent it from self-reaping.
659 static inline void tracehook_report_vfork_done(struct task_struct *child,
663 if (current->utrace_flags & UTRACE_EVENT(VFORK_DONE))
664 utrace_report_vfork_done(child_pid);
669 * Called for system call entry or exit.
671 static inline void tracehook_report_syscall(struct pt_regs *regs, int is_exit)
674 if (current->utrace_flags & (is_exit ? UTRACE_EVENT(SYSCALL_EXIT)
675 : UTRACE_EVENT(SYSCALL_ENTRY)))
676 utrace_report_syscall(regs, is_exit);
681 * Called after system call exit if single/block-stepped into the syscall.
683 static inline void tracehook_report_syscall_step(struct pt_regs *regs)
688 * Called when a signal handler has been set up.
689 * Register and stack state reflects the user handler about to run.
690 * Signal mask changes have already been made.
692 static inline void tracehook_report_handle_signal(int sig,
693 const struct k_sigaction *ka,
694 const sigset_t *oldset,
695 struct pt_regs *regs)
698 struct task_struct *tsk = current;
699 if ((tsk->utrace_flags & UTRACE_EVENT_SIGNAL_ALL)
700 && (tsk->utrace_flags & (UTRACE_ACTION_SINGLESTEP
701 | UTRACE_ACTION_BLOCKSTEP)))
702 utrace_signal_handler_singlestep(tsk, regs);
707 #endif /* <linux/tracehook.h> */