1. SYNOPSIS

autotune [ options ]

2. 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.

3. 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.

4. VERSIONS

autotune appeared in Xenomai 3.0 for the Cobalt real-time core.

5. 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.

6. AUTHOR

autotune was written by Philippe Gerum <rpm@xenomai.org>.