<?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>Events and Callbacks</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="ch01.html" title="Chapter 1. utrace concepts" /><link rel="prev" href="ch01.html" title="Chapter 1. utrace concepts" /><link rel="next" href="ch01s03.html" title="Stopping Safely" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Events and Callbacks</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch01.html">Prev</a> </td><th width="60%" align="center">Chapter 1. utrace concepts</th><td width="20%" align="right"> <a accesskey="n" href="ch01s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Events and Callbacks"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="callbacks"></a>Events and Callbacks</h2></div></div></div><p>
An attached engine does nothing by default. An engine makes something
happen by requesting callbacks via <code class="function">utrace_set_events</code>
and poking the thread with <code class="function">utrace_control</code>.
The synchronization issues related to these two calls
are discussed further below in <a class="xref" href="ch01s04.html" title="Tear-down Races">the section called “Tear-down Races”</a>.
</p><p>
Events are specified using the macro
<code class="constant">UTRACE_EVENT(<em class="replaceable"><code>type</code></em>)</code>.
Each event type is associated with a callback in <span class="structname">struct
utrace_engine_ops</span>. A tracing engine can leave unused
callbacks <code class="constant">NULL</code>. The only callbacks required
are those used by the event flags it sets.
</p><p>
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.
</p><p>
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
<code class="function">kmalloc</code> and the like, but never wait for i/o or
for user mode to do something. If you need the thread to wait, use
<code class="constant">UTRACE_STOP</code> and return from the callback
quickly. When your i/o finishes or whatever, you can use
<code class="function">utrace_control</code> to resume the thread.
</p><p>
The <code class="constant">UTRACE_EVENT(SYSCALL_ENTRY)</code> 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 <code class="function">report_syscall_entry</code> callback is
special in two ways. For this event, engines are called in reverse of
the normal order (this includes the <code class="function">report_quiesce</code>
call that precedes a <code class="function">report_syscall_entry</code> 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 <code class="constant">UTRACE_STOP</code> (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.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch01s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. utrace concepts </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Stopping Safely</td></tr></table></div></body></html>
