ftrace framework

//--------------------------------------------------------------------------

// ftrace.txt

Introduction

------------

Ftrace is an internal tracer designed to help out developers and

designers of systems to find what is going on inside the kernel.

It can be used for debugging or analyzing latencies and

performance issues that take place outside of user-space.

Although ftrace is typically considered the function tracer, it

is really a frame work of several assorted tracing utilities.

There's latency tracing to examine what occurs between interrupts

disabled and enabled, as well as for preemption and from a time

a task is woken to the task is actually scheduled in.

One of the most common uses of ftrace is the event tracing.

Through out the kernel is hundreds of static event points that

can be enabled via the debugfs file system to see what is

going on in certain parts of the kernel.

Implementation Details

----------------------

See ftrace-design.txt for details for arch porters and such.

The File System

---------------

Ftrace uses the debugfs file system to hold the control files as

well as the files to display output.

The Tracers

-----------

Examples of using the tracer

----------------------------

//--------------------------------------------------------------------------

//ftrace-design.txt

在编译的时候,就注入了接口, 另外:HAVE_FUNCTION_TRACER和FUNCTION_TRACER是两个不同的宏

ifdef CONFIG_FUNCTION_TRACER

ORIG_CFLAGS := $(KBUILD_CFLAGS)

KBUILD_CFLAGS = $(subst -pg,,$(ORIG_CFLAGS))

endif

HAVE_FUNCTION_TRACER

--------------------

You will need to implement the mcount and the ftrace_stub functions.

The exact mcount symbol name will depend on your toolchain. Some call it

"mcount", "_mcount", or even "__mcount". You can probably figure it out by

running something like:

$ echo 'main(){}' | gcc -x c -S -o - - -pg | grep mcount

call mcount

We'll make the assumption below that the symbol is "mcount" just to keep things

nice and simple in the examples.

Keep in mind that the ABI that is in effect inside of the mcount function is

*highly* architecture/toolchain specific. We cannot help you in this regard,

sorry. Dig up some old documentation and/or find someone more familiar than

you to bang ideas off of. Typically, register usage (argument/scratch/etc...)

is a major issue at this point, especially in relation to the location of the

mcount call (before/after function prologue). You might also want to look at

how glibc has implemented the mcount function for your architecture. It might

be (semi-)relevant.

The mcount function should check the function pointer ftrace_trace_function

to see if it is set to ftrace_stub. If it is, there is nothing for you to do,

so return immediately. If it isn't, then call that function in the same way

the mcount function normally calls __mcount_internal -- the first argument is

the "frompc" while the second argument is the "selfpc" (adjusted to remove the

size of the mcount call that is embedded in the function).

For example, if the function foo() calls bar(), when the bar() function calls

mcount(), the arguments mcount() will pass to the tracer are:

"frompc" - the address bar() will use to return to foo()

"selfpc" - the address bar() (with mcount() size adjustment)

Also keep in mind that this mcount function will be called *a lot*, so

optimizing for the default case of no tracer will help the smooth running of

your system when tracing is disabled. So the start of the mcount function is

typically the bare minimum with checking things before returning. That also

means the code flow should usually be kept linear (i.e. no branching in the nop

case). This is of course an optimization and not a hard requirement.

Here is some pseudo code that should help (these functions should actually be

implemented in assembly):

void ftrace_stub(void)

{

return;

}

void mcount(void)

{

/* save any bare state needed in order to do initial checking */

extern void (*ftrace_trace_function)(unsigned long, unsigned long);

if (ftrace_trace_function != ftrace_stub)

goto do_trace;

/* restore any bare state */

return;

do_trace:

/* save all state needed by the ABI (see paragraph above) */

unsigned long frompc = ...;

unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE;

ftrace_trace_function(frompc, selfpc);

/* restore all state needed by the ABI */

}

//--------------------------------------------------------------------------

tracepoints.txt

This document introduces Linux Kernel Tracepoints and their use. It

provides examples of how to insert tracepoints in the kernel and

connect probe functions to them and provides some examples of probe

functions.

* Purpose of tracepoints

A tracepoint placed in code provides a hook to call a function (probe)

that you can provide at runtime. A tracepoint can be "on" (a probe is

connected to it) or "off" (no probe is attached). When a tracepoint is

"off" it has no effect, except for adding a tiny time penalty

(checking a condition for a branch) and space penalty (adding a few

bytes for the function call at the end of the instrumented function

and adds a data structure in a separate section). When a tracepoint

is "on", the function you provide is called each time the tracepoint

is executed, in the execution context of the caller. When the function

provided ends its execution, it returns to the caller (continuing from

the tracepoint site).

You can put tracepoints at important locations in the code. They are

lightweight hooks that can pass an arbitrary number of parameters,

which prototypes are described in a tracepoint declaration placed in a

header file.

They can be used for tracing and performance accounting.

* Usage

Two elements are required for tracepoints :

- A tracepoint definition, placed in a header file.

- The tracepoint statement, in C code.

In order to use tracepoints, you should include linux/tracepoint.h.

In include/trace/events/subsys.h :

#undef TRACE_SYSTEM

#define TRACE_SYSTEM subsys

#if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ)

#define _TRACE_SUBSYS_H

#include <linux/tracepoint.h>

DECLARE_TRACE(subsys_eventname,

TP_PROTO(int firstarg, struct task_struct *p),

TP_ARGS(firstarg, p));

#endif /* _TRACE_SUBSYS_H */

/* This part must be outside protection */

#include <trace/define_trace.h>

In subsys/file.c (where the tracing statement must be added) :

#include <trace/events/subsys.h>

#define CREATE_TRACE_POINTS

DEFINE_TRACE(subsys_eventname);

void somefct(void)

{

...

trace_subsys_eventname(arg, task);

...

}

Where :

- subsys_eventname is an identifier unique to your event

- subsys is the name of your subsystem.

- eventname is the name of the event to trace.

- TP_PROTO(int firstarg, struct task_struct *p) is the prototype of the

function called by this tracepoint.

- TP_ARGS(firstarg, p) are the parameters names, same as found in the

prototype.

- if you use the header in multiple source files, #define CREATE_TRACE_POINTS

should appear only in one source file.

Connecting a function (probe) to a tracepoint is done by providing a

probe (function to call) for the specific tracepoint through

register_trace_subsys_eventname(). Removing a probe is done through

unregister_trace_subsys_eventname(); it will remove the probe.

tracepoint_synchronize_unregister() must be called before the end of

the module exit function to make sure there is no caller left using

the probe. This, and the fact that preemption is disabled around the

probe call, make sure that probe removal and module unload are safe.

The tracepoint mechanism supports inserting multiple instances of the

same tracepoint, but a single definition must be made of a given

tracepoint name over all the kernel to make sure no type conflict will

occur. Name mangling of the tracepoints is done using the prototypes

to make sure typing is correct. Verification of probe type correctness

is done at the registration site by the compiler. Tracepoints can be

put in inline functions, inlined static functions, and unrolled loops

as well as regular functions.

The naming scheme "subsys_event" is suggested here as a convention

intended to limit collisions. Tracepoint names are global to the

kernel: they are considered as being the same whether they are in the

core kernel image or in modules.

If the tracepoint has to be used in kernel modules, an

EXPORT_TRACEPOINT_SYMBOL_GPL() or EXPORT_TRACEPOINT_SYMBOL() can be

used to export the defined tracepoints.

If you need to do a bit of work for a tracepoint parameter, and

that work is only used for the tracepoint, that work can be encapsulated

within an if statement with the following:

if (trace_foo_bar_enabled()) {

int i;

int tot = 0;

for (i = 0; i < count; i++)

tot += calculate_nuggets();

trace_foo_bar(tot);

}

All trace_<tracepoint>() calls have a matching trace_<tracepoint>_enabled()

function defined that returns true if the tracepoint is enabled and

false otherwise. The trace_<tracepoint>() should always be within the

block of the if (trace_<tracepoint>_enabled()) to prevent races between

the tracepoint being enabled and the check being seen.

The advantage of using the trace_<tracepoint>_enabled() is that it uses

the static_key of the tracepoint to allow the if statement to be implemented

with jump labels and avoid conditional branches.

//------------------------------------------------------------------------

event:

1. Introduction

===============

Tracepoints (see Documentation/trace/tracepoints.txt) can be used

without creating custom kernel modules to register probe functions

using the event tracing infrastructure.

Not all tracepoints can be traced using the event tracing system;

the kernel developer must provide code snippets which define how the

tracing information is saved into the tracing buffer, and how the

tracing information should be printed.