[6/6] Documentation/rtla: Add hwnoise man page
Commit Message
Add a man page for the new rtla hwnoise tool, mostly based in the
rtla osnoise top.
Signed-off-by: Daniel Bristot de Oliveira <bristot@kernel.org>
Cc: Daniel Bristot de Oliveira <bristot@kernel.org>
Cc: Steven Rostedt <rostedt@goodmis.org>
Cc: Jonathan Corbet <corbet@lwn.net>
---
Documentation/tools/rtla/rtla-hwnoise.rst | 107 ++++++++++++++++++++++
1 file changed, 107 insertions(+)
create mode 100644 Documentation/tools/rtla/rtla-hwnoise.rst
Comments
Hi Daniel,
I love your patch! Perhaps something to improve:
[auto build test WARNING on lwn/docs-next]
[also build test WARNING on linus/master v6.2-rc3 next-20230111]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]
url: https://github.com/intel-lab-lkp/linux/commits/Daniel-Bristot-de-Oliveira/rtla-osnoise-Add-helper-functions-to-manipulate-osnoise-options/20230111-040954
base: git://git.lwn.net/linux.git docs-next
patch link: https://lore.kernel.org/r/d4bdb3920693381794511068f04bf56cf221fb1f.1673380089.git.bristot%40kernel.org
patch subject: [PATCH 6/6] Documentation/rtla: Add hwnoise man page
reproduce:
# https://github.com/intel-lab-lkp/linux/commit/c24519ca82e368045e62c10252623ecdfc3b5e85
git remote add linux-review https://github.com/intel-lab-lkp/linux
git fetch --no-tags linux-review Daniel-Bristot-de-Oliveira/rtla-osnoise-Add-helper-functions-to-manipulate-osnoise-options/20230111-040954
git checkout c24519ca82e368045e62c10252623ecdfc3b5e85
make menuconfig
# enable CONFIG_COMPILE_TEST, CONFIG_WARN_MISSING_DOCUMENTS, CONFIG_WARN_ABI_ERRORS
make htmldocs
If you fix the issue, kindly add following tag where applicable
| Reported-by: kernel test robot <lkp@intel.com>
All warnings (new ones prefixed by >>):
>> Documentation/tools/rtla/rtla-hwnoise.rst: WARNING: document isn't included in any toctree
On Tue, Jan 10, 2023 at 09:08:07PM +0100, Daniel Bristot de Oliveira wrote:
> Add a man page for the new rtla hwnoise tool, mostly based in the
> rtla osnoise top.
>
> Signed-off-by: Daniel Bristot de Oliveira <bristot@kernel.org>
> Cc: Daniel Bristot de Oliveira <bristot@kernel.org>
> Cc: Steven Rostedt <rostedt@goodmis.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/tools/rtla/rtla-hwnoise.rst | 107 ++++++++++++++++++++++
> 1 file changed, 107 insertions(+)
> create mode 100644 Documentation/tools/rtla/rtla-hwnoise.rst
>
As kernel test robot has reported [1], you seems like forgetting to add the new
doc to the parent doc's index:
---- >8 ----
diff --git a/Documentation/tools/rtla/index.rst b/Documentation/tools/rtla/index.rst
index 840f0bf3e8036f..19bda03c68f45f 100644
--- a/Documentation/tools/rtla/index.rst
+++ b/Documentation/tools/rtla/index.rst
@@ -11,6 +11,7 @@ behavior on specific hardware.
:maxdepth: 1
rtla
+ rtla-hwnoise
rtla-osnoise
rtla-osnoise-hist
rtla-osnoise-top
Thanks.
[1]: https://lore.kernel.org/linux-doc/202301111416.SZPJ8cq5-lkp@intel.com/
new file mode 100644
@@ -0,0 +1,107 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+rtla-hwnoise
+============
+------------------------------------------
+Detect and quantify hardware-related noise
+------------------------------------------
+
+:Manual section: 1
+
+SYNOPSIS
+========
+
+**rtla hwnoise** [*OPTIONS*]
+
+DESCRIPTION
+===========
+
+**rtla hwnoise** collects the periodic summary from the *osnoise* tracer
+running with *interrupts disabled*. By disabling interrupts, and the scheduling
+of threads as a consequence, only non-maskable interrupts and hardware-related
+noise is allowed.
+
+The tool also allows the configurations of the *osnoise* tracer and the
+collection of the tracer output.
+
+OPTIONS
+=======
+.. include:: common_osnoise_options.rst
+
+.. include:: common_top_options.rst
+
+.. include:: common_options.rst
+
+EXAMPLE
+=======
+In the example below, the **rtla hwnoise** tool is set to run on CPUs *1-7*
+on a system with 8 cores/16 threads with hyper-threading enabled.
+
+The tool is set to detect any noise higher than *one microsecond*,
+to run for *ten minutes*, displaying a summary of the report at the
+end of the session::
+
+ # 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
+
+
+The first column shows the *CPU*, and the second column shows how many
+*Periods* the tool ran during the session. The *Runtime* is the time
+the tool effectively runs on the CPU. The *Noise* column is the sum of
+all noise that the tool observed, and the *% CPU Aval* is the relation
+between the *Runtime* and *Noise*.
+
+The *Max Noise* column is the maximum hardware noise the tool detected in a
+single period, and the *Max Single* is the maximum single noise seen.
+
+The *HW* and *NMI* columns show the total number of *hardware* and *NMI* noise
+occurrence observed by the tool.
+
+For example, *CPU 3* ran *599* periods of *1 second Runtime*. The CPU received
+*86 us* of noise during the entire execution, leaving *99.99997 %* of CPU time
+for the application. In the worst single period, the CPU caused *4 us* of
+noise to the application, but it was certainly caused by more than one single
+noise, as the *Max Single* noise was of *3 us*. The CPU has *HW noise,* at a
+rate of *six occurrences*/*ten minutes*. The CPU also has *NMIs*, at a higher
+frequency: around *seven per second*.
+
+The tool should report *0* 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 **rtla hwnoise**), it was possible to reach
+the ideal situation in the same hardware::
+
+ # 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
+
+SEE ALSO
+========
+
+**rtla-osnoise**\(1)
+
+Osnoise tracer documentation: <https://www.kernel.org/doc/html/latest/trace/osnoise-tracer.html>
+
+AUTHOR
+======
+Written by Daniel Bristot de Oliveira <bristot@kernel.org>
+
+.. include:: common_appendix.rst