<?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="Tracepoints">
<bookinfo>
<title>The Linux Kernel Tracepoint API</title>
<authorgroup>
<author>
<firstname>Jason</firstname>
<surname>Baron</surname>
<affiliation>
<address>
<email>jbaron@redhat.com</email>
</address>
</affiliation>
</author>
</authorgroup>
<legalnotice>
<para>
This documentation is free software; you can redistribute
it and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.
</para>
<para>
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
</para>
<para>
You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA
</para>
<para>
For more details see the file COPYING in the source
distribution of Linux.
</para>
</legalnotice>
</bookinfo>
<toc></toc>
<chapter id="intro">
<title>Introduction</title>
<para>
Tracepoints are static probe points that are located in strategic points
throughout the kernel. 'Probes' register/unregister with tracepoints
via a callback mechanism. The 'probes' are strictly typed functions that
are passed a unique set of parameters defined by each tracepoint.
</para>
<para>
From this simple callback mechanism, 'probes' can be used to profile, debug,
and understand kernel behavior. There are a number of tools that provide a
framework for using 'probes'. These tools include Systemtap, ftrace, and
LTTng.
</para>
<para>
Tracepoints are defined in a number of header files via various macros. Thus,
the purpose of this document is to provide a clear accounting of the available
tracepoints. The intention is to understand not only what tracepoints are
available but also to understand where future tracepoints might be added.
</para>
<para>
The API presented has functions of the form:
<function>trace_tracepointname(function parameters)</function>. These are the
tracepoints callbacks that are found throughout the code. Registering and
unregistering probes with these callback sites is covered in the
<filename>Documentation/trace/*</filename> directory.
</para>
</chapter>
<chapter id="irq">
<title>IRQ</title>
<!-- include/trace/events/irq.h -->
<refentry id="API-trace-irq-handler-entry">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>trace_irq_handler_entry</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>trace_irq_handler_entry</refname>
<refpurpose>
called immediately before the irq action handler
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>trace_irq_handler_entry </function></funcdef>
<paramdef>int <parameter>irq</parameter></paramdef>
<paramdef>struct irqaction * <parameter>action</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>irq</parameter></term>
<listitem>
<para>
irq number
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>action</parameter></term>
<listitem>
<para>
pointer to struct irqaction
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
The struct irqaction pointed to by <parameter>action</parameter> contains various
information about the handler, including the device name,
<parameter>action</parameter>->name, and the device id, <parameter>action</parameter>->dev_id. When used in
conjunction with the irq_handler_exit tracepoint, we can figure
out irq handler latencies.
</para>
</refsect1>
</refentry>
<refentry id="API-trace-irq-handler-exit">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>trace_irq_handler_exit</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>trace_irq_handler_exit</refname>
<refpurpose>
called immediately after the irq action handler returns
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>trace_irq_handler_exit </function></funcdef>
<paramdef>int <parameter>irq</parameter></paramdef>
<paramdef>struct irqaction * <parameter>action</parameter></paramdef>
<paramdef>int <parameter>ret</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>irq</parameter></term>
<listitem>
<para>
irq number
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>action</parameter></term>
<listitem>
<para>
pointer to struct irqaction
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ret</parameter></term>
<listitem>
<para>
return value
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
If the <parameter>ret</parameter> value is set to IRQ_HANDLED, then we know that the corresponding
<parameter>action</parameter>->handler scuccessully handled this irq. Otherwise, the irq might be
a shared irq line, or the irq was not handled successfully. Can be used in
conjunction with the irq_handler_entry to understand irq handler latencies.
</para>
</refsect1>
</refentry>
<refentry id="API-trace-softirq-entry">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>trace_softirq_entry</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>trace_softirq_entry</refname>
<refpurpose>
called immediately before the softirq handler
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>trace_softirq_entry </function></funcdef>
<paramdef>struct softirq_action * <parameter>h</parameter></paramdef>
<paramdef>struct softirq_action * <parameter>vec</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>h</parameter></term>
<listitem>
<para>
pointer to struct softirq_action
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>vec</parameter></term>
<listitem>
<para>
pointer to first struct softirq_action in softirq_vec array
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
The <parameter>h</parameter> parameter, contains a pointer to the struct softirq_action
which has a pointer to the action handler that is called. By subtracting
the <parameter>vec</parameter> pointer from the <parameter>h</parameter> pointer, we can determine the softirq
number. Also, when used in combination with the softirq_exit tracepoint
we can determine the softirq latency.
</para>
</refsect1>
</refentry>
<refentry id="API-trace-softirq-exit">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>trace_softirq_exit</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>trace_softirq_exit</refname>
<refpurpose>
called immediately after the softirq handler returns
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>trace_softirq_exit </function></funcdef>
<paramdef>struct softirq_action * <parameter>h</parameter></paramdef>
<paramdef>struct softirq_action * <parameter>vec</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>h</parameter></term>
<listitem>
<para>
pointer to struct softirq_action
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>vec</parameter></term>
<listitem>
<para>
pointer to first struct softirq_action in softirq_vec array
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
The <parameter>h</parameter> parameter contains a pointer to the struct softirq_action
that has handled the softirq. By subtracting the <parameter>vec</parameter> pointer from
the <parameter>h</parameter> pointer, we can determine the softirq number. Also, when used in
combination with the softirq_entry tracepoint we can determine the softirq
latency.
</para>
</refsect1>
</refentry>
</chapter>
<chapter id="signal">
<title>SIGNAL</title>
<!-- include/trace/events/signal.h -->
<refentry id="API-trace-signal-generate">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>trace_signal_generate</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>trace_signal_generate</refname>
<refpurpose>
called when a signal is generated
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>trace_signal_generate </function></funcdef>
<paramdef>int <parameter>sig</parameter></paramdef>
<paramdef>struct siginfo * <parameter>info</parameter></paramdef>
<paramdef>struct task_struct * <parameter>task</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sig</parameter></term>
<listitem>
<para>
signal number
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>info</parameter></term>
<listitem>
<para>
pointer to struct siginfo
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
pointer to struct task_struct
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Current process sends a 'sig' signal to 'task' process with
'info' siginfo. If 'info' is SEND_SIG_NOINFO or SEND_SIG_PRIV,
'info' is not a pointer and you can't access its field. Instead,
SEND_SIG_NOINFO means that si_code is SI_USER, and SEND_SIG_PRIV
means that si_code is SI_KERNEL.
</para>
</refsect1>
</refentry>
<refentry id="API-trace-signal-deliver">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>trace_signal_deliver</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>trace_signal_deliver</refname>
<refpurpose>
called when a signal is delivered
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>trace_signal_deliver </function></funcdef>
<paramdef>int <parameter>sig</parameter></paramdef>
<paramdef>struct siginfo * <parameter>info</parameter></paramdef>
<paramdef>struct k_sigaction * <parameter>ka</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sig</parameter></term>
<listitem>
<para>
signal number
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>info</parameter></term>
<listitem>
<para>
pointer to struct siginfo
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ka</parameter></term>
<listitem>
<para>
pointer to struct k_sigaction
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
A 'sig' signal is delivered to current process with 'info' siginfo,
and it will be handled by 'ka'. ka->sa.sa_handler can be SIG_IGN or
SIG_DFL.
Note that some signals reported by signal_generate tracepoint can be
lost, ignored or modified (by debugger) before hitting this tracepoint.
This means, this can show which signals are actually delivered, but
matching generated signals and delivered signals may not be correct.
</para>
</refsect1>
</refentry>
<refentry id="API-trace-signal-overflow-fail">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>trace_signal_overflow_fail</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>trace_signal_overflow_fail</refname>
<refpurpose>
called when signal queue is overflow
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>trace_signal_overflow_fail </function></funcdef>
<paramdef>int <parameter>sig</parameter></paramdef>
<paramdef>int <parameter>group</parameter></paramdef>
<paramdef>struct siginfo * <parameter>info</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sig</parameter></term>
<listitem>
<para>
signal number
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>group</parameter></term>
<listitem>
<para>
signal to process group or not (bool)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>info</parameter></term>
<listitem>
<para>
pointer to struct siginfo
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Kernel fails to generate 'sig' signal with 'info' siginfo, because
siginfo queue is overflow, and the signal is dropped.
'group' is not 0 if the signal will be sent to a process group.
'sig' is always one of RT signals.
</para>
</refsect1>
</refentry>
<refentry id="API-trace-signal-lose-info">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>June 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>trace_signal_lose_info</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>trace_signal_lose_info</refname>
<refpurpose>
called when siginfo is lost
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>trace_signal_lose_info </function></funcdef>
<paramdef>int <parameter>sig</parameter></paramdef>
<paramdef>int <parameter>group</parameter></paramdef>
<paramdef>struct siginfo * <parameter>info</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>sig</parameter></term>
<listitem>
<para>
signal number
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>group</parameter></term>
<listitem>
<para>
signal to process group or not (bool)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>info</parameter></term>
<listitem>
<para>
pointer to struct siginfo
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Kernel generates 'sig' signal but loses 'info' siginfo, because siginfo
queue is overflow.
'group' is not 0 if the signal will be sent to a process group.
'sig' is always one of non-RT signals.
</para>
</refsect1>
</refentry>
</chapter>
</book>
