<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>struct utrace_engine_ops</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="index.html" title="The utrace User Debugging Infrastructure" /><link rel="up" href="ch02.html" title="Chapter 2. utrace core API" /><link rel="prev" href="re09.html" title="utrace_engine_put" /><link rel="next" href="re11.html" title="struct utrace_examiner" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"><span>struct utrace_engine_ops</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="re09.html">Prev</a> </td><th width="60%" align="center">Chapter 2. utrace core API</th><td width="20%" align="right"> <a accesskey="n" href="re11.html">Next</a></td></tr></table><hr /></div><div class="refentry" title="struct utrace_engine_ops"><a id="API-struct-utrace-engine-ops"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>struct utrace_engine_ops —
tracing engine callbacks
</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><pre class="programlisting">
struct utrace_engine_ops {
u32 (* report_quiesce) (u32 action, struct utrace_engine *engine,unsigned long event);
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);
u32 (* report_clone) (u32 action, struct utrace_engine *engine,unsigned long clone_flags,struct task_struct *child);
u32 (* report_jctl) (u32 action, struct utrace_engine *engine,int type, int notify);
u32 (* report_exec) (u32 action, struct utrace_engine *engine,const struct linux_binfmt *fmt,const struct linux_binprm *bprm,struct pt_regs *regs);
u32 (* report_syscall_entry) (u32 action, struct utrace_engine *engine,struct pt_regs *regs);
u32 (* report_syscall_exit) (u32 action, struct utrace_engine *engine,struct pt_regs *regs);
u32 (* report_exit) (u32 action, struct utrace_engine *engine,long orig_code, long *code);
u32 (* report_death) (struct utrace_engine *engine,bool group_dead, int signal);
void (* report_reap) (struct utrace_engine *engine,struct task_struct *task);
void (* release) (void *data);
}; </pre></div><div class="refsect1" title="Members"><a id="id2889566"></a><h2>Members</h2><div class="variablelist"><dl><dt><span class="term">report_quiesce</span></dt><dd><p>
Requested by <code class="constant">UTRACE_EVENT</code>(<code class="constant">QUIESCE</code>).
This does not indicate any event, but just that <em class="parameter"><code>current</code></em> is in a
safe place for examination. This call is made before each specific
event callback, except for <em class="parameter"><code>report_reap</code></em>. The <em class="parameter"><code>event</code></em> argument gives
the <code class="constant">UTRACE_EVENT</code>(<em class="parameter"><code>which</code></em>) value for the event occurring. This
callback might be made for events <em class="parameter"><code>engine</code></em> has not requested, if
some other engine is tracing the event; calling <code class="function">utrace_set_events</code>
call here can request the immediate callback for this occurrence of
<em class="parameter"><code>event</code></em>. <em class="parameter"><code>event</code></em> is zero when there is no other event, <em class="parameter"><code>current</code></em> is
now ready to check for signals and return to user mode, and some
engine has used <code class="constant">UTRACE_REPORT</code> or <code class="constant">UTRACE_INTERRUPT</code> to request this
callback. For this case, if <em class="parameter"><code>report_signal</code></em> is not <code class="constant">NULL</code>, the
<em class="parameter"><code>report_quiesce</code></em> callback may be replaced with a <em class="parameter"><code>report_signal</code></em>
callback passing <code class="constant">UTRACE_SIGNAL_REPORT</code> in its <em class="parameter"><code>action</code></em> argument,
whenever <em class="parameter"><code>current</code></em> is entering the signal-check path anyway.
</p></dd><dt><span class="term">report_signal</span></dt><dd><p>
Requested by <code class="constant">UTRACE_EVENT</code>(<code class="constant">SIGNAL_</code>*) or <code class="constant">UTRACE_EVENT</code>(<code class="constant">QUIESCE</code>).
Use <code class="function">utrace_signal_action</code> and <code class="function">utrace_resume_action</code> on <em class="parameter"><code>action</code></em>.
The signal action is <code class="constant">UTRACE_SIGNAL_REPORT</code> when some engine has
used <code class="constant">UTRACE_REPORT</code> or <code class="constant">UTRACE_INTERRUPT</code>; the callback can choose
to stop or to deliver an artificial signal, before pending signals.
It's <code class="constant">UTRACE_SIGNAL_HANDLER</code> instead when signal handler setup just
finished (after a previous <code class="constant">UTRACE_SIGNAL_DELIVER</code> return); this
serves in lieu of any <code class="constant">UTRACE_SIGNAL_REPORT</code> callback requested by
<code class="constant">UTRACE_REPORT</code> or <code class="constant">UTRACE_INTERRUPT</code>, and is also implicitly
requested by <code class="constant">UTRACE_SINGLESTEP</code> or <code class="constant">UTRACE_BLOCKSTEP</code> into the
signal delivery. The other signal actions indicate a signal about
to be delivered; the previous engine's return value sets the signal
action seen by the the following engine's callback. The <em class="parameter"><code>info</code></em> data
can be changed at will, including <em class="parameter"><code>info</code></em>->si_signo. The settings in
<em class="parameter"><code>return_ka</code></em> determines what <code class="constant">UTRACE_SIGNAL_DELIVER</code> does. <em class="parameter"><code>orig_ka</code></em>
is what was in force before other tracing engines intervened, and
it's <code class="constant">NULL</code> when this report began as <code class="constant">UTRACE_SIGNAL_REPORT</code> or
<code class="constant">UTRACE_SIGNAL_HANDLER</code>. For a report without a new signal, <em class="parameter"><code>info</code></em>
is left uninitialized and must be set completely by an engine that
chooses to deliver a signal; if there was a previous <em class="parameter"><code>report_signal</code></em>
callback ending in <code class="constant">UTRACE_STOP</code> and it was just resumed using
<code class="constant">UTRACE_REPORT</code> or <code class="constant">UTRACE_INTERRUPT</code>, then <em class="parameter"><code>info</code></em> is left unchanged
from the previous callback. In this way, the original signal can
be left in <em class="parameter"><code>info</code></em> while returning <code class="constant">UTRACE_STOP</code>|<code class="constant">UTRACE_SIGNAL_IGN</code>
and then found again when resuming with <code class="constant">UTRACE_INTERRUPT</code>.
The <code class="constant">UTRACE_SIGNAL_HOLD</code> flag bit can be OR'd into the return value,
and might be in <em class="parameter"><code>action</code></em> if the previous engine returned it. This
flag asks that the signal in <em class="parameter"><code>info</code></em> be pushed back on <em class="parameter"><code>current</code></em>'s queue
so that it will be seen again after whatever action is taken now.
</p></dd><dt><span class="term">report_clone</span></dt><dd><p>
Requested by <code class="constant">UTRACE_EVENT</code>(<code class="constant">CLONE</code>).
Event reported for parent, before the new task <em class="parameter"><code>child</code></em> might run.
<em class="parameter"><code>clone_flags</code></em> gives the flags used in the clone system call, or
equivalent flags for a <code class="function">fork</code> or <code class="function">vfork</code> system call. This
function can use <code class="function">utrace_attach_task</code> on <em class="parameter"><code>child</code></em>. Then passing
<code class="constant">UTRACE_STOP</code> to <code class="function">utrace_control</code> on <em class="parameter"><code>child</code></em> here keeps the child
stopped before it ever runs in user mode, <code class="constant">UTRACE_REPORT</code> or
<code class="constant">UTRACE_INTERRUPT</code> ensures a callback from <em class="parameter"><code>child</code></em> before it
starts in user mode.
</p></dd><dt><span class="term">report_jctl</span></dt><dd><p>
Requested by <code class="constant">UTRACE_EVENT</code>(<code class="constant">JCTL</code>).
Job control event; <em class="parameter"><code>type</code></em> is <code class="constant">CLD_STOPPED</code> or <code class="constant">CLD_CONTINUED</code>,
indicating whether we are stopping or resuming now. If <em class="parameter"><code>notify</code></em>
is nonzero, <em class="parameter"><code>current</code></em> is the last thread to stop and so will send
<code class="constant">SIGCHLD</code> to its parent after this callback; <em class="parameter"><code>notify</code></em> reflects
what the parent's <code class="constant">SIGCHLD</code> has in <em class="parameter"><code>si_code</code></em>, which can sometimes
be <code class="constant">CLD_STOPPED</code> even when <em class="parameter"><code>type</code></em> is <code class="constant">CLD_CONTINUED</code>.
</p></dd><dt><span class="term">report_exec</span></dt><dd><p>
Requested by <code class="constant">UTRACE_EVENT</code>(<code class="constant">EXEC</code>).
An execve system call has succeeded and the new program is about to
start running. The initial user register state is handy to be tweaked
directly in <em class="parameter"><code>regs</code></em>. <em class="parameter"><code>fmt</code></em> and <em class="parameter"><code>bprm</code></em> gives the details of this exec.
</p></dd><dt><span class="term">report_syscall_entry</span></dt><dd><p>
Requested by <code class="constant">UTRACE_EVENT</code>(<code class="constant">SYSCALL_ENTRY</code>).
Thread has entered the kernel to request a system call.
The user register state is handy to be tweaked directly in <em class="parameter"><code>regs</code></em>.
The <em class="parameter"><code>action</code></em> argument contains an <span class="structname">enum</span> utrace_syscall_action,
use <code class="function">utrace_syscall_action</code> to extract it. The return value
overrides the last engine's action for the system call.
If the final action is <code class="constant">UTRACE_SYSCALL_ABORT</code>, no system call
is made. The details of the system call being attempted can
be fetched here with <code class="function">syscall_get_nr</code> and <code class="function">syscall_get_arguments</code>.
The parameter registers can be changed with <code class="function">syscall_set_arguments</code>.
See above about the <code class="constant">UTRACE_SYSCALL_RESUMED</code> flag in <em class="parameter"><code>action</code></em>.
Use <code class="constant">UTRACE_REPORT</code> in the return value to guarantee you get
another callback (with <code class="constant">UTRACE_SYSCALL_RESUMED</code> flag) in case
<em class="parameter"><code>current</code></em> stops with <code class="constant">UTRACE_STOP</code> before attempting the system call.
</p></dd><dt><span class="term">report_syscall_exit</span></dt><dd><p>
Requested by <code class="constant">UTRACE_EVENT</code>(<code class="constant">SYSCALL_EXIT</code>).
Thread is about to leave the kernel after a system call request.
The user register state is handy to be tweaked directly in <em class="parameter"><code>regs</code></em>.
The results of the system call attempt can be examined here using
<code class="function">syscall_get_error</code> and <code class="function">syscall_get_return_value</code>. It is safe
here to call <code class="function">syscall_set_return_value</code> or <code class="function">syscall_rollback</code>.
</p></dd><dt><span class="term">report_exit</span></dt><dd><p>
Requested by <code class="constant">UTRACE_EVENT</code>(<code class="constant">EXIT</code>).
Thread is exiting and cannot be prevented from doing so,
but all its state is still live. The <em class="parameter"><code>code</code></em> value will be
the wait result seen by the parent, and can be changed by
this engine or others. The <em class="parameter"><code>orig_code</code></em> value is the real
status, not changed by any tracing engine. Returning <code class="constant">UTRACE_STOP</code>
here keeps <em class="parameter"><code>current</code></em> stopped before it cleans up its state and dies,
so it can be examined by other processes. When <em class="parameter"><code>current</code></em> is allowed
to run, it will die and get to the <em class="parameter"><code>report_death</code></em> callback.
</p></dd><dt><span class="term">report_death</span></dt><dd><p>
Requested by <code class="constant">UTRACE_EVENT</code>(<code class="constant">DEATH</code>).
Thread is really dead now. It might be reaped by its parent at
any time, or self-reap immediately. Though the actual reaping
may happen in parallel, a <code class="function">report_reap</code> callback will always be
ordered after a <code class="function">report_death</code> callback.
</p></dd><dt><span class="term">report_reap</span></dt><dd><p>
Requested by <code class="constant">UTRACE_EVENT</code>(<code class="constant">REAP</code>).
Called when someone reaps the dead task (parent, init, or self).
This means the parent called wait, or else this was a detached
thread or a process whose parent ignores SIGCHLD.
No more callbacks are made after this one.
The engine is always detached.
There is nothing more a tracing engine can do about this thread.
After this callback, the <em class="parameter"><code>engine</code></em> pointer will become invalid.
The <em class="parameter"><code>task</code></em> pointer may become invalid if <code class="function">get_task_struct</code> hasn't
been used to keep it alive.
An engine should always request this callback if it stores the
<em class="parameter"><code>engine</code></em> pointer or stores any pointer in <em class="parameter"><code>engine</code></em>->data, so it
can clean up its data structures.
Unlike other callbacks, this can be called from the parent's context
rather than from the traced thread itself--it must not delay the
parent by blocking.
</p></dd><dt><span class="term">release</span></dt><dd><p>
If not <code class="constant">NULL</code>, this is called after the last <code class="function">utrace_engine_put</code>
call for a <span class="structname">struct utrace_engine</span>, which could be implicit after
a <code class="constant">UTRACE_DETACH</code> return from another callback. Its argument is
the engine's <em class="parameter"><code>data</code></em> member.
</p></dd></dl></div></div><div class="refsect1" title="Description"><a id="id2890383"></a><h2>Description</h2><p>
</p><p>
Each <em class="parameter"><code>report_</code></em>*() callback corresponds to an <code class="constant">UTRACE_EVENT</code>(*) bit.
<code class="function">utrace_set_events</code> calls on <em class="parameter"><code>engine</code></em> choose which callbacks will
be made to <em class="parameter"><code>engine</code></em> from <em class="parameter"><code>task</code></em>.
</p><p>
Most callbacks take an <em class="parameter"><code>action</code></em> argument, giving the resume action
chosen by other tracing engines. All callbacks take an <em class="parameter"><code>engine</code></em>
argument. The <em class="parameter"><code>report_reap</code></em> callback takes a <em class="parameter"><code>task</code></em> argument that
might or might not be <em class="parameter"><code>current</code></em>. All other <em class="parameter"><code>report_</code></em>* callbacks
report an event in the <em class="parameter"><code>current</code></em> task.
</p><p>
For some calls, <em class="parameter"><code>action</code></em> also includes bits specific to that event
and <code class="function">utrace_resume_action</code> is used to extract the resume action.
This shows what would happen if <em class="parameter"><code>engine</code></em> wasn't there, or will if
the callback's return value uses <code class="constant">UTRACE_RESUME</code>. This always
starts as <code class="constant">UTRACE_RESUME</code> when no other tracing is being done on
this task.
</p><p>
All return values contain <span class="structname">enum</span> utrace_resume_action bits. For
some calls, other bits specific to that kind of event are added to
the resume action bits with OR. These are the same bits used in
the <em class="parameter"><code>action</code></em> argument. The resume action returned by a callback
does not override previous engines' choices, it only says what
<em class="parameter"><code>engine</code></em> wants done. What <em class="parameter"><code>current</code></em> actually does is the action that's
most constrained among the choices made by all attached engines.
See <code class="function">utrace_control</code> for more information on the actions.
</p><p>
When <code class="constant">UTRACE_STOP</code> is used in <em class="parameter"><code>report_syscall_entry</code></em>, then <em class="parameter"><code>current</code></em>
stops before attempting the system call. In this case, another
<em class="parameter"><code>report_syscall_entry</code></em> callback will follow after <em class="parameter"><code>current</code></em> resumes if
<code class="constant">UTRACE_REPORT</code> or <code class="constant">UTRACE_INTERRUPT</code> was returned by some callback
or passed to <code class="function">utrace_control</code>. In a second or later callback,
<code class="constant">UTRACE_SYSCALL_RESUMED</code> is set in the <em class="parameter"><code>action</code></em> argument to indicate
a repeat callback still waiting to attempt the same system call
invocation. This repeat callback gives each engine an opportunity
to reexamine registers another engine might have changed while
<em class="parameter"><code>current</code></em> was held in <code class="constant">UTRACE_STOP</code>.
</p><p>
In other cases, the resume action does not take effect until <em class="parameter"><code>current</code></em>
is ready to check for signals and return to user mode. If there
are more callbacks to be made, the last round of calls determines
the final action. A <em class="parameter"><code>report_quiesce</code></em> callback with <em class="parameter"><code>event</code></em> zero, or
a <em class="parameter"><code>report_signal</code></em> callback, will always be the last one made before
<em class="parameter"><code>current</code></em> resumes. Only <code class="constant">UTRACE_STOP</code> is <span class="quote">“<span class="quote">sticky</span>”</span>--if <em class="parameter"><code>engine</code></em> returned
<code class="constant">UTRACE_STOP</code> then <em class="parameter"><code>current</code></em> stays stopped unless <em class="parameter"><code>engine</code></em> returns
different from a following callback.
</p><p>
The <code class="function">report_death</code> and <code class="function">report_reap</code> callbacks do not take <em class="parameter"><code>action</code></em>
arguments, and only <code class="constant">UTRACE_DETACH</code> is meaningful in the return value
from a <code class="function">report_death</code> callback. None of the resume actions applies
to a dead thread.
</p><p>
All <em class="parameter"><code>report_</code></em>*() hooks are called with no locks held, in a generally
safe environment when we will be returning to user mode soon (or just
entered the kernel). It is fine to block for memory allocation and
the like, but all hooks are asynchronous and must not block on
external events! If you want the thread to block, use <code class="constant">UTRACE_STOP</code>
in your hook's return value; then later wake it up with <code class="function">utrace_control</code>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="re09.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="re11.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span>utrace_engine_put</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span>struct utrace_examiner</span></td></tr></table></div></body></html>
