Provided by: rt-tests_0.93-1ubuntu1_amd64 bug

NAME

       cyclictest - High resolution test program

SYNOPSIS

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

OPTIONS

       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-SET]
              Run threads on the set  of  procesors  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.
              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
              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.

       -A, --align=USEC
              Align measurement thread wakeups to a specific offset in microseconds

       -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
                  * CONFIG_CRITICAL_PREEMPT_TIMING=y
                  * CONFIG_CRITICAL_IRQSOFF_TIMING=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 priority--.

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

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

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

       -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-
              mountpoint>/kernel/debug/tracing/available_tracers

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

              n:c:v

              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

       -U, --numa
              Similar  to the above --smp option, this implies the "-t -a -n" options, as well as
              a constant measurement interval, but  also  forces  memory  allocations  using  the
              numa(3)  policy  library.  Thread stacks and data structures are allocated from the
              NUMA node local to the core to which the thread is bound. Requires  the  underlying
              kernel to have NUMA support compiled in.

SEE ALSO

       numactl(8),

AUTHOR

       cyclictest was written by Thomas Gleixner <tglx@linuxtronix.de>.

       This  manual  page was written by Alessio Igor Bogani <abogani@texware.it>, for the Debian
       project (but may be used by others).

                                        december  20, 2007                          CYCLICTEST(8)