.\" 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-HWNOISE" 1 "" "" .SH NAME rtla-hwnoise \- Detect and quantify hardware-related noise .\" SPDX-License-Identifier: GPL-2.0 . .SH SYNOPSIS .sp \fBrtla hwnoise\fP [\fIOPTIONS\fP] .SH DESCRIPTION .sp \fBrtla hwnoise\fP collects the periodic summary from the \fIosnoise\fP tracer running with \fIinterrupts disabled\fP\&. By disabling interrupts, and the scheduling of threads as a consequence, only non\-maskable interrupts and hardware\-related noise is allowed. .sp The tool also allows the configurations of the \fIosnoise\fP tracer and the collection of the tracer output. .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\-s\fP \fIus\fP \fB\-T 1 \-t\fP\&. .UNINDENT .UNINDENT .sp \fB\-p\fP, \fB\-\-period\fP \fIus\fP .INDENT 0.0 .INDENT 3.5 Set the \fIosnoise\fP tracer period in microseconds. .UNINDENT .UNINDENT .sp \fB\-r\fP, \fB\-\-runtime\fP \fIus\fP .INDENT 0.0 .INDENT 3.5 Set the \fIosnoise\fP tracer runtime in microseconds. .UNINDENT .UNINDENT .sp \fB\-s\fP, \fB\-\-stop\fP \fIus\fP .INDENT 0.0 .INDENT 3.5 Stop the trace if a single sample is higher than the argument in microseconds. If \fB\-T\fP is set, it will also save the trace to the output. .UNINDENT .UNINDENT .sp \fB\-S\fP, \fB\-\-stop\-total\fP \fIus\fP .INDENT 0.0 .INDENT 3.5 Stop the trace if the total sample is higher than the argument in microseconds. If \fB\-T\fP is set, it will also save the trace to the output. .UNINDENT .UNINDENT .sp \fB\-T\fP, \fB\-\-threshold\fP \fIus\fP .INDENT 0.0 .INDENT 3.5 Specify the minimum delta between two time reads to be considered noise. The default threshold is \fI5 us\fP\&. .UNINDENT .UNINDENT .sp \fB\-q\fP, \fB\-\-quiet\fP .INDENT 0.0 .INDENT 3.5 Print only a summary at the end of the session. .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 .SH EXAMPLE .sp In the example below, the \fBrtla hwnoise\fP tool is set to run on CPUs \fI1\-7\fP on a system with 8 cores/16 threads with hyper\-threading enabled. .sp The tool is set to detect any noise higher than \fIone microsecond\fP, to run for \fIten minutes\fP, displaying a summary of the report at the end of the session: .INDENT 0.0 .INDENT 3.5 .sp .EX # rtla hwnoise \-c 1\-7 \-T 1 \-d 10m \-q Hardware\-related Noise duration: 0 00:10:00 | time is in us CPU Period Runtime Noise % CPU Aval Max Noise Max Single HW NMI 1 #599 599000000 138 99.99997 3 3 4 74 2 #599 599000000 85 99.99998 3 3 4 75 3 #599 599000000 86 99.99998 4 3 6 75 4 #599 599000000 81 99.99998 4 4 2 75 5 #599 599000000 85 99.99998 2 2 2 75 6 #599 599000000 76 99.99998 2 2 0 75 7 #599 599000000 77 99.99998 3 3 0 75 .EE .UNINDENT .UNINDENT .sp The first column shows the \fICPU\fP, and the second column shows how many \fIPeriods\fP the tool ran during the session. The \fIRuntime\fP is the time the tool effectively runs on the CPU. The \fINoise\fP column is the sum of all noise that the tool observed, and the \fI% CPU Aval\fP is the relation between the \fIRuntime\fP and \fINoise\fP\&. .sp The \fIMax Noise\fP column is the maximum hardware noise the tool detected in a single period, and the \fIMax Single\fP is the maximum single noise seen. .sp The \fIHW\fP and \fINMI\fP columns show the total number of \fIhardware\fP and \fINMI\fP noise occurrence observed by the tool. .sp For example, \fICPU 3\fP ran \fI599\fP periods of \fI1 second Runtime\fP\&. The CPU received \fI86 us\fP of noise during the entire execution, leaving \fI99.99997 %\fP of CPU time for the application. In the worst single period, the CPU caused \fI4 us\fP of noise to the application, but it was certainly caused by more than one single noise, as the \fIMax Single\fP noise was of \fI3 us\fP\&. The CPU has \fIHW noise,\fP at a rate of \fIsix occurrences\fP/\fIten minutes\fP\&. The CPU also has \fINMIs\fP, at a higher frequency: around \fIseven per second\fP\&. .sp The tool should report \fI0\fP hardware\-related noise in the ideal situation. For example, by disabling hyper\-threading to remove the hardware noise, and disabling the TSC watchdog to remove the NMI (it is possible to identify this using tracing options of \fBrtla hwnoise\fP), it was possible to reach the ideal situation in the same hardware: .INDENT 0.0 .INDENT 3.5 .sp .EX # rtla hwnoise \-c 1\-7 \-T 1 \-d 10m \-q Hardware\-related Noise duration: 0 00:10:00 | time is in us CPU Period Runtime Noise % CPU Aval Max Noise Max Single HW NMI 1 #599 599000000 0 100.00000 0 0 0 0 2 #599 599000000 0 100.00000 0 0 0 0 3 #599 599000000 0 100.00000 0 0 0 0 4 #599 599000000 0 100.00000 0 0 0 0 5 #599 599000000 0 100.00000 0 0 0 0 6 #599 599000000 0 100.00000 0 0 0 0 7 #599 599000000 0 100.00000 0 0 0 0 .EE .UNINDENT .UNINDENT .SH SEE ALSO .sp \fBrtla\-osnoise\fP(1) .sp Osnoise tracer documentation: <\fI\%https://www.kernel.org/doc/html/latest/trace/osnoise\-tracer.html\fP> .SH AUTHOR .sp Written by Daniel Bristot de Oliveira <\fI\%bristot@kernel.org\fP> .SH REPORTING BUGS .sp Report bugs to <\fI\%linux\-kernel@vger.kernel.org\fP> and <\fI\%linux\-trace\-devel@vger.kernel.org\fP> .SH LICENSE .sp \fBrtla\fP is Free Software licensed under the GNU GPLv2 .SH COPYING .sp Copyright (C) 2021 Red Hat, Inc. Free use of this software is granted under the terms of the GNU Public License (GPL). .\" Generated by docutils manpage writer. .