<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
<book id="utrace">
<bookinfo>
<title>The utrace User Debugging Infrastructure</title>
</bookinfo>
<toc></toc>
<chapter id="concepts"><title>utrace concepts</title>
<sect1 id="intro"><title>Introduction</title>
<para>
<application>utrace</application> is infrastructure code for tracing
and controlling user threads. This is the foundation for writing
tracing engines, which can be loadable kernel modules.
</para>
<para>
The basic actors in <application>utrace</application> are the thread
and the tracing engine. A tracing engine is some body of code that
calls into the <filename><linux/utrace.h></filename>
interfaces, represented by a <structname>struct
utrace_engine_ops</structname>. (Usually it's a kernel module,
though the legacy <function>ptrace</function> support is a tracing
engine that is not in a kernel module.) The interface operates on
individual threads (<structname>struct task_struct</structname>).
If an engine wants to treat several threads as a group, that is up
to its higher-level code.
</para>
<para>
Tracing begins by attaching an engine to a thread, using
<function>utrace_attach_task</function> or
<function>utrace_attach_pid</function>. If successful, it returns a
pointer that is the handle used in all other calls.
</para>
</sect1>
<sect1 id="callbacks"><title>Events and Callbacks</title>
<para>
An attached engine does nothing by default. An engine makes something
happen by requesting callbacks via <function>utrace_set_events</function>
and poking the thread with <function>utrace_control</function>.
The synchronization issues related to these two calls
are discussed further below in <xref linkend="teardown"/>.
</para>
<para>
Events are specified using the macro
<constant>UTRACE_EVENT(<replaceable>type</replaceable>)</constant>.
Each event type is associated with a callback in <structname>struct
utrace_engine_ops</structname>. A tracing engine can leave unused
callbacks <constant>NULL</constant>. The only callbacks required
are those used by the event flags it sets.
</para>
<para>
Many engines can be attached to each thread. When a thread has an
event, each engine gets a callback if it has set the event flag for
that event type. For most events, engines are called in the order they
attached. Engines that attach after the event has occurred do not get
callbacks for that event. This includes any new engines just attached
by an existing engine's callback function. Once the sequence of
callbacks for that one event has completed, such new engines are then
eligible in the next sequence that starts when there is another event.
</para>
<para>
Event reporting callbacks have details particular to the event type,
but are all called in similar environments and have the same
constraints. Callbacks are made from safe points, where no locks
are held, no special resources are pinned (usually), and the
user-mode state of the thread is accessible. So, callback code has
a pretty free hand. But to be a good citizen, callback code should
never block for long periods. It is fine to block in
<function>kmalloc</function> and the like, but never wait for i/o or
for user mode to do something. If you need the thread to wait, use
<constant>UTRACE_STOP</constant> and return from the callback
quickly. When your i/o finishes or whatever, you can use
<function>utrace_control</function> to resume the thread.
</para>
<para>
The <constant>UTRACE_EVENT(SYSCALL_ENTRY)</constant> event is a special
case. While other events happen in the kernel when it will return to
user mode soon, this event happens when entering the kernel before it
will proceed with the work requested from user mode. Because of this
difference, the <function>report_syscall_entry</function> callback is
special in two ways. For this event, engines are called in reverse of
the normal order (this includes the <function>report_quiesce</function>
call that precedes a <function>report_syscall_entry</function> call).
This preserves the semantics that the last engine to attach is called
"closest to user mode"--the engine that is first to see a thread's user
state when it enters the kernel is also the last to see that state when
the thread returns to user mode. For the same reason, if these
callbacks use <constant>UTRACE_STOP</constant> (see the next section),
the thread stops immediately after callbacks rather than only when it's
ready to return to user mode; when allowed to resume, it will actually
attempt the system call indicated by the register values at that time.
</para>
</sect1>
<sect1 id="safely"><title>Stopping Safely</title>
<sect2 id="well-behaved"><title>Writing well-behaved callbacks</title>
<para>
Well-behaved callbacks are important to maintain two essential
properties of the interface. The first of these is that unrelated
tracing engines should not interfere with each other. If your engine's
event callback does not return quickly, then another engine won't get
the event notification in a timely manner. The second important
property is that tracing should be as noninvasive as possible to the
normal operation of the system overall and of the traced thread in
particular. That is, attached tracing engines should not perturb a
thread's behavior, except to the extent that changing its user-visible
state is explicitly what you want to do. (Obviously some perturbation
is unavoidable, primarily timing changes, ranging from small delays due
to the overhead of tracing, to arbitrary pauses in user code execution
when a user stops a thread with a debugger for examination.) Even when
you explicitly want the perturbation of making the traced thread block,
just blocking directly in your callback has more unwanted effects. For
example, the <constant>CLONE</constant> event callbacks are called when
the new child thread has been created but not yet started running; the
child can never be scheduled until the <constant>CLONE</constant>
tracing callbacks return. (This allows engines tracing the parent to
attach to the child.) If a <constant>CLONE</constant> event callback
blocks the parent thread, it also prevents the child thread from
running (even to process a <constant>SIGKILL</constant>). If what you
want is to make both the parent and child block, then use
<function>utrace_attach_task</function> on the child and then use
<constant>UTRACE_STOP</constant> on both threads. A more crucial
problem with blocking in callbacks is that it can prevent
<constant>SIGKILL</constant> from working. A thread that is blocking
due to <constant>UTRACE_STOP</constant> will still wake up and die
immediately when sent a <constant>SIGKILL</constant>, as all threads
should. Relying on the <application>utrace</application>
infrastructure rather than on private synchronization calls in event
callbacks is an important way to help keep tracing robustly
noninvasive.
</para>
</sect2>
<sect2 id="UTRACE_STOP"><title>Using <constant>UTRACE_STOP</constant></title>
<para>
To control another thread and access its state, it must be stopped
with <constant>UTRACE_STOP</constant>. This means that it is
stopped and won't start running again while we access it. When a
thread is not already stopped, <function>utrace_control</function>
returns <constant>-EINPROGRESS</constant> and an engine must wait
for an event callback when the thread is ready to stop. The thread
may be running on another CPU or may be blocked. When it is ready
to be examined, it will make callbacks to engines that set the
<constant>UTRACE_EVENT(QUIESCE)</constant> event bit. To wake up an
interruptible wait, use <constant>UTRACE_INTERRUPT</constant>.
</para>
<para>
As long as some engine has used <constant>UTRACE_STOP</constant> and
not called <function>utrace_control</function> to resume the thread,
then the thread will remain stopped. <constant>SIGKILL</constant>
will wake it up, but it will not run user code. When the stop is
cleared with <function>utrace_control</function> or a callback
return value, the thread starts running again.
(See also <xref linkend="teardown"/>.)
</para>
</sect2>
</sect1>
<sect1 id="teardown"><title>Tear-down Races</title>
<sect2 id="SIGKILL"><title>Primacy of <constant>SIGKILL</constant></title>
<para>
Ordinarily synchronization issues for tracing engines are kept fairly
straightforward by using <constant>UTRACE_STOP</constant>. You ask a
thread to stop, and then once it makes the
<function>report_quiesce</function> callback it cannot do anything else
that would result in another callback, until you let it with a
<function>utrace_control</function> call. This simple arrangement
avoids complex and error-prone code in each one of a tracing engine's
event callbacks to keep them serialized with the engine's other
operations done on that thread from another thread of control.
However, giving tracing engines complete power to keep a traced thread
stuck in place runs afoul of a more important kind of simplicity that
the kernel overall guarantees: nothing can prevent or delay
<constant>SIGKILL</constant> from making a thread die and release its
resources. To preserve this important property of
<constant>SIGKILL</constant>, it as a special case can break
<constant>UTRACE_STOP</constant> like nothing else normally can. This
includes both explicit <constant>SIGKILL</constant> signals and the
implicit <constant>SIGKILL</constant> sent to each other thread in the
same thread group by a thread doing an exec, or processing a fatal
signal, or making an <function>exit_group</function> system call. A
tracing engine can prevent a thread from beginning the exit or exec or
dying by signal (other than <constant>SIGKILL</constant>) if it is
attached to that thread, but once the operation begins, no tracing
engine can prevent or delay all other threads in the same thread group
dying.
</para>
</sect2>
<sect2 id="reap"><title>Final callbacks</title>
<para>
The <function>report_reap</function> callback is always the final event
in the life cycle of a traced thread. Tracing engines can use this as
the trigger to clean up their own data structures. The
<function>report_death</function> callback is always the penultimate
event a tracing engine might see; it's seen unless the thread was
already in the midst of dying when the engine attached. Many tracing
engines will have no interest in when a parent reaps a dead process,
and nothing they want to do with a zombie thread once it dies; for
them, the <function>report_death</function> callback is the natural
place to clean up data structures and detach. To facilitate writing
such engines robustly, given the asynchrony of
<constant>SIGKILL</constant>, and without error-prone manual
implementation of synchronization schemes, the
<application>utrace</application> infrastructure provides some special
guarantees about the <function>report_death</function> and
<function>report_reap</function> callbacks. It still takes some care
to be sure your tracing engine is robust to tear-down races, but these
rules make it reasonably straightforward and concise to handle a lot of
corner cases correctly.
</para>
</sect2>
<sect2 id="refcount"><title>Engine and task pointers</title>
<para>
The first sort of guarantee concerns the core data structures
themselves. <structname>struct utrace_engine</structname> is
a reference-counted data structure. While you hold a reference, an
engine pointer will always stay valid so that you can safely pass it to
any <application>utrace</application> call. Each call to
<function>utrace_attach_task</function> or
<function>utrace_attach_pid</function> returns an engine pointer with a
reference belonging to the caller. You own that reference until you
drop it using <function>utrace_engine_put</function>. There is an
implicit reference on the engine while it is attached. So if you drop
your only reference, and then use
<function>utrace_attach_task</function> without
<constant>UTRACE_ATTACH_CREATE</constant> to look up that same engine,
you will get the same pointer with a new reference to replace the one
you dropped, just like calling <function>utrace_engine_get</function>.
When an engine has been detached, either explicitly with
<constant>UTRACE_DETACH</constant> or implicitly after
<function>report_reap</function>, then any references you hold are all
that keep the old engine pointer alive.
</para>
<para>
There is nothing a kernel module can do to keep a <structname>struct
task_struct</structname> alive outside of
<function>rcu_read_lock</function>. When the task dies and is reaped
by its parent (or itself), that structure can be freed so that any
dangling pointers you have stored become invalid.
<application>utrace</application> will not prevent this, but it can
help you detect it safely. By definition, a task that has been reaped
has had all its engines detached. All
<application>utrace</application> calls can be safely called on a
detached engine if the caller holds a reference on that engine pointer,
even if the task pointer passed in the call is invalid. All calls
return <constant>-ESRCH</constant> for a detached engine, which tells
you that the task pointer you passed could be invalid now. Since
<function>utrace_control</function> and
<function>utrace_set_events</function> do not block, you can call those
inside a <function>rcu_read_lock</function> section and be sure after
they don't return <constant>-ESRCH</constant> that the task pointer is
still valid until <function>rcu_read_unlock</function>. The
infrastructure never holds task references of its own. Though neither
<function>rcu_read_lock</function> nor any other lock is held while
making a callback, it's always guaranteed that the <structname>struct
task_struct</structname> and the <structname>struct
utrace_engine</structname> passed as arguments remain valid
until the callback function returns.
</para>
<para>
The common means for safely holding task pointers that is available to
kernel modules is to use <structname>struct pid</structname>, which
permits <function>put_pid</function> from kernel modules. When using
that, the calls <function>utrace_attach_pid</function>,
<function>utrace_control_pid</function>,
<function>utrace_set_events_pid</function>, and
<function>utrace_barrier_pid</function> are available.
</para>
</sect2>
<sect2 id="reap-after-death">
<title>
Serialization of <constant>DEATH</constant> and <constant>REAP</constant>
</title>
<para>
The second guarantee is the serialization of
<constant>DEATH</constant> and <constant>REAP</constant> event
callbacks for a given thread. The actual reaping by the parent
(<function>release_task</function> call) can occur simultaneously
while the thread is still doing the final steps of dying, including
the <function>report_death</function> callback. If a tracing engine
has requested both <constant>DEATH</constant> and
<constant>REAP</constant> event reports, it's guaranteed that the
<function>report_reap</function> callback will not be made until
after the <function>report_death</function> callback has returned.
If the <function>report_death</function> callback itself detaches
from the thread, then the <function>report_reap</function> callback
will never be made. Thus it is safe for a
<function>report_death</function> callback to clean up data
structures and detach.
</para>
</sect2>
<sect2 id="interlock"><title>Interlock with final callbacks</title>
<para>
The final sort of guarantee is that a tracing engine will know for sure
whether or not the <function>report_death</function> and/or
<function>report_reap</function> callbacks will be made for a certain
thread. These tear-down races are disambiguated by the error return
values of <function>utrace_set_events</function> and
<function>utrace_control</function>. Normally
<function>utrace_control</function> called with
<constant>UTRACE_DETACH</constant> returns zero, and this means that no
more callbacks will be made. If the thread is in the midst of dying,
it returns <constant>-EALREADY</constant> to indicate that the
<constant>report_death</constant> callback may already be in progress;
when you get this error, you know that any cleanup your
<function>report_death</function> callback does is about to happen or
has just happened--note that if the <function>report_death</function>
callback does not detach, the engine remains attached until the thread
gets reaped. If the thread is in the midst of being reaped,
<function>utrace_control</function> returns <constant>-ESRCH</constant>
to indicate that the <function>report_reap</function> callback may
already be in progress; this means the engine is implicitly detached
when the callback completes. This makes it possible for a tracing
engine that has decided asynchronously to detach from a thread to
safely clean up its data structures, knowing that no
<function>report_death</function> or <function>report_reap</function>
callback will try to do the same. <constant>utrace_detach</constant>
returns <constant>-ESRCH</constant> when the <structname>struct
utrace_engine</structname> has already been detached, but is
still a valid pointer because of its reference count. A tracing engine
can use this to safely synchronize its own independent multiple threads
of control with each other and with its event callbacks that detach.
</para>
<para>
In the same vein, <function>utrace_set_events</function> normally
returns zero; if the target thread was stopped before the call, then
after a successful call, no event callbacks not requested in the new
flags will be made. It fails with <constant>-EALREADY</constant> if
you try to clear <constant>UTRACE_EVENT(DEATH)</constant> when the
<function>report_death</function> callback may already have begun, if
you try to clear <constant>UTRACE_EVENT(REAP)</constant> when the
<function>report_reap</function> callback may already have begun, or if
you try to newly set <constant>UTRACE_EVENT(DEATH)</constant> or
<constant>UTRACE_EVENT(QUIESCE)</constant> when the target is already
dead or dying. Like <function>utrace_control</function>, it returns
<constant>-ESRCH</constant> when the thread has already been detached
(including forcible detach on reaping). This lets the tracing engine
know for sure which event callbacks it will or won't see after
<function>utrace_set_events</function> has returned. By checking for
errors, it can know whether to clean up its data structures immediately
or to let its callbacks do the work.
</para>
</sect2>
<sect2 id="barrier"><title>Using <function>utrace_barrier</function></title>
<para>
When a thread is safely stopped, calling
<function>utrace_control</function> with <constant>UTRACE_DETACH</constant>
or calling <function>utrace_set_events</function> to disable some events
ensures synchronously that your engine won't get any more of the callbacks
that have been disabled (none at all when detaching). But these can also
be used while the thread is not stopped, when it might be simultaneously
making a callback to your engine. For this situation, these calls return
<constant>-EINPROGRESS</constant> when it's possible a callback is in
progress. If you are not prepared to have your old callbacks still run,
then you can synchronize to be sure all the old callbacks are finished,
using <function>utrace_barrier</function>. This is necessary if the
kernel module containing your callback code is going to be unloaded.
</para>
<para>
After using <constant>UTRACE_DETACH</constant> once, further calls to
<function>utrace_control</function> with the same engine pointer will
return <constant>-ESRCH</constant>. In contrast, after getting
<constant>-EINPROGRESS</constant> from
<function>utrace_set_events</function>, you can call
<function>utrace_set_events</function> again later and if it returns zero
then know the old callbacks have finished.
</para>
<para>
Unlike all other calls, <function>utrace_barrier</function> (and
<function>utrace_barrier_pid</function>) will accept any engine pointer you
hold a reference on, even if <constant>UTRACE_DETACH</constant> has already
been used. After any <function>utrace_control</function> or
<function>utrace_set_events</function> call (these do not block), you can
call <function>utrace_barrier</function> to block until callbacks have
finished. This returns <constant>-ESRCH</constant> only if the engine is
completely detached (finished all callbacks). Otherwise it waits
until the thread is definitely not in the midst of a callback to this
engine and then returns zero, but can return
<constant>-ERESTARTSYS</constant> if its wait is interrupted.
</para>
</sect2>
</sect1>
</chapter>
<chapter id="core"><title>utrace core API</title>
<para>
The utrace API is declared in <filename><linux/utrace.h></filename>.
</para>
<!-- include/linux/utrace.h -->
<refentry id="API-enum-utrace-resume-action">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>enum utrace_resume_action</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>enum utrace_resume_action</refname>
<refpurpose>
engine's choice of action for a traced task
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
enum utrace_resume_action {
UTRACE_STOP,
UTRACE_INTERRUPT,
UTRACE_REPORT,
UTRACE_SINGLESTEP,
UTRACE_BLOCKSTEP,
UTRACE_RESUME,
UTRACE_DETACH,
UTRACE_RESUME_MAX
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Constants</title>
<variablelist>
<varlistentry> <term>UTRACE_STOP</term>
<listitem><para>
Stay quiescent after callbacks.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_INTERRUPT</term>
<listitem><para>
Make <parameter>report_signal</parameter>() callback soon.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_REPORT</term>
<listitem><para>
Make some callback soon.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_SINGLESTEP</term>
<listitem><para>
Resume in user mode for one instruction.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_BLOCKSTEP</term>
<listitem><para>
Resume in user mode until next branch.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_RESUME</term>
<listitem><para>
Resume normally in user mode.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_DETACH</term>
<listitem><para>
Detach my engine (implies <constant>UTRACE_RESUME</constant>).
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_RESUME_MAX</term>
<listitem><para>
-- undescribed --
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
See <function>utrace_control</function> for detailed descriptions of each action. This is
encoded in the <parameter>action</parameter> argument and the return value for every callback
with a <structname>u32</structname> return value.
</para><para>
The order of these is important. When there is more than one engine,
each supplies its choice and the smallest value prevails.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-resume-action">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_resume_action</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_resume_action</refname>
<refpurpose>
<structname>enum</structname> utrace_resume_action from callback action
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>enum utrace_resume_action <function>utrace_resume_action </function></funcdef>
<paramdef>u32 <parameter>action</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>action</parameter></term>
<listitem>
<para>
<structname>u32</structname> callback <parameter>action</parameter> argument or return value
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This extracts the <structname>enum</structname> utrace_resume_action from <parameter>action</parameter>,
which is the <parameter>action</parameter> argument to a <structname>struct utrace_engine_ops</structname>
callback or the return value from one.
</para>
</refsect1>
</refentry>
<refentry id="API-enum-utrace-signal-action">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>enum utrace_signal_action</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>enum utrace_signal_action</refname>
<refpurpose>
disposition of signal
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
enum utrace_signal_action {
UTRACE_SIGNAL_DELIVER,
UTRACE_SIGNAL_IGN,
UTRACE_SIGNAL_TERM,
UTRACE_SIGNAL_CORE,
UTRACE_SIGNAL_STOP,
UTRACE_SIGNAL_TSTP,
UTRACE_SIGNAL_REPORT,
UTRACE_SIGNAL_HANDLER
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Constants</title>
<variablelist>
<varlistentry> <term>UTRACE_SIGNAL_DELIVER</term>
<listitem><para>
Deliver according to sigaction.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_SIGNAL_IGN</term>
<listitem><para>
Ignore the signal.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_SIGNAL_TERM</term>
<listitem><para>
Terminate the process.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_SIGNAL_CORE</term>
<listitem><para>
Terminate with core dump.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_SIGNAL_STOP</term>
<listitem><para>
Deliver as absolute stop.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_SIGNAL_TSTP</term>
<listitem><para>
Deliver as job control stop.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_SIGNAL_REPORT</term>
<listitem><para>
Reporting before pending signals.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_SIGNAL_HANDLER</term>
<listitem><para>
Reporting after signal handler setup.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is encoded in the <parameter>action</parameter> argument and the return value for
a <parameter>report_signal</parameter>() callback. It says what will happen to the
signal described by the <structname>siginfo_t</structname> parameter to the callback.
</para><para>
The <constant>UTRACE_SIGNAL_REPORT</constant> value is used in an <parameter>action</parameter> argument when
a tracing report is being made before dequeuing any pending signal.
If this is immediately after a signal handler has been set up, then
<constant>UTRACE_SIGNAL_HANDLER</constant> is used instead. A <parameter>report_signal</parameter> callback
that uses <constant>UTRACE_SIGNAL_DELIVER</constant>|<constant>UTRACE_SINGLESTEP</constant> will ensure
it sees a <constant>UTRACE_SIGNAL_HANDLER</constant> report.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-signal-action">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_signal_action</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_signal_action</refname>
<refpurpose>
<structname>enum</structname> utrace_signal_action from callback action
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>enum utrace_signal_action <function>utrace_signal_action </function></funcdef>
<paramdef>u32 <parameter>action</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>action</parameter></term>
<listitem>
<para>
<parameter>report_signal</parameter> callback <parameter>action</parameter> argument or return value
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This extracts the <structname>enum</structname> utrace_signal_action from <parameter>action</parameter>, which
is the <parameter>action</parameter> argument to a <parameter>report_signal</parameter> callback or the
return value from one.
</para>
</refsect1>
</refentry>
<refentry id="API-enum-utrace-syscall-action">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>enum utrace_syscall_action</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>enum utrace_syscall_action</refname>
<refpurpose>
disposition of system call attempt
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
enum utrace_syscall_action {
UTRACE_SYSCALL_RUN,
UTRACE_SYSCALL_ABORT
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Constants</title>
<variablelist>
<varlistentry> <term>UTRACE_SYSCALL_RUN</term>
<listitem><para>
Run the system call.
</para></listitem>
</varlistentry>
<varlistentry> <term>UTRACE_SYSCALL_ABORT</term>
<listitem><para>
Don't run the system call.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is encoded in the <parameter>action</parameter> argument and the return value for
a <parameter>report_syscall_entry</parameter> callback.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-syscall-action">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_syscall_action</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_syscall_action</refname>
<refpurpose>
<structname>enum</structname> utrace_syscall_action from callback action
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>enum utrace_syscall_action <function>utrace_syscall_action </function></funcdef>
<paramdef>u32 <parameter>action</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>action</parameter></term>
<listitem>
<para>
<parameter>report_syscall_entry</parameter> callback <parameter>action</parameter> or return value
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This extracts the <structname>enum</structname> utrace_syscall_action from <parameter>action</parameter>, which
is the <parameter>action</parameter> argument to a <parameter>report_syscall_entry</parameter> callback or the
return value from one.
</para>
</refsect1>
</refentry>
<refentry id="API-struct-utrace-engine">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct utrace_engine</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct utrace_engine</refname>
<refpurpose>
per-engine structure
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct utrace_engine {
const struct utrace_engine_ops * ops;
void * data;
unsigned long flags;
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>ops</term>
<listitem><para>
<structname>struct utrace_engine_ops</structname> pointer passed to <function>utrace_attach_task</function>
</para></listitem>
</varlistentry>
<varlistentry> <term>data</term>
<listitem><para>
engine-private <structname>void</structname> * passed to <function>utrace_attach_task</function>
</para></listitem>
</varlistentry>
<varlistentry> <term>flags</term>
<listitem><para>
event mask set by <function>utrace_set_events</function> plus internal flag bits
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
The task itself never has to worry about engines detaching while
it's doing event callbacks. These structures are removed from the
task's active list only when it's stopped, or by the task itself.
</para><para>
<function>utrace_engine_get</function> and <function>utrace_engine_put</function> maintain a reference count.
When it drops to zero, the structure is freed. One reference is held
implicitly while the engine is attached to its task.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-engine-get">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_engine_get</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_engine_get</refname>
<refpurpose>
acquire a reference on a <structname>struct utrace_engine</structname>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>utrace_engine_get </function></funcdef>
<paramdef>struct utrace_engine * <parameter>engine</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>engine</parameter></term>
<listitem>
<para>
<structname>struct utrace_engine</structname> pointer
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
You must hold a reference on <parameter>engine</parameter>, and you get another.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-engine-put">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_engine_put</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_engine_put</refname>
<refpurpose>
release a reference on a <structname>struct utrace_engine</structname>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>utrace_engine_put </function></funcdef>
<paramdef>struct utrace_engine * <parameter>engine</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>engine</parameter></term>
<listitem>
<para>
<structname>struct utrace_engine</structname> pointer
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
You must hold a reference on <parameter>engine</parameter>, and you lose that reference.
If it was the last one, <parameter>engine</parameter> becomes an invalid pointer.
</para>
</refsect1>
</refentry>
<refentry id="API-struct-utrace-engine-ops">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct utrace_engine_ops</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct utrace_engine_ops</refname>
<refpurpose>
tracing engine callbacks
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<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);
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>report_quiesce</term>
<listitem><para>
Requested by <constant>UTRACE_EVENT</constant>(<constant>QUIESCE</constant>).
This does not indicate any event, but just that <parameter>current</parameter> is in a
safe place for examination. This call is made before each specific
event callback, except for <parameter>report_reap</parameter>. The <parameter>event</parameter> argument gives
the <constant>UTRACE_EVENT</constant>(<parameter>which</parameter>) value for the event occurring. This
callback might be made for events <parameter>engine</parameter> has not requested, if
some other engine is tracing the event; calling <function>utrace_set_events</function>
call here can request the immediate callback for this occurrence of
<parameter>event</parameter>. <parameter>event</parameter> is zero when there is no other event, <parameter>current</parameter> is
now ready to check for signals and return to user mode, and some
engine has used <constant>UTRACE_REPORT</constant> or <constant>UTRACE_INTERRUPT</constant> to request this
callback. For this case, if <parameter>report_signal</parameter> is not <constant>NULL</constant>, the
<parameter>report_quiesce</parameter> callback may be replaced with a <parameter>report_signal</parameter>
callback passing <constant>UTRACE_SIGNAL_REPORT</constant> in its <parameter>action</parameter> argument,
whenever <parameter>current</parameter> is entering the signal-check path anyway.
</para></listitem>
</varlistentry>
<varlistentry> <term>report_signal</term>
<listitem><para>
Requested by <constant>UTRACE_EVENT</constant>(<constant>SIGNAL_</constant>*) or <constant>UTRACE_EVENT</constant>(<constant>QUIESCE</constant>).
Use <function>utrace_signal_action</function> and <function>utrace_resume_action</function> on <parameter>action</parameter>.
The signal action is <constant>UTRACE_SIGNAL_REPORT</constant> when some engine has
used <constant>UTRACE_REPORT</constant> or <constant>UTRACE_INTERRUPT</constant>; the callback can choose
to stop or to deliver an artificial signal, before pending signals.
It's <constant>UTRACE_SIGNAL_HANDLER</constant> instead when signal handler setup just
finished (after a previous <constant>UTRACE_SIGNAL_DELIVER</constant> return); this
serves in lieu of any <constant>UTRACE_SIGNAL_REPORT</constant> callback requested by
<constant>UTRACE_REPORT</constant> or <constant>UTRACE_INTERRUPT</constant>, and is also implicitly
requested by <constant>UTRACE_SINGLESTEP</constant> or <constant>UTRACE_BLOCKSTEP</constant> 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 <parameter>info</parameter> data
can be changed at will, including <parameter>info</parameter>->si_signo. The settings in
<parameter>return_ka</parameter> determines what <constant>UTRACE_SIGNAL_DELIVER</constant> does. <parameter>orig_ka</parameter>
is what was in force before other tracing engines intervened, and
it's <constant>NULL</constant> when this report began as <constant>UTRACE_SIGNAL_REPORT</constant> or
<constant>UTRACE_SIGNAL_HANDLER</constant>. For a report without a new signal, <parameter>info</parameter>
is left uninitialized and must be set completely by an engine that
chooses to deliver a signal; if there was a previous <parameter>report_signal</parameter>
callback ending in <constant>UTRACE_STOP</constant> and it was just resumed using
<constant>UTRACE_REPORT</constant> or <constant>UTRACE_INTERRUPT</constant>, then <parameter>info</parameter> is left unchanged
from the previous callback. In this way, the original signal can
be left in <parameter>info</parameter> while returning <constant>UTRACE_STOP</constant>|<constant>UTRACE_SIGNAL_IGN</constant>
and then found again when resuming with <constant>UTRACE_INTERRUPT</constant>.
The <constant>UTRACE_SIGNAL_HOLD</constant> flag bit can be OR'd into the return value,
and might be in <parameter>action</parameter> if the previous engine returned it. This
flag asks that the signal in <parameter>info</parameter> be pushed back on <parameter>current</parameter>'s queue
so that it will be seen again after whatever action is taken now.
</para></listitem>
</varlistentry>
<varlistentry> <term>report_clone</term>
<listitem><para>
Requested by <constant>UTRACE_EVENT</constant>(<constant>CLONE</constant>).
Event reported for parent, before the new task <parameter>child</parameter> might run.
<parameter>clone_flags</parameter> gives the flags used in the clone system call, or
equivalent flags for a <function>fork</function> or <function>vfork</function> system call. This
function can use <function>utrace_attach_task</function> on <parameter>child</parameter>. Then passing
<constant>UTRACE_STOP</constant> to <function>utrace_control</function> on <parameter>child</parameter> here keeps the child
stopped before it ever runs in user mode, <constant>UTRACE_REPORT</constant> or
<constant>UTRACE_INTERRUPT</constant> ensures a callback from <parameter>child</parameter> before it
starts in user mode.
</para></listitem>
</varlistentry>
<varlistentry> <term>report_jctl</term>
<listitem><para>
Requested by <constant>UTRACE_EVENT</constant>(<constant>JCTL</constant>).
Job control event; <parameter>type</parameter> is <constant>CLD_STOPPED</constant> or <constant>CLD_CONTINUED</constant>,
indicating whether we are stopping or resuming now. If <parameter>notify</parameter>
is nonzero, <parameter>current</parameter> is the last thread to stop and so will send
<constant>SIGCHLD</constant> to its parent after this callback; <parameter>notify</parameter> reflects
what the parent's <constant>SIGCHLD</constant> has in <parameter>si_code</parameter>, which can sometimes
be <constant>CLD_STOPPED</constant> even when <parameter>type</parameter> is <constant>CLD_CONTINUED</constant>.
</para></listitem>
</varlistentry>
<varlistentry> <term>report_exec</term>
<listitem><para>
Requested by <constant>UTRACE_EVENT</constant>(<constant>EXEC</constant>).
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 <parameter>regs</parameter>. <parameter>fmt</parameter> and <parameter>bprm</parameter> gives the details of this exec.
</para></listitem>
</varlistentry>
<varlistentry> <term>report_syscall_entry</term>
<listitem><para>
Requested by <constant>UTRACE_EVENT</constant>(<constant>SYSCALL_ENTRY</constant>).
Thread has entered the kernel to request a system call.
The user register state is handy to be tweaked directly in <parameter>regs</parameter>.
The <parameter>action</parameter> argument contains an <structname>enum</structname> utrace_syscall_action,
use <function>utrace_syscall_action</function> to extract it. The return value
overrides the last engine's action for the system call.
If the final action is <constant>UTRACE_SYSCALL_ABORT</constant>, no system call
is made. The details of the system call being attempted can
be fetched here with <function>syscall_get_nr</function> and <function>syscall_get_arguments</function>.
The parameter registers can be changed with <function>syscall_set_arguments</function>.
See above about the <constant>UTRACE_SYSCALL_RESUMED</constant> flag in <parameter>action</parameter>.
Use <constant>UTRACE_REPORT</constant> in the return value to guarantee you get
another callback (with <constant>UTRACE_SYSCALL_RESUMED</constant> flag) in case
<parameter>current</parameter> stops with <constant>UTRACE_STOP</constant> before attempting the system call.
</para></listitem>
</varlistentry>
<varlistentry> <term>report_syscall_exit</term>
<listitem><para>
Requested by <constant>UTRACE_EVENT</constant>(<constant>SYSCALL_EXIT</constant>).
Thread is about to leave the kernel after a system call request.
The user register state is handy to be tweaked directly in <parameter>regs</parameter>.
The results of the system call attempt can be examined here using
<function>syscall_get_error</function> and <function>syscall_get_return_value</function>. It is safe
here to call <function>syscall_set_return_value</function> or <function>syscall_rollback</function>.
</para></listitem>
</varlistentry>
<varlistentry> <term>report_exit</term>
<listitem><para>
Requested by <constant>UTRACE_EVENT</constant>(<constant>EXIT</constant>).
Thread is exiting and cannot be prevented from doing so,
but all its state is still live. The <parameter>code</parameter> value will be
the wait result seen by the parent, and can be changed by
this engine or others. The <parameter>orig_code</parameter> value is the real
status, not changed by any tracing engine. Returning <constant>UTRACE_STOP</constant>
here keeps <parameter>current</parameter> stopped before it cleans up its state and dies,
so it can be examined by other processes. When <parameter>current</parameter> is allowed
to run, it will die and get to the <parameter>report_death</parameter> callback.
</para></listitem>
</varlistentry>
<varlistentry> <term>report_death</term>
<listitem><para>
Requested by <constant>UTRACE_EVENT</constant>(<constant>DEATH</constant>).
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 <function>report_reap</function> callback will always be
ordered after a <function>report_death</function> callback.
</para></listitem>
</varlistentry>
<varlistentry> <term>report_reap</term>
<listitem><para>
Requested by <constant>UTRACE_EVENT</constant>(<constant>REAP</constant>).
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 <parameter>engine</parameter> pointer will become invalid.
The <parameter>task</parameter> pointer may become invalid if <function>get_task_struct</function> hasn't
been used to keep it alive.
An engine should always request this callback if it stores the
<parameter>engine</parameter> pointer or stores any pointer in <parameter>engine</parameter>->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.
</para></listitem>
</varlistentry>
<varlistentry> <term>release</term>
<listitem><para>
If not <constant>NULL</constant>, this is called after the last <function>utrace_engine_put</function>
call for a <structname>struct utrace_engine</structname>, which could be implicit after
a <constant>UTRACE_DETACH</constant> return from another callback. Its argument is
the engine's <parameter>data</parameter> member.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
Each <parameter>report_</parameter>*() callback corresponds to an <constant>UTRACE_EVENT</constant>(*) bit.
<function>utrace_set_events</function> calls on <parameter>engine</parameter> choose which callbacks will
be made to <parameter>engine</parameter> from <parameter>task</parameter>.
</para><para>
Most callbacks take an <parameter>action</parameter> argument, giving the resume action
chosen by other tracing engines. All callbacks take an <parameter>engine</parameter>
argument. The <parameter>report_reap</parameter> callback takes a <parameter>task</parameter> argument that
might or might not be <parameter>current</parameter>. All other <parameter>report_</parameter>* callbacks
report an event in the <parameter>current</parameter> task.
</para><para>
For some calls, <parameter>action</parameter> also includes bits specific to that event
and <function>utrace_resume_action</function> is used to extract the resume action.
This shows what would happen if <parameter>engine</parameter> wasn't there, or will if
the callback's return value uses <constant>UTRACE_RESUME</constant>. This always
starts as <constant>UTRACE_RESUME</constant> when no other tracing is being done on
this task.
</para><para>
All return values contain <structname>enum</structname> 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 <parameter>action</parameter> argument. The resume action returned by a callback
does not override previous engines' choices, it only says what
<parameter>engine</parameter> wants done. What <parameter>current</parameter> actually does is the action that's
most constrained among the choices made by all attached engines.
See <function>utrace_control</function> for more information on the actions.
</para><para>
When <constant>UTRACE_STOP</constant> is used in <parameter>report_syscall_entry</parameter>, then <parameter>current</parameter>
stops before attempting the system call. In this case, another
<parameter>report_syscall_entry</parameter> callback will follow after <parameter>current</parameter> resumes if
<constant>UTRACE_REPORT</constant> or <constant>UTRACE_INTERRUPT</constant> was returned by some callback
or passed to <function>utrace_control</function>. In a second or later callback,
<constant>UTRACE_SYSCALL_RESUMED</constant> is set in the <parameter>action</parameter> 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
<parameter>current</parameter> was held in <constant>UTRACE_STOP</constant>.
</para><para>
In other cases, the resume action does not take effect until <parameter>current</parameter>
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 <parameter>report_quiesce</parameter> callback with <parameter>event</parameter> zero, or
a <parameter>report_signal</parameter> callback, will always be the last one made before
<parameter>current</parameter> resumes. Only <constant>UTRACE_STOP</constant> is <quote>sticky</quote>--if <parameter>engine</parameter> returned
<constant>UTRACE_STOP</constant> then <parameter>current</parameter> stays stopped unless <parameter>engine</parameter> returns
different from a following callback.
</para><para>
The <function>report_death</function> and <function>report_reap</function> callbacks do not take <parameter>action</parameter>
arguments, and only <constant>UTRACE_DETACH</constant> is meaningful in the return value
from a <function>report_death</function> callback. None of the resume actions applies
to a dead thread.
</para><para>
All <parameter>report_</parameter>*() 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 <constant>UTRACE_STOP</constant>
in your hook's return value; then later wake it up with <function>utrace_control</function>.
</para>
</refsect1>
</refentry>
<refentry id="API-struct-utrace-examiner">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct utrace_examiner</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct utrace_examiner</refname>
<refpurpose>
private state for using <function>utrace_prepare_examine</function>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct utrace_examiner {
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<para>
None
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
The members of <structname>struct utrace_examiner</structname> are private to the implementation.
This data type holds the state from a call to <function>utrace_prepare_examine</function>
to be used by a call to <function>utrace_finish_examine</function>.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-control-pid">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_control_pid</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_control_pid</refname>
<refpurpose>
control a thread being traced by a tracing engine
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>__must_check int <function>utrace_control_pid </function></funcdef>
<paramdef>struct pid * <parameter>pid</parameter></paramdef>
<paramdef>struct utrace_engine * <parameter>engine</parameter></paramdef>
<paramdef>enum utrace_resume_action <parameter>action</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pid</parameter></term>
<listitem>
<para>
thread to affect
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>engine</parameter></term>
<listitem>
<para>
attached engine to affect
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>action</parameter></term>
<listitem>
<para>
<structname>enum</structname> utrace_resume_action for thread to do
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is the same as <function>utrace_control</function>, but takes a <structname>struct pid</structname>
pointer rather than a <structname>struct task_struct</structname> pointer. The caller must
hold a ref on <parameter>pid</parameter>, but does not need to worry about the task
staying valid. If it's been reaped so that <parameter>pid</parameter> points nowhere,
then this call returns -<constant>ESRCH</constant>.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-set-events-pid">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_set_events_pid</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_set_events_pid</refname>
<refpurpose>
choose which event reports a tracing engine gets
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>__must_check int <function>utrace_set_events_pid </function></funcdef>
<paramdef>struct pid * <parameter>pid</parameter></paramdef>
<paramdef>struct utrace_engine * <parameter>engine</parameter></paramdef>
<paramdef>unsigned long <parameter>eventmask</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pid</parameter></term>
<listitem>
<para>
thread to affect
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>engine</parameter></term>
<listitem>
<para>
attached engine to affect
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>eventmask</parameter></term>
<listitem>
<para>
new event mask
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is the same as <function>utrace_set_events</function>, but takes a <structname>struct pid</structname>
pointer rather than a <structname>struct task_struct</structname> pointer. The caller must
hold a ref on <parameter>pid</parameter>, but does not need to worry about the task
staying valid. If it's been reaped so that <parameter>pid</parameter> points nowhere,
then this call returns -<constant>ESRCH</constant>.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-barrier-pid">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_barrier_pid</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_barrier_pid</refname>
<refpurpose>
synchronize with simultaneous tracing callbacks
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>__must_check int <function>utrace_barrier_pid </function></funcdef>
<paramdef>struct pid * <parameter>pid</parameter></paramdef>
<paramdef>struct utrace_engine * <parameter>engine</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pid</parameter></term>
<listitem>
<para>
thread to affect
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>engine</parameter></term>
<listitem>
<para>
engine to affect (can be detached)
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is the same as <function>utrace_barrier</function>, but takes a <structname>struct pid</structname>
pointer rather than a <structname>struct task_struct</structname> pointer. The caller must
hold a ref on <parameter>pid</parameter>, but does not need to worry about the task
staying valid. If it's been reaped so that <parameter>pid</parameter> points nowhere,
then this call returns -<constant>ESRCH</constant>.
</para>
</refsect1>
</refentry>
<!-- kernel/utrace.c -->
<refentry id="API-utrace-attach-task">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_attach_task</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_attach_task</refname>
<refpurpose>
attach new engine, or look up an attached engine
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct utrace_engine * <function>utrace_attach_task </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>const struct utrace_engine_ops * <parameter>ops</parameter></paramdef>
<paramdef>void * <parameter>data</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread to attach to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
flag bits combined with OR, see below
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ops</parameter></term>
<listitem>
<para>
callback table for new engine
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
engine private data pointer
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
The caller must ensure that the <parameter>target</parameter> thread does not get freed,
i.e. hold a ref or be its parent. It is always safe to call this
on <parameter>current</parameter>, or on the <parameter>child</parameter> pointer in a <parameter>report_clone</parameter> callback.
For most other cases, it's easier to use <function>utrace_attach_pid</function> instead.
</para>
</refsect1>
<refsect1>
<title>UTRACE_ATTACH_CREATE</title>
<para>
Create a new engine. If <constant>UTRACE_ATTACH_CREATE</constant> is not specified, you
only look up an existing engine already attached to the thread.
</para>
</refsect1>
<refsect1>
<title>UTRACE_ATTACH_EXCLUSIVE</title>
<para>
Attempting to attach a second (matching) engine fails with -<constant>EEXIST</constant>.
</para>
</refsect1>
<refsect1>
<title>UTRACE_ATTACH_MATCH_OPS</title>
<para>
Only consider engines matching <parameter>ops</parameter>.
</para>
</refsect1>
<refsect1>
<title>UTRACE_ATTACH_MATCH_DATA</title>
<para>
Only consider engines matching <parameter>data</parameter>.
</para><para>
Calls with neither <constant>UTRACE_ATTACH_MATCH_OPS</constant> nor <constant>UTRACE_ATTACH_MATCH_DATA</constant>
match the first among any engines attached to <parameter>target</parameter>. That means that
<constant>UTRACE_ATTACH_EXCLUSIVE</constant> in such a call fails with -<constant>EEXIST</constant> if there
are any engines on <parameter>target</parameter> at all.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-attach-pid">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_attach_pid</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_attach_pid</refname>
<refpurpose>
attach new engine, or look up an attached engine
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct utrace_engine * <function>utrace_attach_pid </function></funcdef>
<paramdef>struct pid * <parameter>pid</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>const struct utrace_engine_ops * <parameter>ops</parameter></paramdef>
<paramdef>void * <parameter>data</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>pid</parameter></term>
<listitem>
<para>
<structname>struct pid</structname> pointer representing thread to attach to
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
flag bits combined with OR, see <function>utrace_attach_task</function>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ops</parameter></term>
<listitem>
<para>
callback table for new engine
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
engine private data pointer
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is the same as <function>utrace_attach_task</function>, but takes a <structname>struct pid</structname>
pointer rather than a <structname>struct task_struct</structname> pointer. The caller must
hold a ref on <parameter>pid</parameter>, but does not need to worry about the task
staying valid. If it's been reaped so that <parameter>pid</parameter> points nowhere,
then this call returns -<constant>ESRCH</constant>.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-set-events">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_set_events</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_set_events</refname>
<refpurpose>
choose which event reports a tracing engine gets
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>utrace_set_events </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>struct utrace_engine * <parameter>engine</parameter></paramdef>
<paramdef>unsigned long <parameter>events</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread to affect
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>engine</parameter></term>
<listitem>
<para>
attached engine to affect
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>events</parameter></term>
<listitem>
<para>
new event mask
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This changes the set of events for which <parameter>engine</parameter> wants callbacks made.
</para><para>
This fails with -<constant>EALREADY</constant> and does nothing if you try to clear
<constant>UTRACE_EVENT</constant>(<constant>DEATH</constant>) when the <parameter>report_death</parameter> callback may already have
begun, if you try to clear <constant>UTRACE_EVENT</constant>(<constant>REAP</constant>) when the <parameter>report_reap</parameter>
callback may already have begun, or if you try to newly set
<constant>UTRACE_EVENT</constant>(<constant>DEATH</constant>) or <constant>UTRACE_EVENT</constant>(<constant>QUIESCE</constant>) when <parameter>target</parameter> is
already dead or dying.
</para><para>
This can fail with -<constant>ESRCH</constant> when <parameter>target</parameter> has already been detached,
including forcible detach on reaping.
</para><para>
If <parameter>target</parameter> was stopped before the call, then after a successful call,
no event callbacks not requested in <parameter>events</parameter> will be made; if
<constant>UTRACE_EVENT</constant>(<constant>QUIESCE</constant>) is included in <parameter>events</parameter>, then a
<parameter>report_quiesce</parameter> callback will be made when <parameter>target</parameter> resumes.
</para><para>
If <parameter>target</parameter> was not stopped and <parameter>events</parameter> excludes some bits that were
set before, this can return -<constant>EINPROGRESS</constant> to indicate that <parameter>target</parameter>
may have been making some callback to <parameter>engine</parameter>. When this returns
zero, you can be sure that no event callbacks you've disabled in
<parameter>events</parameter> can be made. If <parameter>events</parameter> only sets new bits that were not set
before on <parameter>engine</parameter>, then -<constant>EINPROGRESS</constant> will never be returned.
</para><para>
To synchronize after an -<constant>EINPROGRESS</constant> return, see <function>utrace_barrier</function>.
</para><para>
When <parameter>target</parameter> is <parameter>current</parameter>, -<constant>EINPROGRESS</constant> is not returned. But note
that a newly-created engine will not receive any callbacks related to
an event notification already in progress. This call enables <parameter>events</parameter>
callbacks to be made as soon as <parameter>engine</parameter> becomes eligible for any
callbacks, see <function>utrace_attach_task</function>.
</para><para>
These rules provide for coherent synchronization based on <constant>UTRACE_STOP</constant>,
even when <constant>SIGKILL</constant> is breaking its normal simple rules.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-control">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_control</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_control</refname>
<refpurpose>
control a thread being traced by a tracing engine
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>utrace_control </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>struct utrace_engine * <parameter>engine</parameter></paramdef>
<paramdef>enum utrace_resume_action <parameter>action</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread to affect
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>engine</parameter></term>
<listitem>
<para>
attached engine to affect
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>action</parameter></term>
<listitem>
<para>
<structname>enum</structname> utrace_resume_action for thread to do
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is how a tracing engine asks a traced thread to do something.
This call is controlled by the <parameter>action</parameter> argument, which has the
same meaning as the <structname>enum</structname> utrace_resume_action value returned by
event reporting callbacks.
</para><para>
If <parameter>target</parameter> is already dead (<parameter>target</parameter>->exit_state nonzero),
all actions except <constant>UTRACE_DETACH</constant> fail with -<constant>ESRCH</constant>.
</para><para>
The following sections describe each option for the <parameter>action</parameter> argument.
</para>
</refsect1>
<refsect1>
<title>UTRACE_DETACH</title>
<para>
</para><para>
After this, the <parameter>engine</parameter> data structure is no longer accessible,
and the thread might be reaped. The thread will start running
again if it was stopped and no longer has any attached engines
that want it stopped.
</para><para>
If the <parameter>report_reap</parameter> callback may already have begun, this fails
with -<constant>ESRCH</constant>. If the <parameter>report_death</parameter> callback may already have
begun, this fails with -<constant>EALREADY</constant>.
</para><para>
If <parameter>target</parameter> is not already stopped, then a callback to this engine
might be in progress or about to start on another CPU. If so,
then this returns -<constant>EINPROGRESS</constant>; the detach happens as soon as
the pending callback is finished. To synchronize after an
-<constant>EINPROGRESS</constant> return, see <function>utrace_barrier</function>.
</para><para>
If <parameter>target</parameter> is properly stopped before <function>utrace_control</function> is called,
then after successful return it's guaranteed that no more callbacks
to the <parameter>engine</parameter>->ops vector will be made.
</para><para>
The only exception is <constant>SIGKILL</constant> (and exec or group-exit by another
thread in the group), which can cause asynchronous <parameter>report_death</parameter>
and/or <parameter>report_reap</parameter> callbacks even when <constant>UTRACE_STOP</constant> was used.
(In that event, this fails with -<constant>ESRCH</constant> or -<constant>EALREADY</constant>, see above.)
</para>
</refsect1>
<refsect1>
<title>UTRACE_STOP</title>
<para>
</para><para>
This asks that <parameter>target</parameter> stop running. This returns 0 only if
<parameter>target</parameter> is already stopped, either for tracing or for job
control. Then <parameter>target</parameter> will remain stopped until another
<function>utrace_control</function> call is made on <parameter>engine</parameter>; <parameter>target</parameter> can be woken
only by <constant>SIGKILL</constant> (or equivalent, such as exec or termination by
another thread in the same thread group).
</para><para>
This returns -<constant>EINPROGRESS</constant> if <parameter>target</parameter> is not already stopped.
Then the effect is like <constant>UTRACE_REPORT</constant>. A <parameter>report_quiesce</parameter> or
<parameter>report_signal</parameter> callback will be made soon. Your callback can
then return <constant>UTRACE_STOP</constant> to keep <parameter>target</parameter> stopped.
</para><para>
This does not interrupt system calls in progress, including ones
that sleep for a long time. For that, use <constant>UTRACE_INTERRUPT</constant>.
To interrupt system calls and then keep <parameter>target</parameter> stopped, your
<parameter>report_signal</parameter> callback can return <constant>UTRACE_STOP</constant>.
</para>
</refsect1>
<refsect1>
<title>UTRACE_RESUME</title>
<para>
</para><para>
Just let <parameter>target</parameter> continue running normally, reversing the effect
of a previous <constant>UTRACE_STOP</constant>. If another engine is keeping <parameter>target</parameter>
stopped, then it remains stopped until all engines let it resume.
If <parameter>target</parameter> was not stopped, this has no effect.
</para>
</refsect1>
<refsect1>
<title>UTRACE_REPORT</title>
<para>
</para><para>
This is like <constant>UTRACE_RESUME</constant>, but also ensures that there will be
a <parameter>report_quiesce</parameter> or <parameter>report_signal</parameter> callback made soon. If
<parameter>target</parameter> had been stopped, then there will be a callback before it
resumes running normally. If another engine is keeping <parameter>target</parameter>
stopped, then there might be no callbacks until all engines let
it resume.
</para><para>
Since this is meaningless unless <parameter>report_quiesce</parameter> callbacks will
be made, it returns -<constant>EINVAL</constant> if <parameter>engine</parameter> lacks <constant>UTRACE_EVENT</constant>(<constant>QUIESCE</constant>).
</para>
</refsect1>
<refsect1>
<title>UTRACE_INTERRUPT</title>
<para>
</para><para>
This is like <constant>UTRACE_REPORT</constant>, but ensures that <parameter>target</parameter> will make a
<parameter>report_signal</parameter> callback before it resumes or delivers signals.
If <parameter>target</parameter> was in a system call or about to enter one, work in
progress will be interrupted as if by <constant>SIGSTOP</constant>. If another
engine is keeping <parameter>target</parameter> stopped, then there might be no
callbacks until all engines let it resume.
</para><para>
This gives <parameter>engine</parameter> an opportunity to introduce a forced signal
disposition via its <parameter>report_signal</parameter> callback.
</para>
</refsect1>
<refsect1>
<title>UTRACE_SINGLESTEP</title>
<para>
</para><para>
It's invalid to use this unless <function>arch_has_single_step</function> returned true.
This is like <constant>UTRACE_RESUME</constant>, but resumes for one user instruction only.
</para><para>
Note that passing <constant>UTRACE_SINGLESTEP</constant> or <constant>UTRACE_BLOCKSTEP</constant> to
<function>utrace_control</function> or returning it from an event callback alone does
not necessarily ensure that stepping will be enabled. If there are
more callbacks made to any engine before returning to user mode,
then the resume action is chosen only by the last set of callbacks.
To be sure, enable <constant>UTRACE_EVENT</constant>(<constant>QUIESCE</constant>) and look for the
<parameter>report_quiesce</parameter> callback with a zero event mask, or the
<parameter>report_signal</parameter> callback with <constant>UTRACE_SIGNAL_REPORT</constant>.
</para><para>
Since this is not robust unless <parameter>report_quiesce</parameter> callbacks will
be made, it returns -<constant>EINVAL</constant> if <parameter>engine</parameter> lacks <constant>UTRACE_EVENT</constant>(<constant>QUIESCE</constant>).
</para>
</refsect1>
<refsect1>
<title>UTRACE_BLOCKSTEP</title>
<para>
</para><para>
It's invalid to use this unless <function>arch_has_block_step</function> returned true.
This is like <constant>UTRACE_SINGLESTEP</constant>, but resumes for one whole basic
block of user instructions.
</para><para>
Since this is not robust unless <parameter>report_quiesce</parameter> callbacks will
be made, it returns -<constant>EINVAL</constant> if <parameter>engine</parameter> lacks <constant>UTRACE_EVENT</constant>(<constant>QUIESCE</constant>).
</para><para>
<constant>UTRACE_BLOCKSTEP</constant> devolves to <constant>UTRACE_SINGLESTEP</constant> when another
tracing engine is using <constant>UTRACE_SINGLESTEP</constant> at the same time.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-barrier">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_barrier</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_barrier</refname>
<refpurpose>
synchronize with simultaneous tracing callbacks
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>utrace_barrier </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>struct utrace_engine * <parameter>engine</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread to affect
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>engine</parameter></term>
<listitem>
<para>
engine to affect (can be detached)
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This blocks while <parameter>target</parameter> might be in the midst of making a callback to
<parameter>engine</parameter>. It can be interrupted by signals and will return -<constant>ERESTARTSYS</constant>.
A return value of zero means no callback from <parameter>target</parameter> to <parameter>engine</parameter> was
in progress. Any effect of its return value (such as <constant>UTRACE_STOP</constant>) has
already been applied to <parameter>engine</parameter>.
</para><para>
It's not necessary to keep the <parameter>target</parameter> pointer alive for this call.
It's only necessary to hold a ref on <parameter>engine</parameter>. This will return
safely even if <parameter>target</parameter> has been reaped and has no task refs.
</para><para>
A successful return from <function>utrace_barrier</function> guarantees its ordering
with respect to <function>utrace_set_events</function> and <function>utrace_control</function> calls. If
<parameter>target</parameter> was not properly stopped, event callbacks just disabled might
still be in progress; <function>utrace_barrier</function> waits until there is no chance
an unwanted callback can be in progress.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-prepare-examine">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_prepare_examine</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_prepare_examine</refname>
<refpurpose>
prepare to examine thread state
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>utrace_prepare_examine </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>struct utrace_engine * <parameter>engine</parameter></paramdef>
<paramdef>struct utrace_examiner * <parameter>exam</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread of interest, a <structname>struct task_struct</structname> pointer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>engine</parameter></term>
<listitem>
<para>
engine pointer returned by <function>utrace_attach_task</function>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>exam</parameter></term>
<listitem>
<para>
temporary state, a <structname>struct utrace_examiner</structname> pointer
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This call prepares to safely examine the thread <parameter>target</parameter> using
<structname>struct user_regset</structname> calls, or direct access to thread-synchronous fields.
</para><para>
When <parameter>target</parameter> is current, this call is superfluous. When <parameter>target</parameter> is
another thread, it must be held stopped via <constant>UTRACE_STOP</constant> by <parameter>engine</parameter>.
</para><para>
This call may block the caller until <parameter>target</parameter> stays stopped, so it must
be called only after the caller is sure <parameter>target</parameter> is about to unschedule.
This means a zero return from a <function>utrace_control</function> call on <parameter>engine</parameter> giving
<constant>UTRACE_STOP</constant>, or a <function>report_quiesce</function> or <function>report_signal</function> callback to
<parameter>engine</parameter> that used <constant>UTRACE_STOP</constant> in its return value.
</para><para>
Returns -<constant>ESRCH</constant> if <parameter>target</parameter> is dead or -<constant>EINVAL</constant> if <constant>UTRACE_STOP</constant> was
not used. If <parameter>target</parameter> has started running again despite <constant>UTRACE_STOP</constant>
(for <constant>SIGKILL</constant> or a spurious wakeup), this call returns -<constant>EAGAIN</constant>.
</para><para>
When this call returns zero, it's safe to use <structname>struct user_regset</structname>
calls and <function>task_user_regset_view</function> on <parameter>target</parameter> and to examine some of
its fields directly. When the examination is complete, a
<function>utrace_finish_examine</function> call must follow to check whether it was
completed safely.
</para>
</refsect1>
</refentry>
<refentry id="API-utrace-finish-examine">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>utrace_finish_examine</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>utrace_finish_examine</refname>
<refpurpose>
complete an examination of thread state
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>utrace_finish_examine </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>struct utrace_engine * <parameter>engine</parameter></paramdef>
<paramdef>struct utrace_examiner * <parameter>exam</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread of interest, a <structname>struct task_struct</structname> pointer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>engine</parameter></term>
<listitem>
<para>
engine pointer returned by <function>utrace_attach_task</function>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>exam</parameter></term>
<listitem>
<para>
pointer passed to <function>utrace_prepare_examine</function> call
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This call completes an examination on the thread <parameter>target</parameter> begun by a
paired <function>utrace_prepare_examine</function> call with the same arguments that
returned success (zero).
</para><para>
When <parameter>target</parameter> is current, this call is superfluous. When <parameter>target</parameter> is
another thread, this returns zero if <parameter>target</parameter> has remained unscheduled
since the paired <function>utrace_prepare_examine</function> call returned zero.
</para><para>
When this returns an error, any examination done since the paired
<function>utrace_prepare_examine</function> call is unreliable and the data extracted
should be discarded. The error is -<constant>EINVAL</constant> if <parameter>engine</parameter> is not
keeping <parameter>target</parameter> stopped, or -<constant>EAGAIN</constant> if <parameter>target</parameter> woke up unexpectedly.
</para>
</refsect1>
</refentry>
</chapter>
<chapter id="machine"><title>Machine State</title>
<para>
The <function>task_current_syscall</function> function can be used on any
valid <structname>struct task_struct</structname> at any time, and does
not even require that <function>utrace_attach_task</function> was used at all.
</para>
<para>
The other ways to access the registers and other machine-dependent state of
a task can only be used on a task that is at a known safe point. The safe
points are all the places where <function>utrace_set_events</function> can
request callbacks (except for the <constant>DEATH</constant> and
<constant>REAP</constant> events). So at any event callback, it is safe to
examine <varname>current</varname>.
</para>
<para>
One task can examine another only after a callback in the target task that
returns <constant>UTRACE_STOP</constant> so that task will not return to user
mode after the safe point. This guarantees that the task will not resume
until the same engine uses <function>utrace_control</function>, unless the
task dies suddenly. To examine safely, one must use a pair of calls to
<function>utrace_prepare_examine</function> and
<function>utrace_finish_examine</function> surrounding the calls to
<structname>struct user_regset</structname> functions or direct examination
of task data structures. <function>utrace_prepare_examine</function> returns
an error if the task is not properly stopped, or is dead. After a
successful examination, the paired <function>utrace_finish_examine</function>
call returns an error if the task ever woke up during the examination. If
so, any data gathered may be scrambled and should be discarded. This means
there was a spurious wake-up (which should not happen), or a sudden death.
</para>
<sect1 id="regset"><title><structname>struct user_regset</structname></title>
<para>
The <structname>struct user_regset</structname> API
is declared in <filename><linux/regset.h></filename>.
</para>
<refentry id="API-user-regset-active-fn">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>user_regset_active_fn</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>user_regset_active_fn</refname>
<refpurpose>
type of <parameter>active</parameter> function in <structname>struct user_regset</structname>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>typedef int <function>user_regset_active_fn </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>const struct user_regset * <parameter>regset</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread being examined
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regset</parameter></term>
<listitem>
<para>
regset being examined
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Return -<constant>ENODEV</constant> if not available on the hardware found.
Return <constant>0</constant> if no interesting state in this thread.
Return ><constant>0</constant> number of <parameter>size</parameter> units of interesting state.
Any get call fetching state beyond that number will
see the default initialization state for this data,
so a caller that knows what the default state is need
not copy it all out.
This call is optional; the pointer is <constant>NULL</constant> if there
is no inexpensive check to yield a value < <parameter>n</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="API-user-regset-get-fn">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>user_regset_get_fn</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>user_regset_get_fn</refname>
<refpurpose>
type of <parameter>get</parameter> function in <structname>struct user_regset</structname>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>typedef int <function>user_regset_get_fn </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>const struct user_regset * <parameter>regset</parameter></paramdef>
<paramdef>unsigned int <parameter>pos</parameter></paramdef>
<paramdef>unsigned int <parameter>count</parameter></paramdef>
<paramdef>void * <parameter>kbuf</parameter></paramdef>
<paramdef>void __user * <parameter>ubuf</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread being examined
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regset</parameter></term>
<listitem>
<para>
regset being examined
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pos</parameter></term>
<listitem>
<para>
offset into the regset data to access, in bytes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>count</parameter></term>
<listitem>
<para>
amount of data to copy, in bytes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>kbuf</parameter></term>
<listitem>
<para>
if not <constant>NULL</constant>, a kernel-space pointer to copy into
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ubuf</parameter></term>
<listitem>
<para>
if <parameter>kbuf</parameter> is <constant>NULL</constant>, a user-space pointer to copy into
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Fetch register values. Return <constant>0</constant> on success; -<constant>EIO</constant> or -<constant>ENODEV</constant>
are usual failure returns. The <parameter>pos</parameter> and <parameter>count</parameter> values are in
bytes, but must be properly aligned. If <parameter>kbuf</parameter> is non-null, that
buffer is used and <parameter>ubuf</parameter> is ignored. If <parameter>kbuf</parameter> is <constant>NULL</constant>, then
ubuf gives a userland pointer to access directly, and an -<constant>EFAULT</constant>
return value is possible.
</para>
</refsect1>
</refentry>
<refentry id="API-user-regset-set-fn">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>user_regset_set_fn</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>user_regset_set_fn</refname>
<refpurpose>
type of <parameter>set</parameter> function in <structname>struct user_regset</structname>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>typedef int <function>user_regset_set_fn </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>const struct user_regset * <parameter>regset</parameter></paramdef>
<paramdef>unsigned int <parameter>pos</parameter></paramdef>
<paramdef>unsigned int <parameter>count</parameter></paramdef>
<paramdef>const void * <parameter>kbuf</parameter></paramdef>
<paramdef>const void __user * <parameter>ubuf</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread being examined
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regset</parameter></term>
<listitem>
<para>
regset being examined
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pos</parameter></term>
<listitem>
<para>
offset into the regset data to access, in bytes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>count</parameter></term>
<listitem>
<para>
amount of data to copy, in bytes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>kbuf</parameter></term>
<listitem>
<para>
if not <constant>NULL</constant>, a kernel-space pointer to copy from
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ubuf</parameter></term>
<listitem>
<para>
if <parameter>kbuf</parameter> is <constant>NULL</constant>, a user-space pointer to copy from
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Store register values. Return <constant>0</constant> on success; -<constant>EIO</constant> or -<constant>ENODEV</constant>
are usual failure returns. The <parameter>pos</parameter> and <parameter>count</parameter> values are in
bytes, but must be properly aligned. If <parameter>kbuf</parameter> is non-null, that
buffer is used and <parameter>ubuf</parameter> is ignored. If <parameter>kbuf</parameter> is <constant>NULL</constant>, then
ubuf gives a userland pointer to access directly, and an -<constant>EFAULT</constant>
return value is possible.
</para>
</refsect1>
</refentry>
<refentry id="API-user-regset-writeback-fn">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>user_regset_writeback_fn</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>user_regset_writeback_fn</refname>
<refpurpose>
type of <parameter>writeback</parameter> function in <structname>struct user_regset</structname>
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>typedef int <function>user_regset_writeback_fn </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>const struct user_regset * <parameter>regset</parameter></paramdef>
<paramdef>int <parameter>immediate</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread being examined
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regset</parameter></term>
<listitem>
<para>
regset being examined
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>immediate</parameter></term>
<listitem>
<para>
zero if writeback at completion of next context switch is OK
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This call is optional; usually the pointer is <constant>NULL</constant>. When
provided, there is some user memory associated with this regset's
hardware, such as memory backing cached register data on register
window machines; the regset's data controls what user memory is
used (e.g. via the stack pointer value).
</para><para>
Write register data back to user memory. If the <parameter>immediate</parameter> flag
is nonzero, it must be written to the user memory so uaccess or
<function>access_process_vm</function> can see it when this call returns; if zero,
then it must be written back by the time the task completes a
context switch (as synchronized with <function>wait_task_inactive</function>).
Return <constant>0</constant> on success or if there was nothing to do, -<constant>EFAULT</constant> for
a memory problem (bad stack pointer or whatever), or -<constant>EIO</constant> for a
hardware problem.
</para>
</refsect1>
</refentry>
<refentry id="API-struct-user-regset">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct user_regset</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct user_regset</refname>
<refpurpose>
accessible thread CPU state
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct user_regset {
user_regset_get_fn * get;
user_regset_set_fn * set;
user_regset_active_fn * active;
user_regset_writeback_fn * writeback;
unsigned int n;
unsigned int size;
unsigned int align;
unsigned int bias;
unsigned int core_note_type;
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>get</term>
<listitem><para>
Function to fetch values.
</para></listitem>
</varlistentry>
<varlistentry> <term>set</term>
<listitem><para>
Function to store values.
</para></listitem>
</varlistentry>
<varlistentry> <term>active</term>
<listitem><para>
Function to report if regset is active, or <constant>NULL</constant>.
</para></listitem>
</varlistentry>
<varlistentry> <term>writeback</term>
<listitem><para>
Function to write data back to user memory, or <constant>NULL</constant>.
</para></listitem>
</varlistentry>
<varlistentry> <term>n</term>
<listitem><para>
Number of slots (registers).
</para></listitem>
</varlistentry>
<varlistentry> <term>size</term>
<listitem><para>
Size in bytes of a slot (register).
</para></listitem>
</varlistentry>
<varlistentry> <term>align</term>
<listitem><para>
Required alignment, in bytes.
</para></listitem>
</varlistentry>
<varlistentry> <term>bias</term>
<listitem><para>
Bias from natural indexing.
</para></listitem>
</varlistentry>
<varlistentry> <term>core_note_type</term>
<listitem><para>
ELF note <parameter>n_type</parameter> value used in core dumps.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This data structure describes a machine resource we call a register set.
This is part of the state of an individual thread, not necessarily
actual CPU registers per se. A register set consists of a number of
similar slots, given by <parameter>n</parameter>. Each slot is <parameter>size</parameter> bytes, and aligned to
<parameter>align</parameter> bytes (which is at least <parameter>size</parameter>).
</para><para>
These functions must be called only on the current thread or on a
thread that is in <constant>TASK_STOPPED</constant> or <constant>TASK_TRACED</constant> state, that we are
guaranteed will not be woken up and return to user mode, and that we
have called <function>wait_task_inactive</function> on. (The target thread always might
wake up for SIGKILL while these functions are working, in which case
that thread's user_regset state might be scrambled.)
</para><para>
The <parameter>pos</parameter> argument must be aligned according to <parameter>align</parameter>; the <parameter>count</parameter>
argument must be a multiple of <parameter>size</parameter>. These functions are not
responsible for checking for invalid arguments.
</para><para>
When there is a natural value to use as an index, <parameter>bias</parameter> gives the
difference between the natural index and the slot index for the
register set. For example, x86 GDT segment descriptors form a regset;
the segment selector produces a natural index, but only a subset of
that index space is available as a regset (the TLS slots); subtracting
<parameter>bias</parameter> from a segment selector index value computes the regset slot.
</para><para>
If nonzero, <parameter>core_note_type</parameter> gives the n_type field (NT_* value)
of the core file note in which this regset's data appears.
NT_PRSTATUS is a special case in that the regset data starts at
offsetof(struct elf_prstatus, pr_reg) into the note data; that is
part of the per-machine ELF formats userland knows about. In
other cases, the core file note contains exactly the whole regset
(<parameter>n</parameter> * <parameter>size</parameter>) and nothing else. The core file note is normally
omitted when there is an <parameter>active</parameter> function and it returns zero.
</para>
</refsect1>
</refentry>
<refentry id="API-struct-user-regset-view">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct user_regset_view</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct user_regset_view</refname>
<refpurpose>
available regsets
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct user_regset_view {
const char * name;
const struct user_regset * regsets;
unsigned int n;
u32 e_flags;
u16 e_machine;
u8 ei_osabi;
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>name</term>
<listitem><para>
Identifier, e.g. UTS_MACHINE string.
</para></listitem>
</varlistentry>
<varlistentry> <term>regsets</term>
<listitem><para>
Array of <parameter>n</parameter> regsets available in this view.
</para></listitem>
</varlistentry>
<varlistentry> <term>n</term>
<listitem><para>
Number of elements in <parameter>regsets</parameter>.
</para></listitem>
</varlistentry>
<varlistentry> <term>e_flags</term>
<listitem><para>
ELF header <parameter>e_flags</parameter> value written in core dumps.
</para></listitem>
</varlistentry>
<varlistentry> <term>e_machine</term>
<listitem><para>
ELF header <parameter>e_machine</parameter> <constant>EM_</constant>* value written in core dumps.
</para></listitem>
</varlistentry>
<varlistentry> <term>ei_osabi</term>
<listitem><para>
ELF header <parameter>e_ident</parameter>[<constant>EI_OSABI</constant>] value written in core dumps.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
A regset view is a collection of regsets (<structname>struct user_regset</structname>,
above). This describes all the state of a thread that can be seen
from a given architecture/ABI environment. More than one view might
refer to the same <structname>struct user_regset</structname>, or more than one regset
might refer to the same machine-specific state in the thread. For
example, a 32-bit thread's state could be examined from the 32-bit
view or from the 64-bit view. Either method reaches the same thread
register state, doing appropriate widening or truncation.
</para>
</refsect1>
</refentry>
<refentry id="API-task-user-regset-view">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>task_user_regset_view</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>task_user_regset_view</refname>
<refpurpose>
Return the process's native regset view.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>const struct user_regset_view * <function>task_user_regset_view </function></funcdef>
<paramdef>struct task_struct * <parameter>tsk</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>tsk</parameter></term>
<listitem>
<para>
a thread of the process in question
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Return the <structname>struct user_regset_view</structname> that is native for the given process.
For example, what it would access when it called <function>ptrace</function>.
Throughout the life of the process, this only changes at exec.
</para>
</refsect1>
</refentry>
<refentry id="API-copy-regset-to-user">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>copy_regset_to_user</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>copy_regset_to_user</refname>
<refpurpose>
fetch a thread's user_regset data into user memory
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>copy_regset_to_user </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>const struct user_regset_view * <parameter>view</parameter></paramdef>
<paramdef>unsigned int <parameter>setno</parameter></paramdef>
<paramdef>unsigned int <parameter>offset</parameter></paramdef>
<paramdef>unsigned int <parameter>size</parameter></paramdef>
<paramdef>void __user * <parameter>data</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread to be examined
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>view</parameter></term>
<listitem>
<para>
<structname>struct user_regset_view</structname> describing user thread machine state
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>setno</parameter></term>
<listitem>
<para>
index in <parameter>view</parameter>->regsets
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
offset into the regset data, in bytes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>size</parameter></term>
<listitem>
<para>
amount of data to copy, in bytes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
user-mode pointer to copy into
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-copy-regset-from-user">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>copy_regset_from_user</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>copy_regset_from_user</refname>
<refpurpose>
store into thread's user_regset data from user memory
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>copy_regset_from_user </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>const struct user_regset_view * <parameter>view</parameter></paramdef>
<paramdef>unsigned int <parameter>setno</parameter></paramdef>
<paramdef>unsigned int <parameter>offset</parameter></paramdef>
<paramdef>unsigned int <parameter>size</parameter></paramdef>
<paramdef>const void __user * <parameter>data</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread to be examined
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>view</parameter></term>
<listitem>
<para>
<structname>struct user_regset_view</structname> describing user thread machine state
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>setno</parameter></term>
<listitem>
<para>
index in <parameter>view</parameter>->regsets
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
offset into the regset data, in bytes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>size</parameter></term>
<listitem>
<para>
amount of data to copy, in bytes
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
user-mode pointer to copy from
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
</sect1>
<sect1 id="task_current_syscall">
<title><filename>System Call Information</filename></title>
<para>
This function is declared in <filename><linux/ptrace.h></filename>.
</para>
<!-- lib/syscall.c -->
<refentry id="API-task-current-syscall">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>task_current_syscall</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>task_current_syscall</refname>
<refpurpose>
Discover what a blocked task is doing.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>task_current_syscall </function></funcdef>
<paramdef>struct task_struct * <parameter>target</parameter></paramdef>
<paramdef>long * <parameter>callno</parameter></paramdef>
<paramdef>unsigned long <parameter>args[6]</parameter></paramdef>
<paramdef>unsigned int <parameter>maxargs</parameter></paramdef>
<paramdef>unsigned long * <parameter>sp</parameter></paramdef>
<paramdef>unsigned long * <parameter>pc</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
thread to examine
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>callno</parameter></term>
<listitem>
<para>
filled with system call number or -1
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>args[6]</parameter></term>
<listitem>
<para>
filled with <parameter>maxargs</parameter> system call arguments
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>maxargs</parameter></term>
<listitem>
<para>
number of elements in <parameter>args</parameter> to fill
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sp</parameter></term>
<listitem>
<para>
filled with user stack pointer
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pc</parameter></term>
<listitem>
<para>
filled with user PC
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
If <parameter>target</parameter> is blocked in a system call, returns zero with *<parameter>callno</parameter>
set to the the call's number and <parameter>args</parameter> filled in with its arguments.
Registers not used for system call arguments may not be available and
it is not kosher to use <structname>struct user_regset</structname> calls while the system
call is still in progress. Note we may get this result if <parameter>target</parameter>
has finished its system call but not yet returned to user mode, such
as when it's stopped for signal handling or syscall exit tracing.
</para><para>
If <parameter>target</parameter> is blocked in the kernel during a fault or exception,
returns zero with *<parameter>callno</parameter> set to -1 and does not fill in <parameter>args</parameter>.
If so, it's now safe to examine <parameter>target</parameter> using <structname>struct user_regset</structname>
<function>get</function> calls as long as we're sure <parameter>target</parameter> won't return to user mode.
</para><para>
Returns -<constant>EAGAIN</constant> if <parameter>target</parameter> does not remain blocked.
</para><para>
Returns -<constant>EINVAL</constant> if <parameter>maxargs</parameter> is too large (maximum is six).
</para>
</refsect1>
</refentry>
</sect1>
<sect1 id="syscall"><title><filename>System Call Tracing</filename></title>
<para>
The arch API for system call information is declared in
<filename><asm/syscall.h></filename>.
Each of these calls can be used only at system call entry tracing,
or can be used only at system call exit and the subsequent safe points
before returning to user mode.
At system call entry tracing means either during a
<structfield>report_syscall_entry</structfield> callback,
or any time after that callback has returned <constant>UTRACE_STOP</constant>.
</para>
<refentry id="API-syscall-get-nr">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>syscall_get_nr</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>syscall_get_nr</refname>
<refpurpose>
find what system call a task is executing
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>syscall_get_nr </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task of interest, must be blocked
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
<function>task_pt_regs</function> of <parameter>task</parameter>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
If <parameter>task</parameter> is executing a system call or is at system call
tracing about to attempt one, returns the system call number.
If <parameter>task</parameter> is not executing a system call, i.e. it's blocked
inside the kernel for a fault or signal, returns -1.
</para><para>
Note this returns int even on 64-bit machines. Only 32 bits of
system call number can be meaningful. If the actual arch value
is 64 bits, this truncates to 32 bits so 0xffffffff means -1.
</para><para>
It's only valid to call this when <parameter>task</parameter> is known to be blocked.
</para>
</refsect1>
</refentry>
<refentry id="API-syscall-rollback">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>syscall_rollback</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>syscall_rollback</refname>
<refpurpose>
roll back registers after an aborted system call
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>syscall_rollback </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task of interest, must be in system call exit tracing
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
<function>task_pt_regs</function> of <parameter>task</parameter>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
It's only valid to call this when <parameter>task</parameter> is stopped for system
call exit tracing (due to TIF_SYSCALL_TRACE or TIF_SYSCALL_AUDIT),
after <function>tracehook_report_syscall_entry</function> returned nonzero to prevent
the system call from taking place.
</para><para>
This rolls back the register state in <parameter>regs</parameter> so it's as if the
system call instruction was a no-op. The registers containing
the system call number and arguments are as they were before the
system call instruction. This may not be the same as what the
register state looked like at system call entry tracing.
</para>
</refsect1>
</refentry>
<refentry id="API-syscall-get-error">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>syscall_get_error</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>syscall_get_error</refname>
<refpurpose>
check result of traced system call
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>long <function>syscall_get_error </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task of interest, must be blocked
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
<function>task_pt_regs</function> of <parameter>task</parameter>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Returns 0 if the system call succeeded, or -ERRORCODE if it failed.
</para><para>
It's only valid to call this when <parameter>task</parameter> is stopped for tracing on exit
from a system call, due to <constant>TIF_SYSCALL_TRACE</constant> or <constant>TIF_SYSCALL_AUDIT</constant>.
</para>
</refsect1>
</refentry>
<refentry id="API-syscall-get-return-value">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>syscall_get_return_value</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>syscall_get_return_value</refname>
<refpurpose>
get the return value of a traced system call
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>long <function>syscall_get_return_value </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task of interest, must be blocked
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
<function>task_pt_regs</function> of <parameter>task</parameter>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Returns the return value of the successful system call.
This value is meaningless if <function>syscall_get_error</function> returned nonzero.
</para><para>
It's only valid to call this when <parameter>task</parameter> is stopped for tracing on exit
from a system call, due to <constant>TIF_SYSCALL_TRACE</constant> or <constant>TIF_SYSCALL_AUDIT</constant>.
</para>
</refsect1>
</refentry>
<refentry id="API-syscall-set-return-value">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>syscall_set_return_value</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>syscall_set_return_value</refname>
<refpurpose>
change the return value of a traced system call
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>syscall_set_return_value </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
<paramdef>int <parameter>error</parameter></paramdef>
<paramdef>long <parameter>val</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task of interest, must be blocked
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
<function>task_pt_regs</function> of <parameter>task</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>error</parameter></term>
<listitem>
<para>
negative error code, or zero to indicate success
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>val</parameter></term>
<listitem>
<para>
user return value if <parameter>error</parameter> is zero
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This changes the results of the system call that user mode will see.
If <parameter>error</parameter> is zero, the user sees a successful system call with a
return value of <parameter>val</parameter>. If <parameter>error</parameter> is nonzero, it's a negated errno
code; the user sees a failed system call with this errno code.
</para><para>
It's only valid to call this when <parameter>task</parameter> is stopped for tracing on exit
from a system call, due to <constant>TIF_SYSCALL_TRACE</constant> or <constant>TIF_SYSCALL_AUDIT</constant>.
</para>
</refsect1>
</refentry>
<refentry id="API-syscall-get-arguments">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>syscall_get_arguments</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>syscall_get_arguments</refname>
<refpurpose>
extract system call parameter values
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>syscall_get_arguments </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
<paramdef>unsigned int <parameter>i</parameter></paramdef>
<paramdef>unsigned int <parameter>n</parameter></paramdef>
<paramdef>unsigned long * <parameter>args</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task of interest, must be blocked
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
<function>task_pt_regs</function> of <parameter>task</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>i</parameter></term>
<listitem>
<para>
argument index [0,5]
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>n</parameter></term>
<listitem>
<para>
number of arguments; n+i must be [1,6].
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>args</parameter></term>
<listitem>
<para>
array filled with argument values
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Fetches <parameter>n</parameter> arguments to the system call starting with the <parameter>i</parameter>'th argument
(from 0 through 5). Argument <parameter>i</parameter> is stored in <parameter>args</parameter>[0], and so on.
An arch inline version is probably optimal when <parameter>i</parameter> and <parameter>n</parameter> are constants.
</para><para>
It's only valid to call this when <parameter>task</parameter> is stopped for tracing on
entry to a system call, due to <constant>TIF_SYSCALL_TRACE</constant> or <constant>TIF_SYSCALL_AUDIT</constant>.
It's invalid to call this with <parameter>i</parameter> + <parameter>n</parameter> > 6; we only support system calls
taking up to 6 arguments.
</para>
</refsect1>
</refentry>
<refentry id="API-syscall-set-arguments">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>syscall_set_arguments</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>syscall_set_arguments</refname>
<refpurpose>
change system call parameter value
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>syscall_set_arguments </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
<paramdef>unsigned int <parameter>i</parameter></paramdef>
<paramdef>unsigned int <parameter>n</parameter></paramdef>
<paramdef>const unsigned long * <parameter>args</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task of interest, must be in system call entry tracing
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
<function>task_pt_regs</function> of <parameter>task</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>i</parameter></term>
<listitem>
<para>
argument index [0,5]
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>n</parameter></term>
<listitem>
<para>
number of arguments; n+i must be [1,6].
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>args</parameter></term>
<listitem>
<para>
array of argument values to store
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Changes <parameter>n</parameter> arguments to the system call starting with the <parameter>i</parameter>'th argument.
Argument <parameter>i</parameter> gets value <parameter>args</parameter>[0], and so on.
An arch inline version is probably optimal when <parameter>i</parameter> and <parameter>n</parameter> are constants.
</para><para>
It's only valid to call this when <parameter>task</parameter> is stopped for tracing on
entry to a system call, due to <constant>TIF_SYSCALL_TRACE</constant> or <constant>TIF_SYSCALL_AUDIT</constant>.
It's invalid to call this with <parameter>i</parameter> + <parameter>n</parameter> > 6; we only support system calls
taking up to 6 arguments.
</para>
</refsect1>
</refentry>
</sect1>
</chapter>
<chapter id="internals"><title>Kernel Internals</title>
<para>
This chapter covers the interface to the tracing infrastructure
from the core of the kernel and the architecture-specific code.
This is for maintainers of the kernel and arch code, and not relevant
to using the tracing facilities described in preceding chapters.
</para>
<sect1 id="tracehook"><title>Core Calls In</title>
<para>
These calls are declared in <filename><linux/tracehook.h></filename>.
The core kernel calls these functions at various important places.
</para>
<refentry id="API-tracehook-expect-breakpoints">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_expect_breakpoints</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_expect_breakpoints</refname>
<refpurpose>
guess if task memory might be touched
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>tracehook_expect_breakpoints </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
current task, making a new mapping
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Return nonzero if <parameter>task</parameter> is expected to want breakpoint insertion in
its memory at some point. A zero return is no guarantee it won't
be done, but this is a hint that it's known to be likely.
</para><para>
May be called with <parameter>task</parameter>->mm->mmap_sem held for writing.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-report-syscall-entry">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_report_syscall_entry</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_report_syscall_entry</refname>
<refpurpose>
task is about to attempt a system call
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>__must_check int <function>tracehook_report_syscall_entry </function></funcdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
user register state of current task
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This will be called if <constant>TIF_SYSCALL_TRACE</constant> has been set, when the
current task has just entered the kernel for a system call.
Full user register state is available here. Changing the values
in <parameter>regs</parameter> can affect the system call number and arguments to be tried.
It is safe to block here, preventing the system call from beginning.
</para><para>
Returns zero normally, or nonzero if the calling arch code should abort
the system call. That must prevent normal entry so no system call is
made. If <parameter>task</parameter> ever returns to user mode after this, its register state
is unspecified, but should be something harmless like an <constant>ENOSYS</constant> error
return. It should preserve enough information so that <function>syscall_rollback</function>
can work (see asm-generic/syscall.h).
</para><para>
Called without locks, just after entering kernel mode.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-report-syscall-exit">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_report_syscall_exit</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_report_syscall_exit</refname>
<refpurpose>
task has just finished a system call
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_report_syscall_exit </function></funcdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
<paramdef>int <parameter>step</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
user register state of current task
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>step</parameter></term>
<listitem>
<para>
nonzero if simulating single-step or block-step
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This will be called if <constant>TIF_SYSCALL_TRACE</constant> has been set, when the
current task has just finished an attempted system call. Full
user register state is available here. It is safe to block here,
preventing signals from being processed.
</para><para>
If <parameter>step</parameter> is nonzero, this report is also in lieu of the normal
trap that would follow the system call instruction because
<function>user_enable_block_step</function> or <function>user_enable_single_step</function> was used.
In this case, <constant>TIF_SYSCALL_TRACE</constant> might not be set.
</para><para>
Called without locks, just before checking for pending signals.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-unsafe-exec">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_unsafe_exec</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_unsafe_exec</refname>
<refpurpose>
check for exec declared unsafe due to tracing
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>tracehook_unsafe_exec </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
current task doing exec
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Return <constant>LSM_UNSAFE_</constant>* bits applied to an exec because of tracing.
</para><para>
<parameter>task</parameter>->cred_guard_mutex is held by the caller through the <function>do_execve</function>.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-tracer-task">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_tracer_task</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_tracer_task</refname>
<refpurpose>
return the task that is tracing the given task
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct task_struct * <function>tracehook_tracer_task </function></funcdef>
<paramdef>struct task_struct * <parameter>tsk</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>tsk</parameter></term>
<listitem>
<para>
task to consider
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Returns NULL if noone is tracing <parameter>task</parameter>, or the <structname>struct task_struct</structname>
pointer to its tracer.
</para><para>
Must called under <function>rcu_read_lock</function>. The pointer returned might be kept
live only by RCU. During exec, this may be called with <function>task_lock</function>
held on <parameter>task</parameter>, still held from when <function>tracehook_unsafe_exec</function> was called.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-report-exec">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_report_exec</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_report_exec</refname>
<refpurpose>
a successful exec was completed
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_report_exec </function></funcdef>
<paramdef>struct linux_binfmt * <parameter>fmt</parameter></paramdef>
<paramdef>struct linux_binprm * <parameter>bprm</parameter></paramdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fmt</parameter></term>
<listitem>
<para>
<structname>struct linux_binfmt</structname> that performed the exec
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>bprm</parameter></term>
<listitem>
<para>
<structname>struct linux_binprm</structname> containing exec details
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
user-mode register state
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
An exec just completed, we are shortly going to return to user mode.
The freshly initialized register state can be seen and changed in <parameter>regs</parameter>.
The name, file and other pointers in <parameter>bprm</parameter> are still on hand to be
inspected, but will be freed as soon as this returns.
</para><para>
Called with no locks, but with some kernel resources held live
and a reference on <parameter>fmt</parameter>->module.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-report-exit">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_report_exit</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_report_exit</refname>
<refpurpose>
task has begun to exit
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_report_exit </function></funcdef>
<paramdef>long * <parameter>exit_code</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>exit_code</parameter></term>
<listitem>
<para>
pointer to value destined for <parameter>current</parameter>->exit_code
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<parameter>exit_code</parameter> points to the value passed to <function>do_exit</function>, which tracing
might change here. This is almost the first thing in <function>do_exit</function>,
before freeing any resources or setting the <constant>PF_EXITING</constant> flag.
</para><para>
Called with no locks held.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-init-task">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_init_task</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_init_task</refname>
<refpurpose>
task_struct has just been copied
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_init_task </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
new <structname>struct task_struct</structname> just copied from parent
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Called from <function>do_fork</function> when <parameter>task</parameter> has just been duplicated.
After this, <parameter>task</parameter> will be passed to <function>tracehook_free_task</function>
even if the rest of its setup fails before it is fully created.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-free-task">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_free_task</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_free_task</refname>
<refpurpose>
task_struct is being freed
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_free_task </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
dead <structname>struct task_struct</structname> being freed
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Called from <function>free_task</function> when <parameter>task</parameter> is no longer in use.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-prepare-clone">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_prepare_clone</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_prepare_clone</refname>
<refpurpose>
prepare for new child to be cloned
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>tracehook_prepare_clone </function></funcdef>
<paramdef>unsigned <parameter>clone_flags</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>clone_flags</parameter></term>
<listitem>
<para>
<constant>CLONE_</constant>* flags from clone/fork/vfork system call
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is called before a new user task is to be cloned.
Its return value will be passed to <function>tracehook_finish_clone</function>.
</para><para>
Called with no locks held.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-finish-clone">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_finish_clone</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_finish_clone</refname>
<refpurpose>
new child created and being attached
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_finish_clone </function></funcdef>
<paramdef>struct task_struct * <parameter>child</parameter></paramdef>
<paramdef>unsigned long <parameter>clone_flags</parameter></paramdef>
<paramdef>int <parameter>trace</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>child</parameter></term>
<listitem>
<para>
new child task
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>clone_flags</parameter></term>
<listitem>
<para>
<constant>CLONE_</constant>* flags from clone/fork/vfork system call
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>trace</parameter></term>
<listitem>
<para>
return value from <function>tracehook_prepare_clone</function>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is called immediately after adding <parameter>child</parameter> to its parent's children list.
The <parameter>trace</parameter> value is that returned by <function>tracehook_prepare_clone</function>.
</para><para>
Called with current's siglock and write_lock_irq(<structname>tasklist_lock</structname>) held.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-report-clone">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_report_clone</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_report_clone</refname>
<refpurpose>
in parent, new child is about to start running
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_report_clone </function></funcdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
<paramdef>unsigned long <parameter>clone_flags</parameter></paramdef>
<paramdef>pid_t <parameter>pid</parameter></paramdef>
<paramdef>struct task_struct * <parameter>child</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
parent's user register state
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>clone_flags</parameter></term>
<listitem>
<para>
flags from parent's system call
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pid</parameter></term>
<listitem>
<para>
new child's PID in the parent's namespace
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>child</parameter></term>
<listitem>
<para>
new child task
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Called after a child is set up, but before it has been started running.
This is not a good place to block, because the child has not started
yet. Suspend the child here if desired, and then block in
<function>tracehook_report_clone_complete</function>. This must prevent the child from
self-reaping if <function>tracehook_report_clone_complete</function> uses the <parameter>child</parameter>
pointer; otherwise it might have died and been released by the time
<function>tracehook_report_clone_complete</function> is called.
</para><para>
Called with no locks held, but the child cannot run until this returns.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-report-clone-complete">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_report_clone_complete</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_report_clone_complete</refname>
<refpurpose>
new child is running
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_report_clone_complete </function></funcdef>
<paramdef>int <parameter>trace</parameter></paramdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
<paramdef>unsigned long <parameter>clone_flags</parameter></paramdef>
<paramdef>pid_t <parameter>pid</parameter></paramdef>
<paramdef>struct task_struct * <parameter>child</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>trace</parameter></term>
<listitem>
<para>
return value from <function>tracehook_prepare_clone</function>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
parent's user register state
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>clone_flags</parameter></term>
<listitem>
<para>
flags from parent's system call
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pid</parameter></term>
<listitem>
<para>
new child's PID in the parent's namespace
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>child</parameter></term>
<listitem>
<para>
child task, already running
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is called just after the child has started running. This is
just before the clone/fork syscall returns, or blocks for vfork
child completion if <parameter>clone_flags</parameter> has the <constant>CLONE_VFORK</constant> bit set.
The <parameter>child</parameter> pointer may be invalid if a self-reaping child died and
<function>tracehook_report_clone</function> took no action to prevent it from self-reaping.
</para><para>
Called with no locks held.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-report-vfork-done">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_report_vfork_done</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_report_vfork_done</refname>
<refpurpose>
vfork parent's child has exited or exec'd
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_report_vfork_done </function></funcdef>
<paramdef>struct task_struct * <parameter>child</parameter></paramdef>
<paramdef>pid_t <parameter>pid</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>child</parameter></term>
<listitem>
<para>
child task, already running
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pid</parameter></term>
<listitem>
<para>
new child's PID in the parent's namespace
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Called after a <constant>CLONE_VFORK</constant> parent has waited for the child to complete.
The clone/vfork system call will return immediately after this.
The <parameter>child</parameter> pointer may be invalid if a self-reaping child died and
<function>tracehook_report_clone</function> took no action to prevent it from self-reaping.
</para><para>
Called with no locks held.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-prepare-release-task">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_prepare_release_task</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_prepare_release_task</refname>
<refpurpose>
task is being reaped, clean up tracing
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_prepare_release_task </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task in <constant>EXIT_DEAD</constant> state
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is called in <function>release_task</function> just before <parameter>task</parameter> gets finally reaped
and freed. This would be the ideal place to remove and clean up any
tracing-related state for <parameter>task</parameter>.
</para><para>
Called with no locks held.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-finish-release-task">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_finish_release_task</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_finish_release_task</refname>
<refpurpose>
final tracing clean-up
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_finish_release_task </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task in <constant>EXIT_DEAD</constant> state
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is called in <function>release_task</function> when <parameter>task</parameter> is being in the middle of
being reaped. After this, there must be no tracing entanglements.
</para><para>
Called with write_lock_irq(<structname>tasklist_lock</structname>) held.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-signal-handler">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_signal_handler</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_signal_handler</refname>
<refpurpose>
signal handler setup is complete
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_signal_handler </function></funcdef>
<paramdef>int <parameter>sig</parameter></paramdef>
<paramdef>siginfo_t * <parameter>info</parameter></paramdef>
<paramdef>const struct k_sigaction * <parameter>ka</parameter></paramdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
<paramdef>int <parameter>stepping</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sig</parameter></term>
<listitem>
<para>
number of signal being delivered
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>info</parameter></term>
<listitem>
<para>
siginfo_t of signal being delivered
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ka</parameter></term>
<listitem>
<para>
sigaction setting that chose the handler
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
user register state
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>stepping</parameter></term>
<listitem>
<para>
nonzero if debugger single-step or block-step in use
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Called by the arch code after a signal handler has been set up.
Register and stack state reflects the user handler about to run.
Signal mask changes have already been made.
</para><para>
Called without locks, shortly before returning to user mode
(or handling more signals).
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-consider-ignored-signal">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_consider_ignored_signal</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_consider_ignored_signal</refname>
<refpurpose>
suppress short-circuit of ignored signal
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>tracehook_consider_ignored_signal </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
<paramdef>int <parameter>sig</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task receiving the signal
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sig</parameter></term>
<listitem>
<para>
signal number being sent
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Return zero iff tracing doesn't care to examine this ignored signal,
so it can short-circuit normal delivery and never even get queued.
</para><para>
Called with <parameter>task</parameter>->sighand->siglock held.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-consider-fatal-signal">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_consider_fatal_signal</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_consider_fatal_signal</refname>
<refpurpose>
suppress special handling of fatal signal
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>tracehook_consider_fatal_signal </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
<paramdef>int <parameter>sig</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task receiving the signal
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sig</parameter></term>
<listitem>
<para>
signal number being sent
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Return nonzero to prevent special handling of this termination signal.
Normally handler for signal is <constant>SIG_DFL</constant>. It can be <constant>SIG_IGN</constant> if <parameter>sig</parameter> is
ignored, in which case <function>force_sig</function> is about to reset it to <constant>SIG_DFL</constant>.
When this returns zero, this signal might cause a quick termination
that does not give the debugger a chance to intercept the signal.
</para><para>
Called with or without <parameter>task</parameter>->sighand->siglock held.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-force-sigpending">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_force_sigpending</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_force_sigpending</refname>
<refpurpose>
let tracing force signal_pending(current) on
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>tracehook_force_sigpending </function></funcdef>
<paramdef> <parameter>void</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>void</parameter></term>
<listitem>
<para>
no arguments
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
Called when recomputing our <function>signal_pending</function> flag. Return nonzero
to force the <function>signal_pending</function> flag on, so that <function>tracehook_get_signal</function>
will be called before the next return to user mode.
</para><para>
Called with <parameter>current</parameter>->sighand->siglock held.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-get-signal">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_get_signal</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_get_signal</refname>
<refpurpose>
deliver synthetic signal to traced task
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>tracehook_get_signal </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
<paramdef>siginfo_t * <parameter>info</parameter></paramdef>
<paramdef>struct k_sigaction * <parameter>return_ka</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
<parameter>current</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
task_pt_regs(<parameter>current</parameter>)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>info</parameter></term>
<listitem>
<para>
details of synthetic signal
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>return_ka</parameter></term>
<listitem>
<para>
sigaction for synthetic signal
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Return zero to check for a real pending signal normally.
Return -1 after releasing the siglock to repeat the check.
Return a signal number to induce an artifical signal delivery,
setting *<parameter>info</parameter> and *<parameter>return_ka</parameter> to specify its details and behavior.
</para><para>
The <parameter>return_ka</parameter>->sa_handler value controls the disposition of the
signal, no matter the signal number. For <constant>SIG_DFL</constant>, the return value
is a representative signal to indicate the behavior (e.g. <constant>SIGTERM</constant>
for death, <constant>SIGQUIT</constant> for core dump, <constant>SIGSTOP</constant> for job control stop,
<constant>SIGTSTP</constant> for stop unless in an orphaned pgrp), but the signal number
reported will be <parameter>info</parameter>->si_signo instead.
</para><para>
Called with <parameter>task</parameter>->sighand->siglock held, before dequeuing pending signals.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-notify-jctl">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_notify_jctl</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_notify_jctl</refname>
<refpurpose>
report about job control stop/continue
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>tracehook_notify_jctl </function></funcdef>
<paramdef>int <parameter>notify</parameter></paramdef>
<paramdef>int <parameter>why</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>notify</parameter></term>
<listitem>
<para>
zero, <constant>CLD_STOPPED</constant> or <constant>CLD_CONTINUED</constant>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>why</parameter></term>
<listitem>
<para>
<constant>CLD_STOPPED</constant> or <constant>CLD_CONTINUED</constant>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is called when we might call <function>do_notify_parent_cldstop</function>.
</para><para>
<parameter>notify</parameter> is zero if we would not ordinarily send a <constant>SIGCHLD</constant>,
or is the <constant>CLD_STOPPED</constant> or <constant>CLD_CONTINUED</constant> .si_code for <constant>SIGCHLD</constant>.
</para><para>
<parameter>why</parameter> is <constant>CLD_STOPPED</constant> when about to stop for job control;
we are already in <constant>TASK_STOPPED</constant> state, about to call <function>schedule</function>.
It might also be that we have just exited (check <constant>PF_EXITING</constant>),
but need to report that a group-wide stop is complete.
</para><para>
<parameter>why</parameter> is <constant>CLD_CONTINUED</constant> when waking up after job control stop and
ready to make a delayed <parameter>notify</parameter> report.
</para><para>
Return the <constant>CLD_</constant>* value for <constant>SIGCHLD</constant>, or zero to generate no signal.
</para><para>
Called with the siglock held.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-finish-jctl">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_finish_jctl</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_finish_jctl</refname>
<refpurpose>
report about return from job control stop
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_finish_jctl </function></funcdef>
<paramdef> <parameter>void</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>void</parameter></term>
<listitem>
<para>
no arguments
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
This is called by <function>do_signal_stop</function> after wakeup.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-notify-death">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_notify_death</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_notify_death</refname>
<refpurpose>
task is dead, ready to notify parent
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>tracehook_notify_death </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
<paramdef>void ** <parameter>death_cookie</parameter></paramdef>
<paramdef>int <parameter>group_dead</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
<parameter>current</parameter> task now exiting
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>death_cookie</parameter></term>
<listitem>
<para>
value to pass to <function>tracehook_report_death</function>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>group_dead</parameter></term>
<listitem>
<para>
nonzero if this was the last thread in the group to die
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
A return value >= 0 means call <function>do_notify_parent</function> with that signal
number. Negative return value can be <constant>DEATH_REAP</constant> to self-reap right
now, or <constant>DEATH_DELAYED_GROUP_LEADER</constant> to a zombie without notifying our
parent. Note that a return value of 0 means a <function>do_notify_parent</function> call
that sends no signal, but still wakes up a parent blocked in wait*().
</para><para>
Called with write_lock_irq(<structname>tasklist_lock</structname>) held.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-report-death">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_report_death</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_report_death</refname>
<refpurpose>
task is dead and ready to be reaped
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_report_death </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
<paramdef>int <parameter>signal</parameter></paramdef>
<paramdef>void * <parameter>death_cookie</parameter></paramdef>
<paramdef>int <parameter>group_dead</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
<parameter>current</parameter> task now exiting
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>signal</parameter></term>
<listitem>
<para>
return value from <function>tracheook_notify_death</function>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>death_cookie</parameter></term>
<listitem>
<para>
value passed back from <function>tracehook_notify_death</function>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>group_dead</parameter></term>
<listitem>
<para>
nonzero if this was the last thread in the group to die
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Thread has just become a zombie or is about to self-reap. If positive,
<parameter>signal</parameter> is the signal number just sent to the parent (usually <constant>SIGCHLD</constant>).
If <parameter>signal</parameter> is <constant>DEATH_REAP</constant>, this thread will self-reap. If <parameter>signal</parameter> is
<constant>DEATH_DELAYED_GROUP_LEADER</constant>, this is a <function>delayed_group_leader</function> zombie.
The <parameter>death_cookie</parameter> was passed back by <function>tracehook_notify_death</function>.
</para><para>
If normal reaping is not inhibited, <parameter>task</parameter>->exit_state might be changing
in parallel.
</para><para>
Called without locks.
</para>
</refsect1>
</refentry>
<refentry id="API-set-notify-resume">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>set_notify_resume</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>set_notify_resume</refname>
<refpurpose>
cause <function>tracehook_notify_resume</function> to be called
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>set_notify_resume </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
task that will call <function>tracehook_notify_resume</function>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Calling this arranges that <parameter>task</parameter> will call <function>tracehook_notify_resume</function>
before returning to user mode. If it's already running in user mode,
it will enter the kernel and call <function>tracehook_notify_resume</function> soon.
If it's blocked, it will not be woken.
</para>
</refsect1>
</refentry>
<refentry id="API-tracehook-notify-resume">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>tracehook_notify_resume</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>tracehook_notify_resume</refname>
<refpurpose>
report when about to return to user mode
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>tracehook_notify_resume </function></funcdef>
<paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>regs</parameter></term>
<listitem>
<para>
user-mode registers of <parameter>current</parameter> task
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This is called when <constant>TIF_NOTIFY_RESUME</constant> has been set. Now we are
about to return to user mode, and the user state in <parameter>regs</parameter> can be
inspected or adjusted. The caller in arch code has cleared
<constant>TIF_NOTIFY_RESUME</constant> before the call. If the flag gets set again
asynchronously, this will be called again before we return to
user mode.
</para><para>
Called without locks. However, on some machines this may be
called with interrupts disabled.
</para>
</refsect1>
</refentry>
</sect1>
<sect1 id="arch"><title>Architecture Calls Out</title>
<para>
An arch that has done all these things sets
<constant>CONFIG_HAVE_ARCH_TRACEHOOK</constant>.
This is required to enable the <application>utrace</application> code.
</para>
<sect2 id="arch-ptrace"><title><filename><asm/ptrace.h></filename></title>
<para>
An arch defines these in <filename><asm/ptrace.h></filename>
if it supports hardware single-step or block-step features.
</para>
<refentry id="API-arch-has-single-step">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>arch_has_single_step</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>arch_has_single_step</refname>
<refpurpose>
does this CPU support user-mode single-step?
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef> <function>arch_has_single_step </function></funcdef>
<void/>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<para>
None
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
If this is defined, then there must be function declarations or
inlines for <function>user_enable_single_step</function> and <function>user_disable_single_step</function>.
<function>arch_has_single_step</function> should evaluate to nonzero iff the machine
supports instruction single-step for user mode.
It can be a constant or it can test a CPU feature bit.
</para>
</refsect1>
</refentry>
<refentry id="API-arch-has-block-step">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>arch_has_block_step</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>arch_has_block_step</refname>
<refpurpose>
does this CPU support user-mode block-step?
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef> <function>arch_has_block_step </function></funcdef>
<void/>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<para>
None
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
If this is defined, then there must be a function declaration or inline
for <function>user_enable_block_step</function>, and <function>arch_has_single_step</function> must be defined
too. <function>arch_has_block_step</function> should evaluate to nonzero iff the machine
supports step-until-branch for user mode. It can be a constant or it
can test a CPU feature bit.
</para>
</refsect1>
</refentry>
<refentry id="API-user-enable-single-step">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>user_enable_single_step</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>user_enable_single_step</refname>
<refpurpose>
single-step in user-mode task
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>user_enable_single_step </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
either current or a task stopped in <constant>TASK_TRACED</constant>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This can only be called when <function>arch_has_single_step</function> has returned nonzero.
Set <parameter>task</parameter> so that when it returns to user mode, it will trap after the
next single instruction executes. If <function>arch_has_block_step</function> is defined,
this must clear the effects of <function>user_enable_block_step</function> too.
</para>
</refsect1>
</refentry>
<refentry id="API-user-enable-block-step">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>user_enable_block_step</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>user_enable_block_step</refname>
<refpurpose>
step until branch in user-mode task
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>user_enable_block_step </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
either current or a task stopped in <constant>TASK_TRACED</constant>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This can only be called when <function>arch_has_block_step</function> has returned nonzero,
and will never be called when single-instruction stepping is being used.
Set <parameter>task</parameter> so that when it returns to user mode, it will trap after the
next branch or trap taken.
</para>
</refsect1>
</refentry>
<refentry id="API-user-disable-single-step">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>user_disable_single_step</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>user_disable_single_step</refname>
<refpurpose>
cancel user-mode single-step
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>user_disable_single_step </function></funcdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
either current or a task stopped in <constant>TASK_TRACED</constant>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Clear <parameter>task</parameter> of the effects of <function>user_enable_single_step</function> and
<function>user_enable_block_step</function>. This can be called whether or not either
of those was ever called on <parameter>task</parameter>, and even if <function>arch_has_single_step</function>
returned zero.
</para>
</refsect1>
</refentry>
</sect2>
<sect2 id="arch-syscall">
<title><filename><asm/syscall.h></filename></title>
<para>
An arch provides <filename><asm/syscall.h></filename> that
defines these as inlines, or declares them as exported functions.
These interfaces are described in <xref linkend="syscall"/>.
</para>
</sect2>
<sect2 id="arch-tracehook">
<title><filename><linux/tracehook.h></filename></title>
<para>
An arch must define <constant>TIF_NOTIFY_RESUME</constant>
and <constant>TIF_SYSCALL_TRACE</constant>
in its <filename><asm/thread_info.h></filename>.
The arch code must call the following functions, all declared
in <filename><linux/tracehook.h></filename> and
described in <xref linkend="tracehook"/>:
<itemizedlist>
<listitem>
<para><function>tracehook_notify_resume</function></para>
</listitem>
<listitem>
<para><function>tracehook_report_syscall_entry</function></para>
</listitem>
<listitem>
<para><function>tracehook_report_syscall_exit</function></para>
</listitem>
<listitem>
<para><function>tracehook_signal_handler</function></para>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
</chapter>
</book>
