| Author: | Jason Baron |
|---|---|
| Author: | William Cohen |
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.
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.
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.
The API presented has functions of the form: trace_tracepointname(function parameters). These are the tracepoints callbacks that are found throughout the code. Registering and unregistering probes with these callback sites is covered in the Documentation/trace/* directory.
called immediately before the irq action handler
Parameters
Description
The struct irqaction pointed to by action contains various information about the handler, including the device name, action->name, and the device id, action->dev_id. When used in conjunction with the irq_handler_exit tracepoint, we can figure out irq handler latencies.
called immediately after the irq action handler returns
Parameters
Description
If the ret value is set to IRQ_HANDLED, then we know that the corresponding action->handler successfully 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.
called immediately before the softirq handler
Parameters
Description
When used in combination with the softirq_exit tracepoint we can determine the softirq handler routine.
called immediately after the softirq handler returns
Parameters
Description
When used in combination with the softirq_entry tracepoint we can determine the softirq handler routine.
called immediately when a softirq is raised
Parameters
Description
When used in combination with the softirq_entry tracepoint we can determine the softirq raise to run latency.
called when a signal is generated
Parameters
Description
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.
called when a signal is delivered
Parameters
Description
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.
mark a buffer accessed
Parameters
Description
Called from touch_buffer().
mark a buffer dirty
Parameters
Description
Called from mark_buffer_dirty().
abort block operation request
Parameters
Description
Called immediately after pending block IO operation request rq in queue q is aborted. The fields in the operation request rq can be examined to determine which device and sectors the pending operation would access.
place block IO request back on a queue
Parameters
Description
The block operation request rq is being placed back into queue q. For some reason the request was not completed and needs to be put back in the queue.
block IO operation completed by device driver
Parameters
Description
The block_rq_complete tracepoint event indicates that some portion of operation request has been completed by the device driver. If the rq->bio is NULL, then there is absolutely no additional work to do for the request. If rq->bio is non-NULL then there is additional work required to complete the request.
insert block operation request into queue
Parameters
Description
Called immediately before block operation request rq is inserted into queue q. The fields in the operation request rq struct can be examined to determine which device and sectors the pending operation would access.
issue pending block IO request operation to device driver
Parameters
Description
Called when block operation request rq from queue q is sent to a device driver for processing.
used bounce buffer when processing block operation
Parameters
Description
A bounce buffer was used to handle the block operation bio in q. This occurs when hardware limitations prevent a direct transfer of data between the bio data memory area and the IO device. Use of a bounce buffer requires extra copying of data and decreases performance.
completed all work on the block operation
Parameters
Description
This tracepoint indicates there is no further work to do on this block IO operation bio.
merging block operation to the end of an existing operation
Parameters
Description
Merging block request bio to the end of an existing block request in queue q.
merging block operation to the beginning of an existing operation
Parameters
Description
Merging block IO operation bio to the beginning of an existing block operation in queue q.
putting new block IO operation in queue
Parameters
Description
About to place the block IO operation bio into queue q.
get a free request entry in queue for block IO operations
Parameters
Description
A request struct for queue q has been allocated to handle the block IO operation bio.
waiting to get a free request entry in queue for block IO operation
Parameters
Description
In the case where a request struct cannot be provided for queue q the process needs to wait for an request struct to become available. This tracepoint event is generated each time the process goes to sleep waiting for request struct become available.
keep operations requests in request queue
Parameters
Description
Plug the request queue q. Do not allow block operation requests to be sent to the device driver. Instead, accumulate requests in the queue to improve throughput performance of the block device.
release of operations requests in request queue
Parameters
Description
Unplug request queue q because device driver is scheduled to work on elements in the request queue.
split a single bio struct into two bio structs
Parameters
Description
The bio request bio in request queue q needs to be split into two bio requests. The newly created bio request starts at new_sector. This split may be required due to hardware limitation such as operation crossing device boundaries in a RAID system.
map request for a logical device to the raw device
Parameters
Description
An operation for a logical device has been mapped to the raw block device.
map request for a block operation request
Parameters
Description
The block operation request rq in q has been remapped. The block operation request rq holds the current information and from hold the original sector.
called when a work gets queued
Parameters
Description
This event occurs when a work is queued immediately or once a delayed work is actually queued on a workqueue (ie: once the delay has been reached).
called when a work gets activated
Parameters
Description
This event occurs when a queued work is put on the active queue, which happens immediately after queueing unless max_active limit is reached.
called immediately before the workqueue callback
Parameters
Description
Allows to track workqueue execution.
called immediately after the workqueue callback
Parameters
Description
Allows to track workqueue execution.