1STRUCT UTRACE_ENGINE(9) utrace core API STRUCT UTRACE_ENGINE(9)
2
6 struct_utrace_engine_ops - tracing engine callbacks
7
9 struct utrace_engine_ops {
10 u32 (* report_quiesce) (u32 action, struct utrace_engine *engine,unsigned long event);
11 u32 (* report_signal) (u32 action, struct utrace_engine *engine,struct pt_regs *regs,siginfo_t *info,const struct k_sigaction *orig_ka,struct k_sigaction *return_ka);
12 u32 (* report_clone) (u32 action, struct utrace_engine *engine,unsigned long clone_flags,struct task_struct *child);
13 u32 (* report_jctl) (u32 action, struct utrace_engine *engine,int type, int notify);
14 u32 (* report_exec) (u32 action, struct utrace_engine *engine,const struct linux_binfmt *fmt,const struct linux_binprm *bprm,struct pt_regs *regs);
15 u32 (* report_syscall_entry) (u32 action, struct utrace_engine *engine,struct pt_regs *regs);
16 u32 (* report_syscall_exit) (u32 action, struct utrace_engine *engine,struct pt_regs *regs);
17 u32 (* report_exit) (u32 action, struct utrace_engine *engine,long orig_code, long *code);
18 u32 (* report_death) (struct utrace_engine *engine,bool group_dead, int signal);
19 void (* report_reap) (struct utrace_engine *engine,struct task_struct *task);
20 void (* release) (void *data);
21 };
22
24 report_quiesce
25 Requested by UTRACE_EVENT(QUIESCE). This does not indicate any
26 event, but just that current is in a safe place for examination.
27 This call is made before each specific event callback, except for
28 report_reap. The event argument gives the UTRACE_EVENT(which) value
29 for the event occurring. This callback might be made for events
30 engine has not requested, if some other engine is tracing the
31 event; calling utrace_set_events call here can request the
32 immediate callback for this occurrence of event. event is zero
33 when there is no other event, current is now ready to check for
34 signals and return to user mode, and some engine has used
35 UTRACE_REPORT or UTRACE_INTERRUPT to request this callback. For
36 this case, if report_signal is not NULL, the report_quiesce
37 callback may be replaced with a report_signal callback passing
38 UTRACE_SIGNAL_REPORT in its action argument, whenever current is
39 entering the signal-check path anyway.
40 report_signal
42 Requested by UTRACE_EVENT(SIGNAL_*) or UTRACE_EVENT(QUIESCE). Use
43 utrace_signal_action and utrace_resume_action on action. The signal
44 action is UTRACE_SIGNAL_REPORT when some engine has used
45 UTRACE_REPORT or UTRACE_INTERRUPT; the callback can choose to stop
46 or to deliver an artificial signal, before pending signals. It´s
47 UTRACE_SIGNAL_HANDLER instead when signal handler setup just
48 finished (after a previous UTRACE_SIGNAL_DELIVER return); this
49 serves in lieu of any UTRACE_SIGNAL_REPORT callback requested by
50 UTRACE_REPORT or UTRACE_INTERRUPT, and is also implicitly requested
51 by UTRACE_SINGLESTEP or UTRACE_BLOCKSTEP into the signal delivery.
52 The other signal actions indicate a signal about to be delivered;
53 the previous engine´s return value sets the signal action seen by
54 the the following engine´s callback. The info data can be changed
55 at will, including info->si_signo. The settings in return_ka
56 determines what UTRACE_SIGNAL_DELIVER does. orig_ka is what was in
57 force before other tracing engines intervened, and it´s NULL when
58 this report began as UTRACE_SIGNAL_REPORT or UTRACE_SIGNAL_HANDLER.
59 For a report without a new signal, info is left uninitialized and
60 must be set completely by an engine that chooses to deliver a
61 signal; if there was a previous report_signal callback ending in
62 UTRACE_STOP and it was just resumed using UTRACE_REPORT or
63 UTRACE_INTERRUPT, then info is left unchanged from the previous
64 callback. In this way, the original signal can be left in info
65 while returning UTRACE_STOP|UTRACE_SIGNAL_IGN and then found again
66 when resuming with UTRACE_INTERRUPT. The UTRACE_SIGNAL_HOLD flag
67 bit can be OR´d into the return value, and might be in action if
68 the previous engine returned it. This flag asks that the signal in
69 info be pushed back on current´s queue so that it will be seen
70 again after whatever action is taken now.
71 report_clone
73 Requested by UTRACE_EVENT(CLONE). Event reported for parent, before
74 the new task child might run. clone_flags gives the flags used in
75 the clone system call, or equivalent flags for a fork or vfork
76 system call. This function can use utrace_attach_task on child.
77 Then passing UTRACE_STOP to utrace_control on child here keeps the
78 child stopped before it ever runs in user mode, UTRACE_REPORT or
79 UTRACE_INTERRUPT ensures a callback from child before it starts in
80 user mode.
81 report_jctl
83 Requested by UTRACE_EVENT(JCTL). Job control event; type is
84 CLD_STOPPED or CLD_CONTINUED, indicating whether we are stopping or
85 resuming now. If notify is nonzero, current is the last thread to
86 stop and so will send SIGCHLD to its parent after this callback;
87 notify reflects what the parent´s SIGCHLD has in si_code, which can
88 sometimes be CLD_STOPPED even when type is CLD_CONTINUED.
89 report_exec
91 Requested by UTRACE_EVENT(EXEC). An execve system call has
92 succeeded and the new program is about to start running. The
93 initial user register state is handy to be tweaked directly in
94 regs. fmt and bprm gives the details of this exec.
95 report_syscall_entry
97 Requested by UTRACE_EVENT(SYSCALL_ENTRY). Thread has entered the
98 kernel to request a system call. The user register state is handy
99 to be tweaked directly in regs. The action argument contains an
100 enum utrace_syscall_action, use utrace_syscall_action to extract
101 it. The return value overrides the last engine´s action for the
102 system call. If the final action is UTRACE_SYSCALL_ABORT, no system
103 call is made. The details of the system call being attempted can be
104 fetched here with syscall_get_nr and syscall_get_arguments. The
105 parameter registers can be changed with syscall_set_arguments. See
106 above about the UTRACE_SYSCALL_RESUMED flag in action. Use
107 UTRACE_REPORT in the return value to guarantee you get another
108 callback (with UTRACE_SYSCALL_RESUMED flag) in case current stops
109 with UTRACE_STOP before attempting the system call.
110 report_syscall_exit
112 Requested by UTRACE_EVENT(SYSCALL_EXIT). Thread is about to leave
113 the kernel after a system call request. The user register state is
114 handy to be tweaked directly in regs. The results of the system
115 call attempt can be examined here using syscall_get_error and
116 syscall_get_return_value. It is safe here to call
117 syscall_set_return_value or syscall_rollback.
118 report_exit
120 Requested by UTRACE_EVENT(EXIT). Thread is exiting and cannot be
121 prevented from doing so, but all its state is still live. The code
122 value will be the wait result seen by the parent, and can be
123 changed by this engine or others. The orig_code value is the real
124 status, not changed by any tracing engine. Returning UTRACE_STOP
125 here keeps current stopped before it cleans up its state and dies,
126 so it can be examined by other processes. When current is allowed
127 to run, it will die and get to the report_death callback.
128 report_death
130 Requested by UTRACE_EVENT(DEATH). Thread is really dead now. It
131 might be reaped by its parent at any time, or self-reap
132 immediately. Though the actual reaping may happen in parallel, a
133 report_reap callback will always be ordered after a report_death
134 callback.
135 report_reap
137 Requested by UTRACE_EVENT(REAP). Called when someone reaps the dead
138 task (parent, init, or self). This means the parent called wait, or
139 else this was a detached thread or a process whose parent ignores
140 SIGCHLD. No more callbacks are made after this one. The engine is
141 always detached. There is nothing more a tracing engine can do
142 about this thread. After this callback, the engine pointer will
143 become invalid. The task pointer may become invalid if
144 get_task_struct hasn´t been used to keep it alive. An engine should
145 always request this callback if it stores the engine pointer or
146 stores any pointer in engine->data, so it can clean up its data
147 structures. Unlike other callbacks, this can be called from the
148 parent´s context rather than from the traced thread itself--it must
149 not delay the parent by blocking.
150 release
152 If not NULL, this is called after the last utrace_engine_put call
153 for a struct utrace_engine, which could be implicit after a
154 UTRACE_DETACH return from another callback. Its argument is the
155 engine´s data member.
156
158 Each report_*() callback corresponds to an UTRACE_EVENT(*) bit.
159 utrace_set_events calls on engine choose which callbacks will be made
160 to engine from task.
161 Most callbacks take an action argument, giving the resume action chosen
163 by other tracing engines. All callbacks take an engine argument. The
164 report_reap callback takes a task argument that might or might not be
165 current. All other report_* callbacks report an event in the current
166 task.
167 For some calls, action also includes bits specific to that event and
169 utrace_resume_action is used to extract the resume action. This shows
170 what would happen if engine wasn´t there, or will if the callback´s
171 return value uses UTRACE_RESUME. This always starts as UTRACE_RESUME
172 when no other tracing is being done on this task.
173 All return values contain enum utrace_resume_action bits. For some
175 calls, other bits specific to that kind of event are added to the
176 resume action bits with OR. These are the same bits used in the action
177 argument. The resume action returned by a callback does not override
178 previous engines´ choices, it only says what engine wants done. What
179 current actually does is the action that´s most constrained among the
180 choices made by all attached engines. See utrace_control for more
181 information on the actions.
182 When UTRACE_STOP is used in report_syscall_entry, then current stops
184 before attempting the system call. In this case, another
185 report_syscall_entry callback will follow after current resumes if
186 UTRACE_REPORT or UTRACE_INTERRUPT was returned by some callback or
187 passed to utrace_control. In a second or later callback,
188 UTRACE_SYSCALL_RESUMED is set in the action argument to indicate a
189 repeat callback still waiting to attempt the same system call
190 invocation. This repeat callback gives each engine an opportunity to
191 reexamine registers another engine might have changed while current was
192 held in UTRACE_STOP.
193 In other cases, the resume action does not take effect until current is
195 ready to check for signals and return to user mode. If there are more
196 callbacks to be made, the last round of calls determines the final
197 action. A report_quiesce callback with event zero, or a report_signal
198 callback, will always be the last one made before current resumes. Only
199 UTRACE_STOP is “sticky”--if engine returned UTRACE_STOP then current
200 stays stopped unless engine returns different from a following
201 callback.
202 The report_death and report_reap callbacks do not take action
204 arguments, and only UTRACE_DETACH is meaningful in the return value
205 from a report_death callback. None of the resume actions applies to a
206 dead thread.
207 All report_*() hooks are called with no locks held, in a generally safe
209 environment when we will be returning to user mode soon (or just
210 entered the kernel). It is fine to block for memory allocation and the
211 like, but all hooks are asynchronous and must not block on external
212 events! If you want the thread to block, use UTRACE_STOP in your hook´s
213 return value; then later wake it up with utrace_control.
214Kernel Hackers Manual 2.6. June 2019 STRUCT UTRACE_ENGINE(9)