Man Linux: Main Page and Category List


       cyclictest - High resolution test program


       cyclictest [ -hfmnqrsvMS ] [-a proc ] [-b usec ] [-c clock ] [-d dist ]
       [-h histogram ] [-i intv ] [-l loop ] [-o red ] [-p prio ]  [-t  num  ]
       [-D time] [-w] [-W] [-y policy]


       These  programs  follow  the  usual  GNU command line syntax, with long
       options starting with two dashes (’--’).
       A summary of options is included below.

       -a, --affinity[=PROC]
              Run all  threads  on  procesor  number  PROC.  If  PROC  is  not
              specified, run thread #N on processor #N.

       -b, --breaktrace=USEC
              Send  break  trace  command  when  latency  >  USEC.  This  is a
              debugging option to control the latency tracer in  the  realtime
              preemption  patch.   It is useful to track down unexpected large
              latencies on a system. This option does only work with following
              kernel config options.

                  For kernel < 2.6.24:
                  * CONFIG_PREEMPT_RT=y
                  * CONFIG_WAKEUP_TIMING=y
                  * CONFIG_LATENCY_TRACE=y

                  For kernel >= 2.6.24:
                  * CONFIG_PREEMPT_RT=y
                  * CONFIG_FTRACE
                  * CONFIG_IRQSOFF_TRACER=y
                  * CONFIG_PREEMPT_TRACER=y
                  * CONFIG_SCHED_TRACER=y
                  * CONFIG_WAKEUP_LATENCY_HIST

              kernel  configuration options enabled. The USEC parameter to the
              -b option defines a maximum latency  value,  which  is  compared
              against  the  actual  latencies  of  the test. Once the measured
              latency is higher than the given maximum, the kernel tracer  and
              cyclictest   is   stopped.   The   trace   can   be   read  from
              /proc/latency_trace.  Please  be  aware  that  the  tracer  adds
              significant  overhead  to  the  kernel, so the latencies will be
              much higher than on a kernel with latency tracing disabled.

       -c, --clock=CLOCK
              Selects the clock, which is used:

                  *  0  selects  CLOCK_MONOTONIC,  which  is   the   monotonic
              increasing system time (default).
                  * 1 selects CLOCK_REALTIME, which is the time of day time.

              CLOCK_REALTIME can be set by settimeofday, while CLOCK_MONOTONIC
              can not be modified by the user.  This option has  no  influence
              when the -s option is given.

       -C, --context
              context switch tracing (used with -b)

       -d, --distance=DIST
              Set the distance of thread intervals in microseconds (default is
              500us). When cyclictest is called with the -t  option  and  more
              than one thread is created, then this distance value is added to
              the   interval   of   the   threads:   Interval(thread   N)    =
              Interval(thread N-1) + DIST

       -E, --event
              event tracing (used with -b)

       -f, --ftrace
              Enable  function  tracing using ftrace as tracer. This option is
              available only with -b.

       -h, --histogram=MAXLATENCYINUS
              Dump latency histogram to stdout. US means the max time to be be
              tracked in microseconds. When you use -h option to get histogram
              data, Cyclictest runs many threads with  same  priority  without

       -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

       -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.

       -n, --nanosleep
              Use clock_nanosleep instead of posix  interval  timers.  Setting
              this option runs the tests with clock_nanosleep instead of posix
              interval timers.

       -N, --nsecs
              Show results in nanoseconds instead of  microseconds,  which  is
              the default unit.

       -o, --oscope=RED
              Oscilloscope mode, reduce verbose output by RED.

       -O, --traceopt=TRACING_OPTION
              Used  to  pass tracing options to ftrace tracers. May be invoked
              mutiple times for multiple  trace  options.  For  example  trace
              options look at /sys/kernel/debug/tracing/trace_options

       -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)

       -q, --quiet
              Run the tests quiet and print only a summary on exit. Useful for
              automated tests, where only  the  summary  output  needs  to  be

       -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.

       -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 in combination with -n
              uses the nanosleep syscall and is not restricted to one  thread.

       -T, --tracer=TRACEFUNC
              set the ftrace tracer function. Used with the -b option. Must be
              one  of   the   trace   functions   available   from   <debugfs-

       -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.

       -m, --mlockall
              Lock  current  and  future  memory  allocations to prevent being
              paged out

       -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:


              where n=task number c=count v=latency  value  in  us.  Use  this
              option in combination with -l

       -D, --duration=TIME
              Run  the test for the specified time, which defaults to seconds.
              Append ’m’, ’h’, or ’d’ to specify minutes, hours or days

       -w, --wakeup
              task wakeup tracing (used with -b)

       -W, --wakeuprt
              rt-task wakeup tracing (used with -b)

       -y, --policy=NAME
              set the scheduler policy of the measurement threads  where  NAME
              is one of: other, normal, batch, idle, fifo, rr

       -M, --refresh_on_max
              delay updating the screen until a new max latency is hit (useful
              for running cyclictest on low-bandwidth connections)

       -S, --smp
              Set options for standard testing on SMP systems.  Equivalent  to
              using  the  options:  "-t  -a  -n" as well keeping any specified
              priority equal across all threads


       cyclictest was written by Thomas Gleixner <>.

       This   manual   page   was   written    by    Alessio    Igor    Bogani
       <>,  for  the  Debian  project  (but  may  be used by

                              december  20, 2007