WhatLatencyTestDoes

What Latency-Test Does

latency-test sets up and runs one or two real-time threads. By default these threads are a fast thread with a 25.0us period and a slow thread with a 1.0ms period. This default setup mimics a common configuration pattern for LinuxCNC. The two threads are referred to as the base thread and the servo thread, respectively.

Each time a thread is started by the scheduler, the code set up by latency-test gets the time and subtracts from it the previous time the same thread started. In a perfect system, this difference would always be equal to the selected period for the thread, e.g., there would be zero latency. Because of vagaries in the system, it usually is not zero. latency-test determines the maximum deviation (both larger and smaller) of this difference compared to the selected period, compares the absolute values of the two deviations, and reports the larger absolute value as the max jitter.

As has been noted in email discussions, latency-test does not record the difference between the actual start-time and the scheduled start-time, which is what some consider the real latency, but rather the difference beween consecutive actual start-times, which it then compares to the period to determine latency indirectly. Given that the thread is started by the inaccessible scheduler and not some measurable external event, the distinction is effectively moot. This situation may change as the art of latency testing matures.

How Latency-Test Works

In a default LinuxCNC installation, latency-test is found in the <linuxcnc>/scripts directory. It is a shell script that may seem mysterious to neophytes.

When invoked, it creates a temporary directory /tmp/tmp.<something> and makes it the current directory. Then it parses the remainder of the command line for user-defined periods, if any, with which to overrode the defaults. Based on the results, it determines how many threads and with what periods to invoke. Then, it

• creates a file named lat.hal which will configure one or two instances of the LinuxCNC timedelta component to do the actual timing, add the instance(s) in a real-time thread and interconnect the instance(s) to an instance of PyVCP with a custom panel to display the progress of the test.
• creates a file named lat.xml which defines this custom panel.
• creates yet another file named latexit.sh which is a shell script to record the maximum latency to the file ~/.latency upon exit from latency-test.

All three files mentioned are created in the temporary directory and exist only for the duration of the test. Finally, latency-test issues the command "halrun lat.hal" <whew>.

Each time a timedelta component instance starts, it gets the time through the LinuxCNC system-call rtapi_get_time() and computes various quantities from it, including the time difference and the deviations. Refer to the man page, the HAL manual, or better yet the source code for details.

As an aside, the latency-test scripts may seem even more mysterious than one might expect because it contains two similar but not identical sections to create the .xml and .hal files for the two cases of running one thread and running two threads. By default, files for a two-thread test case are created. Files for the single-thread test case are created only if the period entered for the fast/base thread is 0 or equal to the period of the slow/servo thread. In this case the sole thread will be reported in the PyVCP panel as the servo thread.

Invoking Latency-Test

The following is taken from the latency-script:

     Usage: latency-test [base-period [servo-period]]
     Default: latency-test 25us 1ms
     Times May be specified with suffix "s", "ms", "us", "µs", or "ns"
     Times without a suffix and less than 1000 are taken to be in us;
     other times without a suffix are taken to be in ns

     The worst-case latency seen in any run of latency-test
     is written to the file ~/.latency

This page was originally created by Kent Reed (aka cncdreamer) on 20121209.