Provided by: xenomai-runtime_2.5.5.2-1ubuntu2_amd64 bug

NAME

       xeno-test - Tests and measures the performance of a Xenomai installation

SYNOPSIS

       xeno-test [-v] [-w workloads] [-d device] [-W command] [-p command] [-L] [-N prefix] [-m |
       -M email | -U url] [-s] [-l samples] [-h [-H categories]  [-B  granularity]]  [-T  seconds
       [-q]] [--] [args] ...

DESCRIPTION

       xeno-test  measures the performance of Xenomai, by executing Xenomai's latency tests while
       generating a high workload on the  system.   The  default  command  that  is  executed  to
       simulate workload (if no alternate command is specified with a -W command option) is:

              dd if=/dev/zero of=/dev/null

       The  executed  latency tests periodically (every second) sample and print out the minimum,
       average, and maximum  latency.   However,  by  default,  if  no  option  is  specified  to
       xeno-test,  those  tests  are  executed with the -q option (see below), which disables the
       printing of samples.  If the -q option is not specified, samples  are  printed  in  groups
       separated  by  headers.   In  addition,  latency  print  statistics for all samples before
       terminating, and can also optionally print statistics for every group of samples (see  the
       -s option), and distribution histograms (see the -h option).

OPTIONS

       If an invalid option is specified, xeno-test prints out an usage help message and exits.

       You  are  strongly  encouraged  to use the -m option, to anonymously help the Xenomai team
       collecting statistics about Xenomai's performance on the widest range of systems.

       The following options are specific to xeno-test:

       -v     Produces more verbose tests results.

       -w workloads
              The number of workload commands to execute simultaneously. By default, this  number
              is 1.

       -d device
              If the default workload command is to be executed, sets the input device to be read
              by dd to device instead of /dev/zero.  For instance, specifying  the  device  of  a
              real hard-drive (e.g. /dev/hda1) is useful for generating interrupts with I/O.  The
              specified device must be mounted, and cannot be an NFS mount.

       -W command
              Executes the specified command to generate workload,  instead  of  the  default  dd
              if=/dev/zero  of=/dev/null command.  If the command requires arguments, the command
              and its arguments must be quoted and passed  as  a  single  command  argument.   In
              addition  to such static arguments, the args optional arguments passed to xeno-test
              are appended to command to execute it.

       -p command
              Makes xeno-test execute the specified command before  and  after  all  the  latency
              executions.

       -L     Activates  logging  of  the  tests  results.   The log file is created in the /tmp/
              directory, and is named test-kernel_release-timestamp, where kernel_release is  the
              release  number  of the running Linux kernel (as determined by executing uname -r),
              and timestamp is a  textual  representation  of  the  current  date  and  time  (as
              determined by executing date) used to reduce the risk of file name collisions.  The
              log file name can  be  customized  by  using  the  -N  option  instead  of,  or  in
              conjunction with this option.

       -N prefix
              Activates  logging  of  the  tests  results.   If  the -L option is also specified,
              prepends  prefix  to  the  log  file   name,   hence   the   log   file   name   is
              prefixtest-kernel_release-timestamp.   If  the  -L option is not specified, the log
              file name is prefix-timestamp.  This option is useful to create the log file  in  a
              different  directory  than  /tmp/  (default  prefix  when  using the -L option), by
              specifying a prefix which starts with an absolute directory  path  or  a  directory
              path relative to the working directory.

       -m     Sends    the    tests    results    to    the    Xenomai   team's   email   address
              (xenotest.output@gmail.com),  to  help  collecting   statistics   about   Xenomai's
              performance.  The email is sent using the system's mail command. The email's sender
              address is xenotest.sender@xenomai.org,  and  the  email's  subject  is  "xeno-test
              results".

       -M email
              Similar  to  the  -m  option,  but  sends  the tests results to the specified email
              address instead of the default one.

       -U url Uploads the tests results to the specified URL.  If there is no file  part  in  the
              specified  url,  and  the  -L  or -N option is also specified, the log file name is
              appended to it to form the URL used for upload.  The tests results are  transmitted
              as  the  contents of an HTTP request using the PUT method.  The upload is performed
              using the curl command.  This option fails silently (i.e. the tests results are not
              sent) if curl is not available.

       The  following  options  are  directly  passed  to  the  latency  test command executed by
       xeno-test.  If no such options are specified, the -s -T  120  -q  options  are  implicitly
       passed  by default by xeno-test.  Any user-specified set of options overrides this default
       set of options.

       -s     Displays statistics (minimum, average, and maximum latencies) for  every  group  of
              samples.   The  number  of  samples  in  each group is determined by the -l samples
              option (default is 21 samples).

       -l samples
              The number of samples in every group of samples.  This  number  is  the  number  of
              sample lines displayed between every header line, and is the number of samples used
              to calculate intermediate statistics if the -s option is  specified.   By  default,
              this number is 21.

       -h     Displays  histograms  of  all  sampled  data,  at  the end of tests.  The number of
              categories - or value intervals -  of  each  histogram  is  determined  by  the  -H
              categories option (default is 100 categories).  The granularity - or bucket size -,
              used to  separate  latency  samples  into  categories,  is  determined  by  the  -B
              granularity option (default is 1000 ns).  This option implies -s.

       -H categories
              The  number of categories - or value intervals - of histograms to display if the -h
              option is specified.  By default, this number is 100.

       -B granularity
              The granularity - or bucket size -, in nanoseconds, used  to  discriminate  between
              the  categories of latency samples in histograms (to be printed if the -h option is
              specified).  By default, this number is 1000 ns.

       -T seconds
              The period, in seconds, during which latency tests are executed.  If that option is
              not  specified,  the  tests execute infinitely until the user types CONTROL-C (i.e.
              sends a SIGINT signal to them).

       -q     Disables the printing of samples and sample group statistics (hence this  overrides
              the  -s  option), and only global statistics and histograms are being printed.  The
              default behaviour, if this option is not specified,  is  to  display  every  sample
              (measured  minimum,  average,  and  maximum  latency)  and  optionally sample group
              statistics (if -s is specified).

       --     Indicates the end of options.  This must be specified before args arguments if  the
              first argument starts with -, so that it is not considered as an option.

RETURN CODES

       0      The tests executed successfully.

       1      An invalid option was specified.

KNOWN BUGS

       latency  allows  to  specify  the  -H categories and -B granularity options without the -h
       option, in which case they have no effect.

       It is possible to specify the period between samples  (default  is  1  second)  using  the
       latency  command's  -p  option,  but  this option cannot be passed through xeno-test (this
       conflicts with xeno-test's own -p option).

       The workload generation task (e.g., the default dd if=/dev/zero of=/dev/null command)  may
       terminate  before  the  tests are finished, which may produce inaccurate tests results. It
       may be necessary to specify an alternate command which lasts longer, using the -W  command
       option.

       Workload processes may not be properly killed when xeno-test terminate.

SEE ALSO

       xeno-load(1), uname(1)