// ** 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>.
