[PATCH v1 00/28] rt-tests: Rework cyclictest manpage

[PATCH v1 00/28] rt-tests: Rework cyclictest manpage

[Ahmed S. Darwish]

Hi,

This series provides much needed bugfixes, cleanups, and updates to the
cyclictest(1) manpage.

A sample before/after view of that manpage can also be checked at:

    https://cacheline.de/pub/mainline/cyclictest-manpage-before-after.png

Thanks!

8<-----

Ahmed S. Darwish (28):
  cyclictest.8: Comment-out SPDX license tag
  cyclictest.8: Synopsis: Remove -U
  cyclictest.8: Synopsis: Remove -w/-W
  cyclictest.8: Synopsis: Remove -y
  cyclictest.8: Synopsis: Remove -h flag
  cyclictest.8: Standardize --verbose paragraph formatting
  cyclictest.8: Remove left-over comments
  cyclictest.8: Align source file to 75 columns
  cyclictest.8: Separate source sections
  cyclictest.8: Capitalize section headers
  cyclictest.8: Synopsis: Fix parameters list rendering
  cyclictest.8: Rework the Synopsis blurb
  cyclictest.8: Synopsis: Distinguish --help mode
  cyclictest.8: Group system-altering options
  cyclictest.8: Group sleep-mechanism (clock) options
  cyclictest.8: Group thread wakeup timing options
  cyclictest.8: Group SMP-related options
  cyclictest.8: Group memory options
  cyclictest.8: Group thread priority options
  cyclictest.8: Group tracing options
  cyclictest.8: Group test duration options
  cyclictest.8: Group output options
  cyclictest.8: Group x86 options
  cyclictest.8: System options: Deprecate --laptop
  cyclictest.8: Options: Expand --default-system description
  cyclictest.8: Options: Reference clock_getres(2)
  cyclictest.8: Add example invocation
  cyclictest.8: Reference rtla-timerlat(1)

 src/cyclictest/cyclictest.8 | 403 +++++++++++++++++++++++-------------
 1 file changed, 264 insertions(+), 139 deletions(-)

base-commit: 9166c3f0bb9c5d3e31dc80aff165a5073b5ac5be
-- 
2.49.0

[PATCH v1 01/28] cyclictest.8: Comment-out SPDX license tag

[Ahmed S. Darwish]

SPDX license tags are internal source code markers, but cyclictest
manpage's SPDX tag is leaked to the output.

Comment it out, as the tag will still be recognized by standard tools
like FSFE's REUSE; i.e. "reuse lint".

While at it, put the SPDX licence tag on top as this is the common
convention.

Fixes: cf75a53807ae ("rt-tests: Add missing SPDX licenses")
Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
Link: https://spdx.dev/learn/handling-license-info/
Link: https://git.fsfe.org/reuse/tool
---
 src/cyclictest/cyclictest.8 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 6becd19..2871daa 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -1,6 +1,6 @@
+.\" SPDX-License-Identifier: GPL-2.0-only
 .\"                                      Hey, EMACS: -*- nroff -*-
 .TH CYCLICTEST 8 "April 22, 2016"
-# SPDX-License-Identifier: GPL-2.0-only
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
-- 
2.49.0

[PATCH v1 02/28] cyclictest.8: Synopsis: Remove -U

[Ahmed S. Darwish]

Commit 7ea837b01d7e ("rt-tests: cyclictest: Remove numa from help")
removed --numa from the manpage but forgot to remove its shorthand, -U.

Remove it.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 2871daa..35f7c90 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -19,7 +19,7 @@ cyclictest \- High resolution test program
 .SY cyclictest
 .RI "[ \-hfmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
 [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
-[\-p " prio " ] [\-t " num " ] [\-D " time "] [\-w] [\-W] [\-y " policy " ] [ \-S | \-U ]"
+[\-p " prio " ] [\-t " num " ] [\-D " time "] [\-w] [\-W] [\-y " policy " ]"
 
 .\" .SH DESCRIPTION
 .\" This manual page documents briefly the
-- 
2.49.0

[PATCH v1 03/28] cyclictest.8: Synopsis: Remove -w/-W

[Ahmed S. Darwish]

Commit 88af497ee57b ("rt-tests: cyclictest.8: Remove invalid tracing
options from the manpage") removed --wakeup, but forgot to remove its
-w/-W shorthand.

Remove it.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 35f7c90..312bf7a 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -19,7 +19,7 @@ cyclictest \- High resolution test program
 .SY cyclictest
 .RI "[ \-hfmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
 [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
-[\-p " prio " ] [\-t " num " ] [\-D " time "] [\-w] [\-W] [\-y " policy " ]"
+[\-p " prio " ] [\-t " num " ] [\-D " time "] [\-y " policy " ]"
 
 .\" .SH DESCRIPTION
 .\" This manual page documents briefly the
-- 
2.49.0

[PATCH v1 04/28] cyclictest.8: Synopsis: Remove -y

[Ahmed S. Darwish]

Commit a3a7ee1a6831 ("cyclictest: modify option handling to use
enumerated types") removed "-y" as a shorthand for --policy, but forgot
removing it from the manpage.

Remove it.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 312bf7a..76b10f3 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -19,7 +19,7 @@ cyclictest \- High resolution test program
 .SY cyclictest
 .RI "[ \-hfmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
 [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
-[\-p " prio " ] [\-t " num " ] [\-D " time "] [\-y " policy " ]"
+[\-p " prio " ] [\-t " num " ] [\-D " time " ]"
 
 .\" .SH DESCRIPTION
 .\" This manual page documents briefly the
@@ -41,7 +41,7 @@ in the set in numeric order, in a round\-robin fashion.
 .br
 The set of processors can be specified as A,B,C, or A-C, or A-B,D-F, and so on*.
 The ! character can be used to negate a set.  For example, !B-D means to use all
-available CPUs except B through D.  The cpu numbers are the same as shown in the 
+available CPUs except B through D.  The cpu numbers are the same as shown in the
 .I processor
 field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU sets.
 * Support for CPU sets requires libnuma version >= 2.  For libnuma v1, PROC-SET,
-- 
2.49.0

[PATCH v1 05/28] cyclictest.8: Synopsis: Remove -h flag

[Ahmed S. Darwish]

Per commit 79ad2eca9abe ("COPYING file and cyclictest's man page added"),
"-h" as a flag is an invalid left-over from the template the manpage was
based on.

Remove it from the cyclictest's flags list, as "-h" is actually a
shorthand for "--histogram", which is already documented.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 76b10f3..c1a7b29 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -17,7 +17,7 @@
 cyclictest \- High resolution test program
 .SH SYNOPSIS
 .SY cyclictest
-.RI "[ \-hfmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
+.RI "[ \-fmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
 [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
 [\-p " prio " ] [\-t " num " ] [\-D " time " ]"
 
-- 
2.49.0

[PATCH v1 06/28] cyclictest.8: Standardize --verbose paragraph formatting

[Ahmed S. Darwish]

All of cyclictest's options are described in the manpage through a single
paragraph except --verbose, which renders the verbose statistics output
format in a separate paragraph for no special reason.

Let the description text of --versbose match the other parameters style.
Beside consistency, this will also be useful when all the options will be
separated at the manpage source level.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index c1a7b29..803c5fd 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -170,11 +170,10 @@ write a trace mark when \-b latency is exceeded.
 force unbuffered output for live processing
 .TP
 .B \-v, \-\-verbose
-Output values on stdout for statistics. This option is used to gather statistical information about the latency distribution. The output is sent to stdout. The output format is:
-
-n:c:v
-
-where n=task number c=count v=latency value in us.
+Output values on stdout for statistics. This option is used to gather
+statistical information about the latency distribution. The output is sent
+to stdout. The output format is: "n:c:v", where n is the task number, c is
+the count, and v is the latency value in microseconds.
 .TP
 .B \-\-dbg_cyclictest
 Print info userful for debugging cyclictest
-- 
2.49.0

[PATCH v1 07/28] cyclictest.8: Remove left-over comments

[Ahmed S. Darwish]

Simplify the cyclictest manpage source by removing all obsolete comments.

Per commit 79ad2eca9abe ("COPYING file and cyclictest's man page added"),
most of such comments are random leftovers from the original template the
cyclictest's manpage was based on.  Namely:

(a) Remove emacs markers; modern emacsen do not need them.

(b) Remove the roff macros description table; they're all already
    documented at man(7).

(c) Reference groff_man_style(7).  Per man(7): "man page authors and
    maintainers who are not already experienced groff users should
    consult groff_man_style(7)."

(d) Remove legacy, commented-out, earlier cyclictest descriptions.

(e) Remove a reference to info pages; cyclictest does not have any.

(f) Remove an obscure joke about the manpage being written by "The Rise
    and Fall of a Fooish Bar."

With this, further documentation cleanups will be easily stacked on top.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 25 +------------------------
 1 file changed, 1 insertion(+), 24 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 803c5fd..d4ce648 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -1,18 +1,6 @@
 .\" SPDX-License-Identifier: GPL-2.0-only
-.\"                                      Hey, EMACS: -*- nroff -*-
+.\" For a man pages tutorial, check groff_man_style(7)
 .TH CYCLICTEST 8 "April 22, 2016"
-.\" Please adjust this date whenever revising the manpage.
-.\"
-.\" Some roff macros, for reference:
-.\" .nh        disable hyphenation
-.\" .hy        enable hyphenation
-.\" .ad l      left justify
-.\" .ad b      justify to both left and right margins
-.\" .nf        disable filling
-.\" .fi        enable filling
-.\" .br        insert line break
-.\" .sp <n>    insert n+1 empty lines
-.\" for manpage-specific macros, see man(7)
 .SH NAME
 cyclictest \- High resolution test program
 .SH SYNOPSIS
@@ -21,18 +9,11 @@ cyclictest \- High resolution test program
 [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
 [\-p " prio " ] [\-t " num " ] [\-D " time " ]"
 
-.\" .SH DESCRIPTION
-.\" This manual page documents briefly the
-.\" .B cyclictest commands.
-.\" .PP
-.\" \fI<whatever>\fP escape sequences to invode bold face and italics, respectively.
-.\" \fBcyclictest\fP is a program that...
 .SH OPTIONS
 These programs follow the usual GNU command line syntax, with long
 options starting with two dashes ('\-\-').
 .br
 A summary of options is included below.
-.\" For a complete description, see the Info files.
 .TP
 .B \-a, \-\-affinity[=PROC-SET]
 Run threads on the set of processors given by PROC-SET.  If PROC-SET is not
@@ -184,10 +165,6 @@ Use POSIX timers instead of clock_nanosleep.
 .SH SEE ALSO
 .BR numa (3),
 .BR numactl (8),
-.\" .br
-.\" The programs are documented fully by
-.\" .IR "The Rise and Fall of a Fooish Bar" ,
-.\" available via the Info system.
 .SH AUTHOR
 cyclictest was written by Thomas Gleixner <tglx@linuxtronix.de>.
 .PP
-- 
2.49.0

[PATCH v1 08/28] cyclictest.8: Align source file to 75 columns

[Ahmed S. Darwish]

Enforce proper column alignment for the whole cyclictest manpage source.
Next commits will significantly expand the parameters' description text,
and without such alignment the expanded text will be hard to read and
review at the source.

Per man-pages(7): "please limit source code line length to no more than
about 75 characters wherever possible."

Note, no content change, as verified before and after by
"man ./cyclictest.8 | md5sum"

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 85 ++++++++++++++++++++++++-------------
 1 file changed, 55 insertions(+), 30 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index d4ce648..6bf983d 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -17,16 +17,17 @@ A summary of options is included below.
 .TP
 .B \-a, \-\-affinity[=PROC-SET]
 Run threads on the set of processors given by PROC-SET.  If PROC-SET is not
-specified, all processors will be used.  Threads will be assigned to processors
-in the set in numeric order, in a round\-robin fashion.
+specified, all processors will be used.  Threads will be assigned to
+processors in the set in numeric order, in a round\-robin fashion.
 .br
-The set of processors can be specified as A,B,C, or A-C, or A-B,D-F, and so on*.
-The ! character can be used to negate a set.  For example, !B-D means to use all
-available CPUs except B through D.  The cpu numbers are the same as shown in the
+The set of processors can be specified as A,B,C, or A-C, or A-B,D-F, and so
+on*.  The ! character can be used to negate a set.  For example, !B-D means
+to use all available CPUs except B through D.  The cpu numbers are the same
+as shown in the
 .I processor
-field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU sets.
-* Support for CPU sets requires libnuma version >= 2.  For libnuma v1, PROC-SET,
-if specified, must be a single CPU number.
+field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU
+sets.  * Support for CPU sets requires libnuma version >= 2.  For libnuma
+v1, PROC-SET, if specified, must be a single CPU number.
 .TP
 .B \-A, \-\-align=USEC
 Align thread wakeups to a specific offset in microseconds
@@ -42,10 +43,14 @@ select clock
 1 = CLOCK_REALTIME
 .TP
 .B \-\-deepest\-idle\-state=n
-Reduce exit from idle latency by limiting idle state up to n on used cpus (-1 disables all idle states). Power management is not suppresed on other cpus.
+Reduce exit from idle latency by limiting idle state up to n on used cpus
+(-1 disables all idle states). Power management is not suppresed on other
+cpus.
 .TP
 .B \-\-default\-system
-Don't attempt to tune the system from cyclictest. Power management is not suppressed. This might give poorer results, but will allow you to discover if you need to tune the system.
+Don't attempt to tune the system from cyclictest. Power management is not
+suppressed. This might give poorer results, but will allow you to discover
+if you need to tune the system.
 .TP
 .B \-d, \-\-distance=DIST
 Distance of thread intervals in us, default = 500
@@ -59,31 +64,41 @@ Append 'm', 'h', or 'd' to specify minutes, hours or days.
 Create a named pipe at path and write stats to it
 .TP
 .B \-h, \-\-histogram=US
-Dump latency histogram to stdout after the run. US is the max latency time to be be tracked in microseconds. This option runs all threads at the same priority.
+Dump latency histogram to stdout after the run. US is the max latency time
+to be be tracked in microseconds. This option runs all threads at the same
+priority.
 .TP
 .B \-H, \-\-histofall=MAXLATENCYINUS
-Same as -h except that an additional histogram column is displayed at the right that contains summary data of all thread histograms. If cyclictest runs a single thread only, the -H option is equivalent to -h.
+Same as -h except that an additional histogram column is displayed at the
+right that contains summary data of all thread histograms. If cyclictest
+runs a single thread only, the -H option is equivalent to -h.
 .TP
 .B \-\-histfile=<path>
 Dump the latency histogram to <path> instead of stdout.
 .TP
 .B \-i, \-\-interval=INTV
-Set the base interval of the thread(s) in microseconds (default is 1000us). This sets the interval of the first thread. See also \-d.
+Set the base interval of the thread(s) in microseconds (default is
+1000us). This sets the interval of the first thread. See also \-d.
 .TP
 .B \-\-json=FILENAME
 Write final results into FILENAME, JSON formatted.
 .TP
 .B \-\-laptop
-Save battery when running cyclictest. This will give you poorer realtime results, but will not drain your battery so quickly.
+Save battery when running cyclictest. This will give you poorer realtime
+results, but will not drain your battery so quickly.
 .TP
 .B \-\-latency=PM_Q0S
-power management latency target value. This value is written to /dev/cpu_dma_latency and affects c-states. The default is 0
+power management latency target value. This value is written to
+/dev/cpu_dma_latency and affects c-states. The default is 0
 .TP
 .B \-l, \-\-loops=LOOPS
-Set the number of loops. The default is 0 (endless). This option is useful for automated tests with a given number of test cycles. Cyclictest is stopped once the number of timer intervals has been reached.
+Set the number of loops. The default is 0 (endless). This option is useful
+for automated tests with a given number of test cycles. Cyclictest is
+stopped once the number of timer intervals has been reached.
 .TP
 .B \-\-mainaffinity=CPUSET
-Run the main thread on CPU #N. This only affects the main thread and not the measurement threads
+Run the main thread on CPU #N. This only affects the main thread and not
+the measurement threads
 .TP
 .B \-m, \-\-mlockall
 Lock current and future memory allocations to prevent being paged out
@@ -93,41 +108,50 @@ Delay updating the screen until a new max latency is hit. (useful for
 running cyclictest on low-bandwidth connections)
 .TP
 .B \-N, \-\-nsecs
-Show results in nanoseconds instead of microseconds, which is the default unit.
+Show results in nanoseconds instead of microseconds, which is the default
+unit.
 .TP
 .B \-o, \-\-oscope=RED
 Oscilloscope mode, reduce verbose output by RED.
 .TP
 .B \-p, \-\-prio=PRIO
-Set the priority of the first thread. The given priority is set to the first test thread. Each further thread gets a lower priority:
+Set the priority of the first thread. The given priority is set to the
+first test thread. Each further thread gets a lower priority:
 Priority(Thread N) = max(Priority(Thread N\-1) \- 1, 0)
 .TP
 .B \-\-policy=NAME
-set the scheduler policy of the measurement threads
-where NAME is one of: other, normal, batch, idle, fifo, rr
+set the scheduler policy of the measurement threads where NAME is one of:
+other, normal, batch, idle, fifo, rr
 .TP
 .B \-\-priospread
 spread priority levels starting at a specified value
 .TP
 .B \-q, \-\-quiet
-Print a summary only on exit. Useful for automated tests, where only the summary output needs to be captured.
+Print a summary only on exit. Useful for automated tests, where only the
+summary output needs to be captured.
 .TP
 .B \-r, \-\-relative
-Use relative timers instead of absolute. The default behaviour of the tests is to use absolute timers. This option is there for completeness and should not be used for reproducible tests.
+Use relative timers instead of absolute. The default behaviour of the tests
+is to use absolute timers. This option is there for completeness and should
+not be used for reproducible tests.
 .TP
 .B \-R, \-\-resolution
-Check clock resolution, calling clock_gettime() many times. List of lock_gettime() values will be reported with -X
+Check clock resolution, calling clock_gettime() many times. List of
+lock_gettime() values will be reported with -X
 .TP
 .B \-\-secaligned [USEC]
 align thread wakeups to the next full second and apply the optional offset.
 .TP
 .B \-s, \-\-system
-Use sys_nanosleep and sys_setitimer instead of posix timers. Note, that \-s can only be used with one thread because itimers are per process and not per thread. \-s uses the nanosleep syscall and is not restricted to one thread.
+Use sys_nanosleep and sys_setitimer instead of posix timers. Note, that \-s
+can only be used with one thread because itimers are per process and not
+per thread. \-s uses the nanosleep syscall and is not restricted to one
+thread.
 .TP
 .B \\-S, \-\-smp
-Set options for standard testing on SMP systems. Equivalent to using
-the options: "\-t \-a" as well keeping any specified priority
-equal across all threads
+Set options for standard testing on SMP systems. Equivalent to using the
+options: "\-t \-a" as well keeping any specified priority equal across all
+threads
 .TP
 .B \-\-spike=<trigger>
 record all spikes > trigger
@@ -141,8 +165,9 @@ The default is 1024 if not specified.
 Enable SMI count/detection on processors with SMI count support.
 .TP
 .B \-t, \-\-threads[=NUM]
-Set the number of test threads (default is 1). Create NUM test threads. If NUM is not specified, NUM is set to
-the number of available CPUs. See \-d, \-i and \-p for further information.
+Set the number of test threads (default is 1). Create NUM test threads. If
+NUM is not specified, NUM is set to the number of available CPUs. See \-d,
+\-i and \-p for further information.
 .TP
 .B \-\-tracemark
 write a trace mark when \-b latency is exceeded.
-- 
2.49.0

[PATCH v1 09/28] cyclictest.8: Separate source sections

[Ahmed S. Darwish]

Further work will significantly expand the cyclictest's parameter
documentation.  Improve the manpage's source readability by separating
its different sections with newlines.

Per groff_man_style(7), use groff's empty request (.) for this vertical
spacing as blank lines shouldn't exist in a manpage source file.
Authoritative manpages like groff_man(7) is also written this way.

No output change, as verified before and after by
"man ./cyclictest.8 | md5sum".

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 47 +++++++++++++++++++++++++++++++++++--
 1 file changed, 45 insertions(+), 2 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 6bf983d..f27fe66 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -1,19 +1,22 @@
 .\" SPDX-License-Identifier: GPL-2.0-only
 .\" For a man pages tutorial, check groff_man_style(7)
 .TH CYCLICTEST 8 "April 22, 2016"
+.
 .SH NAME
 cyclictest \- High resolution test program
+.
 .SH SYNOPSIS
 .SY cyclictest
 .RI "[ \-fmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
 [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
 [\-p " prio " ] [\-t " num " ] [\-D " time " ]"
-
+.
 .SH OPTIONS
 These programs follow the usual GNU command line syntax, with long
 options starting with two dashes ('\-\-').
 .br
 A summary of options is included below.
+.
 .TP
 .B \-a, \-\-affinity[=PROC-SET]
 Run threads on the set of processors given by PROC-SET.  If PROC-SET is not
@@ -28,12 +31,15 @@ as shown in the
 field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU
 sets.  * Support for CPU sets requires libnuma version >= 2.  For libnuma
 v1, PROC-SET, if specified, must be a single CPU number.
+.
 .TP
 .B \-A, \-\-align=USEC
 Align thread wakeups to a specific offset in microseconds
+.
 .TP
 .B \-b, \-\-breaktrace=USEC
 Send break trace command when latency > USEC
+.
 .TP
 .B \-c, \-\-clock=CLOCK
 select clock
@@ -41,155 +47,192 @@ select clock
 0 = CLOCK_MONOTONIC (default)
 .br
 1 = CLOCK_REALTIME
+.
 .TP
 .B \-\-deepest\-idle\-state=n
 Reduce exit from idle latency by limiting idle state up to n on used cpus
 (-1 disables all idle states). Power management is not suppresed on other
 cpus.
+.
 .TP
 .B \-\-default\-system
 Don't attempt to tune the system from cyclictest. Power management is not
 suppressed. This might give poorer results, but will allow you to discover
 if you need to tune the system.
+.
 .TP
 .B \-d, \-\-distance=DIST
 Distance of thread intervals in us, default = 500
+.
 .TP
 .B \-D, \-\-duration=TIME
 Specify a length for the test run.
 .br
 Append 'm', 'h', or 'd' to specify minutes, hours or days.
+.
 .TP
 .B \-F, \-\-fifo=<path>
 Create a named pipe at path and write stats to it
+.
 .TP
 .B \-h, \-\-histogram=US
 Dump latency histogram to stdout after the run. US is the max latency time
 to be be tracked in microseconds. This option runs all threads at the same
 priority.
+.
 .TP
 .B \-H, \-\-histofall=MAXLATENCYINUS
 Same as -h except that an additional histogram column is displayed at the
 right that contains summary data of all thread histograms. If cyclictest
 runs a single thread only, the -H option is equivalent to -h.
+.
 .TP
 .B \-\-histfile=<path>
 Dump the latency histogram to <path> instead of stdout.
+.
 .TP
 .B \-i, \-\-interval=INTV
 Set the base interval of the thread(s) in microseconds (default is
 1000us). This sets the interval of the first thread. See also \-d.
+.
 .TP
 .B \-\-json=FILENAME
 Write final results into FILENAME, JSON formatted.
+.
 .TP
 .B \-\-laptop
 Save battery when running cyclictest. This will give you poorer realtime
 results, but will not drain your battery so quickly.
+.
 .TP
 .B \-\-latency=PM_Q0S
 power management latency target value. This value is written to
 /dev/cpu_dma_latency and affects c-states. The default is 0
+.
 .TP
 .B \-l, \-\-loops=LOOPS
 Set the number of loops. The default is 0 (endless). This option is useful
 for automated tests with a given number of test cycles. Cyclictest is
 stopped once the number of timer intervals has been reached.
+.
 .TP
 .B \-\-mainaffinity=CPUSET
 Run the main thread on CPU #N. This only affects the main thread and not
 the measurement threads
+.
 .TP
 .B \-m, \-\-mlockall
 Lock current and future memory allocations to prevent being paged out
+.
 .TP
 .B \\-M, \-\-refresh_on_max
 Delay updating the screen until a new max latency is hit. (useful for
 running cyclictest on low-bandwidth connections)
+.
 .TP
 .B \-N, \-\-nsecs
 Show results in nanoseconds instead of microseconds, which is the default
 unit.
+.
 .TP
 .B \-o, \-\-oscope=RED
 Oscilloscope mode, reduce verbose output by RED.
+.
 .TP
 .B \-p, \-\-prio=PRIO
 Set the priority of the first thread. The given priority is set to the
 first test thread. Each further thread gets a lower priority:
 Priority(Thread N) = max(Priority(Thread N\-1) \- 1, 0)
+.
 .TP
 .B \-\-policy=NAME
 set the scheduler policy of the measurement threads where NAME is one of:
 other, normal, batch, idle, fifo, rr
+.
 .TP
 .B \-\-priospread
 spread priority levels starting at a specified value
+.
 .TP
 .B \-q, \-\-quiet
 Print a summary only on exit. Useful for automated tests, where only the
 summary output needs to be captured.
+.
 .TP
 .B \-r, \-\-relative
 Use relative timers instead of absolute. The default behaviour of the tests
 is to use absolute timers. This option is there for completeness and should
 not be used for reproducible tests.
+.
 .TP
 .B \-R, \-\-resolution
 Check clock resolution, calling clock_gettime() many times. List of
 lock_gettime() values will be reported with -X
+.
 .TP
 .B \-\-secaligned [USEC]
 align thread wakeups to the next full second and apply the optional offset.
+.
 .TP
 .B \-s, \-\-system
 Use sys_nanosleep and sys_setitimer instead of posix timers. Note, that \-s
 can only be used with one thread because itimers are per process and not
 per thread. \-s uses the nanosleep syscall and is not restricted to one
 thread.
+.
 .TP
 .B \\-S, \-\-smp
 Set options for standard testing on SMP systems. Equivalent to using the
 options: "\-t \-a" as well keeping any specified priority equal across all
 threads
+.
 .TP
 .B \-\-spike=<trigger>
 record all spikes > trigger
+.
 .TP
 .B \-\-spike-nodes=[num of nodes]
 These are the maximum number of spikes we can record.
 .br
 The default is 1024 if not specified.
+.
 .TP
 .B \\-\-smi
 Enable SMI count/detection on processors with SMI count support.
+.
 .TP
 .B \-t, \-\-threads[=NUM]
 Set the number of test threads (default is 1). Create NUM test threads. If
 NUM is not specified, NUM is set to the number of available CPUs. See \-d,
 \-i and \-p for further information.
+.
 .TP
 .B \-\-tracemark
 write a trace mark when \-b latency is exceeded.
+.
 .TP
 .B \-u, \-\-unbuffered
 force unbuffered output for live processing
+.
 .TP
 .B \-v, \-\-verbose
 Output values on stdout for statistics. This option is used to gather
 statistical information about the latency distribution. The output is sent
 to stdout. The output format is: "n:c:v", where n is the task number, c is
 the count, and v is the latency value in microseconds.
+.
 .TP
 .B \-\-dbg_cyclictest
 Print info userful for debugging cyclictest
+.
 .TP
 .B \-x, \-\-posix_timers
 Use POSIX timers instead of clock_nanosleep.
-
+.
 .SH SEE ALSO
 .BR numa (3),
 .BR numactl (8),
+.
 .SH AUTHOR
 cyclictest was written by Thomas Gleixner <tglx@linuxtronix.de>.
 .PP
-- 
2.49.0

[PATCH v1 10/28] cyclictest.8: Capitalize section headers

[Ahmed S. Darwish]

Per groff(7) and groff_man_style(7), capitalize the section headers
without resorting to all caps.

This makes the manpage's output calmer to read as well.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index f27fe66..7f1bd39 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -1,17 +1,17 @@
 .\" SPDX-License-Identifier: GPL-2.0-only
 .\" For a man pages tutorial, check groff_man_style(7)
-.TH CYCLICTEST 8 "April 22, 2016"
+.TH Cyclictest 8 "April 22, 2016"
 .
-.SH NAME
+.SH Name
 cyclictest \- High resolution test program
 .
-.SH SYNOPSIS
+.SH Synopsis
 .SY cyclictest
 .RI "[ \-fmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
 [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
 [\-p " prio " ] [\-t " num " ] [\-D " time " ]"
 .
-.SH OPTIONS
+.SH Options
 These programs follow the usual GNU command line syntax, with long
 options starting with two dashes ('\-\-').
 .br
@@ -229,11 +229,11 @@ Print info userful for debugging cyclictest
 .B \-x, \-\-posix_timers
 Use POSIX timers instead of clock_nanosleep.
 .
-.SH SEE ALSO
+.SH "See also"
 .BR numa (3),
 .BR numactl (8),
 .
-.SH AUTHOR
+.SH Authors
 cyclictest was written by Thomas Gleixner <tglx@linuxtronix.de>.
 .PP
 This manual page was written by Alessio Igor Bogani <abogani@texware.it>,
-- 
2.49.0

[PATCH v1 11/28] cyclictest.8: Synopsis: Fix parameters list rendering

[Ahmed S. Darwish]

Follow groff_man_style(7) parameters documentation style.  Namely:

- Order cyclictest flags in the form -abcCeEgGijklNpRsStUVXzZ

- Present the flag and option names in bold to cue the user that they
  should be input literally.

- Use the non-breaking adjustable space escape sequence "\~" to prevent
  the line output from being broken within the option brackets.

- Use the output line continuation escape sequence "\c" to allow all
  three font styles to be set without breakable space among them.

- End the parameters list with .YS, the "End synopsis" macro.  It
  restores indentation, adjustment, and hyphenation to their previous
  state.

Beside just following the standards, this makes the groff rendering of
the cyclictest's parameter list way more legible and comprehensible.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 31 ++++++++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 7f1bd39..f093677 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -7,9 +7,34 @@ cyclictest \- High resolution test program
 .
 .SH Synopsis
 .SY cyclictest
-.RI "[ \-fmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
-[\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
-[\-p " prio " ] [\-t " num " ] [\-D " time " ]"
+.RB [ \-fmMnqrsMv ]
+.RB [ \-a\~\c
+.IR proc ]
+.RB [ \-A\~\c
+.IR align ]
+.RB [ \-b\~\c
+.IR usec ]
+.RB [ \-c\~\c
+.IR clock ]
+.RB [ \-d\~\c
+.IR dist ]
+.RB [ \-h\~\c
+.IR histogram ]
+.RB [ \-i\~\c
+.IR intv ]
+.RB [ \-\-json\~\c
+.IR filename ]
+.RB [ \-l\~\c
+.IR loop ]
+.RB [ \-o\~\c
+.IR red ]
+.RB [ \-p\~\c
+.IR prio ]
+.RB [ \-t\~\c
+.IR num ]
+.RB [ \-D\~\c
+.IR time ]
+.YS
 .
 .SH Options
 These programs follow the usual GNU command line syntax, with long
-- 
2.49.0

[PATCH v1 12/28] cyclictest.8: Rework the Synopsis blurb

[Ahmed S. Darwish]

The cyclictest's SYNOPSIS blurb is buggy and incomplete.

For the cyclictest's flag list:

  - Remove 'f', for --fifo, as it's not a flag and requires the fifo's path
  - Add 'N', for --nsecs
  - Add 'R', for --resolution
  - Add 'S', for --smp
  - Add 'u', for --unbuffered
  - Add 'x', for --posix_timers

For options with arguments, expand the argument names with something
comprehensible since the whole purpose of the SYNOPSIS section is to get,
in a blitz, an understanding of the tool's actual options.  The original
argument names, especially when -combined with the one-letter option's
shorthand form, were totally -incomprehensible.

For consistency, be coherent regarding the arguments' names; e.g.,
"*-path" for all file paths like file-path and fifo-path, "proc-set" for
cpuset-related arguments, "num-*" for counts like num-threads and
num-loops; "*-usec" for microsecond arguments, and so on.

Also add the missing options --deepest-idle-state, --histfile, --latency,
--mainaffinity, --policy, --spike, --spike-nodes, --dbg_cyclictest,
--default-system, --smi, --priospread, --smi, and --tracemark.  Do not
add --laptop since it is deprecated.

Note, this makes the cyclictest's SYNOPSIS blurb complete and gives a
comprehensive view of cyclictest's abilities in a glance.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 57 ++++++++++++++++++++++++++-----------
 1 file changed, 41 insertions(+), 16 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index f093677..0271f5c 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -7,33 +7,58 @@ cyclictest \- High resolution test program
 .
 .SH Synopsis
 .SY cyclictest
-.RB [ \-fmMnqrsMv ]
+.RB [ \-mMNqrRsSuvx ]
 .RB [ \-a\~\c
-.IR proc ]
+.IR proc\-set ]
 .RB [ \-A\~\c
-.IR align ]
+.IR alignment\-usec ]
 .RB [ \-b\~\c
-.IR usec ]
+.IR break\-usec ]
 .RB [ \-c\~\c
-.IR clock ]
+.IR clock\-type ]
 .RB [ \-d\~\c
-.IR dist ]
+.IR distance\-usec ]
+.RB [ \-D\~\c
+.IR duration\-mhd ]
+.RB [ \-f\~\c
+.IR fifo\-path ]
 .RB [ \-h\~\c
-.IR histogram ]
+.IR max\-latency\-usec ]
+.RB [ \-H\~\c
+.IR max\-latency\-usec ]
 .RB [ \-i\~\c
-.IR intv ]
-.RB [ \-\-json\~\c
-.IR filename ]
+.IR interval\-usec ]
 .RB [ \-l\~\c
-.IR loop ]
+.IR num\-loops ]
 .RB [ \-o\~\c
-.IR red ]
+.IR oscope\-red ]
 .RB [ \-p\~\c
-.IR prio ]
+.IR thread\-prio ]
 .RB [ \-t\~\c
-.IR num ]
-.RB [ \-D\~\c
-.IR time ]
+.IR num\-threads ]
+.RB [ \-\-deepest\-idle\-state\~\c
+.IR idle-state-num ]
+.RB [ \-\-histfile\~\c
+.IR file\-path ]
+.RB [ \-\-json\~\c
+.IR file\-path ]
+.RB [ \-\-latency\~\c
+.IR pm\-c\-state ]
+.RB [ \-\-mainaffinity\~\c
+.IR proc-set ]
+.RB [ \-\-policy\~\c
+.IR threads\-sched\-policy ]
+.RB [ \-\-secaligned\~\c
+.IR wakeup\-usec ]
+.RB [ \-\-spike\~\c
+.IR trigger\-point-usec ]
+.RB [ \-\-spike\-nodes\~\c
+.IR num\-nodes ]
+.RB [ \-\-dbg_cyclictest ]
+.RB [ \-\-default\-system ]
+.RB [ \-\-priospread ]
+.RB [ \-\-smi ]
+.RB [ \-\-tracemark ]
 .YS
 .
 .SH Options
-- 
2.49.0

[PATCH v1 13/28] cyclictest.8: Synopsis: Distinguish --help mode

[Ahmed S. Darwish]

Per groff_man_style(7), different command operation modes should be
distinguished through unique Synopsis (.SY/.YS) blocks.

Distinguish "cyclictest --help" with its own section, as other parameters
won't be recognized when --help is passed.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 0271f5c..1fd550f 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -6,6 +6,7 @@
 cyclictest \- High resolution test program
 .
 .SH Synopsis
+.
 .SY cyclictest
 .RB [ \-mMNqrRsSuvx ]
 .RB [ \-a\~\c
@@ -61,11 +62,14 @@ cyclictest \- High resolution test program
 .RB [ \-\-tracemark ]
 .YS
 .
+.SY cyclictest
+.B \-\-help
+.YS
+.
 .SH Options
-These programs follow the usual GNU command line syntax, with long
-options starting with two dashes ('\-\-').
-.br
-A summary of options is included below.
+.
+.B \-\-help
+display a usage message and exit.
 .
 .TP
 .B \-a, \-\-affinity[=PROC-SET]
-- 
2.49.0

[PATCH v1 14/28] cyclictest.8: Group system-altering options

[Ahmed S. Darwish]

The number and breadth of cyclictest's options is huge, and just
exploring them in sequence can get the manpage reader lost.

Put the cyclictest's system-altering options:

       --default-system
       --latency=PM_QOS
       --deepest-idle-state=n
       --laptop

into their own group.  Adjust the Synopsis accordingly as well.

Further groupings will be added next.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 58 ++++++++++++++++++++-----------------
 1 file changed, 31 insertions(+), 27 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 1fd550f..0bc2fc1 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -9,6 +9,11 @@ cyclictest \- High resolution test program
 .
 .SY cyclictest
 .RB [ \-mMNqrRsSuvx ]
+.RB [ \-\-default\-system ]
+.RB [ \-\-latency\~\c
+.IR pm\-c\-state ]
+.RB [ \-\-deepest\-idle\-state\~\c
+.IR idle-state-num ]
 .RB [ \-a\~\c
 .IR proc\-set ]
 .RB [ \-A\~\c
@@ -37,14 +42,10 @@ cyclictest \- High resolution test program
 .IR thread\-prio ]
 .RB [ \-t\~\c
 .IR num\-threads ]
-.RB [ \-\-deepest\-idle\-state\~\c
-.IR idle-state-num ]
 .RB [ \-\-histfile\~\c
 .IR file\-path ]
 .RB [ \-\-json\~\c
 .IR file\-path ]
-.RB [ \-\-latency\~\c
-.IR pm\-c\-state ]
 .RB [ \-\-mainaffinity\~\c
 .IR proc-set ]
 .RB [ \-\-policy\~\c
@@ -56,7 +57,6 @@ cyclictest \- High resolution test program
 .RB [ \-\-spike\-nodes\~\c
 .IR num\-nodes ]
 .RB [ \-\-dbg_cyclictest ]
-.RB [ \-\-default\-system ]
 .RB [ \-\-priospread ]
 .RB [ \-\-smi ]
 .RB [ \-\-tracemark ]
@@ -71,6 +71,32 @@ cyclictest \- High resolution test program
 .B \-\-help
 display a usage message and exit.
 .
+.SS "System-altering options"
+.
+.TP
+.B \-\-default\-system
+Don't attempt to tune the system from cyclictest. Power management is not
+suppressed. This might give poorer results, but will allow you to discover
+if you need to tune the system.
+.
+.TP
+.B \-\-latency=PM_Q0S
+power management latency target value. This value is written to
+/dev/cpu_dma_latency and affects c-states. The default is 0
+.
+.TP
+.B \-\-deepest\-idle\-state=n
+Reduce exit from idle latency by limiting idle state up to n on used cpus
+(-1 disables all idle states). Power management is not suppresed on other
+cpus.
+.
+.TP
+.B \-\-laptop
+Save battery when running cyclictest. This will give you poorer realtime
+results, but will not drain your battery so quickly.
+.
+.SS "Other options"
+.
 .TP
 .B \-a, \-\-affinity[=PROC-SET]
 Run threads on the set of processors given by PROC-SET.  If PROC-SET is not
@@ -103,18 +129,6 @@ select clock
 1 = CLOCK_REALTIME
 .
 .TP
-.B \-\-deepest\-idle\-state=n
-Reduce exit from idle latency by limiting idle state up to n on used cpus
-(-1 disables all idle states). Power management is not suppresed on other
-cpus.
-.
-.TP
-.B \-\-default\-system
-Don't attempt to tune the system from cyclictest. Power management is not
-suppressed. This might give poorer results, but will allow you to discover
-if you need to tune the system.
-.
-.TP
 .B \-d, \-\-distance=DIST
 Distance of thread intervals in us, default = 500
 .
@@ -154,16 +168,6 @@ Set the base interval of the thread(s) in microseconds (default is
 Write final results into FILENAME, JSON formatted.
 .
 .TP
-.B \-\-laptop
-Save battery when running cyclictest. This will give you poorer realtime
-results, but will not drain your battery so quickly.
-.
-.TP
-.B \-\-latency=PM_Q0S
-power management latency target value. This value is written to
-/dev/cpu_dma_latency and affects c-states. The default is 0
-.
-.TP
 .B \-l, \-\-loops=LOOPS
 Set the number of loops. The default is 0 (endless). This option is useful
 for automated tests with a given number of test cycles. Cyclictest is
-- 
2.49.0

[PATCH v1 15/28] cyclictest.8: Group sleep-mechanism (clock) options

[Ahmed S. Darwish]

The number and breadth of cyclictest's options is huge, and just
exploring them in sequence can get the manpage reader lost.

Put the cyclictest's sleep-mechanism related options:

       -c, --clock=CLOCK
       -x, --posix_timers
       -s, --system
       -r, --relative
       -R, --resolution

into their own group.  Adjust the Synopsis accordingly as well.

Further groupings will be added next.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 66 +++++++++++++++++++------------------
 1 file changed, 34 insertions(+), 32 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 0bc2fc1..eb7d713 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -14,14 +14,14 @@ cyclictest \- High resolution test program
 .IR pm\-c\-state ]
 .RB [ \-\-deepest\-idle\-state\~\c
 .IR idle-state-num ]
+.RB [ \-c\~\c
+.IR clock\-type ]
 .RB [ \-a\~\c
 .IR proc\-set ]
 .RB [ \-A\~\c
 .IR alignment\-usec ]
 .RB [ \-b\~\c
 .IR break\-usec ]
-.RB [ \-c\~\c
-.IR clock\-type ]
 .RB [ \-d\~\c
 .IR distance\-usec ]
 .RB [ \-D\~\c
@@ -95,6 +95,38 @@ cpus.
 Save battery when running cyclictest. This will give you poorer realtime
 results, but will not drain your battery so quickly.
 .
+.SS "Sleep-mechanism clock options"
+.
+.TP
+.B \-c, \-\-clock=CLOCK
+select clock
+.br
+0 = CLOCK_MONOTONIC (default)
+.br
+1 = CLOCK_REALTIME
+.
+.TP
+.B \-x, \-\-posix_timers
+Use POSIX timers instead of clock_nanosleep.
+.
+.TP
+.B \-s, \-\-system
+Use sys_nanosleep and sys_setitimer instead of posix timers. Note, that \-s
+can only be used with one thread because itimers are per process and not
+per thread. \-s uses the nanosleep syscall and is not restricted to one
+thread.
+.
+.TP
+.B \-r, \-\-relative
+Use relative timers instead of absolute. The default behaviour of the tests
+is to use absolute timers. This option is there for completeness and should
+not be used for reproducible tests.
+.
+.TP
+.B \-R, \-\-resolution
+Check clock resolution, calling clock_gettime() many times. List of
+lock_gettime() values will be reported with -X
+.
 .SS "Other options"
 .
 .TP
@@ -121,14 +153,6 @@ Align thread wakeups to a specific offset in microseconds
 Send break trace command when latency > USEC
 .
 .TP
-.B \-c, \-\-clock=CLOCK
-select clock
-.br
-0 = CLOCK_MONOTONIC (default)
-.br
-1 = CLOCK_REALTIME
-.
-.TP
 .B \-d, \-\-distance=DIST
 Distance of thread intervals in us, default = 500
 .
@@ -217,28 +241,10 @@ Print a summary only on exit. Useful for automated tests, where only the
 summary output needs to be captured.
 .
 .TP
-.B \-r, \-\-relative
-Use relative timers instead of absolute. The default behaviour of the tests
-is to use absolute timers. This option is there for completeness and should
-not be used for reproducible tests.
-.
-.TP
-.B \-R, \-\-resolution
-Check clock resolution, calling clock_gettime() many times. List of
-lock_gettime() values will be reported with -X
-.
-.TP
 .B \-\-secaligned [USEC]
 align thread wakeups to the next full second and apply the optional offset.
 .
 .TP
-.B \-s, \-\-system
-Use sys_nanosleep and sys_setitimer instead of posix timers. Note, that \-s
-can only be used with one thread because itimers are per process and not
-per thread. \-s uses the nanosleep syscall and is not restricted to one
-thread.
-.
-.TP
 .B \\-S, \-\-smp
 Set options for standard testing on SMP systems. Equivalent to using the
 options: "\-t \-a" as well keeping any specified priority equal across all
@@ -283,10 +289,6 @@ the count, and v is the latency value in microseconds.
 .B \-\-dbg_cyclictest
 Print info userful for debugging cyclictest
 .
-.TP
-.B \-x, \-\-posix_timers
-Use POSIX timers instead of clock_nanosleep.
-.
 .SH "See also"
 .BR numa (3),
 .BR numactl (8),
-- 
2.49.0

[PATCH v1 16/28] cyclictest.8: Group thread wakeup timing options

[Ahmed S. Darwish]

The number and breadth of cyclictest's options is huge, and just
exploring them in sequence can get the manpage reader lost.

Put the cyclictest's thread-wakeup timing options:

       -d, --distance=DIST
       -i, --interval=INTV
       --secaligned [USEC]
       -A, --align=USEC

into their own group.  Adjust the Synopsis accordingly as well.

Further groupings will be added next.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 52 +++++++++++++++++++------------------
 1 file changed, 27 insertions(+), 25 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index eb7d713..6ab3b19 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -16,14 +16,18 @@ cyclictest \- High resolution test program
 .IR idle-state-num ]
 .RB [ \-c\~\c
 .IR clock\-type ]
-.RB [ \-a\~\c
-.IR proc\-set ]
+.RB [ \-d\~\c
+.IR distance\-usec ]
+.RB [ \-i\~\c
+.IR interval\-usec ]
+.RB [ \-\-secaligned\~\c
+.IR wakeup\-usec ]
 .RB [ \-A\~\c
 .IR alignment\-usec ]
+.RB [ \-a\~\c
+.IR proc\-set ]
 .RB [ \-b\~\c
 .IR break\-usec ]
-.RB [ \-d\~\c
-.IR distance\-usec ]
 .RB [ \-D\~\c
 .IR duration\-mhd ]
 .RB [ \-f\~\c
@@ -32,8 +36,6 @@ cyclictest \- High resolution test program
 .IR max\-latency\-usec ]
 .RB [ \-H\~\c
 .IR max\-latency\-usec ]
-.RB [ \-i\~\c
-.IR interval\-usec ]
 .RB [ \-l\~\c
 .IR num\-loops ]
 .RB [ \-o\~\c
@@ -50,8 +52,6 @@ cyclictest \- High resolution test program
 .IR proc-set ]
 .RB [ \-\-policy\~\c
 .IR threads\-sched\-policy ]
-.RB [ \-\-secaligned\~\c
-.IR wakeup\-usec ]
 .RB [ \-\-spike\~\c
 .IR trigger\-point-usec ]
 .RB [ \-\-spike\-nodes\~\c
@@ -127,6 +127,25 @@ not be used for reproducible tests.
 Check clock resolution, calling clock_gettime() many times. List of
 lock_gettime() values will be reported with -X
 .
+.SS "Thread-waekup timing options"
+.
+.TP
+.B \-d, \-\-distance=DIST
+Distance of thread intervals in us, default = 500
+.
+.TP
+.B \-i, \-\-interval=INTV
+Set the base interval of the thread(s) in microseconds (default is
+1000us). This sets the interval of the first thread. See also \-d.
+.
+.TP
+.B \-\-secaligned [USEC]
+align thread wakeups to the next full second and apply the optional offset.
+.
+.TP
+.B \-A, \-\-align=USEC
+Align thread wakeups to a specific offset in microseconds
+.
 .SS "Other options"
 .
 .TP
@@ -145,18 +164,10 @@ sets.  * Support for CPU sets requires libnuma version >= 2.  For libnuma
 v1, PROC-SET, if specified, must be a single CPU number.
 .
 .TP
-.B \-A, \-\-align=USEC
-Align thread wakeups to a specific offset in microseconds
-.
-.TP
 .B \-b, \-\-breaktrace=USEC
 Send break trace command when latency > USEC
 .
 .TP
-.B \-d, \-\-distance=DIST
-Distance of thread intervals in us, default = 500
-.
-.TP
 .B \-D, \-\-duration=TIME
 Specify a length for the test run.
 .br
@@ -183,11 +194,6 @@ runs a single thread only, the -H option is equivalent to -h.
 Dump the latency histogram to <path> instead of stdout.
 .
 .TP
-.B \-i, \-\-interval=INTV
-Set the base interval of the thread(s) in microseconds (default is
-1000us). This sets the interval of the first thread. See also \-d.
-.
-.TP
 .B \-\-json=FILENAME
 Write final results into FILENAME, JSON formatted.
 .
@@ -241,10 +247,6 @@ Print a summary only on exit. Useful for automated tests, where only the
 summary output needs to be captured.
 .
 .TP
-.B \-\-secaligned [USEC]
-align thread wakeups to the next full second and apply the optional offset.
-.
-.TP
 .B \\-S, \-\-smp
 Set options for standard testing on SMP systems. Equivalent to using the
 options: "\-t \-a" as well keeping any specified priority equal across all
-- 
2.49.0

[PATCH v1 17/28] cyclictest.8: Group SMP-related options

[Ahmed S. Darwish]

The number and breadth of cyclictest's options is huge, and just
exploring them in sequence can get the manpage reader lost.

Put the cyclictest's SMP-related options:

       -S, --smp
       -t, --threads[=NUM]
       --mainaffinity=CPUSET
       -a, --affinity[=PROC-SET]

into their own group.

Further groupings will be added next.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 46 +++++++++++++++++++------------------
 1 file changed, 24 insertions(+), 22 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 6ab3b19..7fc0420 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -24,6 +24,10 @@ cyclictest \- High resolution test program
 .IR wakeup\-usec ]
 .RB [ \-A\~\c
 .IR alignment\-usec ]
+.RB [ \-t\~\c
+.IR num\-threads ]
+.RB [ \-\-mainaffinity\~\c
+.IR proc-set ]
 .RB [ \-a\~\c
 .IR proc\-set ]
 .RB [ \-b\~\c
@@ -42,14 +46,10 @@ cyclictest \- High resolution test program
 .IR oscope\-red ]
 .RB [ \-p\~\c
 .IR thread\-prio ]
-.RB [ \-t\~\c
-.IR num\-threads ]
 .RB [ \-\-histfile\~\c
 .IR file\-path ]
 .RB [ \-\-json\~\c
 .IR file\-path ]
-.RB [ \-\-mainaffinity\~\c
-.IR proc-set ]
 .RB [ \-\-policy\~\c
 .IR threads\-sched\-policy ]
 .RB [ \-\-spike\~\c
@@ -146,7 +146,24 @@ align thread wakeups to the next full second and apply the optional offset.
 .B \-A, \-\-align=USEC
 Align thread wakeups to a specific offset in microseconds
 .
-.SS "Other options"
+.SS "SMP-related options"
+.
+.TP
+.B \\-S, \-\-smp
+Set options for standard testing on SMP systems. Equivalent to using the
+options: "\-t \-a" as well keeping any specified priority equal across all
+threads
+.
+.TP
+.B \-t, \-\-threads[=NUM]
+Set the number of test threads (default is 1). Create NUM test threads. If
+NUM is not specified, NUM is set to the number of available CPUs. See \-d,
+\-i and \-p for further information.
+.
+.TP
+.B \-\-mainaffinity=CPUSET
+Run the main thread on CPU #N. This only affects the main thread and not
+the measurement threads
 .
 .TP
 .B \-a, \-\-affinity[=PROC-SET]
@@ -163,6 +180,8 @@ field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU
 sets.  * Support for CPU sets requires libnuma version >= 2.  For libnuma
 v1, PROC-SET, if specified, must be a single CPU number.
 .
+.SS "Other options"
+.
 .TP
 .B \-b, \-\-breaktrace=USEC
 Send break trace command when latency > USEC
@@ -204,11 +223,6 @@ for automated tests with a given number of test cycles. Cyclictest is
 stopped once the number of timer intervals has been reached.
 .
 .TP
-.B \-\-mainaffinity=CPUSET
-Run the main thread on CPU #N. This only affects the main thread and not
-the measurement threads
-.
-.TP
 .B \-m, \-\-mlockall
 Lock current and future memory allocations to prevent being paged out
 .
@@ -247,12 +261,6 @@ Print a summary only on exit. Useful for automated tests, where only the
 summary output needs to be captured.
 .
 .TP
-.B \\-S, \-\-smp
-Set options for standard testing on SMP systems. Equivalent to using the
-options: "\-t \-a" as well keeping any specified priority equal across all
-threads
-.
-.TP
 .B \-\-spike=<trigger>
 record all spikes > trigger
 .
@@ -267,12 +275,6 @@ The default is 1024 if not specified.
 Enable SMI count/detection on processors with SMI count support.
 .
 .TP
-.B \-t, \-\-threads[=NUM]
-Set the number of test threads (default is 1). Create NUM test threads. If
-NUM is not specified, NUM is set to the number of available CPUs. See \-d,
-\-i and \-p for further information.
-.
-.TP
 .B \-\-tracemark
 write a trace mark when \-b latency is exceeded.
 .
-- 
2.49.0

[PATCH v1 18/28] cyclictest.8: Group memory options

[Ahmed S. Darwish]

The number and breadth of cyclictest's options is huge, and just
exploring them in sequence can get the manpage reader lost.

Put the cyclictest's memory-related option:

       -m, --mlockall

into its own group.

Further groupings will be added next.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 7fc0420..a099416 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -180,6 +180,12 @@ field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU
 sets.  * Support for CPU sets requires libnuma version >= 2.  For libnuma
 v1, PROC-SET, if specified, must be a single CPU number.
 .
+.SS "Memory options"
+.
+.TP
+.B \-m, \-\-mlockall
+Lock current and future memory allocations to prevent being paged out
+.
 .SS "Other options"
 .
 .TP
@@ -223,10 +229,6 @@ for automated tests with a given number of test cycles. Cyclictest is
 stopped once the number of timer intervals has been reached.
 .
 .TP
-.B \-m, \-\-mlockall
-Lock current and future memory allocations to prevent being paged out
-.
-.TP
 .B \\-M, \-\-refresh_on_max
 Delay updating the screen until a new max latency is hit. (useful for
 running cyclictest on low-bandwidth connections)
-- 
2.49.0

[PATCH v1 19/28] cyclictest.8: Group thread priority options

[Ahmed S. Darwish]

The number and breadth of cyclictest's options is huge, and just
exploring them in sequence can get the manpage reader lost.

Put the cyclictest's thread priority options:

       --policy=NAME
       -p, --prio=PRIO
       --priospread

into their own group.  Adjust the Synopsis accordingly as well.

Further groupings will be added next.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 25 +++++--------------------
 1 file changed, 5 insertions(+), 20 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index a099416..90a3e08 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -30,6 +30,11 @@ cyclictest \- High resolution test program
 .IR proc-set ]
 .RB [ \-a\~\c
 .IR proc\-set ]
+.RB [ \-\-policy\~\c
+.IR threads\-sched\-policy ]
+.RB [ \-p\~\c
+.IR thread\-prio ]
+.RB [ \-\-priospread ]
 .RB [ \-b\~\c
 .IR break\-usec ]
 .RB [ \-D\~\c
@@ -44,20 +49,15 @@ cyclictest \- High resolution test program
 .IR num\-loops ]
 .RB [ \-o\~\c
 .IR oscope\-red ]
-.RB [ \-p\~\c
-.IR thread\-prio ]
 .RB [ \-\-histfile\~\c
 .IR file\-path ]
 .RB [ \-\-json\~\c
 .IR file\-path ]
-.RB [ \-\-policy\~\c
-.IR threads\-sched\-policy ]
 .RB [ \-\-spike\~\c
 .IR trigger\-point-usec ]
 .RB [ \-\-spike\-nodes\~\c
 .IR num\-nodes ]
 .RB [ \-\-dbg_cyclictest ]
-.RB [ \-\-priospread ]
 .RB [ \-\-smi ]
 .RB [ \-\-tracemark ]
 .YS
@@ -243,21 +243,6 @@ unit.
 Oscilloscope mode, reduce verbose output by RED.
 .
 .TP
-.B \-p, \-\-prio=PRIO
-Set the priority of the first thread. The given priority is set to the
-first test thread. Each further thread gets a lower priority:
-Priority(Thread N) = max(Priority(Thread N\-1) \- 1, 0)
-.
-.TP
-.B \-\-policy=NAME
-set the scheduler policy of the measurement threads where NAME is one of:
-other, normal, batch, idle, fifo, rr
-.
-.TP
-.B \-\-priospread
-spread priority levels starting at a specified value
-.
-.TP
 .B \-q, \-\-quiet
 Print a summary only on exit. Useful for automated tests, where only the
 summary output needs to be captured.
-- 
2.49.0

[PATCH v1 20/28] cyclictest.8: Group tracing options

[Ahmed S. Darwish]

The number and breadth of cyclictest's options is huge, and just
exploring them in sequence can get the manpage reader lost.

Put the cyclictest's system-altering options:

       -b, --breaktrace=USEC
       --tracemark

into their own group.  Adjust the Synopsis accordingly as well.

Further groupings will be added next.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 90a3e08..964996f 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -37,6 +37,7 @@ cyclictest \- High resolution test program
 .RB [ \-\-priospread ]
 .RB [ \-b\~\c
 .IR break\-usec ]
+.RB [ \-\-tracemark ]
 .RB [ \-D\~\c
 .IR duration\-mhd ]
 .RB [ \-f\~\c
@@ -59,7 +60,6 @@ cyclictest \- High resolution test program
 .IR num\-nodes ]
 .RB [ \-\-dbg_cyclictest ]
 .RB [ \-\-smi ]
-.RB [ \-\-tracemark ]
 .YS
 .
 .SY cyclictest
@@ -186,13 +186,19 @@ v1, PROC-SET, if specified, must be a single CPU number.
 .B \-m, \-\-mlockall
 Lock current and future memory allocations to prevent being paged out
 .
-.SS "Other options"
+.SS "Tracing options"
 .
 .TP
 .B \-b, \-\-breaktrace=USEC
 Send break trace command when latency > USEC
 .
 .TP
+.B \-\-tracemark
+write a trace mark when \-b latency is exceeded.
+.
+.SS "Other options"
+.
+.TP
 .B \-D, \-\-duration=TIME
 Specify a length for the test run.
 .br
@@ -262,10 +268,6 @@ The default is 1024 if not specified.
 Enable SMI count/detection on processors with SMI count support.
 .
 .TP
-.B \-\-tracemark
-write a trace mark when \-b latency is exceeded.
-.
-.TP
 .B \-u, \-\-unbuffered
 force unbuffered output for live processing
 .
-- 
2.49.0

[PATCH v1 21/28] cyclictest.8: Group test duration options

[Ahmed S. Darwish]

The number and breadth of cyclictest's options is huge, and just
exploring them in sequence can get the manpage reader lost.

Put the cyclictest's system-altering options:

       -D, --duration=TIME
       -l, --loops=LOOPS

into their own group.  Adjust the Synopsis accordingly as well.

Further groupings will be added next.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 964996f..c2c963c 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -40,14 +40,14 @@ cyclictest \- High resolution test program
 .RB [ \-\-tracemark ]
 .RB [ \-D\~\c
 .IR duration\-mhd ]
+.RB [ \-l\~\c
+.IR num\-loops ]
 .RB [ \-f\~\c
 .IR fifo\-path ]
 .RB [ \-h\~\c
 .IR max\-latency\-usec ]
 .RB [ \-H\~\c
 .IR max\-latency\-usec ]
-.RB [ \-l\~\c
-.IR num\-loops ]
 .RB [ \-o\~\c
 .IR oscope\-red ]
 .RB [ \-\-histfile\~\c
@@ -196,7 +196,7 @@ Send break trace command when latency > USEC
 .B \-\-tracemark
 write a trace mark when \-b latency is exceeded.
 .
-.SS "Other options"
+.SS "Test-duration options"
 .
 .TP
 .B \-D, \-\-duration=TIME
@@ -205,6 +205,14 @@ Specify a length for the test run.
 Append 'm', 'h', or 'd' to specify minutes, hours or days.
 .
 .TP
+.B \-l, \-\-loops=LOOPS
+Set the number of loops. The default is 0 (endless). This option is useful
+for automated tests with a given number of test cycles. Cyclictest is
+stopped once the number of timer intervals has been reached.
+.
+.SS "Other options"
+.
+.TP
 .B \-F, \-\-fifo=<path>
 Create a named pipe at path and write stats to it
 .
@@ -229,12 +237,6 @@ Dump the latency histogram to <path> instead of stdout.
 Write final results into FILENAME, JSON formatted.
 .
 .TP
-.B \-l, \-\-loops=LOOPS
-Set the number of loops. The default is 0 (endless). This option is useful
-for automated tests with a given number of test cycles. Cyclictest is
-stopped once the number of timer intervals has been reached.
-.
-.TP
 .B \\-M, \-\-refresh_on_max
 Delay updating the screen until a new max latency is hit. (useful for
 running cyclictest on low-bandwidth connections)
-- 
2.49.0

[PATCH v1 22/28] cyclictest.8: Group output options

[Ahmed S. Darwish]

The number and breadth of cyclictest's options is huge, and just
exploring them in sequence can get the manpage reader lost.

Put the cyclictest's output options:

       --dbg_cyclictest
       -o, --oscope=RED
       -F, --fifo=<path>
       -h, --histogram=US
       -H, --histofall=MAXLATENCYINUS
       --spike=<trigger>
       --spike-nodes=[num of nodes]
        --histfile=<path>
       --json=FILENAME
       -M, --refresh_on_max
       -N, --nsecs
       -q, --quiet
       -u, --unbuffered
       -v, --verbose

into their own group.  Adjust the Synopsis accordingly as well.

Further groupings will be added next.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 58 +++++++++++++++++++------------------
 1 file changed, 30 insertions(+), 28 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index c2c963c..ca75884 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -42,23 +42,23 @@ cyclictest \- High resolution test program
 .IR duration\-mhd ]
 .RB [ \-l\~\c
 .IR num\-loops ]
+.RB [ \-\-dbg_cyclictest ]
+.RB [ \-o\~\c
+.IR oscope\-red ]
 .RB [ \-f\~\c
 .IR fifo\-path ]
 .RB [ \-h\~\c
 .IR max\-latency\-usec ]
 .RB [ \-H\~\c
 .IR max\-latency\-usec ]
-.RB [ \-o\~\c
-.IR oscope\-red ]
-.RB [ \-\-histfile\~\c
-.IR file\-path ]
-.RB [ \-\-json\~\c
-.IR file\-path ]
 .RB [ \-\-spike\~\c
 .IR trigger\-point-usec ]
 .RB [ \-\-spike\-nodes\~\c
 .IR num\-nodes ]
-.RB [ \-\-dbg_cyclictest ]
+.RB [ \-\-histfile\~\c
+.IR file\-path ]
+.RB [ \-\-json\~\c
+.IR file\-path ]
 .RB [ \-\-smi ]
 .YS
 .
@@ -210,7 +210,15 @@ Set the number of loops. The default is 0 (endless). This option is useful
 for automated tests with a given number of test cycles. Cyclictest is
 stopped once the number of timer intervals has been reached.
 .
-.SS "Other options"
+.SS "Output options"
+.
+.TP
+.B \-\-dbg_cyclictest
+Print info userful for debugging cyclictest
+.
+.TP
+.B \-o, \-\-oscope=RED
+Oscilloscope mode, reduce verbose output by RED.
 .
 .TP
 .B \-F, \-\-fifo=<path>
@@ -229,6 +237,16 @@ right that contains summary data of all thread histograms. If cyclictest
 runs a single thread only, the -H option is equivalent to -h.
 .
 .TP
+.B \-\-spike=<trigger>
+record all spikes > trigger
+.
+.TP
+.B \-\-spike-nodes=[num of nodes]
+These are the maximum number of spikes we can record.
+.br
+The default is 1024 if not specified.
+.
+.TP
 .B \-\-histfile=<path>
 Dump the latency histogram to <path> instead of stdout.
 .
@@ -247,29 +265,11 @@ Show results in nanoseconds instead of microseconds, which is the default
 unit.
 .
 .TP
-.B \-o, \-\-oscope=RED
-Oscilloscope mode, reduce verbose output by RED.
-.
-.TP
 .B \-q, \-\-quiet
 Print a summary only on exit. Useful for automated tests, where only the
 summary output needs to be captured.
 .
 .TP
-.B \-\-spike=<trigger>
-record all spikes > trigger
-.
-.TP
-.B \-\-spike-nodes=[num of nodes]
-These are the maximum number of spikes we can record.
-.br
-The default is 1024 if not specified.
-.
-.TP
-.B \\-\-smi
-Enable SMI count/detection on processors with SMI count support.
-.
-.TP
 .B \-u, \-\-unbuffered
 force unbuffered output for live processing
 .
@@ -280,9 +280,11 @@ statistical information about the latency distribution. The output is sent
 to stdout. The output format is: "n:c:v", where n is the task number, c is
 the count, and v is the latency value in microseconds.
 .
+.SS "Other options"
+.
 .TP
-.B \-\-dbg_cyclictest
-Print info userful for debugging cyclictest
+.B \\-\-smi
+Enable SMI count/detection on processors with SMI count support.
 .
 .SH "See also"
 .BR numa (3),
-- 
2.49.0

[PATCH v1 23/28] cyclictest.8: Group x86 options

[Ahmed S. Darwish]

The number and breadth of cyclictest's options is huge, and just
exploring them in sequence can get the manpage reader lost.

Put the cyclictest's x86 options into their own group.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index ca75884..f320f66 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -280,7 +280,7 @@ statistical information about the latency distribution. The output is sent
 to stdout. The output format is: "n:c:v", where n is the task number, c is
 the count, and v is the latency value in microseconds.
 .
-.SS "Other options"
+.SS "X86 options"
 .
 .TP
 .B \\-\-smi
-- 
2.49.0

[PATCH v1 24/28] cyclictest.8: System options: Deprecate --laptop

[Ahmed S. Darwish]

Per 61ba1aa3a0db ("rt-tests: cyclictest: Add --default-system option"),
explicitly mark the --laptop option as obsolete and recommend using
--default-system instead.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index f320f66..aff900d 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -92,8 +92,7 @@ cpus.
 .
 .TP
 .B \-\-laptop
-Save battery when running cyclictest. This will give you poorer realtime
-results, but will not drain your battery so quickly.
+Obsolete option.  Please use \-\-default\-system instead.
 .
 .SS "Sleep-mechanism clock options"
 .
-- 
2.49.0

[PATCH v1 25/28] cyclictest.8: Options: Expand --default-system description

[Ahmed S. Darwish]

Now that --laptop is explicitly obsoleted and --default-system is
recommended as its replacement, better formulate the latter's help text.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index aff900d..6982234 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -75,9 +75,11 @@ display a usage message and exit.
 .
 .TP
 .B \-\-default\-system
-Don't attempt to tune the system from cyclictest. Power management is not
-suppressed. This might give poorer results, but will allow you to discover
-if you need to tune the system.
+Stop cyclictest from force-tuning the system. Without this option,
+cyclictest writes a value of 0 to /dev/cpu_dma_latency, which prevents the
+CPU from entering deep sleep states.  While such force-tuning might help at
+showing lower latency numbers, it obscures the fact that the system may
+require additional tuning.
 .
 .TP
 .B \-\-latency=PM_Q0S
-- 
2.49.0

[PATCH v1 26/28] cyclictest.8: Options: Reference clock_getres(2)

[Ahmed S. Darwish]

The cyclictest's manpage references CLOCK_MONOTONIC and CLOCK_REALTIME
multiple times without providing a relevant description or reference.

Reference clock_getres(2) where such clocks are extensively described.

Pick the Linux version, instead of the POSIX (3p) one, as the former has
details that are relevant to cyclictest's "--secaligned" implementation;
i.e., Linux's CLOCK_MONOTONIC starts from 0.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 6982234..12fb9c1 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -100,11 +100,15 @@ Obsolete option.  Please use \-\-default\-system instead.
 .
 .TP
 .B \-c, \-\-clock=CLOCK
-select clock
+Select the system clock to be used for calculating the measuring thread's
+latency. Allowed CLOCK values are:
 .br
 0 = CLOCK_MONOTONIC (default)
 .br
 1 = CLOCK_REALTIME
+.br
+For more information on the Linux implementation of such clocks, check
+.MR clock_getres 2
 .
 .TP
 .B \-x, \-\-posix_timers
-- 
2.49.0

[PATCH v1 27/28] cyclictest.8: Add example invocation

[Ahmed S. Darwish]

Add a cyclictest example invocation, while warning the user that testing
a realtime system is hardware and workload dependent.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 12fb9c1..16e8190 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -291,6 +291,24 @@ the count, and v is the latency value in microseconds.
 .B \\-\-smi
 Enable SMI count/detection on processors with SMI count support.
 .
+.SH "Example invocation"
+.
+Testing a realtime system is hardware and workload dependent.  With that
+in mind, below cyclictest example invocation can provide a good start:
+.PP
+.nf
+.B cyclictest
+   --default-system
+   --secaligned
+   --interval=250
+   --distance=0
+   --mlockall
+   --smp
+   --priority=98
+   --histogram=1000
+   --histfile=output.txt
+.fi
+
 .SH "See also"
 .BR numa (3),
 .BR numactl (8),
-- 
2.49.0

[PATCH v1 28/28] cyclictest.8: Reference rtla-timerlat(1)

[Ahmed S. Darwish]

rtla-timerlat should be the official cyclictest replacement at some point.
Mention it at the "See also" section.

While at it, use the correct nroff macro for referencing manpages for the
whole section.

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 src/cyclictest/cyclictest.8 | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
index 16e8190..bbb0b41 100644
--- a/src/cyclictest/cyclictest.8
+++ b/src/cyclictest/cyclictest.8
@@ -308,10 +308,11 @@ in mind, below cyclictest example invocation can provide a good start:
    --histogram=1000
    --histfile=output.txt
 .fi
-
+.
 .SH "See also"
-.BR numa (3),
-.BR numactl (8),
+.MR numa 3 ,
+.MR numactl 8 ,
+.MR rtla-timerlat 1
 .
 .SH Authors
 cyclictest was written by Thomas Gleixner <tglx@linuxtronix.de>.
-- 
2.49.0

Re: [PATCH v1 04/28] cyclictest.8: Synopsis: Remove -y

[Sebastian Andrzej Siewior]

On 2025-07-04 15:26:57 [+0200], Ahmed S. Darwish wrote:
> @@ -41,7 +41,7 @@ in the set in numeric order, in a round\-robin fashion.
>  .br
>  The set of processors can be specified as A,B,C, or A-C, or A-B,D-F, and so on*.
>  The ! character can be used to negate a set.  For example, !B-D means to use all
> -available CPUs except B through D.  The cpu numbers are the same as shown in the 
> +available CPUs except B through D.  The cpu numbers are the same as shown in the

This looks identical. Is this white space clean up?

>  .I processor
>  field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU sets.
>  * Support for CPU sets requires libnuma version >= 2.  For libnuma v1, PROC-SET,

Sebastian

Re: [PATCH v1 08/28] cyclictest.8: Align source file to 75 columns

[Sebastian Andrzej Siewior]

On 2025-07-04 15:27:01 [+0200], Ahmed S. Darwish wrote:
> Enforce proper column alignment for the whole cyclictest manpage source.
> Next commits will significantly expand the parameters' description text,
> and without such alignment the expanded text will be hard to read and
> review at the source.
> 
> Per man-pages(7): "please limit source code line length to no more than
> about 75 characters wherever possible."
> 
> Note, no content change, as verified before and after by
> "man ./cyclictest.8 | md5sum"

While this is already an improvement you could also go for "semantic
newlines".

> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>

Sebastian

Re: [PATCH v1 00/28] rt-tests: Rework cyclictest manpage

[Sebastian Andrzej Siewior]

On 2025-07-04 15:26:53 [+0200], Ahmed S. Darwish wrote:
> Hi,
Hi,

> This series provides much needed bugfixes, cleanups, and updates to the
> cyclictest(1) manpage.

I would merge the "remove $X" flag patches. It is a few times the same
thing.
Then you have update troff syntax, re-grouping options and then you
extend a few/ update them.

Given how difficult it seems to be to write these things I would suggest
to either switch to asciidoc or pandoc and let one of the tools
generate the man page and/or html from it.

perf uses asciidoc while rtla uses rst2man. I don't care which one of
these is used but after I saw the cleanup I think it is easier for
maintenance to use one of these simple tools.

Therefore I would suggest to write a new page for cyclictest based on
what we have after content wise after #28, let rt-tests generate the
man-page from it, remove the current man-page.

John, Ahmed ?

Sebastian

Re: [PATCH v1 00/28] rt-tests: Rework cyclictest manpage

[John Kacur]

On Mon, 14 Jul 2025, Sebastian Andrzej Siewior wrote:

> On 2025-07-04 15:26:53 [+0200], Ahmed S. Darwish wrote:
> > Hi,
> Hi,
> 
> > This series provides much needed bugfixes, cleanups, and updates to the
> > cyclictest(1) manpage.
> 
> I would merge the "remove $X" flag patches. It is a few times the same
> thing.
> Then you have update troff syntax, re-grouping options and then you
> extend a few/ update them.
> 
> Given how difficult it seems to be to write these things I would suggest
> to either switch to asciidoc or pandoc and let one of the tools
> generate the man page and/or html from it.
> 
> perf uses asciidoc while rtla uses rst2man. I don't care which one of
> these is used but after I saw the cleanup I think it is easier for
> maintenance to use one of these simple tools.
> 
> Therefore I would suggest to write a new page for cyclictest based on
> what we have after content wise after #28, let rt-tests generate the
> man-page from it, remove the current man-page.
> 
> John, Ahmed ?

Sure, I'm open to a new way of doing things. I would prefer rst2man
over asciidoc.

We can still accept the patches that Ahmed sent fist, after I review them.

John Kacur

Re: [PATCH v1 00/28] rt-tests: Rework cyclictest manpage

[Ahmed S. Darwish]

Hi,

On Mon, 14 Jul 2025, Sebastian Andrzej Siewior wrote:
>
> I would merge the "remove $X" flag patches. It is a few times the same
> thing.
>

Each "remove -$X" patch references the rt-tests commit that removed the
cyclictest option in question.  I felt it's valuable to reference such
option removal commits on a one-by-one basis.

> Therefore I would suggest to write a new page for cyclictest based on
> what we have after content wise after #28, let rt-tests generate the
> man-page from it, remove the current man-page.

Perfect is the enemy of the good.

I have another patch series on top of this one which further expands upon
most of the parameters' description.

So, I would suggest that we first:

  (a) review/merge this series

  (b) review/merge the next one

  (c) I send a third patch queue that transforms most of the project's
      manpages to rst2man.

The rt-tests project already has 19 groff manpages:

      rt-tests (main)$ find src/ -name '*.8'

      src/sigwaittest/sigwaittest.8
      src/hackbench/hackbench.8
      src/oslat/oslat.8
      src/pi_tests/pi_stress.8
      src/pi_tests/pip_stress.8
      src/svsematest/svsematest.8
      src/backfire/sendme.8
      src/hwlatdetect/hwlatdetect.8
      src/pmqtest/pmqtest.8
      src/queuelat/queuelat.8
      src/queuelat/determine_maximum_mpps.8
      src/signaltest/signaltest.8
      src/ptsematest/ptsematest.8
      src/rt-migrate-test/rt-migrate-test.8
      src/cyclictest/get_cyclictest_snapshot.8
      src/cyclictest/cyclictest.8
      src/ssdd/ssdd.8
      src/sched_deadline/cyclicdeadline.8
      src/sched_deadline/deadline_test.8

So IMHO there's a weak ground for requesting the format transformation
beforehand; i.e., the (a)-(b)-(c) development order above is the most
sensible.

Thanks!

--
Ahmed S. Darwish
Linutronix GmbH

Re: [PATCH v1 02/28] cyclictest.8: Synopsis: Remove -U

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Commit 7ea837b01d7e ("rt-tests: cyclictest: Remove numa from help")
> removed --numa from the manpage but forgot to remove its shorthand, -U.
> 
> Remove it.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 2871daa..35f7c90 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -19,7 +19,7 @@ cyclictest \- High resolution test program
>  .SY cyclictest
>  .RI "[ \-hfmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
>  [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
> -[\-p " prio " ] [\-t " num " ] [\-D " time "] [\-w] [\-W] [\-y " policy " ] [ \-S | \-U ]"
> +[\-p " prio " ] [\-t " num " ] [\-D " time "] [\-w] [\-W] [\-y " policy " ]"

But don't remove -S

John Kacur

Re: [PATCH v1 02/28] cyclictest.8: Synopsis: Remove -U

[Ahmed S. Darwish]

On Mon, 21 Jul 2025, John Kacur wrote:
>
> On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:
>
> > Commit 7ea837b01d7e ("rt-tests: cyclictest: Remove numa from help")
> > removed --numa from the manpage but forgot to remove its shorthand, -U.
> >
> > Remove it.
...
> > -[\-p " prio " ] [\-t " num " ] [\-D " time "] [\-w] [\-W] [\-y " policy " ] [ \-S | \-U ]"
> > +[\-p " prio " ] [\-t " num " ] [\-D " time "] [\-w] [\-W] [\-y " policy " ]"
>
> But don't remove -S
>

Correct; will do.

Thanks,
Ahmed

Re: [PATCH v1 04/28] cyclictest.8: Synopsis: Remove -y

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Commit a3a7ee1a6831 ("cyclictest: modify option handling to use
> enumerated types") removed "-y" as a shorthand for --policy, but forgot
> removing it from the manpage.
> 
> Remove it.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 312bf7a..76b10f3 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -19,7 +19,7 @@ cyclictest \- High resolution test program
>  .SY cyclictest
>  .RI "[ \-hfmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
>  [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
> -[\-p " prio " ] [\-t " num " ] [\-D " time "] [\-y " policy " ]"
> +[\-p " prio " ] [\-t " num " ] [\-D " time " ]"
>  
>  .\" .SH DESCRIPTION
>  .\" This manual page documents briefly the
> @@ -41,7 +41,7 @@ in the set in numeric order, in a round\-robin fashion.
>  .br
>  The set of processors can be specified as A,B,C, or A-C, or A-B,D-F, and so on*.
>  The ! character can be used to negate a set.  For example, !B-D means to use all
> -available CPUs except B through D.  The cpu numbers are the same as shown in the 
> +available CPUs except B through D.  The cpu numbers are the same as shown in the
>  .I processor
>  field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU sets.
>  * Support for CPU sets requires libnuma version >= 2.  For libnuma v1, PROC-SET,
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 05/28] cyclictest.8: Synopsis: Remove -h flag

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Per commit 79ad2eca9abe ("COPYING file and cyclictest's man page added"),
> "-h" as a flag is an invalid left-over from the template the manpage was
> based on.
> 
> Remove it from the cyclictest's flags list, as "-h" is actually a
> shorthand for "--histogram", which is already documented.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 76b10f3..c1a7b29 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -17,7 +17,7 @@
>  cyclictest \- High resolution test program
>  .SH SYNOPSIS
>  .SY cyclictest
> -.RI "[ \-hfmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
> +.RI "[ \-fmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
>  [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
>  [\-p " prio " ] [\-t " num " ] [\-D " time " ]"
>  
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

(it kind of works anyway, since we get a usage message when histogram 
doesn't have a value)

Re: [PATCH v1 06/28] cyclictest.8: Standardize --verbose paragraph formatting

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> All of cyclictest's options are described in the manpage through a single
> paragraph except --verbose, which renders the verbose statistics output
> format in a separate paragraph for no special reason.
> 
> Let the description text of --versbose match the other parameters style.
> Beside consistency, this will also be useful when all the options will be
> separated at the manpage source level.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 9 ++++-----
>  1 file changed, 4 insertions(+), 5 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index c1a7b29..803c5fd 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -170,11 +170,10 @@ write a trace mark when \-b latency is exceeded.
>  force unbuffered output for live processing
>  .TP
>  .B \-v, \-\-verbose
> -Output values on stdout for statistics. This option is used to gather statistical information about the latency distribution. The output is sent to stdout. The output format is:
> -
> -n:c:v
> -
> -where n=task number c=count v=latency value in us.
> +Output values on stdout for statistics. This option is used to gather
> +statistical information about the latency distribution. The output is sent
> +to stdout. The output format is: "n:c:v", where n is the task number, c is
> +the count, and v is the latency value in microseconds.
>  .TP
>  .B \-\-dbg_cyclictest
>  Print info userful for debugging cyclictest
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 07/28] cyclictest.8: Remove left-over comments

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Simplify the cyclictest manpage source by removing all obsolete comments.
> 
> Per commit 79ad2eca9abe ("COPYING file and cyclictest's man page added"),
> most of such comments are random leftovers from the original template the
> cyclictest's manpage was based on.  Namely:
> 
> (a) Remove emacs markers; modern emacsen do not need them.
> 
> (b) Remove the roff macros description table; they're all already
>     documented at man(7).
> 
> (c) Reference groff_man_style(7).  Per man(7): "man page authors and
>     maintainers who are not already experienced groff users should
>     consult groff_man_style(7)."
> 
> (d) Remove legacy, commented-out, earlier cyclictest descriptions.
> 
> (e) Remove a reference to info pages; cyclictest does not have any.
> 
> (f) Remove an obscure joke about the manpage being written by "The Rise
>     and Fall of a Fooish Bar."
> 
> With this, further documentation cleanups will be easily stacked on top.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 25 +------------------------
>  1 file changed, 1 insertion(+), 24 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 803c5fd..d4ce648 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -1,18 +1,6 @@
>  .\" SPDX-License-Identifier: GPL-2.0-only
> -.\"                                      Hey, EMACS: -*- nroff -*-
> +.\" For a man pages tutorial, check groff_man_style(7)
>  .TH CYCLICTEST 8 "April 22, 2016"
> -.\" Please adjust this date whenever revising the manpage.
> -.\"
> -.\" Some roff macros, for reference:
> -.\" .nh        disable hyphenation
> -.\" .hy        enable hyphenation
> -.\" .ad l      left justify
> -.\" .ad b      justify to both left and right margins
> -.\" .nf        disable filling
> -.\" .fi        enable filling
> -.\" .br        insert line break
> -.\" .sp <n>    insert n+1 empty lines
> -.\" for manpage-specific macros, see man(7)
>  .SH NAME
>  cyclictest \- High resolution test program
>  .SH SYNOPSIS
> @@ -21,18 +9,11 @@ cyclictest \- High resolution test program
>  [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
>  [\-p " prio " ] [\-t " num " ] [\-D " time " ]"
>  
> -.\" .SH DESCRIPTION
> -.\" This manual page documents briefly the
> -.\" .B cyclictest commands.
> -.\" .PP
> -.\" \fI<whatever>\fP escape sequences to invode bold face and italics, respectively.
> -.\" \fBcyclictest\fP is a program that...
>  .SH OPTIONS
>  These programs follow the usual GNU command line syntax, with long
>  options starting with two dashes ('\-\-').
>  .br
>  A summary of options is included below.
> -.\" For a complete description, see the Info files.
>  .TP
>  .B \-a, \-\-affinity[=PROC-SET]
>  Run threads on the set of processors given by PROC-SET.  If PROC-SET is not
> @@ -184,10 +165,6 @@ Use POSIX timers instead of clock_nanosleep.
>  .SH SEE ALSO
>  .BR numa (3),
>  .BR numactl (8),
> -.\" .br
> -.\" The programs are documented fully by
> -.\" .IR "The Rise and Fall of a Fooish Bar" ,
> -.\" available via the Info system.
>  .SH AUTHOR
>  cyclictest was written by Thomas Gleixner <tglx@linuxtronix.de>.
>  .PP
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 08/28] cyclictest.8: Align source file to 75 columns

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Enforce proper column alignment for the whole cyclictest manpage source.
> Next commits will significantly expand the parameters' description text,
> and without such alignment the expanded text will be hard to read and
> review at the source.
> 
> Per man-pages(7): "please limit source code line length to no more than
> about 75 characters wherever possible."
> 
> Note, no content change, as verified before and after by
> "man ./cyclictest.8 | md5sum"
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 85 ++++++++++++++++++++++++-------------
>  1 file changed, 55 insertions(+), 30 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index d4ce648..6bf983d 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -17,16 +17,17 @@ A summary of options is included below.
>  .TP
>  .B \-a, \-\-affinity[=PROC-SET]
>  Run threads on the set of processors given by PROC-SET.  If PROC-SET is not
> -specified, all processors will be used.  Threads will be assigned to processors
> -in the set in numeric order, in a round\-robin fashion.
> +specified, all processors will be used.  Threads will be assigned to
> +processors in the set in numeric order, in a round\-robin fashion.
>  .br
> -The set of processors can be specified as A,B,C, or A-C, or A-B,D-F, and so on*.
> -The ! character can be used to negate a set.  For example, !B-D means to use all
> -available CPUs except B through D.  The cpu numbers are the same as shown in the
> +The set of processors can be specified as A,B,C, or A-C, or A-B,D-F, and so
> +on*.  The ! character can be used to negate a set.  For example, !B-D means
> +to use all available CPUs except B through D.  The cpu numbers are the same
> +as shown in the
>  .I processor
> -field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU sets.
> -* Support for CPU sets requires libnuma version >= 2.  For libnuma v1, PROC-SET,
> -if specified, must be a single CPU number.
> +field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU
> +sets.  * Support for CPU sets requires libnuma version >= 2.  For libnuma
> +v1, PROC-SET, if specified, must be a single CPU number.
>  .TP
>  .B \-A, \-\-align=USEC
>  Align thread wakeups to a specific offset in microseconds
> @@ -42,10 +43,14 @@ select clock
>  1 = CLOCK_REALTIME
>  .TP
>  .B \-\-deepest\-idle\-state=n
> -Reduce exit from idle latency by limiting idle state up to n on used cpus (-1 disables all idle states). Power management is not suppresed on other cpus.
> +Reduce exit from idle latency by limiting idle state up to n on used cpus
> +(-1 disables all idle states). Power management is not suppresed on other
> +cpus.
>  .TP
>  .B \-\-default\-system
> -Don't attempt to tune the system from cyclictest. Power management is not suppressed. This might give poorer results, but will allow you to discover if you need to tune the system.
> +Don't attempt to tune the system from cyclictest. Power management is not
> +suppressed. This might give poorer results, but will allow you to discover
> +if you need to tune the system.
>  .TP
>  .B \-d, \-\-distance=DIST
>  Distance of thread intervals in us, default = 500
> @@ -59,31 +64,41 @@ Append 'm', 'h', or 'd' to specify minutes, hours or days.
>  Create a named pipe at path and write stats to it
>  .TP
>  .B \-h, \-\-histogram=US
> -Dump latency histogram to stdout after the run. US is the max latency time to be be tracked in microseconds. This option runs all threads at the same priority.
> +Dump latency histogram to stdout after the run. US is the max latency time
> +to be be tracked in microseconds. This option runs all threads at the same
> +priority.
>  .TP
>  .B \-H, \-\-histofall=MAXLATENCYINUS
> -Same as -h except that an additional histogram column is displayed at the right that contains summary data of all thread histograms. If cyclictest runs a single thread only, the -H option is equivalent to -h.
> +Same as -h except that an additional histogram column is displayed at the
> +right that contains summary data of all thread histograms. If cyclictest
> +runs a single thread only, the -H option is equivalent to -h.
>  .TP
>  .B \-\-histfile=<path>
>  Dump the latency histogram to <path> instead of stdout.
>  .TP
>  .B \-i, \-\-interval=INTV
> -Set the base interval of the thread(s) in microseconds (default is 1000us). This sets the interval of the first thread. See also \-d.
> +Set the base interval of the thread(s) in microseconds (default is
> +1000us). This sets the interval of the first thread. See also \-d.
>  .TP
>  .B \-\-json=FILENAME
>  Write final results into FILENAME, JSON formatted.
>  .TP
>  .B \-\-laptop
> -Save battery when running cyclictest. This will give you poorer realtime results, but will not drain your battery so quickly.
> +Save battery when running cyclictest. This will give you poorer realtime
> +results, but will not drain your battery so quickly.
>  .TP
>  .B \-\-latency=PM_Q0S
> -power management latency target value. This value is written to /dev/cpu_dma_latency and affects c-states. The default is 0
> +power management latency target value. This value is written to
> +/dev/cpu_dma_latency and affects c-states. The default is 0
>  .TP
>  .B \-l, \-\-loops=LOOPS
> -Set the number of loops. The default is 0 (endless). This option is useful for automated tests with a given number of test cycles. Cyclictest is stopped once the number of timer intervals has been reached.
> +Set the number of loops. The default is 0 (endless). This option is useful
> +for automated tests with a given number of test cycles. Cyclictest is
> +stopped once the number of timer intervals has been reached.
>  .TP
>  .B \-\-mainaffinity=CPUSET
> -Run the main thread on CPU #N. This only affects the main thread and not the measurement threads
> +Run the main thread on CPU #N. This only affects the main thread and not
> +the measurement threads
>  .TP
>  .B \-m, \-\-mlockall
>  Lock current and future memory allocations to prevent being paged out
> @@ -93,41 +108,50 @@ Delay updating the screen until a new max latency is hit. (useful for
>  running cyclictest on low-bandwidth connections)
>  .TP
>  .B \-N, \-\-nsecs
> -Show results in nanoseconds instead of microseconds, which is the default unit.
> +Show results in nanoseconds instead of microseconds, which is the default
> +unit.
>  .TP
>  .B \-o, \-\-oscope=RED
>  Oscilloscope mode, reduce verbose output by RED.
>  .TP
>  .B \-p, \-\-prio=PRIO
> -Set the priority of the first thread. The given priority is set to the first test thread. Each further thread gets a lower priority:
> +Set the priority of the first thread. The given priority is set to the
> +first test thread. Each further thread gets a lower priority:
>  Priority(Thread N) = max(Priority(Thread N\-1) \- 1, 0)
>  .TP
>  .B \-\-policy=NAME
> -set the scheduler policy of the measurement threads
> -where NAME is one of: other, normal, batch, idle, fifo, rr
> +set the scheduler policy of the measurement threads where NAME is one of:
> +other, normal, batch, idle, fifo, rr
>  .TP
>  .B \-\-priospread
>  spread priority levels starting at a specified value
>  .TP
>  .B \-q, \-\-quiet
> -Print a summary only on exit. Useful for automated tests, where only the summary output needs to be captured.
> +Print a summary only on exit. Useful for automated tests, where only the
> +summary output needs to be captured.
>  .TP
>  .B \-r, \-\-relative
> -Use relative timers instead of absolute. The default behaviour of the tests is to use absolute timers. This option is there for completeness and should not be used for reproducible tests.
> +Use relative timers instead of absolute. The default behaviour of the tests
> +is to use absolute timers. This option is there for completeness and should
> +not be used for reproducible tests.
>  .TP
>  .B \-R, \-\-resolution
> -Check clock resolution, calling clock_gettime() many times. List of lock_gettime() values will be reported with -X
> +Check clock resolution, calling clock_gettime() many times. List of
> +lock_gettime() values will be reported with -X
>  .TP
>  .B \-\-secaligned [USEC]
>  align thread wakeups to the next full second and apply the optional offset.
>  .TP
>  .B \-s, \-\-system
> -Use sys_nanosleep and sys_setitimer instead of posix timers. Note, that \-s can only be used with one thread because itimers are per process and not per thread. \-s uses the nanosleep syscall and is not restricted to one thread.
> +Use sys_nanosleep and sys_setitimer instead of posix timers. Note, that \-s
> +can only be used with one thread because itimers are per process and not
> +per thread. \-s uses the nanosleep syscall and is not restricted to one
> +thread.
>  .TP
>  .B \\-S, \-\-smp
> -Set options for standard testing on SMP systems. Equivalent to using
> -the options: "\-t \-a" as well keeping any specified priority
> -equal across all threads
> +Set options for standard testing on SMP systems. Equivalent to using the
> +options: "\-t \-a" as well keeping any specified priority equal across all
> +threads
>  .TP
>  .B \-\-spike=<trigger>
>  record all spikes > trigger
> @@ -141,8 +165,9 @@ The default is 1024 if not specified.
>  Enable SMI count/detection on processors with SMI count support.
>  .TP
>  .B \-t, \-\-threads[=NUM]
> -Set the number of test threads (default is 1). Create NUM test threads. If NUM is not specified, NUM is set to
> -the number of available CPUs. See \-d, \-i and \-p for further information.
> +Set the number of test threads (default is 1). Create NUM test threads. If
> +NUM is not specified, NUM is set to the number of available CPUs. See \-d,
> +\-i and \-p for further information.
>  .TP
>  .B \-\-tracemark
>  write a trace mark when \-b latency is exceeded.
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 09/28] cyclictest.8: Separate source sections

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Further work will significantly expand the cyclictest's parameter
> documentation.  Improve the manpage's source readability by separating
> its different sections with newlines.
> 
> Per groff_man_style(7), use groff's empty request (.) for this vertical
> spacing as blank lines shouldn't exist in a manpage source file.
> Authoritative manpages like groff_man(7) is also written this way.
> 
> No output change, as verified before and after by
> "man ./cyclictest.8 | md5sum".
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 47 +++++++++++++++++++++++++++++++++++--
>  1 file changed, 45 insertions(+), 2 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 6bf983d..f27fe66 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -1,19 +1,22 @@
>  .\" SPDX-License-Identifier: GPL-2.0-only
>  .\" For a man pages tutorial, check groff_man_style(7)
>  .TH CYCLICTEST 8 "April 22, 2016"
> +.
>  .SH NAME
>  cyclictest \- High resolution test program
> +.
>  .SH SYNOPSIS
>  .SY cyclictest
>  .RI "[ \-fmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
>  [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
>  [\-p " prio " ] [\-t " num " ] [\-D " time " ]"
> -
> +.
>  .SH OPTIONS
>  These programs follow the usual GNU command line syntax, with long
>  options starting with two dashes ('\-\-').
>  .br
>  A summary of options is included below.
> +.
>  .TP
>  .B \-a, \-\-affinity[=PROC-SET]
>  Run threads on the set of processors given by PROC-SET.  If PROC-SET is not
> @@ -28,12 +31,15 @@ as shown in the
>  field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU
>  sets.  * Support for CPU sets requires libnuma version >= 2.  For libnuma
>  v1, PROC-SET, if specified, must be a single CPU number.
> +.
>  .TP
>  .B \-A, \-\-align=USEC
>  Align thread wakeups to a specific offset in microseconds
> +.
>  .TP
>  .B \-b, \-\-breaktrace=USEC
>  Send break trace command when latency > USEC
> +.
>  .TP
>  .B \-c, \-\-clock=CLOCK
>  select clock
> @@ -41,155 +47,192 @@ select clock
>  0 = CLOCK_MONOTONIC (default)
>  .br
>  1 = CLOCK_REALTIME
> +.
>  .TP
>  .B \-\-deepest\-idle\-state=n
>  Reduce exit from idle latency by limiting idle state up to n on used cpus
>  (-1 disables all idle states). Power management is not suppresed on other
>  cpus.
> +.
>  .TP
>  .B \-\-default\-system
>  Don't attempt to tune the system from cyclictest. Power management is not
>  suppressed. This might give poorer results, but will allow you to discover
>  if you need to tune the system.
> +.
>  .TP
>  .B \-d, \-\-distance=DIST
>  Distance of thread intervals in us, default = 500
> +.
>  .TP
>  .B \-D, \-\-duration=TIME
>  Specify a length for the test run.
>  .br
>  Append 'm', 'h', or 'd' to specify minutes, hours or days.
> +.
>  .TP
>  .B \-F, \-\-fifo=<path>
>  Create a named pipe at path and write stats to it
> +.
>  .TP
>  .B \-h, \-\-histogram=US
>  Dump latency histogram to stdout after the run. US is the max latency time
>  to be be tracked in microseconds. This option runs all threads at the same
>  priority.
> +.
>  .TP
>  .B \-H, \-\-histofall=MAXLATENCYINUS
>  Same as -h except that an additional histogram column is displayed at the
>  right that contains summary data of all thread histograms. If cyclictest
>  runs a single thread only, the -H option is equivalent to -h.
> +.
>  .TP
>  .B \-\-histfile=<path>
>  Dump the latency histogram to <path> instead of stdout.
> +.
>  .TP
>  .B \-i, \-\-interval=INTV
>  Set the base interval of the thread(s) in microseconds (default is
>  1000us). This sets the interval of the first thread. See also \-d.
> +.
>  .TP
>  .B \-\-json=FILENAME
>  Write final results into FILENAME, JSON formatted.
> +.
>  .TP
>  .B \-\-laptop
>  Save battery when running cyclictest. This will give you poorer realtime
>  results, but will not drain your battery so quickly.
> +.
>  .TP
>  .B \-\-latency=PM_Q0S
>  power management latency target value. This value is written to
>  /dev/cpu_dma_latency and affects c-states. The default is 0
> +.
>  .TP
>  .B \-l, \-\-loops=LOOPS
>  Set the number of loops. The default is 0 (endless). This option is useful
>  for automated tests with a given number of test cycles. Cyclictest is
>  stopped once the number of timer intervals has been reached.
> +.
>  .TP
>  .B \-\-mainaffinity=CPUSET
>  Run the main thread on CPU #N. This only affects the main thread and not
>  the measurement threads
> +.
>  .TP
>  .B \-m, \-\-mlockall
>  Lock current and future memory allocations to prevent being paged out
> +.
>  .TP
>  .B \\-M, \-\-refresh_on_max
>  Delay updating the screen until a new max latency is hit. (useful for
>  running cyclictest on low-bandwidth connections)
> +.
>  .TP
>  .B \-N, \-\-nsecs
>  Show results in nanoseconds instead of microseconds, which is the default
>  unit.
> +.
>  .TP
>  .B \-o, \-\-oscope=RED
>  Oscilloscope mode, reduce verbose output by RED.
> +.
>  .TP
>  .B \-p, \-\-prio=PRIO
>  Set the priority of the first thread. The given priority is set to the
>  first test thread. Each further thread gets a lower priority:
>  Priority(Thread N) = max(Priority(Thread N\-1) \- 1, 0)
> +.
>  .TP
>  .B \-\-policy=NAME
>  set the scheduler policy of the measurement threads where NAME is one of:
>  other, normal, batch, idle, fifo, rr
> +.
>  .TP
>  .B \-\-priospread
>  spread priority levels starting at a specified value
> +.
>  .TP
>  .B \-q, \-\-quiet
>  Print a summary only on exit. Useful for automated tests, where only the
>  summary output needs to be captured.
> +.
>  .TP
>  .B \-r, \-\-relative
>  Use relative timers instead of absolute. The default behaviour of the tests
>  is to use absolute timers. This option is there for completeness and should
>  not be used for reproducible tests.
> +.
>  .TP
>  .B \-R, \-\-resolution
>  Check clock resolution, calling clock_gettime() many times. List of
>  lock_gettime() values will be reported with -X
> +.
>  .TP
>  .B \-\-secaligned [USEC]
>  align thread wakeups to the next full second and apply the optional offset.
> +.
>  .TP
>  .B \-s, \-\-system
>  Use sys_nanosleep and sys_setitimer instead of posix timers. Note, that \-s
>  can only be used with one thread because itimers are per process and not
>  per thread. \-s uses the nanosleep syscall and is not restricted to one
>  thread.
> +.
>  .TP
>  .B \\-S, \-\-smp
>  Set options for standard testing on SMP systems. Equivalent to using the
>  options: "\-t \-a" as well keeping any specified priority equal across all
>  threads
> +.
>  .TP
>  .B \-\-spike=<trigger>
>  record all spikes > trigger
> +.
>  .TP
>  .B \-\-spike-nodes=[num of nodes]
>  These are the maximum number of spikes we can record.
>  .br
>  The default is 1024 if not specified.
> +.
>  .TP
>  .B \\-\-smi
>  Enable SMI count/detection on processors with SMI count support.
> +.
>  .TP
>  .B \-t, \-\-threads[=NUM]
>  Set the number of test threads (default is 1). Create NUM test threads. If
>  NUM is not specified, NUM is set to the number of available CPUs. See \-d,
>  \-i and \-p for further information.
> +.
>  .TP
>  .B \-\-tracemark
>  write a trace mark when \-b latency is exceeded.
> +.
>  .TP
>  .B \-u, \-\-unbuffered
>  force unbuffered output for live processing
> +.
>  .TP
>  .B \-v, \-\-verbose
>  Output values on stdout for statistics. This option is used to gather
>  statistical information about the latency distribution. The output is sent
>  to stdout. The output format is: "n:c:v", where n is the task number, c is
>  the count, and v is the latency value in microseconds.
> +.
>  .TP
>  .B \-\-dbg_cyclictest
>  Print info userful for debugging cyclictest
> +.
>  .TP
>  .B \-x, \-\-posix_timers
>  Use POSIX timers instead of clock_nanosleep.
> -
> +.
>  .SH SEE ALSO
>  .BR numa (3),
>  .BR numactl (8),
> +.
>  .SH AUTHOR
>  cyclictest was written by Thomas Gleixner <tglx@linuxtronix.de>.
>  .PP
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com

Re: [PATCH v1 10/28] cyclictest.8: Capitalize section headers

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Per groff(7) and groff_man_style(7), capitalize the section headers
> without resorting to all caps.
> 
> This makes the manpage's output calmer to read as well.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index f27fe66..7f1bd39 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -1,17 +1,17 @@
>  .\" SPDX-License-Identifier: GPL-2.0-only
>  .\" For a man pages tutorial, check groff_man_style(7)
> -.TH CYCLICTEST 8 "April 22, 2016"
> +.TH Cyclictest 8 "April 22, 2016"
>  .
> -.SH NAME
> +.SH Name
>  cyclictest \- High resolution test program
>  .
> -.SH SYNOPSIS
> +.SH Synopsis
>  .SY cyclictest
>  .RI "[ \-fmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
>  [\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
>  [\-p " prio " ] [\-t " num " ] [\-D " time " ]"
>  .
> -.SH OPTIONS
> +.SH Options
>  These programs follow the usual GNU command line syntax, with long
>  options starting with two dashes ('\-\-').
>  .br
> @@ -229,11 +229,11 @@ Print info userful for debugging cyclictest
>  .B \-x, \-\-posix_timers
>  Use POSIX timers instead of clock_nanosleep.
>  .
> -.SH SEE ALSO
> +.SH "See also"
>  .BR numa (3),
>  .BR numactl (8),
>  .
> -.SH AUTHOR
> +.SH Authors
>  cyclictest was written by Thomas Gleixner <tglx@linuxtronix.de>.
>  .PP
>  This manual page was written by Alessio Igor Bogani <abogani@texware.it>,
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 11/28] cyclictest.8: Synopsis: Fix parameters list rendering

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Follow groff_man_style(7) parameters documentation style.  Namely:
> 
> - Order cyclictest flags in the form -abcCeEgGijklNpRsStUVXzZ
> 
> - Present the flag and option names in bold to cue the user that they
>   should be input literally.
> 
> - Use the non-breaking adjustable space escape sequence "\~" to prevent
>   the line output from being broken within the option brackets.
> 
> - Use the output line continuation escape sequence "\c" to allow all
>   three font styles to be set without breakable space among them.
> 
> - End the parameters list with .YS, the "End synopsis" macro.  It
>   restores indentation, adjustment, and hyphenation to their previous
>   state.
> 
> Beside just following the standards, this makes the groff rendering of
> the cyclictest's parameter list way more legible and comprehensible.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 31 ++++++++++++++++++++++++++++---
>  1 file changed, 28 insertions(+), 3 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 7f1bd39..f093677 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -7,9 +7,34 @@ cyclictest \- High resolution test program
>  .
>  .SH Synopsis
>  .SY cyclictest
> -.RI "[ \-fmnqrsvMS ] [\-a " proc " ] [\-A " align " ] [\-b " usec " ] [\-c " clock " ] [\-d " dist " ] \
> -[\-h " histogram " ] [\-i " intv " ] [\-\-json " filename " ] [\-l " loop " ] [\-o " red " ] \
> -[\-p " prio " ] [\-t " num " ] [\-D " time " ]"
> +.RB [ \-fmMnqrsMv ]
> +.RB [ \-a\~\c
> +.IR proc ]
> +.RB [ \-A\~\c
> +.IR align ]
> +.RB [ \-b\~\c
> +.IR usec ]
> +.RB [ \-c\~\c
> +.IR clock ]
> +.RB [ \-d\~\c
> +.IR dist ]
> +.RB [ \-h\~\c
> +.IR histogram ]
> +.RB [ \-i\~\c
> +.IR intv ]
> +.RB [ \-\-json\~\c
> +.IR filename ]
> +.RB [ \-l\~\c
> +.IR loop ]
> +.RB [ \-o\~\c
> +.IR red ]
> +.RB [ \-p\~\c
> +.IR prio ]
> +.RB [ \-t\~\c
> +.IR num ]
> +.RB [ \-D\~\c
> +.IR time ]
> +.YS
>  .
>  .SH Options
>  These programs follow the usual GNU command line syntax, with long
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 12/28] cyclictest.8: Rework the Synopsis blurb

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> The cyclictest's SYNOPSIS blurb is buggy and incomplete.
> 
> For the cyclictest's flag list:
> 
>   - Remove 'f', for --fifo, as it's not a flag and requires the fifo's path
>   - Add 'N', for --nsecs
>   - Add 'R', for --resolution
>   - Add 'S', for --smp
>   - Add 'u', for --unbuffered
>   - Add 'x', for --posix_timers
> 
> For options with arguments, expand the argument names with something
> comprehensible since the whole purpose of the SYNOPSIS section is to get,
> in a blitz, an understanding of the tool's actual options.  The original
> argument names, especially when -combined with the one-letter option's
> shorthand form, were totally -incomprehensible.
> 
> For consistency, be coherent regarding the arguments' names; e.g.,
> "*-path" for all file paths like file-path and fifo-path, "proc-set" for
> cpuset-related arguments, "num-*" for counts like num-threads and
> num-loops; "*-usec" for microsecond arguments, and so on.
> 
> Also add the missing options --deepest-idle-state, --histfile, --latency,
> --mainaffinity, --policy, --spike, --spike-nodes, --dbg_cyclictest,
> --default-system, --smi, --priospread, --smi, and --tracemark.  Do not
> add --laptop since it is deprecated.
> 
> Note, this makes the cyclictest's SYNOPSIS blurb complete and gives a
> comprehensive view of cyclictest's abilities in a glance.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 57 ++++++++++++++++++++++++++-----------
>  1 file changed, 41 insertions(+), 16 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index f093677..0271f5c 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -7,33 +7,58 @@ cyclictest \- High resolution test program
>  .
>  .SH Synopsis
>  .SY cyclictest
> -.RB [ \-fmMnqrsMv ]
> +.RB [ \-mMNqrRsSuvx ]
>  .RB [ \-a\~\c
> -.IR proc ]
> +.IR proc\-set ]
>  .RB [ \-A\~\c
> -.IR align ]
> +.IR alignment\-usec ]
>  .RB [ \-b\~\c
> -.IR usec ]
> +.IR break\-usec ]
>  .RB [ \-c\~\c
> -.IR clock ]
> +.IR clock\-type ]
>  .RB [ \-d\~\c
> -.IR dist ]
> +.IR distance\-usec ]
> +.RB [ \-D\~\c
> +.IR duration\-mhd ]
> +.RB [ \-f\~\c
> +.IR fifo\-path ]
>  .RB [ \-h\~\c
> -.IR histogram ]
> +.IR max\-latency\-usec ]
> +.RB [ \-H\~\c
> +.IR max\-latency\-usec ]
>  .RB [ \-i\~\c
> -.IR intv ]
> -.RB [ \-\-json\~\c
> -.IR filename ]
> +.IR interval\-usec ]
>  .RB [ \-l\~\c
> -.IR loop ]
> +.IR num\-loops ]
>  .RB [ \-o\~\c
> -.IR red ]
> +.IR oscope\-red ]
>  .RB [ \-p\~\c
> -.IR prio ]
> +.IR thread\-prio ]
>  .RB [ \-t\~\c
> -.IR num ]
> -.RB [ \-D\~\c
> -.IR time ]
> +.IR num\-threads ]
> +.RB [ \-\-deepest\-idle\-state\~\c
> +.IR idle-state-num ]
> +.RB [ \-\-histfile\~\c
> +.IR file\-path ]
> +.RB [ \-\-json\~\c
> +.IR file\-path ]
> +.RB [ \-\-latency\~\c
> +.IR pm\-c\-state ]
> +.RB [ \-\-mainaffinity\~\c
> +.IR proc-set ]
> +.RB [ \-\-policy\~\c
> +.IR threads\-sched\-policy ]
> +.RB [ \-\-secaligned\~\c
> +.IR wakeup\-usec ]
> +.RB [ \-\-spike\~\c
> +.IR trigger\-point-usec ]
> +.RB [ \-\-spike\-nodes\~\c
> +.IR num\-nodes ]
> +.RB [ \-\-dbg_cyclictest ]
> +.RB [ \-\-default\-system ]
> +.RB [ \-\-priospread ]
> +.RB [ \-\-smi ]
> +.RB [ \-\-tracemark ]
>  .YS
>  .
>  .SH Options
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 13/28] cyclictest.8: Synopsis: Distinguish --help mode

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Per groff_man_style(7), different command operation modes should be
> distinguished through unique Synopsis (.SY/.YS) blocks.
> 
> Distinguish "cyclictest --help" with its own section, as other parameters
> won't be recognized when --help is passed.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 12 ++++++++----
>  1 file changed, 8 insertions(+), 4 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 0271f5c..1fd550f 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -6,6 +6,7 @@
>  cyclictest \- High resolution test program
>  .
>  .SH Synopsis
> +.
>  .SY cyclictest
>  .RB [ \-mMNqrRsSuvx ]
>  .RB [ \-a\~\c
> @@ -61,11 +62,14 @@ cyclictest \- High resolution test program
>  .RB [ \-\-tracemark ]
>  .YS
>  .
> +.SY cyclictest
> +.B \-\-help
> +.YS
> +.
>  .SH Options
> -These programs follow the usual GNU command line syntax, with long
> -options starting with two dashes ('\-\-').
> -.br
> -A summary of options is included below.
> +.
> +.B \-\-help
> +display a usage message and exit.
>  .
>  .TP
>  .B \-a, \-\-affinity[=PROC-SET]
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 14/28] cyclictest.8: Group system-altering options

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> The number and breadth of cyclictest's options is huge, and just
> exploring them in sequence can get the manpage reader lost.
> 
> Put the cyclictest's system-altering options:
> 
>        --default-system
>        --latency=PM_QOS
>        --deepest-idle-state=n
>        --laptop
> 
> into their own group.  Adjust the Synopsis accordingly as well.
> 
> Further groupings will be added next.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 58 ++++++++++++++++++++-----------------
>  1 file changed, 31 insertions(+), 27 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 1fd550f..0bc2fc1 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -9,6 +9,11 @@ cyclictest \- High resolution test program
>  .
>  .SY cyclictest
>  .RB [ \-mMNqrRsSuvx ]
> +.RB [ \-\-default\-system ]
> +.RB [ \-\-latency\~\c
> +.IR pm\-c\-state ]
> +.RB [ \-\-deepest\-idle\-state\~\c
> +.IR idle-state-num ]
>  .RB [ \-a\~\c
>  .IR proc\-set ]
>  .RB [ \-A\~\c
> @@ -37,14 +42,10 @@ cyclictest \- High resolution test program
>  .IR thread\-prio ]
>  .RB [ \-t\~\c
>  .IR num\-threads ]
> -.RB [ \-\-deepest\-idle\-state\~\c
> -.IR idle-state-num ]
>  .RB [ \-\-histfile\~\c
>  .IR file\-path ]
>  .RB [ \-\-json\~\c
>  .IR file\-path ]
> -.RB [ \-\-latency\~\c
> -.IR pm\-c\-state ]
>  .RB [ \-\-mainaffinity\~\c
>  .IR proc-set ]
>  .RB [ \-\-policy\~\c
> @@ -56,7 +57,6 @@ cyclictest \- High resolution test program
>  .RB [ \-\-spike\-nodes\~\c
>  .IR num\-nodes ]
>  .RB [ \-\-dbg_cyclictest ]
> -.RB [ \-\-default\-system ]
>  .RB [ \-\-priospread ]
>  .RB [ \-\-smi ]
>  .RB [ \-\-tracemark ]
> @@ -71,6 +71,32 @@ cyclictest \- High resolution test program
>  .B \-\-help
>  display a usage message and exit.
>  .
> +.SS "System-altering options"
> +.
> +.TP
> +.B \-\-default\-system
> +Don't attempt to tune the system from cyclictest. Power management is not
> +suppressed. This might give poorer results, but will allow you to discover
> +if you need to tune the system.
> +.
> +.TP
> +.B \-\-latency=PM_Q0S
> +power management latency target value. This value is written to
> +/dev/cpu_dma_latency and affects c-states. The default is 0
> +.
> +.TP
> +.B \-\-deepest\-idle\-state=n
> +Reduce exit from idle latency by limiting idle state up to n on used cpus
> +(-1 disables all idle states). Power management is not suppresed on other
> +cpus.
> +.
> +.TP
> +.B \-\-laptop
> +Save battery when running cyclictest. This will give you poorer realtime
> +results, but will not drain your battery so quickly.
> +.
> +.SS "Other options"
> +.
>  .TP
>  .B \-a, \-\-affinity[=PROC-SET]
>  Run threads on the set of processors given by PROC-SET.  If PROC-SET is not
> @@ -103,18 +129,6 @@ select clock
>  1 = CLOCK_REALTIME
>  .
>  .TP
> -.B \-\-deepest\-idle\-state=n
> -Reduce exit from idle latency by limiting idle state up to n on used cpus
> -(-1 disables all idle states). Power management is not suppresed on other
> -cpus.
> -.
> -.TP
> -.B \-\-default\-system
> -Don't attempt to tune the system from cyclictest. Power management is not
> -suppressed. This might give poorer results, but will allow you to discover
> -if you need to tune the system.
> -.
> -.TP
>  .B \-d, \-\-distance=DIST
>  Distance of thread intervals in us, default = 500
>  .
> @@ -154,16 +168,6 @@ Set the base interval of the thread(s) in microseconds (default is
>  Write final results into FILENAME, JSON formatted.
>  .
>  .TP
> -.B \-\-laptop
> -Save battery when running cyclictest. This will give you poorer realtime
> -results, but will not drain your battery so quickly.
> -.
> -.TP
> -.B \-\-latency=PM_Q0S
> -power management latency target value. This value is written to
> -/dev/cpu_dma_latency and affects c-states. The default is 0
> -.
> -.TP
>  .B \-l, \-\-loops=LOOPS
>  Set the number of loops. The default is 0 (endless). This option is useful
>  for automated tests with a given number of test cycles. Cyclictest is
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 15/28] cyclictest.8: Group sleep-mechanism (clock) options

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> The number and breadth of cyclictest's options is huge, and just
> exploring them in sequence can get the manpage reader lost.
> 
> Put the cyclictest's sleep-mechanism related options:
> 
>        -c, --clock=CLOCK
>        -x, --posix_timers
>        -s, --system
>        -r, --relative
>        -R, --resolution
> 
> into their own group.  Adjust the Synopsis accordingly as well.
> 
> Further groupings will be added next.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 66 +++++++++++++++++++------------------
>  1 file changed, 34 insertions(+), 32 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 0bc2fc1..eb7d713 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -14,14 +14,14 @@ cyclictest \- High resolution test program
>  .IR pm\-c\-state ]
>  .RB [ \-\-deepest\-idle\-state\~\c
>  .IR idle-state-num ]
> +.RB [ \-c\~\c
> +.IR clock\-type ]
>  .RB [ \-a\~\c
>  .IR proc\-set ]
>  .RB [ \-A\~\c
>  .IR alignment\-usec ]
>  .RB [ \-b\~\c
>  .IR break\-usec ]
> -.RB [ \-c\~\c
> -.IR clock\-type ]
>  .RB [ \-d\~\c
>  .IR distance\-usec ]
>  .RB [ \-D\~\c
> @@ -95,6 +95,38 @@ cpus.
>  Save battery when running cyclictest. This will give you poorer realtime
>  results, but will not drain your battery so quickly.
>  .
> +.SS "Sleep-mechanism clock options"
> +.
> +.TP
> +.B \-c, \-\-clock=CLOCK
> +select clock
> +.br
> +0 = CLOCK_MONOTONIC (default)
> +.br
> +1 = CLOCK_REALTIME
> +.
> +.TP
> +.B \-x, \-\-posix_timers
> +Use POSIX timers instead of clock_nanosleep.
> +.
> +.TP
> +.B \-s, \-\-system
> +Use sys_nanosleep and sys_setitimer instead of posix timers. Note, that \-s
> +can only be used with one thread because itimers are per process and not
> +per thread. \-s uses the nanosleep syscall and is not restricted to one
> +thread.
> +.
> +.TP
> +.B \-r, \-\-relative
> +Use relative timers instead of absolute. The default behaviour of the tests
> +is to use absolute timers. This option is there for completeness and should
> +not be used for reproducible tests.
> +.
> +.TP
> +.B \-R, \-\-resolution
> +Check clock resolution, calling clock_gettime() many times. List of
> +lock_gettime() values will be reported with -X
> +.
>  .SS "Other options"
>  .
>  .TP
> @@ -121,14 +153,6 @@ Align thread wakeups to a specific offset in microseconds
>  Send break trace command when latency > USEC
>  .
>  .TP
> -.B \-c, \-\-clock=CLOCK
> -select clock
> -.br
> -0 = CLOCK_MONOTONIC (default)
> -.br
> -1 = CLOCK_REALTIME
> -.
> -.TP
>  .B \-d, \-\-distance=DIST
>  Distance of thread intervals in us, default = 500
>  .
> @@ -217,28 +241,10 @@ Print a summary only on exit. Useful for automated tests, where only the
>  summary output needs to be captured.
>  .
>  .TP
> -.B \-r, \-\-relative
> -Use relative timers instead of absolute. The default behaviour of the tests
> -is to use absolute timers. This option is there for completeness and should
> -not be used for reproducible tests.
> -.
> -.TP
> -.B \-R, \-\-resolution
> -Check clock resolution, calling clock_gettime() many times. List of
> -lock_gettime() values will be reported with -X
> -.
> -.TP
>  .B \-\-secaligned [USEC]
>  align thread wakeups to the next full second and apply the optional offset.
>  .
>  .TP
> -.B \-s, \-\-system
> -Use sys_nanosleep and sys_setitimer instead of posix timers. Note, that \-s
> -can only be used with one thread because itimers are per process and not
> -per thread. \-s uses the nanosleep syscall and is not restricted to one
> -thread.
> -.
> -.TP
>  .B \\-S, \-\-smp
>  Set options for standard testing on SMP systems. Equivalent to using the
>  options: "\-t \-a" as well keeping any specified priority equal across all
> @@ -283,10 +289,6 @@ the count, and v is the latency value in microseconds.
>  .B \-\-dbg_cyclictest
>  Print info userful for debugging cyclictest
>  .
> -.TP
> -.B \-x, \-\-posix_timers
> -Use POSIX timers instead of clock_nanosleep.
> -.
>  .SH "See also"
>  .BR numa (3),
>  .BR numactl (8),
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 16/28] cyclictest.8: Group thread wakeup timing options

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> The number and breadth of cyclictest's options is huge, and just
> exploring them in sequence can get the manpage reader lost.
> 
> Put the cyclictest's thread-wakeup timing options:
> 
>        -d, --distance=DIST
>        -i, --interval=INTV
>        --secaligned [USEC]
>        -A, --align=USEC
> 
> into their own group.  Adjust the Synopsis accordingly as well.
> 
> Further groupings will be added next.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 52 +++++++++++++++++++------------------
>  1 file changed, 27 insertions(+), 25 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index eb7d713..6ab3b19 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -16,14 +16,18 @@ cyclictest \- High resolution test program
>  .IR idle-state-num ]
>  .RB [ \-c\~\c
>  .IR clock\-type ]
> -.RB [ \-a\~\c
> -.IR proc\-set ]
> +.RB [ \-d\~\c
> +.IR distance\-usec ]
> +.RB [ \-i\~\c
> +.IR interval\-usec ]
> +.RB [ \-\-secaligned\~\c
> +.IR wakeup\-usec ]
>  .RB [ \-A\~\c
>  .IR alignment\-usec ]
> +.RB [ \-a\~\c
> +.IR proc\-set ]
>  .RB [ \-b\~\c
>  .IR break\-usec ]
> -.RB [ \-d\~\c
> -.IR distance\-usec ]
>  .RB [ \-D\~\c
>  .IR duration\-mhd ]
>  .RB [ \-f\~\c
> @@ -32,8 +36,6 @@ cyclictest \- High resolution test program
>  .IR max\-latency\-usec ]
>  .RB [ \-H\~\c
>  .IR max\-latency\-usec ]
> -.RB [ \-i\~\c
> -.IR interval\-usec ]
>  .RB [ \-l\~\c
>  .IR num\-loops ]
>  .RB [ \-o\~\c
> @@ -50,8 +52,6 @@ cyclictest \- High resolution test program
>  .IR proc-set ]
>  .RB [ \-\-policy\~\c
>  .IR threads\-sched\-policy ]
> -.RB [ \-\-secaligned\~\c
> -.IR wakeup\-usec ]
>  .RB [ \-\-spike\~\c
>  .IR trigger\-point-usec ]
>  .RB [ \-\-spike\-nodes\~\c
> @@ -127,6 +127,25 @@ not be used for reproducible tests.
>  Check clock resolution, calling clock_gettime() many times. List of
>  lock_gettime() values will be reported with -X
>  .
> +.SS "Thread-waekup timing options"
> +.
> +.TP
> +.B \-d, \-\-distance=DIST
> +Distance of thread intervals in us, default = 500
> +.
> +.TP
> +.B \-i, \-\-interval=INTV
> +Set the base interval of the thread(s) in microseconds (default is
> +1000us). This sets the interval of the first thread. See also \-d.
> +.
> +.TP
> +.B \-\-secaligned [USEC]
> +align thread wakeups to the next full second and apply the optional offset.
> +.
> +.TP
> +.B \-A, \-\-align=USEC
> +Align thread wakeups to a specific offset in microseconds
> +.
>  .SS "Other options"
>  .
>  .TP
> @@ -145,18 +164,10 @@ sets.  * Support for CPU sets requires libnuma version >= 2.  For libnuma
>  v1, PROC-SET, if specified, must be a single CPU number.
>  .
>  .TP
> -.B \-A, \-\-align=USEC
> -Align thread wakeups to a specific offset in microseconds
> -.
> -.TP
>  .B \-b, \-\-breaktrace=USEC
>  Send break trace command when latency > USEC
>  .
>  .TP
> -.B \-d, \-\-distance=DIST
> -Distance of thread intervals in us, default = 500
> -.
> -.TP
>  .B \-D, \-\-duration=TIME
>  Specify a length for the test run.
>  .br
> @@ -183,11 +194,6 @@ runs a single thread only, the -H option is equivalent to -h.
>  Dump the latency histogram to <path> instead of stdout.
>  .
>  .TP
> -.B \-i, \-\-interval=INTV
> -Set the base interval of the thread(s) in microseconds (default is
> -1000us). This sets the interval of the first thread. See also \-d.
> -.
> -.TP
>  .B \-\-json=FILENAME
>  Write final results into FILENAME, JSON formatted.
>  .
> @@ -241,10 +247,6 @@ Print a summary only on exit. Useful for automated tests, where only the
>  summary output needs to be captured.
>  .
>  .TP
> -.B \-\-secaligned [USEC]
> -align thread wakeups to the next full second and apply the optional offset.
> -.
> -.TP
>  .B \\-S, \-\-smp
>  Set options for standard testing on SMP systems. Equivalent to using the
>  options: "\-t \-a" as well keeping any specified priority equal across all
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 17/28] cyclictest.8: Group SMP-related options

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> The number and breadth of cyclictest's options is huge, and just
> exploring them in sequence can get the manpage reader lost.
> 
> Put the cyclictest's SMP-related options:
> 
>        -S, --smp
>        -t, --threads[=NUM]
>        --mainaffinity=CPUSET
>        -a, --affinity[=PROC-SET]
> 
> into their own group.
> 
> Further groupings will be added next.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 46 +++++++++++++++++++------------------
>  1 file changed, 24 insertions(+), 22 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 6ab3b19..7fc0420 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -24,6 +24,10 @@ cyclictest \- High resolution test program
>  .IR wakeup\-usec ]
>  .RB [ \-A\~\c
>  .IR alignment\-usec ]
> +.RB [ \-t\~\c
> +.IR num\-threads ]
> +.RB [ \-\-mainaffinity\~\c
> +.IR proc-set ]
>  .RB [ \-a\~\c
>  .IR proc\-set ]
>  .RB [ \-b\~\c
> @@ -42,14 +46,10 @@ cyclictest \- High resolution test program
>  .IR oscope\-red ]
>  .RB [ \-p\~\c
>  .IR thread\-prio ]
> -.RB [ \-t\~\c
> -.IR num\-threads ]
>  .RB [ \-\-histfile\~\c
>  .IR file\-path ]
>  .RB [ \-\-json\~\c
>  .IR file\-path ]
> -.RB [ \-\-mainaffinity\~\c
> -.IR proc-set ]
>  .RB [ \-\-policy\~\c
>  .IR threads\-sched\-policy ]
>  .RB [ \-\-spike\~\c
> @@ -146,7 +146,24 @@ align thread wakeups to the next full second and apply the optional offset.
>  .B \-A, \-\-align=USEC
>  Align thread wakeups to a specific offset in microseconds
>  .
> -.SS "Other options"
> +.SS "SMP-related options"
> +.
> +.TP
> +.B \\-S, \-\-smp
> +Set options for standard testing on SMP systems. Equivalent to using the
> +options: "\-t \-a" as well keeping any specified priority equal across all
> +threads
> +.
> +.TP
> +.B \-t, \-\-threads[=NUM]
> +Set the number of test threads (default is 1). Create NUM test threads. If
> +NUM is not specified, NUM is set to the number of available CPUs. See \-d,
> +\-i and \-p for further information.
> +.
> +.TP
> +.B \-\-mainaffinity=CPUSET
> +Run the main thread on CPU #N. This only affects the main thread and not
> +the measurement threads
>  .
>  .TP
>  .B \-a, \-\-affinity[=PROC-SET]
> @@ -163,6 +180,8 @@ field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU
>  sets.  * Support for CPU sets requires libnuma version >= 2.  For libnuma
>  v1, PROC-SET, if specified, must be a single CPU number.
>  .
> +.SS "Other options"
> +.
>  .TP
>  .B \-b, \-\-breaktrace=USEC
>  Send break trace command when latency > USEC
> @@ -204,11 +223,6 @@ for automated tests with a given number of test cycles. Cyclictest is
>  stopped once the number of timer intervals has been reached.
>  .
>  .TP
> -.B \-\-mainaffinity=CPUSET
> -Run the main thread on CPU #N. This only affects the main thread and not
> -the measurement threads
> -.
> -.TP
>  .B \-m, \-\-mlockall
>  Lock current and future memory allocations to prevent being paged out
>  .
> @@ -247,12 +261,6 @@ Print a summary only on exit. Useful for automated tests, where only the
>  summary output needs to be captured.
>  .
>  .TP
> -.B \\-S, \-\-smp
> -Set options for standard testing on SMP systems. Equivalent to using the
> -options: "\-t \-a" as well keeping any specified priority equal across all
> -threads
> -.
> -.TP
>  .B \-\-spike=<trigger>
>  record all spikes > trigger
>  .
> @@ -267,12 +275,6 @@ The default is 1024 if not specified.
>  Enable SMI count/detection on processors with SMI count support.
>  .
>  .TP
> -.B \-t, \-\-threads[=NUM]
> -Set the number of test threads (default is 1). Create NUM test threads. If
> -NUM is not specified, NUM is set to the number of available CPUs. See \-d,
> -\-i and \-p for further information.
> -.
> -.TP
>  .B \-\-tracemark
>  write a trace mark when \-b latency is exceeded.
>  .
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 18/28] cyclictest.8: Group memory options

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> The number and breadth of cyclictest's options is huge, and just
> exploring them in sequence can get the manpage reader lost.
> 
> Put the cyclictest's memory-related option:
> 
>        -m, --mlockall
> 
> into its own group.
> 
> Further groupings will be added next.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 7fc0420..a099416 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -180,6 +180,12 @@ field in /proc/cpuinfo.  See numa(3) for more information on specifying CPU
>  sets.  * Support for CPU sets requires libnuma version >= 2.  For libnuma
>  v1, PROC-SET, if specified, must be a single CPU number.
>  .
> +.SS "Memory options"
> +.
> +.TP
> +.B \-m, \-\-mlockall
> +Lock current and future memory allocations to prevent being paged out
> +.
>  .SS "Other options"
>  .
>  .TP
> @@ -223,10 +229,6 @@ for automated tests with a given number of test cycles. Cyclictest is
>  stopped once the number of timer intervals has been reached.
>  .
>  .TP
> -.B \-m, \-\-mlockall
> -Lock current and future memory allocations to prevent being paged out
> -.
> -.TP
>  .B \\-M, \-\-refresh_on_max
>  Delay updating the screen until a new max latency is hit. (useful for
>  running cyclictest on low-bandwidth connections)
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur@redhat.com>

Re: [PATCH v1 19/28] cyclictest.8: Group thread priority options

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> The number and breadth of cyclictest's options is huge, and just
> exploring them in sequence can get the manpage reader lost.
> 
> Put the cyclictest's thread priority options:
> 
>        --policy=NAME
>        -p, --prio=PRIO
>        --priospread
> 
> into their own group.  Adjust the Synopsis accordingly as well.
> 
> Further groupings will be added next.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 25 +++++--------------------
>  1 file changed, 5 insertions(+), 20 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index a099416..90a3e08 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -30,6 +30,11 @@ cyclictest \- High resolution test program
>  .IR proc-set ]
>  .RB [ \-a\~\c
>  .IR proc\-set ]
> +.RB [ \-\-policy\~\c
> +.IR threads\-sched\-policy ]
> +.RB [ \-p\~\c
> +.IR thread\-prio ]
> +.RB [ \-\-priospread ]
>  .RB [ \-b\~\c
>  .IR break\-usec ]
>  .RB [ \-D\~\c
> @@ -44,20 +49,15 @@ cyclictest \- High resolution test program
>  .IR num\-loops ]
>  .RB [ \-o\~\c
>  .IR oscope\-red ]
> -.RB [ \-p\~\c
> -.IR thread\-prio ]
>  .RB [ \-\-histfile\~\c
>  .IR file\-path ]
>  .RB [ \-\-json\~\c
>  .IR file\-path ]
> -.RB [ \-\-policy\~\c
> -.IR threads\-sched\-policy ]
>  .RB [ \-\-spike\~\c
>  .IR trigger\-point-usec ]
>  .RB [ \-\-spike\-nodes\~\c
>  .IR num\-nodes ]
>  .RB [ \-\-dbg_cyclictest ]
> -.RB [ \-\-priospread ]
>  .RB [ \-\-smi ]
>  .RB [ \-\-tracemark ]
>  .YS
> @@ -243,21 +243,6 @@ unit.
>  Oscilloscope mode, reduce verbose output by RED.
>  .
>  .TP
> -.B \-p, \-\-prio=PRIO
> -Set the priority of the first thread. The given priority is set to the
> -first test thread. Each further thread gets a lower priority:
> -Priority(Thread N) = max(Priority(Thread N\-1) \- 1, 0)
> -.
> -.TP
> -.B \-\-policy=NAME
> -set the scheduler policy of the measurement threads where NAME is one of:
> -other, normal, batch, idle, fifo, rr
> -.
> -.TP
> -.B \-\-priospread
> -spread priority levels starting at a specified value
> -.
> -.TP
>  .B \-q, \-\-quiet
>  Print a summary only on exit. Useful for automated tests, where only the
>  summary output needs to be captured.
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 20/28] cyclictest.8: Group tracing options

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> The number and breadth of cyclictest's options is huge, and just
> exploring them in sequence can get the manpage reader lost.
> 
> Put the cyclictest's system-altering options:
> 
>        -b, --breaktrace=USEC
>        --tracemark
> 
> into their own group.  Adjust the Synopsis accordingly as well.
> 
> Further groupings will be added next.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 14 ++++++++------
>  1 file changed, 8 insertions(+), 6 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 90a3e08..964996f 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -37,6 +37,7 @@ cyclictest \- High resolution test program
>  .RB [ \-\-priospread ]
>  .RB [ \-b\~\c
>  .IR break\-usec ]
> +.RB [ \-\-tracemark ]
>  .RB [ \-D\~\c
>  .IR duration\-mhd ]
>  .RB [ \-f\~\c
> @@ -59,7 +60,6 @@ cyclictest \- High resolution test program
>  .IR num\-nodes ]
>  .RB [ \-\-dbg_cyclictest ]
>  .RB [ \-\-smi ]
> -.RB [ \-\-tracemark ]
>  .YS
>  .
>  .SY cyclictest
> @@ -186,13 +186,19 @@ v1, PROC-SET, if specified, must be a single CPU number.
>  .B \-m, \-\-mlockall
>  Lock current and future memory allocations to prevent being paged out
>  .
> -.SS "Other options"
> +.SS "Tracing options"
>  .
>  .TP
>  .B \-b, \-\-breaktrace=USEC
>  Send break trace command when latency > USEC
>  .
>  .TP
> +.B \-\-tracemark
> +write a trace mark when \-b latency is exceeded.
> +.
> +.SS "Other options"
> +.
> +.TP
>  .B \-D, \-\-duration=TIME
>  Specify a length for the test run.
>  .br
> @@ -262,10 +268,6 @@ The default is 1024 if not specified.
>  Enable SMI count/detection on processors with SMI count support.
>  .
>  .TP
> -.B \-\-tracemark
> -write a trace mark when \-b latency is exceeded.
> -.
> -.TP
>  .B \-u, \-\-unbuffered
>  force unbuffered output for live processing
>  .
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 21/28] cyclictest.8: Group test duration options

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> The number and breadth of cyclictest's options is huge, and just
> exploring them in sequence can get the manpage reader lost.
> 
> Put the cyclictest's system-altering options:
> 
>        -D, --duration=TIME
>        -l, --loops=LOOPS
> 
> into their own group.  Adjust the Synopsis accordingly as well.
> 
> Further groupings will be added next.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 20 +++++++++++---------
>  1 file changed, 11 insertions(+), 9 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 964996f..c2c963c 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -40,14 +40,14 @@ cyclictest \- High resolution test program
>  .RB [ \-\-tracemark ]
>  .RB [ \-D\~\c
>  .IR duration\-mhd ]
> +.RB [ \-l\~\c
> +.IR num\-loops ]
>  .RB [ \-f\~\c
>  .IR fifo\-path ]
>  .RB [ \-h\~\c
>  .IR max\-latency\-usec ]
>  .RB [ \-H\~\c
>  .IR max\-latency\-usec ]
> -.RB [ \-l\~\c
> -.IR num\-loops ]
>  .RB [ \-o\~\c
>  .IR oscope\-red ]
>  .RB [ \-\-histfile\~\c
> @@ -196,7 +196,7 @@ Send break trace command when latency > USEC
>  .B \-\-tracemark
>  write a trace mark when \-b latency is exceeded.
>  .
> -.SS "Other options"
> +.SS "Test-duration options"
>  .
>  .TP
>  .B \-D, \-\-duration=TIME
> @@ -205,6 +205,14 @@ Specify a length for the test run.
>  Append 'm', 'h', or 'd' to specify minutes, hours or days.
>  .
>  .TP
> +.B \-l, \-\-loops=LOOPS
> +Set the number of loops. The default is 0 (endless). This option is useful
> +for automated tests with a given number of test cycles. Cyclictest is
> +stopped once the number of timer intervals has been reached.
> +.
> +.SS "Other options"
> +.
> +.TP
>  .B \-F, \-\-fifo=<path>
>  Create a named pipe at path and write stats to it
>  .
> @@ -229,12 +237,6 @@ Dump the latency histogram to <path> instead of stdout.
>  Write final results into FILENAME, JSON formatted.
>  .
>  .TP
> -.B \-l, \-\-loops=LOOPS
> -Set the number of loops. The default is 0 (endless). This option is useful
> -for automated tests with a given number of test cycles. Cyclictest is
> -stopped once the number of timer intervals has been reached.
> -.
> -.TP
>  .B \\-M, \-\-refresh_on_max
>  Delay updating the screen until a new max latency is hit. (useful for
>  running cyclictest on low-bandwidth connections)
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 22/28] cyclictest.8: Group output options

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> The number and breadth of cyclictest's options is huge, and just
> exploring them in sequence can get the manpage reader lost.
> 
> Put the cyclictest's output options:
> 
>        --dbg_cyclictest
>        -o, --oscope=RED
>        -F, --fifo=<path>
>        -h, --histogram=US
>        -H, --histofall=MAXLATENCYINUS
>        --spike=<trigger>
>        --spike-nodes=[num of nodes]
>         --histfile=<path>
>        --json=FILENAME
>        -M, --refresh_on_max
>        -N, --nsecs
>        -q, --quiet
>        -u, --unbuffered
>        -v, --verbose
> 
> into their own group.  Adjust the Synopsis accordingly as well.
> 
> Further groupings will be added next.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 58 +++++++++++++++++++------------------
>  1 file changed, 30 insertions(+), 28 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index c2c963c..ca75884 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -42,23 +42,23 @@ cyclictest \- High resolution test program
>  .IR duration\-mhd ]
>  .RB [ \-l\~\c
>  .IR num\-loops ]
> +.RB [ \-\-dbg_cyclictest ]
> +.RB [ \-o\~\c
> +.IR oscope\-red ]
>  .RB [ \-f\~\c
>  .IR fifo\-path ]
>  .RB [ \-h\~\c
>  .IR max\-latency\-usec ]
>  .RB [ \-H\~\c
>  .IR max\-latency\-usec ]
> -.RB [ \-o\~\c
> -.IR oscope\-red ]
> -.RB [ \-\-histfile\~\c
> -.IR file\-path ]
> -.RB [ \-\-json\~\c
> -.IR file\-path ]
>  .RB [ \-\-spike\~\c
>  .IR trigger\-point-usec ]
>  .RB [ \-\-spike\-nodes\~\c
>  .IR num\-nodes ]
> -.RB [ \-\-dbg_cyclictest ]
> +.RB [ \-\-histfile\~\c
> +.IR file\-path ]
> +.RB [ \-\-json\~\c
> +.IR file\-path ]
>  .RB [ \-\-smi ]
>  .YS
>  .
> @@ -210,7 +210,15 @@ Set the number of loops. The default is 0 (endless). This option is useful
>  for automated tests with a given number of test cycles. Cyclictest is
>  stopped once the number of timer intervals has been reached.
>  .
> -.SS "Other options"
> +.SS "Output options"
> +.
> +.TP
> +.B \-\-dbg_cyclictest
> +Print info userful for debugging cyclictest
> +.
> +.TP
> +.B \-o, \-\-oscope=RED
> +Oscilloscope mode, reduce verbose output by RED.
>  .
>  .TP
>  .B \-F, \-\-fifo=<path>
> @@ -229,6 +237,16 @@ right that contains summary data of all thread histograms. If cyclictest
>  runs a single thread only, the -H option is equivalent to -h.
>  .
>  .TP
> +.B \-\-spike=<trigger>
> +record all spikes > trigger
> +.
> +.TP
> +.B \-\-spike-nodes=[num of nodes]
> +These are the maximum number of spikes we can record.
> +.br
> +The default is 1024 if not specified.
> +.
> +.TP
>  .B \-\-histfile=<path>
>  Dump the latency histogram to <path> instead of stdout.
>  .
> @@ -247,29 +265,11 @@ Show results in nanoseconds instead of microseconds, which is the default
>  unit.
>  .
>  .TP
> -.B \-o, \-\-oscope=RED
> -Oscilloscope mode, reduce verbose output by RED.
> -.
> -.TP
>  .B \-q, \-\-quiet
>  Print a summary only on exit. Useful for automated tests, where only the
>  summary output needs to be captured.
>  .
>  .TP
> -.B \-\-spike=<trigger>
> -record all spikes > trigger
> -.
> -.TP
> -.B \-\-spike-nodes=[num of nodes]
> -These are the maximum number of spikes we can record.
> -.br
> -The default is 1024 if not specified.
> -.
> -.TP
> -.B \\-\-smi
> -Enable SMI count/detection on processors with SMI count support.
> -.
> -.TP
>  .B \-u, \-\-unbuffered
>  force unbuffered output for live processing
>  .
> @@ -280,9 +280,11 @@ statistical information about the latency distribution. The output is sent
>  to stdout. The output format is: "n:c:v", where n is the task number, c is
>  the count, and v is the latency value in microseconds.
>  .
> +.SS "Other options"
> +.
>  .TP
> -.B \-\-dbg_cyclictest
> -Print info userful for debugging cyclictest
> +.B \\-\-smi
> +Enable SMI count/detection on processors with SMI count support.
>  .
>  .SH "See also"
>  .BR numa (3),
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 23/28] cyclictest.8: Group x86 options

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> The number and breadth of cyclictest's options is huge, and just
> exploring them in sequence can get the manpage reader lost.
> 
> Put the cyclictest's x86 options into their own group.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index ca75884..f320f66 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -280,7 +280,7 @@ statistical information about the latency distribution. The output is sent
>  to stdout. The output format is: "n:c:v", where n is the task number, c is
>  the count, and v is the latency value in microseconds.
>  .
> -.SS "Other options"
> +.SS "X86 options"
>  .
>  .TP
>  .B \\-\-smi
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 24/28] cyclictest.8: System options: Deprecate --laptop

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Per 61ba1aa3a0db ("rt-tests: cyclictest: Add --default-system option"),
> explicitly mark the --laptop option as obsolete and recommend using
> --default-system instead.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index f320f66..aff900d 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -92,8 +92,7 @@ cpus.
>  .
>  .TP
>  .B \-\-laptop
> -Save battery when running cyclictest. This will give you poorer realtime
> -results, but will not drain your battery so quickly.
> +Obsolete option.  Please use \-\-default\-system instead.
>  .
>  .SS "Sleep-mechanism clock options"
>  .
> -- 
> 2.49.0
> 
> 
> 
I think this requires a patch to cyclictest as well, but otherwise
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 25/28] cyclictest.8: Options: Expand --default-system description

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Now that --laptop is explicitly obsoleted and --default-system is
> recommended as its replacement, better formulate the latter's help text.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index aff900d..6982234 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -75,9 +75,11 @@ display a usage message and exit.
>  .
>  .TP
>  .B \-\-default\-system
> -Don't attempt to tune the system from cyclictest. Power management is not
> -suppressed. This might give poorer results, but will allow you to discover
> -if you need to tune the system.
> +Stop cyclictest from force-tuning the system. Without this option,
> +cyclictest writes a value of 0 to /dev/cpu_dma_latency, which prevents the
> +CPU from entering deep sleep states.  While such force-tuning might help at
> +showing lower latency numbers, it obscures the fact that the system may
> +require additional tuning.
>  .
>  .TP
>  .B \-\-latency=PM_Q0S
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 25/28] cyclictest.8: Options: Expand --default-system description

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Now that --laptop is explicitly obsoleted and --default-system is
> recommended as its replacement, better formulate the latter's help text.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index aff900d..6982234 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -75,9 +75,11 @@ display a usage message and exit.
>  .
>  .TP
>  .B \-\-default\-system
> -Don't attempt to tune the system from cyclictest. Power management is not
> -suppressed. This might give poorer results, but will allow you to discover
> -if you need to tune the system.
> +Stop cyclictest from force-tuning the system. Without this option,
> +cyclictest writes a value of 0 to /dev/cpu_dma_latency, which prevents the
> +CPU from entering deep sleep states.  While such force-tuning might help at
> +showing lower latency numbers, it obscures the fact that the system may
> +require additional tuning.
>  .
>  .TP
>  .B \-\-latency=PM_Q0S
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 26/28] cyclictest.8: Options: Reference clock_getres(2)

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> The cyclictest's manpage references CLOCK_MONOTONIC and CLOCK_REALTIME
> multiple times without providing a relevant description or reference.
> 
> Reference clock_getres(2) where such clocks are extensively described.
> 
> Pick the Linux version, instead of the POSIX (3p) one, as the former has
> details that are relevant to cyclictest's "--secaligned" implementation;
> i.e., Linux's CLOCK_MONOTONIC starts from 0.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 6982234..12fb9c1 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -100,11 +100,15 @@ Obsolete option.  Please use \-\-default\-system instead.
>  .
>  .TP
>  .B \-c, \-\-clock=CLOCK
> -select clock
> +Select the system clock to be used for calculating the measuring thread's
> +latency. Allowed CLOCK values are:
>  .br
>  0 = CLOCK_MONOTONIC (default)
>  .br
>  1 = CLOCK_REALTIME
> +.br
> +For more information on the Linux implementation of such clocks, check
> +.MR clock_getres 2
>  .
>  .TP
>  .B \-x, \-\-posix_timers
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 27/28] cyclictest.8: Add example invocation

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> Add a cyclictest example invocation, while warning the user that testing
> a realtime system is hardware and workload dependent.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 12fb9c1..16e8190 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -291,6 +291,24 @@ the count, and v is the latency value in microseconds.
>  .B \\-\-smi
>  Enable SMI count/detection on processors with SMI count support.
>  .
> +.SH "Example invocation"
> +.
> +Testing a realtime system is hardware and workload dependent.  With that
> +in mind, below cyclictest example invocation can provide a good start:
> +.PP
> +.nf
> +.B cyclictest
> +   --default-system
> +   --secaligned
> +   --interval=250
> +   --distance=0
> +   --mlockall
> +   --smp
> +   --priority=98
> +   --histogram=1000
> +   --histfile=output.txt
> +.fi
> +
>  .SH "See also"
>  .BR numa (3),
>  .BR numactl (8),
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 28/28] cyclictest.8: Reference rtla-timerlat(1)

[John Kacur]

On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:

> rtla-timerlat should be the official cyclictest replacement at some point.
> Mention it at the "See also" section.
> 
> While at it, use the correct nroff macro for referencing manpages for the
> whole section.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> ---
>  src/cyclictest/cyclictest.8 | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/src/cyclictest/cyclictest.8 b/src/cyclictest/cyclictest.8
> index 16e8190..bbb0b41 100644
> --- a/src/cyclictest/cyclictest.8
> +++ b/src/cyclictest/cyclictest.8
> @@ -308,10 +308,11 @@ in mind, below cyclictest example invocation can provide a good start:
>     --histogram=1000
>     --histfile=output.txt
>  .fi
> -
> +.
>  .SH "See also"
> -.BR numa (3),
> -.BR numactl (8),
> +.MR numa 3 ,
> +.MR numactl 8 ,
> +.MR rtla-timerlat 1
>  .
>  .SH Authors
>  cyclictest was written by Thomas Gleixner <tglx@linuxtronix.de>.
> -- 
> 2.49.0
> 
> 
> 
Signed-off-by: John Kacur <jkacur@redhat.com>

Re: [PATCH v1 02/28] cyclictest.8: Synopsis: Remove -U

[John Kacur]

On Mon, 21 Jul 2025, Ahmed S. Darwish wrote:

> On Mon, 21 Jul 2025, John Kacur wrote:
> >
> > On Fri, 4 Jul 2025, Ahmed S. Darwish wrote:
> >
> > > Commit 7ea837b01d7e ("rt-tests: cyclictest: Remove numa from help")
> > > removed --numa from the manpage but forgot to remove its shorthand, -U.
> > >
> > > Remove it.
> ...
> > > -[\-p " prio " ] [\-t " num " ] [\-D " time "] [\-w] [\-W] [\-y " policy " ] [ \-S | \-U ]"
> > > +[\-p " prio " ] [\-t " num " ] [\-D " time "] [\-w] [\-W] [\-y " policy " ]"
> >
> > But don't remove -S
> >
> 
> Correct; will do.
> 
> Thanks,
> Ahmed
> 
> 
I a branch called manpage
Rather than having to respin every patch, I signed off on the above, so 
send a follow-up patch to correct the above please

John Kacur

Re: [PATCH v1 04/28] cyclictest.8: Synopsis: Remove -y

[Petr Tesarik]

On Mon, 14 Jul 2025 14:20:02 +0200
Sebastian Andrzej Siewior <bigeasy@linutronix.de> wrote:

> On 2025-07-04 15:26:57 [+0200], Ahmed S. Darwish wrote:
> > @@ -41,7 +41,7 @@ in the set in numeric order, in a round\-robin fashion.
> >  .br
> >  The set of processors can be specified as A,B,C, or A-C, or A-B,D-F, and so on*.
> >  The ! character can be used to negate a set.  For example, !B-D means to use all
> > -available CPUs except B through D.  The cpu numbers are the same as shown in the 
> > +available CPUs except B through D.  The cpu numbers are the same as shown in the  
> 
> This looks identical. Is this white space clean up?

Yes, it removes a trailing space. I can understand why it's not a
separate patch of its own, but maybe it should be moved to patch
07/28, which already contains a lot of small cleanups.

Petr T

Re: [PATCH v1 07/28] cyclictest.8: Remove left-over comments

[Petr Tesarik]

On Fri,  4 Jul 2025 15:27:00 +0200
"Ahmed S. Darwish" <darwi@linutronix.de> wrote:

> Simplify the cyclictest manpage source by removing all obsolete comments.
> 
> Per commit 79ad2eca9abe ("COPYING file and cyclictest's man page added"),
> most of such comments are random leftovers from the original template the
> cyclictest's manpage was based on.  Namely:
> 
> (a) Remove emacs markers; modern emacsen do not need them.
> 
> (b) Remove the roff macros description table; they're all already
>     documented at man(7).
> 
> (c) Reference groff_man_style(7).  Per man(7): "man page authors and
>     maintainers who are not already experienced groff users should
>     consult groff_man_style(7)."
> 
> (d) Remove legacy, commented-out, earlier cyclictest descriptions.
> 
> (e) Remove a reference to info pages; cyclictest does not have any.
> 
> (f) Remove an obscure joke about the manpage being written by "The Rise
>     and Fall of a Fooish Bar."

FTR this was not even an obscure joke, it was another invalid left-over
from the template the manpage was based on. You can find references to
Fooish Bar in many other projects that forgot to remove it.

Glad it's gone, nonetheless. Thank you!

Petr T