1CYCLICTEST(8) System Manager's Manual CYCLICTEST(8)
2# SPDX-License-Identifier: GPL-2.0-only
6
8 cyclictest - High resolution test program
9
11 cyclictest [ -hfmnqrsvMS ] [-a proc ] [-A align ] [-b usec ] [-c clock
12 ] [-d dist ] [-h histogram ] [-i intv ] [--json filename ]
13 [-l loop ] [-o red ] [-p prio ] [-t num ] [-D time] [-w]
14 [-W] [-y policy ] [ -S | -U ]
15
18 These programs follow the usual GNU command line syntax, with long
19 options starting with two dashes ('--').
20 A summary of options is included below.
21 -a, --affinity[=PROC-SET]
23 Run threads on the set of processors given by PROC-SET. If
24 PROC-SET is not specified, all processors will be used. Threads
25 will be assigned to processors in the set in numeric order, in a
26 round-robin fashion.
27 The set of processors can be specified as A,B,C, or A-C, or A-
28 B,D-F, and so on*. The ! character can be used to negate a set.
29 For example, !B-D means to use all available CPUs except B
30 through D. The cpu numbers are the same as shown in the
31 processor field in /proc/cpuinfo. See numa(3) for more
32 information on specifying CPU sets. * Support for CPU sets
33 requires libnuma version >= 2. For libnuma v1, PROC-SET, if
34 specified, must be a single CPU number.
35 -A, --align=USEC
37 Align thread wakeups to a specific offset in microseconds
38 -b, --breaktrace=USEC
40 Send break trace command when latency > USEC
41 -c, --clock=CLOCK
43 select clock
44 0 = CLOCK_MONOTONIC (default)
45 1 = CLOCK_REALTIME
46 --default-system
48 Don't attempt to tune the system from cyclictest. Power
49 management is not suppressed. This might give poorer results,
50 but will allow you to discover if you need to tune the system.
51 -d, --distance=DIST
53 Distance of thread intervals in us, default = 500
54 -D, --duration=TIME
56 Specify a length for the test run.
57 Append 'm', 'h', or 'd' to specify minutes, hours or days.
58 -F, --fifo=<path>
60 Create a named pipe at path and write stats to it
61 -h, --histogram=US
63 Dump latency histogram to stdout after the run. US is the max
64 latency time to be be tracked in microseconds. This option runs
65 all threads at the same priority.
66 -H, --histofall=MAXLATENCYINUS
68 Same as -h except that an additional histogram column is
69 displayed at the right that contains summary data of all thread
70 histograms. If cyclictest runs a single thread only, the -H
71 option is equivalent to -h.
72 --histfile=<path>
74 Dump the latency histogram to <path> instead of stdout.
75 -i, --interval=INTV
77 Set the base interval of the thread(s) in microseconds (default
78 is 1000us). This sets the interval of the first thread. See also
79 -d.
80 --json=FILENAME
82 Write final results into FILENAME, JSON formatted.
83 --laptop
85 Save battery when running cyclictest. This will give you poorer
86 realtime results, but will not drain your battery so quickly.
87 --latency=PM_Q0S
89 power management latency target value. This value is written to
90 /dev/cpu_dma_latency and affects c-states. The default is 0
91 -l, --loops=LOOPS
93 Set the number of loops. The default is 0 (endless). This option
94 is useful for automated tests with a given number of test
95 cycles. Cyclictest is stopped once the number of timer intervals
96 has been reached.
97 --mainaffinity=CPUSET
99 Run the main thread on CPU #N. This only affects the main thread
100 and not the measurement threads
101 -m, --mlockall
103 Lock current and future memory allocations to prevent being
104 paged out
105 -M, --refresh_on_max
107 Delay updating the screen until a new max latency is hit.
108 (useful for running cyclictest on low-bandwidth connections)
109 -N, --nsecs
111 Show results in nanoseconds instead of microseconds, which is
112 the default unit.
113 -o, --oscope=RED
115 Oscilloscope mode, reduce verbose output by RED.
116 -p, --prio=PRIO
118 Set the priority of the first thread. The given priority is set
119 to the first test thread. Each further thread gets a lower
120 priority: Priority(Thread N) = max(Priority(Thread N-1) - 1, 0)
121 --policy=NAME
123 set the scheduler policy of the measurement threads where NAME
124 is one of: other, normal, batch, idle, fifo, rr
125 --priospread
127 spread priority levels starting at a specified value
128 -q, --quiet
130 Print a summary only on exit. Useful for automated tests, where
131 only the summary output needs to be captured.
132 -r, --relative
134 Use relative timers instead of absolute. The default behaviour
135 of the tests is to use absolute timers. This option is there for
136 completeness and should not be used for reproducible tests.
137 -R, --resolution
139 Check clock resolution, calling clock_gettime() many times. List
140 of lock_gettime() values will be reported with -X
141 --secaligned [USEC]
143 align thread wakeups to the next full second and apply the
144 optional offset.
145 -s, --system
147 Use sys_nanosleep and sys_setitimer instead of posix timers.
148 Note, that -s can only be used with one thread because itimers
149 are per process and not per thread. -s uses the nanosleep
150 syscall and is not restricted to one thread.
151 -S, --smp
153 Set options for standard testing on SMP systems. Equivalent to
154 using the options: "-t -a" as well keeping any specified
155 priority equal across all threads
156 --spike=<trigger>
158 record all spikes > trigger
159 --spike-nodes=[num of nodes]
161 These are the maximum number of spikes we can record.
162 The default is 1024 if not specified.
163 --smi Enable SMI count/detection on processors with SMI count support.
165 -t, --threads[=NUM]
167 Set the number of test threads (default is 1). Create NUM test
168 threads. If NUM is not specified, NUM is set to the number of
169 available CPUs. See -d, -i and -p for further information.
170 --tracemark
172 write a trace mark when -b latency is exceeded.
173 -u, --unbuffered
175 force unbuffered output for live processing
176 -v, --verbose
178 Output values on stdout for statistics. This option is used to
179 gather statistical information about the latency distribution.
180 The output is sent to stdout. The output format is:
181 n:c:v
183 where n=task number c=count v=latency value in us.
185 --dbg_cyclictest
187 Print info userful for debugging cyclictest
188 -x, --posix_timers
190 Use POSIX timers instead of clock_nanosleep.
191
194 numa(3), numactl(8),
195
197 cyclictest was written by Thomas Gleixner <tglx@linuxtronix.de>.
198 This manual page was written by Alessio Igor Bogani
200 <abogani@texware.it>, for the Debian project (but may be used by
201 others).
202 Updated by John Kacur <jkacur@redhat.com>
203 April 22, 2016 CYCLICTEST(8)