Cyclictest accurately and repeatedly measures the difference between a thread's intended wake-up time and the time at which it actually wakes up in order to provide statistics about the system's latencies. It can measure latencies in real-time systems caused by the hardware, the firmware, and the operating system.

The original test was written by Thomas Gleixner (tglx), but several people have subsequently contributed modifications. Cyclictest is currently maintained by Clark Williams and John Kacur and is part of the test suite rt-tests.

• System benchmarking
• Latency debugging
• Approximating application performance

To measure latencies, Cyclictest runs a non real-time master thread (scheduling class SCHED_OTHER) which starts a defined number of measuring threads with a defined real-time priority (scheduling class SCHED_FIFO). The measuring threads are woken up periodically with a defined interval by an expiring timer (cyclic alarm). Subsequently, the difference between the programmed and the effective wake-up time is calculated and handed over to the master thread via shared memory. The master thread tracks the latency values and prints the minimum, maximum and average for the latency once the number of iterations specified is completed.

Cyclictest can be installed by following the instructions on the rt-tests page.

Cyclictest must be run as root, with sudo, or as a member of the realtime group. Here is a test case that is relevant for most SMP real-time systems:

# cyclictest --mlockall --smp --priority=80 --interval=200 --distance=0

The options above are not relevant for every situation on every system. The following section goes into more detail about how to choose the right options for measuring a specific latency on a given system. Additionally, cyclictest -h provides a quick description of the different program options and more detailed explanations can be found by running man ./src/cyclictest/cyclictest.8 from the root of the rt-tests files.

Running Cyclictest without any options is not recommended as it will not necessarily measure anything useful. Without parameters cyclictest creates one thread with an intended wake up period of 1 ms.

Cyclictest can be used to detect latencies that occur in a variety of different systems and situations. However, when measuring the latency of a specific situation, the test set-up and the parameters passed to the tool need to be carefully considered and chosen based on this situation. If these elements are not considered thoughtfully, the Cyclictest results will not accurately represent the latencies that occur in the situation that was supposed to be measured. In other words, it is relatively easy to accidentally not measure what a test was intended to measure.

cyclictest is one of the most frequently used programs for bench-marking realtime systems. It is usually used with some sort of loads. Following are some of the ways cyclictest can be utilized to benchmark a real-time system:

• RTEval
• Worst Case Latency Test Scenarios