<?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.76.1" /><link rel="home" href="index.html" title="The utrace User Debugging Infrastructure" /><link rel="up" href="core.html" title="Chapter 2. utrace core API" /><link rel="prev" href="API-utrace-set-events.html" title="utrace_set_events" /><link rel="next" href="API-utrace-barrier.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="API-utrace-set-events.html">Prev</a> </td><th width="60%" align="center">Chapter 2. utrace core API</th><td width="20%" align="right"> <a accesskey="n" href="API-utrace-barrier.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 <strong>fsfuncutrace_control </strong>(</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="id2768134"></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="id2768196"></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="id2768248"></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="id2768362"></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="id2768469"></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="id2768504"></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="id2768568"></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="id2768626"></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="id2768712"></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="API-utrace-set-events.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="core.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-utrace-barrier.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>