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, 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.
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
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 it starts, a timedelta component 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 generate the .xml and .hal files for the two cases of running one thread and running two threads. By default a two-thread test case is run. The single-thread test case is run 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.
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