Usage

voraus-rt-ipc-eval has two configuration layers:

CLI flags: control how the tool is invoked (results location, verbosity, …). These can be passed on the command line or set via environment variables.
Test settings: control the test itself (duration, load, cyclictest parameters). These cannot be set via CLI flags and are read from a JSON config file, environment variables, or built-in defaults (in that order of precedence).

In general the defaults are just fine and you only need to change/set:

DURATION (e.g. to do a longer test)
ENABLE_NETWORK_RTT_TEST (to enable or disable the network round trip time test)
NETWORK_RTT_TEST__INTERFACE (to set the network interface for the test)
NETWORK_RTT_TEST__CPU_AFFINITY (to set the CPU affinity for the networking thread)
CYCLICTEST__CPU_AFFINITY (to set the CPU affinity for cyclictest threads, if necessary)

If you enable the network round trip time test, make sure to set the CPU affinity to the same isolated CPU that the respective network interface is pinned to. Also make sure, that cyclictest does not spawn a measurement thread on this CPU to not interfere with the network test. This can be achieved by setting CYCLICTEST__CPU_AFFINITY to all non-isolated CPUs (e.g. 0,2,3 or !1 if CPU 1 is isolated).

CLI Options

Option	Env variable	Default	Description
`--results-dir PATH`	`RESULTS_DIR`	`./results`	Directory where result files are written.
`--config-file PATH`	`CONFIG_FILE`	(none)	Path to a JSON configuration file (see below).
`--create-results-subdir`	`CREATE_RESULTS_SUBDIR`	`false`	Create a timestamped subdirectory in the results dir.
`--verbose`	`VERBOSE`	`false`	Enable debug-level logging.
`--version`	`VERSION`	`-`	Print the tool version and exit.

Configuration File

It is possible to use a config file for the test settings. Mount the file into the container with an additional -v flag:

docker run --rm ... \
  -v "$(pwd)/config.json:/config.json" \
  -v "$(pwd)/results:/results" \
  voraus.jfrog.io/docker/voraus-rt-ipc-eval \
  --config-file /config.json --results-dir /results

Config file reference

{
  "duration": "15m",
  "snapshot_interval": "auto",
  "load_args": ["stress-ng", "--cpu", "50%", "--io", "50%", "--pipe", "50%", "--vm", "25%", "--timeout", "0"],
  "cyclictest": {
    "interval": 250,
    "priority": 80,
    "lock_memory": true,
    "histogram_size": 500,
    "cpu_affinity": "0,2,3",
    "distance": 0,
    "break_threshold": null
  },
  "enable_network_rtt_test": true,
  "network_rtt_test": {
    "interface": "eth0",
    "cycletime": 1000,
    "priority": 49,
    "cpu_affinity": 1,
    "lock_memory": true,
    "prevent_sleep_states": true,
    "stats_frequency": null
  }
}

Setting	Default	Description
`duration`	`15m`	Total test duration. Accepts a number followed by a unit: `s`, `m`, `h`, or `d`.
`snapshot_interval`	`auto`	How often intermediate results of cyclictest and the network RTT test are written to the log while the test is running. Accepts a duration like `30s` or `5m`. `auto` derives the interval from `duration` so that roughly 200 snapshots are taken over the whole run, but never more often than every 60 s. Set to `null` to disable snapshots.
`load_args`	`stress-ng …`	Command and arguments used to generate system load during the test.
`cyclictest.interval`	`250`	Measurement interval between cyclictest samples in µs.
`cyclictest.priority`	`80`	`SCHED_FIFO` priority for the cyclictest threads (1–99).
`cyclictest.lock_memory`	`true`	Lock process memory (`mlock`) to prevent page-fault latency spikes.
`cyclictest.histogram_size`	`500`	Maximum latency bucket in the output histogram in µs.
`cyclictest.cpu_affinity`	all CPUs	The cpu affinity to use for cyclictest.
`cyclictest.distance`	`0`	Per-thread interval offset in µs. Set to `0` to use the same interval on all threads.
`cyclictest.break_threshold`	(none)	Stop the test immediately if a latency sample exceeds this value in µs. Omit or set to `null` to disable.
`enable_network_rtt_test`	`false`	Enable the network round trip time test.
`network_rtt_test.interface`	(none)	Network interface to use for the EtherCAT loopback test (e.g. `eth0`).
`network_rtt_test.cycletime`	`1000`	Cycle time to test with in µs.
`network_rtt_test.priority`	`49`	`SCHED_FIFO` priority for the network RTT test thread (1–99). `-1` uses `SCHED_OTHER`.
`network_rtt_test.cpu_affinity`	`-1`	CPU index on which the network RTT test thread is pinned. `-1` means no affinity.
`network_rtt_test.lock_memory`	`true`	Lock process memory (`mlock`) to prevent page-fault latency spikes during the test.
`network_rtt_test.prevent_sleep_states`	`true`	Request that the kernel keeps CPUs out of deep C-states for the duration of the test.
`network_rtt_test.stats_frequency`	(none)	How often intermediate statistics are logged. Omit or set to `null` to disable.

Environment Variables

Every setting from the config file can also be set via environment variable, which is particularly convenient for Docker deployments. Pass variables with -e in the docker run command.

Nested settings use __ (double underscore) as delimiter (e.g. cyclictest.interval → CYCLICTEST__INTERVAL).

Environment variable	Equivalent config key	Example
`DURATION`	`duration`	`DURATION=1h`
`SNAPSHOT_INTERVAL`	`snapshot_interval`	`SNAPSHOT_INTERVAL=5m`
`CYCLICTEST__INTERVAL`	`cyclictest.interval`	`CYCLICTEST__INTERVAL=500`
`CYCLICTEST__PRIORITY`	`cyclictest.priority`	`CYCLICTEST__PRIORITY=90`
`CYCLICTEST__LOCK_MEMORY`	`cyclictest.lock_memory`	`CYCLICTEST__LOCK_MEMORY=true`
`CYCLICTEST__HISTOGRAM_SIZE`	`cyclictest.histogram_size`	`CYCLICTEST__HISTOGRAM_SIZE=1000`
`CYCLICTEST__CPU_AFFINITY`	`cyclictest.cpu_affinity`	`CYCLICTEST__CPU_AFFINITY="0,1,2,3"`, `CYCLICTEST__CPU_AFFINITY="!1"`
`CYCLICTEST__DISTANCE`	`cyclictest.distance`	`CYCLICTEST__DISTANCE=0`
`CYCLICTEST__BREAK_THRESHOLD`	`cyclictest.break_threshold`	`CYCLICTEST__BREAK_THRESHOLD=200`
`ENABLE_NETWORK_RTT_TEST`	`enable_network_rtt_test`	`ENABLE_NETWORK_RTT_TEST=true`
`NETWORK_RTT_TEST__INTERFACE`	`network_rtt_test.interface`	`NETWORK_RTT_TEST__INTERFACE=eth0`
`NETWORK_RTT_TEST__CYCLETIME`	`network_rtt_test.cycletime`	`NETWORK_RTT_TEST__CYCLETIME=1000`
`NETWORK_RTT_TEST__PRIORITY`	`network_rtt_test.priority`	`NETWORK_RTT_TEST__PRIORITY=80`
`NETWORK_RTT_TEST__CPU_AFFINITY`	`network_rtt_test.cpu_affinity`	`NETWORK_RTT_TEST__CPU_AFFINITY=1`
`NETWORK_RTT_TEST__LOCK_MEMORY`	`network_rtt_test.lock_memory`	`NETWORK_RTT_TEST__LOCK_MEMORY=true`
`NETWORK_RTT_TEST__PREVENT_SLEEP_STATES`	`network_rtt_test.prevent_sleep_states`	`NETWORK_RTT_TEST__PREVENT_SLEEP_STATES=true`
`NETWORK_RTT_TEST__STATS_FREQUENCY`	`network_rtt_test.stats_frequency`	`NETWORK_RTT_TEST__STATS_FREQUENCY=5s`

note

A config file takes precedence over environment variables for any setting defined in both.

CLI Options​

Configuration File​

Config file reference​

Environment Variables​

CLI Options

Configuration File

Config file reference

Environment Variables