[Xenomai-core] xeno-test manpage patch

[Xenomai-core] xeno-test manpage patch

[Romain Lenglet]

[-- Attachment #1: Type: text/plain, Size: 86 bytes --]

Added documentation for the new -U option, and did some cleanups.

-- 
Romain LENGLET

[-- Attachment #2: xeno-test-docupdateagain_2006-04-25.patch --]
[-- Type: text/x-diff, Size: 8886 bytes --]

--- xenomai/ChangeLog	2006-04-25 11:23:20.032161304 +0900
+++ xenomai-xeno-test-docupdate/ChangeLog	2006-04-25 14:56:27.087233456 +0900
@@ -1,3 +1,12 @@
+2006-04-25  Romain Lenglet <rlenglet@domain.hid>
+
+	* doc/man/xeno-test.man.in: Add documentation for the new -U option.
+	Correct the synopsis to reflect the depencency between -m, -M, -U and
+	-L. Remove references to long removed klatency test command.
+
+	* scripts/xeno-test.in: Typo: "UEL"->"URL". Remove documentation for
+	-u from printed usage until it is actually implemented.
+
 2006-04-24  Gilles Chanteperdrix  <gilles.chanteperdrix@xenomai.org>
 
 	* ksrc/skins/posix/syscall.c (__shm_open, __mmap_epilogue): Handle
--- xenomai/doc/man/xeno-test.man.in	2006-04-25 11:23:19.790198088 +0900
+++ xenomai-xeno-test-docupdate/doc/man/xeno-test.man.in	2006-04-25 14:58:55.723637288 +0900
@@ -9,23 +9,23 @@
 .\" Xenomai distribution.
 .\"
 .pc
-.TH XENO-TEST 1 "2006-04-21" "@PACKAGE_VERSION@" "Xenomai"
+.TH XENO-TEST 1 "2006-04-25" "@PACKAGE_VERSION@" "Xenomai"
 .SH NAME
 xeno\-test \- Tests and measures the performance of a Xenomai installation
 .SH SYNOPSIS
-\fBxeno\-test\fP [\fB\-v\fP] [\fB\-w\fP \fIworkloads\fP] [\fB\-d\fP \fIdevice\fP] [\fB\-W\fP \fIcommand\fP] [\fB\-p\fP \fIcommand\fP] [\fB\-L\fP [\fB\-N\fP \fIprefix\fP]] [\fB\-m\fP | \fB\-M\fP \fIemail\fP] [\fB\-s\fP] [\fB\-l\fP \fIsamples\fP] [\fB\-h\fP [\fB\-H\fP \fIcategories\fP] [\fB\-B\fP \fIgranularity\fP]] [\fB\-T\fP \fIseconds\fP [\fB\-q\fP]] [\fB\-\-\fP] [\fIargs\fP] ...
+\fBxeno\-test\fP [\fB\-v\fP] [\fB\-w\fP \fIworkloads\fP] [\fB\-d\fP \fIdevice\fP] [\fB\-W\fP \fIcommand\fP] [\fB\-p\fP \fIcommand\fP] [\fB\-L\fP [\fB\-N\fP \fIprefix\fP] [\fB\-m\fP | \fB\-M\fP \fIemail\fP | \fB\-U\fP \fIurl\fP]] [\fB\-s\fP] [\fB\-l\fP \fIsamples\fP] [\fB\-h\fP [\fB\-H\fP \fIcategories\fP] [\fB\-B\fP \fIgranularity\fP]] [\fB\-T\fP \fIseconds\fP [\fB\-q\fP]] [\fB\-\-\fP] [\fIargs\fP] ...
 .SH DESCRIPTION
-\fBxeno\-test\fP measures the performance of Xenomai, by executing Xenomai's \fBlatency\fP and \fBklatency\fP tests while generating a high workload on the system.
+\fBxeno\-test\fP measures the performance of Xenomai, by executing Xenomai's \fBlatency\fP 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 \fB-W\fP \fIcommand\fP option) is:
 .RS
 .sp
 .B dd if=/dev/zero of=/dev/null
 .sp
 .RE
-The executed \fBlatency\fP and \fBklatency\fP tests periodically (every second) sample and print out the minimum, average, and maximum latency.
+The executed \fBlatency\fP tests periodically (every second) sample and print out the minimum, average, and maximum latency.
 However, by default, if no option is specified to \fBxeno\-test\fP, those tests are executed with the \fB\-q\fP option (see below), which disables the printing of samples.
 If the \fB\-q\fP option is not specified, samples are printed in groups separated by headers.
-In addition, \fBlatency\fP and \fBklatency\fP print statistics for all samples before terminating, and can also optionally print statistics for every group of samples (see the \fB\-s\fP option), and distribution histograms (see the \fB\-h\fP option).
+In addition, \fBlatency\fP print statistics for all samples before terminating, and can also optionally print statistics for every group of samples (see the \fB\-s\fP option), and distribution histograms (see the \fB\-h\fP option).
 
 If an invalid option is specified, \fBxeno\-test\fP prints out an usage help message and exits.
 
@@ -52,22 +52,28 @@
 In addition to such static arguments, the \fIargs\fP optional arguments passed to \fBxeno\-test\fP are appended to \fIcommand\fP to execute it. 
 .TP
 \fB\-p\fP \fIcommand\fP
-Makes \fBxeno\-test\fP execute the specified \fIcommand\fP before, between and after the \fBlatency\fP and \fBklatency\fP tests.
+Makes \fBxeno\-test\fP execute the specified \fIcommand\fP before, between and after the \fBlatency\fP executions. 
 .TP
 \fB\-L\fP
-Activates logging. The log file is created in the current directory, and is named \fBtest\-\fP\fIkernel_release\fP, where \fIkernel_release\fP is the release number of the running Linux kernel (as determined by executing \fBuname \-r\fP).
+Activates logging of the tests results. The log file is created in the \fB/tmp/\fP directory, and is named \fBtest\-\fP\fIkernel_release\fP, where \fIkernel_release\fP is the release number of the running Linux kernel (as determined by executing \fBuname \-r\fP).
 .TP
 \fB\-N\fP \fIprefix\fP
 Prepends \fIprefix\fP\fB\-\fP to the log file name, hence if the \fB\-L\fP option is also specified the log file name is \fIprefix\fP\fB\-test\-\fP\fIkernel_release\fP.
-This option is useful to create the log file in a different directory, by specifying a \fIprefix\fP that starts with the relative path to that directory.
+This option is useful to create the log file in a different directory than \fB/tmp/\fP, by specifying a \fIprefix\fP that starts with the relative path to that directory.
 .TP
 \fB\-m\fP
-Sends the results of the tests to the Xenomai team's email address, to help collecting statistics about Xenomai's performance. The email is sent using the system's mail(1) command.
+Sends the tests results log file to the Xenomai team's email address (\fBxenotest.output@domain.hid), to help collecting statistics about Xenomai's performance. The email is sent using the system's mail(1) command. The email's sender address is \fBxenotest.sender@domain.hid, and the email's subject is \fB"xeno-test results"\fP.
 .TP
 \fB\-M\fP \fIemail\fP
-Sends the results of the tests to the specified email address. The email is sent using the system's mail(1) command.
+Similar to the \fB\-m\fP option, but sends the tests results log file to the specified email address instead of the default one.
+.TP
+\fB\-U\fP \fIurl\fP
+Uploads the tests results log file to the specified URL.
+If there is no file part in the specified \fIurl\fP, the log file name is appended to it to form the URL used for upload.
+The file is transmitted as an attachment, with the log file name as a filename, in an HTTP POST request of MIME type multi-part/form-data (like with a HTML-form-based file uploads).
+The upload is performed using the curl(1) command.
 .PP
-The following options are directly passed to the \fBlatency\fP and \fBklatency\fP test commands executed by \fBxeno\-test\fP.
+The following options are directly passed to the \fBlatency\fP test command executed by \fBxeno\-test\fP.
 If no such options are specified, the \fB\-s \-T 10 \-q\fP options are passed by default by \fBxeno\-test\fP.
 .TP
 \fB\-s\fP
@@ -93,7 +99,7 @@
 By default, this number is \fB1000\fP ns.
 .TP
 \fB\-T\fP \fIseconds\fP
-The period, in seconds, during which \fBlatency\fP and \fBklatency\fP tests are respectively executed.
+The period, in seconds, during which \fBlatency\fP tests are executed.
 If that option is not specified, the tests execute infinitely until the user types \fBCONTROL-C\fP (i.e. sends a SIGINT signal to them).
 .TP
 \fB\-q\fP
@@ -114,14 +120,17 @@
 .SH KNOWN BUGS
 \fBxeno\-test\fP allows to specify the \fB\-N\fP \fIlogprefix\fP option without the \fB\-L\fP option, in which case the log file name is: \fIlogprefix\fP\fB\-\fP.
 
-\fBlatency\fP and \fBklatency\fP allow to specify the \fB\-H\fP \fIcategories\fP and \fB\-B\fP \fIgranularity\fP options without the \fB\-h\fP option, in which case they have no effect.
+\fBlatency\fP allows to specify the \fB\-H\fP \fIcategories\fP and \fB\-B\fP \fIgranularity\fP options without the \fB\-h\fP option, in which case they have no effect.
 
-It is not possible to specify the period between samples (default is \fB1 second\fP) since this is not configurable for \fBklatency\fP, although this may be configured for \fBlatency\fP through this command's \fB\-p\fP option.
+It is possible to specify the period between samples (default is \fB1 second\fP) using the \fBlatency\fP command's \fB\-p\fP option, but this option cannot be passed through \fBxeno-test\fP.
 .SH "SEE ALSO"
 .BR xeno\-load (1),
 .BR uname (1)
 .SH HISTORY
 .TP
+2006-04-25
+Updated to document the new -U option. Removed references to the klatency command. Modified the synopsis to reflect the dependency of -m, -M and -U options on the -L option.
+.TP
 2006-04-21
 Updated to document the new -v option.
 .TP
--- xenomai/scripts/xeno-test.in	2006-04-25 11:23:17.825496768 +0900
+++ xenomai-xeno-test-docupdate/scripts/xeno-test.in	2006-04-25 14:57:42.056836344 +0900
@@ -20,8 +20,7 @@
   -v		verbose
   -M <email>	sends output to given addr
   -m		sends output to xenotest.output@domain.hid
-  -U <url>	uploads output to given UEL
-  -u		uploads output to (TBD)
+  -U <url>	uploads output to given URL
 	
   # following options are passed thru to latency
   -s	print statistics of sampled data (default on)

Re: [Xenomai-core] xeno-test manpage patch

[Jim Cromie]

Romain Lenglet wrote:
> Added documentation for the new -U option, and did some cleanups.
>   
thanks

I should have noted, this option isnt yet tested
- I dont at this point have a server to test against.
At some point I can -U <mylaptop> , just need some tuits.
(not that this changes anything - even if the script is broken,
the feature is still workable)

Re: [Xenomai-core] xeno-test manpage patch

[Jim Cromie]

Romain Lenglet wrote:
> Added documentation for the new -U option, and did some cleanups.
>   

FYI,

a few *tiny* issues.

-d   eg: /dev/hda1 might be better than /dev/hda/,  and drop trailing slash.

-m, -M.    log-file not required.

-N   path can be /absolute too, not just ../relative

-p 'cmd'   no longer run between latencies, just before & after

pass-thru:

 -s -T 10 -q    the 10 is now 120.

more subtly - your intro doesnt express the defaulting behavior that 
this section does describe.
any pass-thru provided with turn off those defaults, so if you just use 
-h, the test will output lines
each second, and never finish, so you dont get histogram (IIRC - you may 
get it from ^C handler).
Im not at all sure its worth touching, and I should probably change the 
defaults to add histogram,
and drop quiet.

-h implies -s   (its just easier that way)

--  needed by testsuite/*/run scripts, not by xeno-test.  I dont recall 
every using it.

BUGS

-N   name is timestamped, giving uniqueness.  This is a caveat, not a bug

-p   oops.   Im open to suggestions whether this is worth fixing.

(workload mgmt)

   workload tasks arent always (ever?) restarted once they finish,
so a real /dev/hda1 workload may end before your test does, causing 
non-uniform &
unexpected load variations.

workloads arent always killed if test is interrupted.


thanks,
jimc

Re: [Xenomai-core] xeno-test manpage patch

[Romain Lenglet]

[-- Attachment #1: Type: text/plain, Size: 2432 bytes --]

Hi,

Here is a patch for the manpages.


Jim Cromie wrote:
> Romain Lenglet wrote:
> > Added documentation for the new -U option, and did some
> > cleanups.
>
> FYI,
>
> a few *tiny* issues.
>
> -d   eg: /dev/hda1 might be better than /dev/hda/,  and drop
> trailing slash.
>
> -m, -M.    log-file not required.
>
> -N   path can be /absolute too, not just ../relative
>
> -p 'cmd'   no longer run between latencies, just before &
> after
>
> pass-thru:
>
>  -s -T 10 -q    the 10 is now 120.

Done.

> more subtly - your intro doesnt express the defaulting
> behavior that this section does describe.
> any pass-thru provided with turn off those defaults, so if you
> just use -h, the test will output lines
> each second, and never finish, so you dont get histogram (IIRC
> - you may get it from ^C handler).
> Im not at all sure its worth touching, and I should probably
> change the defaults to add histogram,
> and drop quiet.

Added warning line:
"Any user-specified set of options overrides this default set of 
options."

> -h implies -s   (its just easier that way)

Done.

> --  needed by testsuite/*/run scripts, not by xeno-test.  I
> dont recall every using it.

xeno-test uses getopts to parse options, and getopts parses -- to 
identify the end of options, e.g. if you run:
xeno-test -s -- -v
-v is not recognized as an option.

> BUGS
>
> -N   name is timestamped, giving uniqueness.  This is a
> caveat, not a bug

No, it is a feature. I added it into the documentation of -L 
and -N.
By the way, I suggest that you use a timestamp in the RFC 3339 
format (a subset of ISO 8601):
date "+%Y-%m-%d %H:%M:%S%:z"
or, assuming date is GNU date:
date --rfc-3339=seconds

> -p   oops.   Im open to suggestions whether this is worth
> fixing.
>
> (workload mgmt)
>
>    workload tasks arent always (ever?) restarted once they
> finish, so a real /dev/hda1 workload may end before your test
> does, causing non-uniform &
> unexpected load variations.
>
> workloads arent always killed if test is interrupted.

Added into the bugs section.



Now, it is my turn to make some remarks on xeno-test... ;)

1-
Option "-u" is in the list of options given to getopts: you 
should remove it for now.

2-
I don't know why there is a sort of option "-n" in the case:
        n)
            # accept note (from the outer process)
            notes=$OPTARG ;;
Those three lines should be removed: this is dead code.

-- 
Romain LENGLET

[-- Attachment #2: xeno-test-doc_2006-04-29.patch --]
[-- Type: text/x-diff, Size: 14526 bytes --]

--- xenomai/ChangeLog	2006-04-29 15:40:09.297135152 +0900
+++ xenomai-yetanotherdocupdate/ChangeLog	2006-04-29 17:37:21.349100760 +0900
@@ -1,3 +1,16 @@
+2006-04-29  Romain Lenglet <rlenglet@domain.hid>
+
+	* doc/man/xeno-test.man.in: Corrections about options: -d, -L, -N, -p.
+	Removed documented dependency between -m and -M, and -L or -N.
+	Removed History section: redundant with Xenomai's ChangeLog.
+	Modified documented set of default options passed to latency, to
+	reflect new value passed in -T option.
+	Other cleanups.
+
+	* doc/man/{runinfo.man.in,xeno-config.man.in,xeno-info.man.in,
+	xeno-load.man.in}: Removed History sections: redundant with Xenomai's
+	ChangeLog.
+
 2006-04-27  Dmitry Adamushko  <dmitry.adamushko@domain.hid>
 
 	* ksrc/skins/native/intr.c (rt_intr_delete):
--- xenomai/doc/man/runinfo.man.in	2006-03-28 14:12:36.105330472 +0900
+++ xenomai-yetanotherdocupdate/doc/man/runinfo.man.in	2006-04-29 17:35:52.185655664 +0900
@@ -2,7 +2,7 @@
 .\" ** The above line should force tbl to be a preprocessor **
 .\" Man page for runinfo
 .\"
-.\" Copyright (C) 2005 Romain Lenglet <rlenglet@domain.hid>
+.\" Copyright (C) 2005, 2006 Romain Lenglet <rlenglet@domain.hid>
 .\"
 .\" You may distribute under the terms of the GNU General Public
 .\" License as specified in the file COPYING that comes with the
@@ -148,8 +148,3 @@
 .BR insmod (8),
 .BR modprobe (8),
 .BR rmmod (8)
-.SH HISTORY
-.TP
-2005-10-18
-Written by Romain Lenglet <rlenglet@domain.hid>
-
--- xenomai/doc/man/xeno-config.man.in	2006-03-28 14:12:36.110329712 +0900
+++ xenomai-yetanotherdocupdate/doc/man/xeno-config.man.in	2006-04-29 17:35:59.321570840 +0900
@@ -2,7 +2,7 @@
 .\" ** The above line should force tbl to be a preprocessor **
 .\" Man page for xeno-config
 .\"
-.\" Copyright (C) 2005 Romain Lenglet <rlenglet@domain.hid>
+.\" Copyright (C) 2005, 2006 Romain Lenglet <rlenglet@domain.hid>
 .\"
 .\" You may distribute under the terms of the GNU General Public
 .\" License as specified in the file COPYING that comes with the
@@ -92,10 +92,3 @@
 .B \-\-posix\-ldflags
 option has been given but Posix support is not available in Xenomai;
 or an invalid argument has been given on the command-line.
-.SH HISTORY
-.TP
-2006-03-27
-Updated to match latest version of xeno-config.
-.TP
-2005-10-18
-Written by Romain Lenglet <rlenglet@domain.hid>
--- xenomai/doc/man/xeno-info.man.in	2006-03-28 14:12:36.107330168 +0900
+++ xenomai-yetanotherdocupdate/doc/man/xeno-info.man.in	2006-04-29 17:35:16.055148336 +0900
@@ -2,7 +2,7 @@
 .\" ** The above line should force tbl to be a preprocessor **
 .\" Man page for xeno-info
 .\"
-.\" Copyright (C) 2005 Romain Lenglet <rlenglet@domain.hid>
+.\" Copyright (C) 2005, 2006 Romain Lenglet <rlenglet@domain.hid>
 .\"
 .\" You may distribute under the terms of the GNU General Public
 .\" License as specified in the file COPYING that comes with the
@@ -18,8 +18,3 @@
 \fBxeno-info\fP outputs information about the release and version of the currently running Linux kernel, the versions of installed kernel-related tools such as compilation utitilies (gcc, make, ...) and filesystem utilities (mount, e2fsprogs, ...), and the names of currently loaded kernel modules.
 
 It is useful to include the output of the \fBxeno-info\fP command in any bug report to the Xenomai project.
-
-.SH HISTORY
-.TP
-2005-10-19
-Written by Romain Lenglet <rlenglet@domain.hid>
--- xenomai/doc/man/xeno-load.man.in	2006-03-28 14:12:36.108330016 +0900
+++ xenomai-yetanotherdocupdate/doc/man/xeno-load.man.in	2006-04-29 17:35:36.768999352 +0900
@@ -2,7 +2,7 @@
 .\" ** The above line should force tbl to be a preprocessor **
 .\" Man page for xeno-load
 .\"
-.\" Copyright (C) 2005 Romain Lenglet <rlenglet@domain.hid>
+.\" Copyright (C) 2005, 2006 Romain Lenglet <rlenglet@domain.hid>
 .\"
 .\" You may distribute under the terms of the GNU General Public
 .\" License as specified in the file COPYING that comes with the
@@ -59,7 +59,3 @@
 .SH "SEE ALSO"
 .BR runinfo (5),
 .BR sudo (8)
-.SH HISTORY
-.TP
-2005-10-18
-Written by Romain Lenglet <rlenglet@domain.hid>
--- xenomai/doc/man/xeno-test.man.in	2006-04-27 13:03:33.141968792 +0900
+++ xenomai-yetanotherdocupdate/doc/man/xeno-test.man.in	2006-04-29 17:56:57.771257408 +0900
@@ -2,18 +2,18 @@
 .\" ** The above line should force tbl to be a preprocessor **
 .\" Man page for xeno-test
 .\"
-.\" Copyright (C) 2005 Romain Lenglet <rlenglet@domain.hid>
+.\" Copyright (C) 2005, 2006 Romain Lenglet <rlenglet@domain.hid>
 .\"
 .\" You may distribute under the terms of the GNU General Public
 .\" License as specified in the file COPYING that comes with the
 .\" Xenomai distribution.
 .\"
 .pc
-.TH XENO-TEST 1 "2006-04-25" "@PACKAGE_VERSION@" "Xenomai"
+.TH XENO-TEST 1 "2006-04-29" "@PACKAGE_VERSION@" "Xenomai"
 .SH NAME
 xeno\-test \- Tests and measures the performance of a Xenomai installation
 .SH SYNOPSIS
-\fBxeno\-test\fP [\fB\-v\fP] [\fB\-w\fP \fIworkloads\fP] [\fB\-d\fP \fIdevice\fP] [\fB\-W\fP \fIcommand\fP] [\fB\-p\fP \fIcommand\fP] [\fB\-L\fP [\fB\-N\fP \fIprefix\fP] [\fB\-m\fP | \fB\-M\fP \fIemail\fP | \fB\-U\fP \fIurl\fP]] [\fB\-s\fP] [\fB\-l\fP \fIsamples\fP] [\fB\-h\fP [\fB\-H\fP \fIcategories\fP] [\fB\-B\fP \fIgranularity\fP]] [\fB\-T\fP \fIseconds\fP [\fB\-q\fP]] [\fB\-\-\fP] [\fIargs\fP] ...
+\fBxeno\-test\fP [\fB\-v\fP] [\fB\-w\fP \fIworkloads\fP] [\fB\-d\fP \fIdevice\fP] [\fB\-W\fP \fIcommand\fP] [\fB\-p\fP \fIcommand\fP] [\fB\-L\fP] [\fB\-N\fP \fIprefix\fP] [\fB\-m\fP | \fB\-M\fP \fIemail\fP | \fB\-U\fP \fIurl\fP] [\fB\-s\fP] [\fB\-l\fP \fIsamples\fP] [\fB\-h\fP [\fB\-H\fP \fIcategories\fP] [\fB\-B\fP \fIgranularity\fP]] [\fB\-T\fP \fIseconds\fP [\fB\-q\fP]] [\fB\-\-\fP] [\fIargs\fP] ...
 .SH DESCRIPTION
 \fBxeno\-test\fP measures the performance of Xenomai, by executing Xenomai's \fBlatency\fP 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 \fB-W\fP \fIcommand\fP option) is:
@@ -27,12 +27,12 @@
 If the \fB\-q\fP option is not specified, samples are printed in groups separated by headers.
 In addition, \fBlatency\fP print statistics for all samples before terminating, and can also optionally print statistics for every group of samples (see the \fB\-s\fP option), and distribution histograms (see the \fB\-h\fP option).
 
+.SH OPTIONS
 If an invalid option is specified, \fBxeno\-test\fP prints out an usage help message and exits.
 
 You are strongly encouraged to use the \fB\-m\fP option, to anonymously help the Xenomai team collecting statistics about Xenomai's performance on the widest range of systems.
 
-.SH OPTIONS
-These following options are specific to \fBxeno\-test\fP:
+The following options are specific to \fBxeno\-test\fP:
 .TP
 \fB\-v\fP
 Produces more verbose tests results.
@@ -42,39 +42,44 @@
 .TP
 \fB\-d\fP \fIdevice\fP
 If the default workload command is to be executed, sets the input device to be read by \fBdd\fP to \fIdevice\fP instead of \fB/dev/zero\fP.
-For instance, specifying the device of a real hard-drive (e.g. \fB/dev/hda/\fP) is useful for generating interrupts with I/O.
+For instance, specifying the device of a real hard-drive (e.g. \fB/dev/hda1\fP) is useful for generating interrupts with I/O.
 The specified \fIdevice\fP must be mounted, and cannot be an NFS mount.
 .TP
 \fB\-W\fP \fIcommand\fP
 Executes the specified \fIcommand\fP to generate workload, instead of the default \fBdd if=/dev/zero of=/dev/null\fP command.
-
 If the command requires arguments, the command and its arguments must be quoted and passed as a single \fIcommand\fP argument.
 In addition to such static arguments, the \fIargs\fP optional arguments passed to \fBxeno\-test\fP are appended to \fIcommand\fP to execute it. 
 .TP
 \fB\-p\fP \fIcommand\fP
-Makes \fBxeno\-test\fP execute the specified \fIcommand\fP before, between and after the \fBlatency\fP executions. 
+Makes \fBxeno\-test\fP execute the specified \fIcommand\fP before and after all the \fBlatency\fP executions. 
 .TP
 \fB\-L\fP
-Activates logging of the tests results. The log file is created in the \fB/tmp/\fP directory, and is named \fBtest\-\fP\fIkernel_release\fP, where \fIkernel_release\fP is the release number of the running Linux kernel (as determined by executing \fBuname \-r\fP).
+Activates logging of the tests results.
+The log file is created in the \fB/tmp/\fP directory, and is named \fBtest\-\fP\fIkernel_release\fP\fB\-\fP\fItimestamp\fP, where \fIkernel_release\fP is the release number of the running Linux kernel (as determined by executing \fBuname \-r\fP), and \fItimestamp\fP is a textual representation of the current date and time (as determined by executing \fBdate\fP) used to reduce the risk of file name collisions.
+The log file name can be customized by using the \fB\-N\fP option instead of, or in conjunction with this option.
 .TP
 \fB\-N\fP \fIprefix\fP
-Prepends \fIprefix\fP\fB\-\fP to the log file name, hence if the \fB\-L\fP option is also specified the log file name is \fIprefix\fP\fB\-test\-\fP\fIkernel_release\fP.
-This option is useful to create the log file in a different directory than \fB/tmp/\fP, by specifying a \fIprefix\fP that starts with the relative path to that directory.
+Activates logging of the tests results.
+If the \fB\-L\fP option is also specified, prepends \fIprefix\fP to the log file name, hence the log file name is \fIprefix\fP\fBtest\-\fP\fIkernel_release\fP\fB\-\fP\fItimestamp\fP.
+If the \fB\-L\fP option is not specified, the log file name is \fIprefix\fP\fB\-\fP\fItimestamp\fP.
+This option is useful to create the log file in a different directory than \fB/tmp/\fP (default prefix when using the \fB\-L\fP option), by specifying a \fIprefix\fP which starts with an absolute directory path or a directory path relative to the working directory.
 .TP
 \fB\-m\fP
-Sends the tests results log file to the Xenomai team's email address (\fBxenotest.output@domain.hid), to help collecting statistics about Xenomai's performance. The email is sent using the system's mail(1) command. The email's sender address is \fBxenotest.sender@domain.hid, and the email's subject is \fB"xeno-test results"\fP.
+Sends the tests results to the Xenomai team's email address (\fBxenotest.output@domain.hid), to help collecting statistics about Xenomai's performance. The email is sent using the system's \fBmail\fP command. The email's sender address is \fBxenotest.sender@domain.hid, and the email's subject is \fB"xeno-test results"\fP.
 .TP
 \fB\-M\fP \fIemail\fP
-Similar to the \fB\-m\fP option, but sends the tests results log file to the specified email address instead of the default one.
+Similar to the \fB\-m\fP option, but sends the tests results to the specified email address instead of the default one.
 .TP
 \fB\-U\fP \fIurl\fP
-Uploads the tests results log file to the specified URL.
-If there is no file part in the specified \fIurl\fP, the log file name is appended to it to form the URL used for upload.
-The file is transmitted as an attachment, with the log file name as a filename, in an HTTP POST request of MIME type multi-part/form-data (like with a HTML-form-based file uploads).
-The upload is performed using the curl(1) command.
+Uploads the tests results to the specified URL.
+If there is no file part in the specified \fIurl\fP, and the \fB\-L\fP or \fB\-N\fP 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 \fBcurl\fP command.
+This option fails silently (i.e. the tests results are not sent) if \fBcurl\fP is not available.
 .PP
 The following options are directly passed to the \fBlatency\fP test command executed by \fBxeno\-test\fP.
-If no such options are specified, the \fB\-s \-T 10 \-q\fP options are passed by default by \fBxeno\-test\fP.
+If no such options are specified, the \fB\-s \-T 120 \-q\fP options are implicitly passed by default by \fBxeno\-test\fP.
+Any user-specified set of options overrides this default set of options.
 .TP
 \fB\-s\fP
 Displays statistics (minimum, average, and maximum latencies) for every group of samples.
@@ -89,6 +94,7 @@
 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 \fB\-H\fP \fIcategories\fP option (default is \fB100\fP categories).
 The granularity - or bucket size -, used to separate latency samples into categories, is determined by the \fB\-B\fP \fIgranularity\fP option (default is \fB1000\fP ns).
+This option implies \fB\-s\fP.
 .TP
 \fB\-H\fP \fIcategories\fP
 The number of categories - or value intervals - of histograms to display if the \fB\-h\fP option is specified.
@@ -118,24 +124,13 @@
 .B 1
 An invalid option was specified.
 .SH KNOWN BUGS
-\fBxeno\-test\fP allows to specify the \fB\-N\fP \fIlogprefix\fP option without the \fB\-L\fP option, in which case the log file name is: \fIlogprefix\fP\fB\-\fP.
-
 \fBlatency\fP allows to specify the \fB\-H\fP \fIcategories\fP and \fB\-B\fP \fIgranularity\fP options without the \fB\-h\fP option, in which case they have no effect.
 
-It is possible to specify the period between samples (default is \fB1 second\fP) using the \fBlatency\fP command's \fB\-p\fP option, but this option cannot be passed through \fBxeno-test\fP.
+It is possible to specify the period between samples (default is \fB1 second\fP) using the \fBlatency\fP command's \fB\-p\fP option, but this option cannot be passed through \fBxeno-test\fP (this conflicts with \fBxeno-test\fP's own \fB\-p\fP option).
+
+The workload generation task (e.g., the default \fBdd if=/dev/zero of=/dev/null\fP 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 \fB-W\fP \fIcommand\fP option.
+
+Workload processes may not be properly killed when \fBxeno-test\fP terminate.
 .SH "SEE ALSO"
 .BR xeno\-load (1),
 .BR uname (1)
-.SH HISTORY
-.TP
-2006-04-25
-Updated to document the new -U option. Removed references to the klatency command. Modified the synopsis to reflect the dependency of -m, -M and -U options on the -L option.
-.TP
-2006-04-21
-Updated to document the new -v option.
-.TP
-2006-04-19
-Updated to document the new -m and -M options.
-.TP
-2005-10-19
-Written by Romain Lenglet <rlenglet@domain.hid>

Re: [Xenomai-core] xeno-test manpage patch

[Philippe Gerum]

Romain Lenglet wrote:
> Hi,
> 
> Here is a patch for the manpages.
> 
> 

Applied, thanks.


-- 

Philippe.

Re: [Xenomai-core] xeno-test manpage patch

[Jim Cromie]

Romain Lenglet wrote:

<doc fixes, skipped>

>> BUGS
>>
>> -N   name is timestamped, giving uniqueness.  This is a
>> caveat, not a bug
>>     
>
> No, it is a feature. I added it into the documentation of -L 
> and -N.
> By the way, I suggest that you use a timestamp in the RFC 3339 
> format (a subset of ISO 8601):
> date "+%Y-%m-%d %H:%M:%S%:z"
> or, assuming date is GNU date:
> date --rfc-3339=seconds
>
>   
I wanted a compact rep.
is there a std format that doesnt have a space ?
its nicer for us xterm double-click cut-pasters.

>> -p   oops.   Im open to suggestions whether this is worth
>> fixing.
>>
>> (workload mgmt)
>>
>>    workload tasks arent always (ever?) restarted once they
>> finish, so a real /dev/hda1 workload may end before your test
>> does, causing non-uniform &
>> unexpected load variations.
>>
>>     
you used the default load in your explanation, which never ends ( 
/dev/zero supplies infinite 0s)
One of these days Ill try to actually fix it.

>> workloads arent always killed if test is interrupted.
>>     
>
> Added into the bugs section.
>
>
>
> Now, it is my turn to make some remarks on xeno-test... ;)
>   
> 2-
> I don't know why there is a sort of option "-n" in the case:
>         n)
>             # accept note (from the outer process)
>             notes=$OPTARG ;;
> Those three lines should be removed: this is dead code.
>   


Ack.  vestigial cruft. 
was meant to pass info into the script as way to show in 1st lines
how test was run. 

Re: [Xenomai-core] xeno-test manpage patch

[Romain Lenglet]

Jim Cromie wrote:
> > By the way, I suggest that you use a timestamp in the RFC
> > 3339 format (a subset of ISO 8601):
> > date "+%Y-%m-%d %H:%M:%S%:z"
> > or, assuming date is GNU date:
> > date --rfc-3339=seconds
>
> I wanted a compact rep.
> is there a std format that doesnt have a space ?
> its nicer for us xterm double-click cut-pasters.

Replace the space with a "T": this is still an ISO 8601 format.

-- 
Romain LENGLET

Re: [Xenomai-core] xeno-test manpage patch

[Thomas Lockhart]

>>I wanted a compact rep.
>>is there a std format that doesnt have a space ?
>>its nicer for us xterm double-click cut-pasters.
> Replace the space with a "T": this is still an ISO 8601 format.

Just a detail: it is "ISO 9601" and (fwiw) I can confirm that the "T" is 
defined there.

                        - Tom


-- 
Thomas Lockhart
Supervisor, Realtime Software Group
Interferometry and Large Optical Systems
Caltech/JPL

Re: [Xenomai-core] xeno-test manpage patch

[Romain Lenglet]

Thomas Lockhart:
> >>I wanted a compact rep.
> >>is there a std format that doesnt have a space ?
> >>its nicer for us xterm double-click cut-pasters.
> >
> > Replace the space with a "T": this is still an ISO 8601
> > format.
>
> Just a detail: it is "ISO 9601" and (fwiw) I can confirm that
> the "T" is defined there.

I am adding some more noise... ;-)

No, it is ISO 8601. There is no ISO 9601 standard (the 9000 
series is about management / quality).
http://www.iso.org/iso/en/CatalogueDetailPage.CatalogueDetail?CSNUMBER=40874&ICS1=1&ICS2=140&ICS3=30

The interesting thing about IETF's RFC 3339 is that they have 
summarized ISO 8601's syntax in ABNF, and defined a 
non-ambiguous subset of it.
The "T" is optional in ISO 8601, but they have made it mandatory 
in RFC 3339's subset to avoid ambiguity:
"ISO 8601 states that the "T" may be omitted under some 
circumstances.  This grammar requires the "T" to avoid 
ambiguity.
[...]
iso-date-time     = date "T" time"


My mistake is, I initially thought that RFC 3339 recommended a 
space instead of "T", but this is only an option for 
readability:
"NOTE: ISO 8601 defines date and time separated by "T". 
Applications using this syntax may choose, for the sake of 
readability, to specify a full-date and full-time separated by 
(say) a space character."


This story about the ambiguity of ISO 8601 is the reason why 
the --iso-8601 option has been dropped from GNU date in favor 
of --rfc-3339. But that option is buggy, since it returns the 
date with a space instead of a "T"... I am filing a bug report!


Conclusion: let's use a "T", to be compatible with everyone! :-)

-- 
Romain LENGLET