Module: xenomai-forge
Branch: next
Commit: 7cbcb40efe80018332b78df382481e7f1b60f4fb
URL:
http://git.xenomai.org/?p=xenomai-forge.git;a=commit;h=7cbcb40efe80018332b78df382481e7f1b60f4fb
Author: Philippe Gerum <r...@xenomai.org>
Date: Sun Aug 3 16:36:57 2014 +0200
doc/autotune: add manpage for the auto-tuner
---
doc/asciidoc/Makefile.am | 46 ++++++++--------
doc/asciidoc/Makefile.in | 46 ++++++++--------
doc/asciidoc/man1/autotune.adoc | 112 +++++++++++++++++++++++++++++++++++++++
3 files changed, 160 insertions(+), 44 deletions(-)
diff --git a/doc/asciidoc/Makefile.am b/doc/asciidoc/Makefile.am
index bd27871..98eaefb 100644
--- a/doc/asciidoc/Makefile.am
+++ b/doc/asciidoc/Makefile.am
@@ -1,60 +1,62 @@
HTML_DOCS = \
+ html/MIGRATION \
+ html/README.APPLICATIONS \
+ html/README.INSTALL \
+ html/TROUBLESHOOTING.COBALT \
+ html/TROUBLESHOOTING.MERCURY \
+ html/asciidoc-icons \
+ html/asciidoc-icons/callouts \
+ html/man1/autotune \
html/man1/clocktest \
- html/man1/slackspot \
html/man1/dohell \
html/man1/latency \
html/man1/rtcanconfig \
html/man1/rtcanrecv \
html/man1/rtcansend \
+ html/man1/slackspot \
html/man1/switchtest \
- html/man1/xeno-config \
- html/man1/xeno-test \
html/man1/xeno \
- html/README.INSTALL \
- html/README.APPLICATIONS \
- html/TROUBLESHOOTING.COBALT \
- html/TROUBLESHOOTING.MERCURY \
- html/MIGRATION \
- html/asciidoc-icons \
- html/asciidoc-icons/callouts
+ html/man1/xeno-config \
+ html/man1/xeno-test
PDF_DOCS = \
- README.INSTALL.pdf \
+ MIGRATION.pdf \
README.APPLICATIONS.pdf \
+ README.INSTALL.pdf \
TROUBLESHOOTING.COBALT.pdf \
- TROUBLESHOOTING.MERCURY.pdf \
- MIGRATION.pdf
+ TROUBLESHOOTING.MERCURY.pdf
TXT_DOCS = \
- README.INSTALL.txt \
+ MIGRATION.txt \
README.APPLICATIONS.txt \
+ README.INSTALL.txt \
TROUBLESHOOTING.COBALT.txt \
- TROUBLESHOOTING.MERCURY.txt \
- MIGRATION.txt
+ TROUBLESHOOTING.MERCURY.txt
MAN1_DOCS = \
+ man1/autotune.1 \
man1/clocktest.1 \
man1/cyclictest.1 \
+ man1/dohell.1 \
man1/latency.1 \
man1/rtcanconfig.1 \
man1/rtcanrecv.1 \
man1/rtcansend.1 \
+ man1/slackspot.1 \
man1/switchtest.1 \
- man1/xeno.1 \
man1/xeno-config.1 \
man1/xeno-test.1 \
- man1/dohell.1 \
- man1/slackspot.1
+ man1/xeno.1
EXTRA_DIST := \
- README.INSTALL.adoc \
+ MIGRATION.adoc \
README.APPLICATIONS.adoc \
+ README.INSTALL.adoc \
TROUBLESHOOTING.COBALT.adoc \
TROUBLESHOOTING.MERCURY.adoc \
- MIGRATION.adoc \
plaintext.conf \
- plaintext_postproc.awk \
plaintext.xsl \
+ plaintext_postproc.awk \
$(MAN1_DOCS:%.1=%.adoc)
if !XENO_BUILD_DOC
diff --git a/doc/asciidoc/Makefile.in b/doc/asciidoc/Makefile.in
index e87bd6f..15ea9ef 100644
--- a/doc/asciidoc/Makefile.in
+++ b/doc/asciidoc/Makefile.in
@@ -295,62 +295,64 @@ top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
HTML_DOCS = \
+ html/MIGRATION \
+ html/README.APPLICATIONS \
+ html/README.INSTALL \
+ html/TROUBLESHOOTING.COBALT \
+ html/TROUBLESHOOTING.MERCURY \
+ html/asciidoc-icons \
+ html/asciidoc-icons/callouts \
+ html/man1/autotune \
html/man1/clocktest \
- html/man1/slackspot \
html/man1/dohell \
html/man1/latency \
html/man1/rtcanconfig \
html/man1/rtcanrecv \
html/man1/rtcansend \
+ html/man1/slackspot \
html/man1/switchtest \
- html/man1/xeno-config \
- html/man1/xeno-test \
html/man1/xeno \
- html/README.INSTALL \
- html/README.APPLICATIONS \
- html/TROUBLESHOOTING.COBALT \
- html/TROUBLESHOOTING.MERCURY \
- html/MIGRATION \
- html/asciidoc-icons \
- html/asciidoc-icons/callouts
+ html/man1/xeno-config \
+ html/man1/xeno-test
PDF_DOCS = \
- README.INSTALL.pdf \
+ MIGRATION.pdf \
README.APPLICATIONS.pdf \
+ README.INSTALL.pdf \
TROUBLESHOOTING.COBALT.pdf \
- TROUBLESHOOTING.MERCURY.pdf \
- MIGRATION.pdf
+ TROUBLESHOOTING.MERCURY.pdf
TXT_DOCS = \
- README.INSTALL.txt \
+ MIGRATION.txt \
README.APPLICATIONS.txt \
+ README.INSTALL.txt \
TROUBLESHOOTING.COBALT.txt \
- TROUBLESHOOTING.MERCURY.txt \
- MIGRATION.txt
+ TROUBLESHOOTING.MERCURY.txt
MAN1_DOCS = \
+ man1/autotune.1 \
man1/clocktest.1 \
man1/cyclictest.1 \
+ man1/dohell.1 \
man1/latency.1 \
man1/rtcanconfig.1 \
man1/rtcanrecv.1 \
man1/rtcansend.1 \
+ man1/slackspot.1 \
man1/switchtest.1 \
- man1/xeno.1 \
man1/xeno-config.1 \
man1/xeno-test.1 \
- man1/dohell.1 \
- man1/slackspot.1
+ man1/xeno.1
EXTRA_DIST := \
- README.INSTALL.adoc \
+ MIGRATION.adoc \
README.APPLICATIONS.adoc \
+ README.INSTALL.adoc \
TROUBLESHOOTING.COBALT.adoc \
TROUBLESHOOTING.MERCURY.adoc \
- MIGRATION.adoc \
plaintext.conf \
- plaintext_postproc.awk \
plaintext.xsl \
+ plaintext_postproc.awk \
$(MAN1_DOCS:%.1=%.adoc)
@XENO_BUILD_DOC_FALSE@HTML_DOCSDIR = $(srcdir)/../prebuilt/
diff --git a/doc/asciidoc/man1/autotune.adoc b/doc/asciidoc/man1/autotune.adoc
new file mode 100644
index 0000000..4c93ae6
--- /dev/null
+++ b/doc/asciidoc/man1/autotune.adoc
@@ -0,0 +1,112 @@
+// ** The above line should force tbl to be a preprocessor **
+// Man page for autotune
+//
+// Copyright (C) 2014 Philippe Gerum <r...@xenomai.org>
+//
+// You may distribute under the terms of the GNU General Public
+// License as specified in the file COPYING that comes with the
+// Xenomai distribution.
+//
+//
+AUTOTUNE(1)
+==========
+:doctype: manpage
+:revdate: 2014/08/03
+:man source: Xenomai
+:man version: {xenover}
+:man manual: Xenomai Manual
+
+NAME
+----
+autotune - Calibrate the Xenomai core clock timer
+
+SYNOPSIS
+---------
+*autotune* [ options ]
+
+DESCRIPTION
+------------
+*autotune* is a utility to determine the best calibration values (aka
+ _gravity triplet_) for the core clock timer.
+
+The time spent traversing the kernel code from the low-level Xenomai
+timer handler until the kernel-based client handler is invoked, is
+shorter than the time required to schedule in a kernel thread
+instead. It takes even more time to switch in a user-space thread,
+which entails changing the current memory address space, performing
+potentially time-consuming MMU-related operations.
+
+For this reason, Xenomai differentiates timers on the target context
+they activate, among IRQ(handler), kernel and user threads,
+anticipating the next timer shot accordingly, so that such context is
+activated as close as possible to the ideal time. This anticipation is
+called the _gravity_ of the clock serving the timer, which is actually
+a triplet representing the three possible types of contexts the timer
+can activate.
+
+Therefore, the gravity is a static adjustment value to account for the
+basic latency of the target system for responding to timer events, as
+perceived by the client code waiting for the wake up events. Such
+latency is increased by additional factors, such as:
+
+- bus or CPU cache latency,
+- delay required to program the timer chip for the next shot,
+- code running with interrupts disabled on the CPU to receive the IRQ,
+- inter-processor serialization (_spinlocks_).
+
+*autotune* runs a series of internal calibration tests for estimating
+the most appropriate gravity values for its real-time clock timer,
+retaining the final values.
+
+[IMPORTANT]
+*autotune* requires the *CONFIG_XENO_OPT_AUTOTUNE* option to be
+ enabled in the kernel configuration.
+
+OPTIONS
+--------
+*autotune* accepts the following options:
+
+*--irq*::
+Estimate the IRQ gravity value, which is the shortest time the
+platform needs to deliver an IRQ to a Xenomai interrupt handler in
+kernel space.
+
+*--kernel*::
+Estimate the kernel gravity value, which is the shortest time the
+platform needs to deliver an IRQ to a RTDM task running in kernel
+space. This delay includes the context switching time.
+
+*--user*::
+Estimate the user gravity value, which is the shortest time the
+platform needs to deliver an IRQ to a user-space task/thread running
+in a Xenomai application process. This delay includes the context
+switching time.
+
+*--reset*::
+Reset the gravity values to their factory defaults. These defaults
+are statically defined by the Xenomai platform code.
+
+*--nohog*::
+Disable load generation while auto-tuning. *autotune* runs a simple
+load generator internally in parallel to estimating the latency, in
+order to eliminate irregular delays which tend to appear on fully idle
+systems. Therefore, keeping the load generation enabled most often
+leads to a more accurate estimation.
+
+*--quiet*::
+Tame down verbosity of the auto-tuner.
+
+*--help*::
+Display a short help.
+
+If none of +--irq+, +--kernel+ or +--user+ is given, an estimation is
+done for each of them in sequence.
+
+VERSIONS
+--------
+
+*autotune* appeared in Xenomai 3.0 for the _Cobalt_ real-time core.
+
+AUTHOR
+-------
+*autotune* was written by Philippe Gerum <r...@xenomai.org>.
_______________________________________________
Xenomai-git mailing list
Xenomai-git@xenomai.org
http://www.xenomai.org/mailman/listinfo/xenomai-git
