<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>utrace_control</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="index.html" title="The utrace User Debugging Infrastructure" /><link rel="up" href="ch02.html" title="Chapter 2. utrace core API" /><link rel="prev" href="re17.html" title="utrace_set_events" /><link rel="next" href="re19.html" title="utrace_barrier" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"><span>utrace_control</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="re17.html">Prev</a> </td><th width="60%" align="center">Chapter 2. utrace core API</th><td width="20%" align="right"> <a accesskey="n" href="re19.html">Next</a></td></tr></table><hr /></div><div class="refentry" title="utrace_control"><a id="API-utrace-control"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>utrace_control —
control a thread being traced by a tracing engine
</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">utrace_control </b>(</code></td><td>struct task_struct * <var class="pdparam">target</var>, </td></tr><tr><td> </td><td>struct utrace_engine * <var class="pdparam">engine</var>, </td></tr><tr><td> </td><td>enum utrace_resume_action <var class="pdparam">action</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Arguments"><a id="id2892449"></a><h2>Arguments</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
thread to affect
</p></dd><dt><span class="term"><em class="parameter"><code>engine</code></em></span></dt><dd><p>
attached engine to affect
</p></dd><dt><span class="term"><em class="parameter"><code>action</code></em></span></dt><dd><p>
<span class="structname">enum</span> utrace_resume_action for thread to do
</p></dd></dl></div></div><div class="refsect1" title="Description"><a id="id2892511"></a><h2>Description</h2><p>
This is how a tracing engine asks a traced thread to do something.
This call is controlled by the <em class="parameter"><code>action</code></em> argument, which has the
same meaning as the <span class="structname">enum</span> utrace_resume_action value returned by
event reporting callbacks.
</p><p>
If <em class="parameter"><code>target</code></em> is already dead (<em class="parameter"><code>target</code></em>->exit_state nonzero),
all actions except <code class="constant">UTRACE_DETACH</code> fail with -<code class="constant">ESRCH</code>.
</p><p>
The following sections describe each option for the <em class="parameter"><code>action</code></em> argument.
</p></div><div class="refsect1" title="UTRACE_DETACH"><a id="id2892562"></a><h2>UTRACE_DETACH</h2><p>
</p><p>
After this, the <em class="parameter"><code>engine</code></em> 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.
</p><p>
If the <em class="parameter"><code>report_reap</code></em> callback may already have begun, this fails
with -<code class="constant">ESRCH</code>. If the <em class="parameter"><code>report_death</code></em> callback may already have
begun, this fails with -<code class="constant">EALREADY</code>.
</p><p>
If <em class="parameter"><code>target</code></em> 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 -<code class="constant">EINPROGRESS</code>; the detach happens as soon as
the pending callback is finished. To synchronize after an
-<code class="constant">EINPROGRESS</code> return, see <code class="function">utrace_barrier</code>.
</p><p>
If <em class="parameter"><code>target</code></em> is properly stopped before <code class="function">utrace_control</code> is called,
then after successful return it's guaranteed that no more callbacks
to the <em class="parameter"><code>engine</code></em>->ops vector will be made.
</p><p>
The only exception is <code class="constant">SIGKILL</code> (and exec or group-exit by another
thread in the group), which can cause asynchronous <em class="parameter"><code>report_death</code></em>
and/or <em class="parameter"><code>report_reap</code></em> callbacks even when <code class="constant">UTRACE_STOP</code> was used.
(In that event, this fails with -<code class="constant">ESRCH</code> or -<code class="constant">EALREADY</code>, see above.)
</p></div><div class="refsect1" title="UTRACE_STOP"><a id="id2892676"></a><h2>UTRACE_STOP</h2><p>
</p><p>
This asks that <em class="parameter"><code>target</code></em> stop running. This returns 0 only if
<em class="parameter"><code>target</code></em> is already stopped, either for tracing or for job
control. Then <em class="parameter"><code>target</code></em> will remain stopped until another
<code class="function">utrace_control</code> call is made on <em class="parameter"><code>engine</code></em>; <em class="parameter"><code>target</code></em> can be woken
only by <code class="constant">SIGKILL</code> (or equivalent, such as exec or termination by
another thread in the same thread group).
</p><p>
This returns -<code class="constant">EINPROGRESS</code> if <em class="parameter"><code>target</code></em> is not already stopped.
Then the effect is like <code class="constant">UTRACE_REPORT</code>. A <em class="parameter"><code>report_quiesce</code></em> or
<em class="parameter"><code>report_signal</code></em> callback will be made soon. Your callback can
then return <code class="constant">UTRACE_STOP</code> to keep <em class="parameter"><code>target</code></em> stopped.
</p><p>
This does not interrupt system calls in progress, including ones
that sleep for a long time. For that, use <code class="constant">UTRACE_INTERRUPT</code>.
To interrupt system calls and then keep <em class="parameter"><code>target</code></em> stopped, your
<em class="parameter"><code>report_signal</code></em> callback can return <code class="constant">UTRACE_STOP</code>.
</p></div><div class="refsect1" title="UTRACE_RESUME"><a id="id2892783"></a><h2>UTRACE_RESUME</h2><p>
</p><p>
Just let <em class="parameter"><code>target</code></em> continue running normally, reversing the effect
of a previous <code class="constant">UTRACE_STOP</code>. If another engine is keeping <em class="parameter"><code>target</code></em>
stopped, then it remains stopped until all engines let it resume.
If <em class="parameter"><code>target</code></em> was not stopped, this has no effect.
</p></div><div class="refsect1" title="UTRACE_REPORT"><a id="id2892818"></a><h2>UTRACE_REPORT</h2><p>
</p><p>
This is like <code class="constant">UTRACE_RESUME</code>, but also ensures that there will be
a <em class="parameter"><code>report_quiesce</code></em> or <em class="parameter"><code>report_signal</code></em> callback made soon. If
<em class="parameter"><code>target</code></em> had been stopped, then there will be a callback before it
resumes running normally. If another engine is keeping <em class="parameter"><code>target</code></em>
stopped, then there might be no callbacks until all engines let
it resume.
</p><p>
Since this is meaningless unless <em class="parameter"><code>report_quiesce</code></em> callbacks will
be made, it returns -<code class="constant">EINVAL</code> if <em class="parameter"><code>engine</code></em> lacks <code class="constant">UTRACE_EVENT</code>(<code class="constant">QUIESCE</code>).
</p></div><div class="refsect1" title="UTRACE_INTERRUPT"><a id="id2892883"></a><h2>UTRACE_INTERRUPT</h2><p>
</p><p>
This is like <code class="constant">UTRACE_REPORT</code>, but ensures that <em class="parameter"><code>target</code></em> will make a
<em class="parameter"><code>report_signal</code></em> callback before it resumes or delivers signals.
If <em class="parameter"><code>target</code></em> was in a system call or about to enter one, work in
progress will be interrupted as if by <code class="constant">SIGSTOP</code>. If another
engine is keeping <em class="parameter"><code>target</code></em> stopped, then there might be no
callbacks until all engines let it resume.
</p><p>
This gives <em class="parameter"><code>engine</code></em> an opportunity to introduce a forced signal
disposition via its <em class="parameter"><code>report_signal</code></em> callback.
</p></div><div class="refsect1" title="UTRACE_SINGLESTEP"><a id="id2892940"></a><h2>UTRACE_SINGLESTEP</h2><p>
</p><p>
It's invalid to use this unless <code class="function">arch_has_single_step</code> returned true.
This is like <code class="constant">UTRACE_RESUME</code>, but resumes for one user instruction only.
</p><p>
Note that passing <code class="constant">UTRACE_SINGLESTEP</code> or <code class="constant">UTRACE_BLOCKSTEP</code> to
<code class="function">utrace_control</code> 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 <code class="constant">UTRACE_EVENT</code>(<code class="constant">QUIESCE</code>) and look for the
<em class="parameter"><code>report_quiesce</code></em> callback with a zero event mask, or the
<em class="parameter"><code>report_signal</code></em> callback with <code class="constant">UTRACE_SIGNAL_REPORT</code>.
</p><p>
Since this is not robust unless <em class="parameter"><code>report_quiesce</code></em> callbacks will
be made, it returns -<code class="constant">EINVAL</code> if <em class="parameter"><code>engine</code></em> lacks <code class="constant">UTRACE_EVENT</code>(<code class="constant">QUIESCE</code>).
</p></div><div class="refsect1" title="UTRACE_BLOCKSTEP"><a id="id2893026"></a><h2>UTRACE_BLOCKSTEP</h2><p>
</p><p>
It's invalid to use this unless <code class="function">arch_has_block_step</code> returned true.
This is like <code class="constant">UTRACE_SINGLESTEP</code>, but resumes for one whole basic
block of user instructions.
</p><p>
Since this is not robust unless <em class="parameter"><code>report_quiesce</code></em> callbacks will
be made, it returns -<code class="constant">EINVAL</code> if <em class="parameter"><code>engine</code></em> lacks <code class="constant">UTRACE_EVENT</code>(<code class="constant">QUIESCE</code>).
</p><p>
<code class="constant">UTRACE_BLOCKSTEP</code> devolves to <code class="constant">UTRACE_SINGLESTEP</code> when another
tracing engine is using <code class="constant">UTRACE_SINGLESTEP</code> at the same time.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="re17.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="re19.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span>utrace_set_events</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span>utrace_barrier</span></td></tr></table></div></body></html>
