| 1 |
.. |threshold| replace:: **-a/--auto**, **-i/--irq**, or **-T/--thread** |
| 2 |
.. |thresharg| replace:: -T |
| 3 |
.. |tracer| replace:: timerlat |
| 4 |
|
| 5 |
.. |actionsperf| replace:: |
| 6 |
For time-sensitive actions, it is recommended to run **rtla timerlat** with BPF |
| 7 |
support and RT priority. Note that due to implementational limitations, actions |
| 8 |
might be delayed up to one second after tracing is stopped if BPF mode is not |
| 9 |
available or disabled. |
| 10 |
|
| 11 |
**-a**, **--auto** *us* |
| 12 |
|
| 13 |
Set the automatic trace mode. This mode sets some commonly used options |
| 14 |
while debugging the system. It is equivalent to use **-T** *us* **-s** *us* |
| 15 |
**-t**. By default, *timerlat* tracer uses FIFO:95 for *timerlat* threads, |
| 16 |
thus equivalent to **-P** *f:95*. |
| 17 |
|
| 18 |
**-p**, **--period** *us* |
| 19 |
|
| 20 |
Set the *timerlat* tracer period in microseconds. |
| 21 |
|
| 22 |
**-i**, **--irq** *us* |
| 23 |
|
| 24 |
Stop trace if the *IRQ* latency is higher than the argument in us. |
| 25 |
|
| 26 |
**-T**, **--thread** *us* |
| 27 |
|
| 28 |
Stop trace if the *Thread* latency is higher than the argument in us. |
| 29 |
|
| 30 |
**-s**, **--stack** *us* |
| 31 |
|
| 32 |
Save the stack trace at the *IRQ* if a *Thread* latency is higher than the |
| 33 |
argument in us. |
| 34 |
|
| 35 |
**-t**, **--trace** \[*file*] |
| 36 |
|
| 37 |
Save the stopped trace to [*file|timerlat_trace.txt*]. |
| 38 |
|
| 39 |
**--dma-latency** *us* |
| 40 |
Set the /dev/cpu_dma_latency to *us*, aiming to bound exit from idle latencies. |
| 41 |
*cyclictest* sets this value to *0* by default, use **--dma-latency** *0* to have |
| 42 |
similar results. |
| 43 |
|
| 44 |
**--deepest-idle-state** *n* |
| 45 |
Disable idle states higher than *n* for cpus that are running timerlat threads to |
| 46 |
reduce exit from idle latencies. If *n* is -1, all idle states are disabled. |
| 47 |
On exit from timerlat, the idle state setting is restored to its original state |
| 48 |
before running timerlat. |
| 49 |
|
| 50 |
Requires rtla to be built with libcpupower. |
| 51 |
|
| 52 |
**-k**, **--kernel-threads** |
| 53 |
|
| 54 |
Use timerlat kernel-space threads, in contrast of **-u**. |
| 55 |
|
| 56 |
**-u**, **--user-threads** |
| 57 |
|
| 58 |
Set timerlat to run without a workload, and then dispatches user-space workloads |
| 59 |
to wait on the timerlat_fd. Once the workload is awakened, it goes to sleep again |
| 60 |
adding so the measurement for the kernel-to-user and user-to-kernel to the tracer |
| 61 |
output. **--user-threads** will be used unless the user specify **-k**. |
| 62 |
|
| 63 |
**-U**, **--user-load** |
| 64 |
|
| 65 |
Set timerlat to run without workload, waiting for the user to dispatch a per-cpu |
| 66 |
task that waits for a new period on the tracing/osnoise/per_cpu/cpu$ID/timerlat_fd. |
| 67 |
See linux/tools/rtla/example/timerlat_load.py for an example of user-load code. |
| 68 |
|
| 69 |
**--bpf-action** *bpf-program* |
| 70 |
|
| 71 |
Loads a BPF program from an ELF file and executes it when a latency threshold is exceeded. |
| 72 |
|
| 73 |
The BPF program must be a valid ELF file loadable with libbpf. The program must contain |
| 74 |
a function named ``action_handler``, stored in an ELF section with the ``tp_`` prefix. |
| 75 |
The prefix is used by libbpf to set BPF program type to BPF_PROG_TYPE_TRACEPOINT. |
| 76 |
|
| 77 |
The program receives a ``struct trace_event_raw_timerlat_sample`` parameter |
| 78 |
containing timerlat sample data. |
| 79 |
|
| 80 |
An example is provided in ``tools/tracing/rtla/example/timerlat_bpf_action.c``. |
| 81 |
This example demonstrates how to create a BPF program that prints latency information using |
| 82 |
bpf_trace_printk() when a threshold is exceeded. |
| 83 |
|
| 84 |
**Note**: BPF actions require BPF support to be available. If BPF is not available |
| 85 |
or disabled, the tool falls back to tracefs mode and BPF actions are not supported. |