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)