// ** The above line should force tbl to be a preprocessor **
|
// Man page for autotune
|
//
|
// Copyright (C) 2014 Philippe Gerum <rpm@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.
|
|
*--period <ns>*::
|
Set the sampling period to the given count of nanoseconds. The
|
estimation is performed by measuring the jitter between the ideal time
|
at which a timer tick should be received, and the actual time it is
|
eventually received, for a series of ticks. This value expresses the
|
delay between two of these ticks. If too short, a lockup might
|
occur. A commonly observed result is that the larger the delay, the higher
|
the latency, due to CPU cache effects (i.e. the real-time code/data is
|
more likely to get evicted from the cachelines as the non real-time
|
activity can slip in, treading over a larger address space).
|
|
*--reset*::
|
Reset the gravity values to their factory defaults. These defaults
|
are statically defined by the Xenomai platform code.
|
|
*--noload*::
|
Disable load generation while auto-tuning. *autotune* runs a 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.
|
|
*--verbose[=level]*::
|
Set verbosity to the desired level, 1 means almost quiet (default), 2
|
means fully verbose.
|
|
*--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.
|
|
NOTES
|
-----
|
The auto-tuning process may take some time for completing the
|
estimation. Although this delay may vary across hardware platforms,
|
running for 30 seconds is common.
|
|
Once the gravity values are known for a particular hardware, one may
|
write them to +/proc/xenomai/clock/coreclck+ from some system init
|
script to set up the Xenomai core clock accordingly, instead of
|
running the auto-tuner after each boot e.g:
|
|
------------------------------------------------------
|
/* change the user gravity to 1728 ns (default) */
|
# echo 1728 > /proc/xenomai/clock/coreclck
|
/* change the IRQ gravity to 129 ns */
|
# echo 129i > /proc/xenomai/clock/coreclck
|
/* change the user and kernel gravities to 1728 and 907 ns resp. */
|
# echo "1728u 907k" > /proc/xenomai/clock/coreclck
|
------------------------------------------------------
|
|
Alternatively, the gravity values can be statically defined in the
|
kernel configuration of the target kernel:
|
|
- CONFIG_XENO_OPT_TIMING_SCHEDLAT should be assigned the user gravity
|
value.
|
|
- CONFIG_XENO_OPT_TIMING_KSCHEDLAT should be assigned the kernel
|
gravity value.
|
|
- CONFIG_XENO_OPT_TIMING_IRQLAT should be assigned the IRQ gravity
|
value.
|
|
AUTHOR
|
-------
|
*autotune* was written by Philippe Gerum <rpm@xenomai.org>.
|
