xeno-test

Langue: en

Version: 2006-04-29 (debian - 07/07/09)

Section: 1 (Commandes utilisateur)

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)