Provided by: rt-tests_0.93-1ubuntu1_i386 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)