.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "RTLA-TIMERLAT-HIST" 1 "" "" .SH NAME rtla-timerlat-hist \- Histograms of the operating system timer latency .SH SYNOPSIS .sp \fBrtla timerlat hist\fP [\fIOPTIONS\fP] ... .SH DESCRIPTION .sp The \fBrtla timerlat\fP tool is an interface for the \fItimerlat\fP tracer. The \fItimerlat\fP tracer dispatches a kernel thread per\-cpu. These threads set a periodic timer to wake themselves up and go back to sleep. After the wakeup, they collect and generate useful information for the debugging of operating system timer latency. .sp The \fItimerlat\fP tracer outputs information in two ways. It periodically prints the timer latency at the timer \fIIRQ\fP handler and the \fIThread\fP handler. It also enable the trace of the most relevant information via \fBosnoise:\fP tracepoints. .sp The \fBrtla timerlat hist\fP displays a histogram of each tracer event occurrence. This tool uses the periodic information, and the \fBosnoise:\fP tracepoints are enabled when using the \fB\-T\fP option. .SH OPTIONS .sp \fB\-a\fP, \fB\-\-auto\fP \fIus\fP .INDENT 0.0 .INDENT 3.5 Set the automatic trace mode. This mode sets some commonly used options while debugging the system. It is equivalent to use \fB\-T\fP \fIus\fP \fB\-s\fP \fIus\fP \fB\-t\fP\&. By default, \fItimerlat\fP tracer uses FIFO:95 for \fItimerlat\fP threads, thus equilavent to \fB\-P\fP \fIf:95\fP\&. .UNINDENT .UNINDENT .sp \fB\-p\fP, \fB\-\-period\fP \fIus\fP .INDENT 0.0 .INDENT 3.5 Set the \fItimerlat\fP tracer period in microseconds. .UNINDENT .UNINDENT .sp \fB\-i\fP, \fB\-\-irq\fP \fIus\fP .INDENT 0.0 .INDENT 3.5 Stop trace if the \fIIRQ\fP latency is higher than the argument in us. .UNINDENT .UNINDENT .sp \fB\-T\fP, \fB\-\-thread\fP \fIus\fP .INDENT 0.0 .INDENT 3.5 Stop trace if the \fIThread\fP latency is higher than the argument in us. .UNINDENT .UNINDENT .sp \fB\-s\fP, \fB\-\-stack\fP \fIus\fP .INDENT 0.0 .INDENT 3.5 Save the stack trace at the \fIIRQ\fP if a \fIThread\fP latency is higher than the argument in us. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fB\-\-dma\-latency\fP \fIus\fP Set the /dev/cpu_dma_latency to \fIus\fP, aiming to bound exit from idle latencies. \fIcyclictest\fP sets this value to \fI0\fP by default, use \fB\-\-dma\-latency\fP \fI0\fP to have similar results. .UNINDENT .sp \fB\-u\fP, \fB\-\-user\-threads\fP .INDENT 0.0 .INDENT 3.5 Set timerlat to run without a workload, and then dispatches user\-space workloads to wait on the timerlat_fd. Once the workload is awakes, it goes to sleep again adding so the measurement for the kernel\-to\-user and user\-to\-kernel to the tracer output. .UNINDENT .UNINDENT .sp \fB\-b\fP, \fB\-\-bucket\-size\fP \fIN\fP .INDENT 0.0 .INDENT 3.5 Set the histogram bucket size (default \fI1\fP). .UNINDENT .UNINDENT .sp \fB\-E\fP, \fB\-\-entries\fP \fIN\fP .INDENT 0.0 .INDENT 3.5 Set the number of entries of the histogram (default 256). .UNINDENT .UNINDENT .sp \fB\-\-no\-header\fP .INDENT 0.0 .INDENT 3.5 Do not print header. .UNINDENT .UNINDENT .sp \fB\-\-no\-summary\fP .INDENT 0.0 .INDENT 3.5 Do not print summary. .UNINDENT .UNINDENT .sp \fB\-\-no\-index\fP .INDENT 0.0 .INDENT 3.5 Do not print index. .UNINDENT .UNINDENT .sp \fB\-\-with\-zeros\fP .INDENT 0.0 .INDENT 3.5 Print zero only entries. .UNINDENT .UNINDENT .sp \fB\-c\fP, \fB\-\-cpus\fP \fIcpu\-list\fP .INDENT 0.0 .INDENT 3.5 Set the osnoise tracer to run the sample threads in the cpu\-list. .UNINDENT .UNINDENT .sp \fB\-H\fP, \fB\-\-house\-keeping\fP \fIcpu\-list\fP .INDENT 0.0 .INDENT 3.5 Run rtla control threads only on the given cpu\-list. .UNINDENT .UNINDENT .sp \fB\-d\fP, \fB\-\-duration\fP \fItime[s|m|h|d]\fP .INDENT 0.0 .INDENT 3.5 Set the duration of the session. .UNINDENT .UNINDENT .sp \fB\-D\fP, \fB\-\-debug\fP .INDENT 0.0 .INDENT 3.5 Print debug info. .UNINDENT .UNINDENT .sp \fB\-t\fP, \fB\-\-trace\fP[\fI=file\fP] .INDENT 0.0 .INDENT 3.5 Save the stopped trace to [\fIfile|osnoise_trace.txt\fP]. .UNINDENT .UNINDENT .sp \fB\-e\fP, \fB\-\-event\fP \fIsys:event\fP .INDENT 0.0 .INDENT 3.5 Enable an event in the trace (\fB\-t\fP) session. The argument can be a specific event, e.g., \fB\-e\fP \fIsched:sched_switch\fP, or all events of a system group, e.g., \fB\-e\fP \fIsched\fP\&. Multiple \fB\-e\fP are allowed. It is only active when \fB\-t\fP or \fB\-a\fP are set. .UNINDENT .UNINDENT .sp \fB\-\-filter\fP \fI\fP .INDENT 0.0 .INDENT 3.5 Filter the previous \fB\-e\fP \fIsys:event\fP event with \fI\fP\&. For further information about event filtering see \fI\%https://www.kernel.org/doc/html/latest/trace/events.html#event\-filtering\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fB\-\-trigger\fP \fI\fP Enable a trace event trigger to the previous \fB\-e\fP \fIsys:event\fP\&. If the \fIhist:\fP trigger is activated, the output histogram will be automatically saved to a file named \fIsystem_event_hist.txt\fP\&. For example, the command: .sp rtla \-t \-e osnoise:irq_noise \-\-trigger=\(dqhist:key=desc,duration/1000:sort=desc,duration/1000:vals=hitcount\(dq .sp Will automatically save the content of the histogram associated to \fIosnoise:irq_noise\fP event in \fIosnoise_irq_noise_hist.txt\fP\&. .sp For further information about event trigger see \fI\%https://www.kernel.org/doc/html/latest/trace/events.html#event\-triggers\fP\&. .UNINDENT .sp \fB\-P\fP, \fB\-\-priority\fP \fIo:prio|r:prio|f:prio|d:runtime:period\fP .INDENT 0.0 .INDENT 3.5 Set scheduling parameters to the osnoise tracer threads, the format to set the priority are: .INDENT 0.0 .IP \(bu 2 \fIo:prio\fP \- use SCHED_OTHER with \fIprio\fP; .IP \(bu 2 \fIr:prio\fP \- use SCHED_RR with \fIprio\fP; .IP \(bu 2 \fIf:prio\fP \- use SCHED_FIFO with \fIprio\fP; .IP \(bu 2 \fId:runtime[us|ms|s]:period[us|ms|s]\fP \- use SCHED_DEADLINE with \fIruntime\fP and \fIperiod\fP in nanoseconds. .UNINDENT .UNINDENT .UNINDENT .sp \fB\-C\fP, \fB\-\-cgroup\fP[\fI=cgroup\fP] .INDENT 0.0 .INDENT 3.5 Set a \fIcgroup\fP to the tracer\(aqs threads. If the \fB\-C\fP option is passed without arguments, the tracer\(aqs thread will inherit \fBrtla\fP\(aqs \fIcgroup\fP\&. Otherwise, the threads will be placed on the \fIcgroup\fP passed to the option. .UNINDENT .UNINDENT .sp \fB\-h\fP, \fB\-\-help\fP .INDENT 0.0 .INDENT 3.5 Print help menu. .UNINDENT .UNINDENT .sp \fB\-\-dump\-tasks\fP .INDENT 0.0 .INDENT 3.5 prints the task running on all CPUs if stop conditions are met (depends on !\-\-no\-aa) .UNINDENT .UNINDENT .sp \fB\-\-no\-aa\fP .INDENT 0.0 .INDENT 3.5 disable auto\-analysis, reducing rtla timerlat cpu usage .UNINDENT .UNINDENT .SH EXAMPLE .sp In the example below, \fBrtla timerlat hist\fP is set to run for \fI10\fP minutes, in the cpus \fI0\-4\fP, \fIskipping zero\fP only lines. Moreover, \fBrtla timerlat hist\fP will change the priority of the \fItimerlat\fP threads to run under \fISCHED_DEADLINE\fP priority, with a \fI100us\fP runtime every \fI1ms\fP period. The \fI1ms\fP period is also passed to the \fItimerlat\fP tracer. Auto\-analysis is disabled to reduce overhead .INDENT 0.0 .INDENT 3.5 .sp .EX [root@alien ~]# timerlat hist \-d 10m \-c 0\-4 \-P d:100us:1ms \-p 1000 \-\-no\-aa # RTLA timerlat histogram # Time unit is microseconds (us) # Duration: 0 00:10:00 Index IRQ\-000 Thr\-000 IRQ\-001 Thr\-001 IRQ\-002 Thr\-002 IRQ\-003 Thr\-003 IRQ\-004 Thr\-004 0 276489 0 206089 0 466018 0 481102 0 205546 0 1 318327 35487 388149 30024 94531 48382 83082 71078 388026 55730 2 3282 122584 4019 126527 28231 109012 23311 89309 4568 98739 3 940 11815 837 9863 6209 16227 6895 17196 910 9780 4 444 17287 424 11574 2097 38443 2169 36736 462 13476 5 206 43291 255 25581 1223 101908 1304 101137 236 28913 6 132 101501 96 64584 635 213774 757 215471 99 73453 7 74 169347 65 124758 350 57466 441 53639 69 148573 8 53 85183 31 156751 229 9052 306 9026 39 139907 9 22 10387 12 42762 161 2554 225 2689 19 26192 10 13 1898 8 5770 114 1247 128 1405 13 3772 11 9 560 9 924 71 686 76 765 8 713 12 4 256 2 360 50 411 64 474 3 278 13 2 167 2 172 43 256 53 350 4 180 14 1 88 1 116 15 198 42 223 0 115 15 2 63 3 94 11 139 20 150 0 58 16 2 37 0 56 5 78 10 102 0 39 17 0 18 0 28 4 57 8 80 0 15 18 0 8 0 17 2 50 6 56 0 12 19 0 9 0 5 0 19 0 48 0 18 20 0 4 0 8 0 11 2 27 0 4 21 0 2 0 3 1 9 1 18 0 6 22 0 1 0 3 1 7 0 3 0 5 23 0 2 0 4 0 2 0 7 0 2 24 0 2 0 2 1 3 0 3 0 5 25 0 0 0 1 0 1 0 1 0 3 26 0 1 0 0 0 2 0 2 0 0 27 0 0 0 3 0 1 0 0 0 1 28 0 0 0 3 0 0 0 1 0 0 29 0 0 0 2 0 2 0 1 0 3 30 0 1 0 0 0 0 0 0 0 0 31 0 1 0 0 0 0 0 2 0 2 32 0 0 0 1 0 2 0 0 0 0 33 0 0 0 2 0 0 0 0 0 1 34 0 0 0 0 0 0 0 0 0 2 35 0 1 0 1 0 0 0 0 0 1 36 0 1 0 0 0 1 0 1 0 0 37 0 0 0 1 0 0 0 0 0 0 40 0 0 0 0 0 1 0 1 0 0 41 0 0 0 0 0 0 0 0 0 1 42 0 0 0 0 0 0 0 0 0 1 44 0 0 0 0 0 1 0 0 0 0 46 0 0 0 0 0 0 0 1 0 0 47 0 0 0 0 0 0 0 0 0 1 50 0 0 0 0 0 0 0 0 0 1 54 0 0 0 1 0 0 0 0 0 0 58 0 0 0 1 0 0 0 0 0 0 over: 0 0 0 0 0 0 0 0 0 0 count: 600002 600002 600002 600002 600002 600002 600002 600002 600002 600002 min: 0 1 0 1 0 1 0 1 0 1 avg: 0 5 0 5 0 4 0 4 0 5 max: 16 36 15 58 24 44 21 46 13 50 .EE .UNINDENT .UNINDENT .SH SEE ALSO .sp \fBrtla\-timerlat\fP(1), \fBrtla\-timerlat\-top\fP(1) .sp \fItimerlat\fP tracer documentation: <\fI\%https://www.kernel.org/doc/html/latest/trace/timerlat\-tracer.html\fP> .SH AUTHOR .sp Written by Daniel Bristot de Oliveira <\fI\%bristot@kernel.org\fP> .\" Generated by docutils manpage writer. .