rttest

rttest is a minimal tool for instrumenting and running tests for synchronous real-time systems. It provides utilities for measuring and plotting jitter, latency, and missed deadlines. It also provides a library with macros for instrumenting code. It is designed with real-time Linux-based systems in mind, such as Preempt RT kernel.

Build instructions

Build from source:

mkdir build
cd build

cmake ..
sudo make install

Alternatively for a local install:

cmake .. -DCMAKE_INSTALL_PREFIX=<build folder>
make install

Build and run the example:

cd examples
mkdir build
cd build
cmake .. (-DCMAKE_INSTALL_PREFIX=<build folder>)
make
./example_loop

Note that if this is run in a Docker container, the IPC_LOCK capability must be added to the container capabilities. This can be managed via the --cap-add flag:

docker run --cap-add IPC_LOCK

Command line arguments

Passing argc and argv of an instrumented main function to rttest_read_args will enable command line arguments for the instrumented function.

-u Specify the update period. Default units are microseconds. Use the suffix “s” for seconds, “ms” for milliseconds, “us” for microseconds, and “ns” for nanoseconds. Default update period is 1ms.

-m Set maximum stack prefault size for static stack prefaulting. “b” for bytes, “kb” for kilobytes, “mb” for megabytes, “gb” for gigabytes (use with caution). Default stack size is 1MB.

-d Set maximum heap prefault size for dynamic memory prefaulting. “b” for bytes, “kb” for kilobytes, “mb” for megabytes, “gb” for gigabytes (use with caution). Default heap size is 8192MB.

-i Specify how many iterations to run the real-time loop. Specifying an iteration value less than or equal to 0 will cause rttest to run forever or until interrupted with Ctrl-C. If running forever, rttest will not save a data buffer and writing results to a file will not work. Default value is 1000.

-tp Set the thread priority of all threads launched by the test program. Individual thread priority can be set using the rttest_set_sched_priority command.

-f Specify the name of the file for writing the collected data. Plot this data file using the rttest_plot script provided in scripts.

Changelog for package rttest

0.18.2 (2024-11-25)

• Don't try to build on BSD (#126)
• Contributors: Scott K Logan

0.18.1 (2024-07-29)

0.18.0 (2024-04-26)

0.17.0 (2023-11-06)

• Update to C++17 (#124)
• Contributors: Chris Lalancette

0.16.0 (2023-04-27)

0.15.0 (2023-02-14)

• [rolling] Update maintainers - 2022-11-07 (#121)
• Contributors: Audrow Nash

0.14.1 (2022-09-13)

• Addressing issues found in Humble testing (#116)
• Contributors: Michael Carroll

0.14.0 (2022-04-29)

0.13.0 (2022-03-01)

• Install includes to include/${PROJECT_NAME} (#114)
• Contributors: Shane Loretz

0.12.1 (2022-01-14)

• Fix include order for cpplint (#113)
• Contributors: Jacob Perron

0.12.0 (2021-12-17)

• Fixes for uncrustify 0.72 (#111)
• Mark dependent targets as PRIVATE (#112)
• Export modern CMake targets (#110)
• Contributors: Chris Lalancette, Shane Loretz

0.11.0 (2021-03-18)

• Fix up nonsensical handling of NULL in rttest_get_{params,statistics} (#107)
• Contributors: Chris Lalancette

0.10.1 (2020-12-08)

• Remove "struct" from rttest_sample_buffer variable declaration. (#105)
• Convert the sample buffer to a vector. (#104)
• Use strdup instead of strlen/strcpy dance. (#100)
• Enable basic warnings in rttest (#99)
• Only copy an rttest_sample_buffer if it is not nullptr. (#98)
• Contributors: Audrow Nash, Chris Lalancette

0.10.0 (2020-06-17)

• Convert timespec to uint64 not long and vice versa (#94) (#96)
• Fix standard deviation overflow(#95) (#97)
• Contributors: y-okumura-isp

0.9.0 (2020-04-30)

• Use std::bind instead of deprecated std::bind2nd (#93)
• Use a uint64_t to store the prefault_dynamic_size. (#90)
• Make dynamic prefault memory size configurable (#89)
• code style only: wrap after open parenthesis if not in one line (#88)
• Contributors: Chris Lalancette, Dirk Thomas, Michel Hidalgo, Roman Sokolkov

0.8.2 (2019-11-13)

0.8.1 (2019-10-23)

• Fix typo (#83)
• Contributors: Servando

0.8.0 (2019-09-26)

• Switch the latency storage to int64_t (#82)
• Only return statistics if they have been calculated (#81)
• Remove non-package from ament_target_dependencies() (#79)
• Fix armhf build warnings (#78)
• Contributors: Chris Lalancette, Prajakta Gokhale, Shane Loretz

0.7.1 (2019-05-08)

0.7.0 (2019-04-14)

• Add section about DCO to CONTRIBUTING.md
• Install headers into the same location when ament_cmake is not used (#72)
• Contributors: Dirk Thomas

0.6.0 (2018-11-20)

• Drop obsolete RTLinux (#68) RTLinux is obsolete, and both commercial and GPL editions were no longer maintained. Through the use of the real-time Linux kernel patch PREEMPT_RT, support for full preemption of critical sections, interrupt handlers, and "interrupt disable" code sequences can be supported.
• Contributors: Jim Huang

0.5.0 (2018-06-27)

• Update the maintainer (#65)
• Contributors: Chris Lalancette

0.4.0 (2017-12-08)

• Update style to match latest uncrustify (#57)
• 0.0.3
• Update style to satisfy new flake8 plugins (#56)
• Use CMAKE_X_STANDARD and check compiler rather than platform
• Comply with flake8 + flake8-import-order linters (#52)
• Require CMake 3.5
• C++14 (#50)
• Remove usage of internal variables and noops (#43)
• Add schema to manifest files
• Disable on Android (#41)
• Use CTest BUILD_TESTING (#38)
• uint32 -> uint64 in a few places for time calculation #33)
• Store filename on heap, add more checks for null pointers (#29)
• Fix memory management of rttest_sample_buffer (#22)
• Fix boundary check (#20)

• Reorganize realtime_support repository (#16)

  • Add tlsf_cpp repo
  • Move rttest into subfolder

• Contributors: Dirk Thomas, Esteve Fernandez, Jackie Kay, Mikael Arguedas, Morgan Quigley, dhood