YAML Specification#

Complete reference for the thread configuration file consumed by cie_thread_configurator. Prepare a single YAML file per ROS 2 application.

Top-level Structure#

hardware_info:       # Optional: validated at startup (auto-generated in prerun mode)
  model_name: ...
  cpu_family: ...

callback_groups:     # ROS 2 callback groups (IDs auto-generated in prerun mode)
  - id: ...
    ...

non_ros_threads:     # Optional: non-ROS worker threads
  - id: ...
    ...

There are two configuration sections: callback_groups for ROS 2 callback groups and non_ros_threads for non-ROS worker threads (see Non-ROS Threads). The CallbackGroup IDs are generated automatically by the tool in prerun mode.

callback_groups#

Each entry configures one CallbackGroup's OS thread:

Field	Required	Description
`id`	Yes	CallbackGroup identifier (auto-generated in prerun mode)
`policy`	Yes	Scheduling policy
`priority`	Yes (except `SCHED_DEADLINE`)	Real-time priority or nice value, depending on policy
`affinity`	No	List of CPU cores the thread may run on
`runtime`	`SCHED_DEADLINE` only	Maximum execution time per period (ns)
`deadline`	`SCHED_DEADLINE` only	Relative deadline from the start of the period (ns)
`period`	`SCHED_DEADLINE` only	Period length (ns)

affinity#

affinity is an array of core numbers allowed to run the thread, corresponding to the CPU set used with sched_setaffinity(2). Leaving the array empty (or ~) allows the thread to run on all cores.

affinity:
  - 0
  - 1

Scheduling policies#

Policy	Scheduler	`priority` meaning
`SCHED_OTHER`	CFS	nice value, `-20` (highest) … `19` (lowest)
`SCHED_BATCH`	CFS	nice value, `-20` (highest) … `19` (lowest)
`SCHED_IDLE`	CFS (idle)	nice value (accepted, but has little practical effect)
`SCHED_FIFO`	FIFO	`99` (highest) … `1` (lowest)
`SCHED_RR`	round-robin	`99` (highest) … `1` (lowest)
`SCHED_DEADLINE`	EDF	not used — set `runtime` / `deadline` / `period` instead

The configurable items differ depending on which scheduler the thread runs on.

CFS (`SCHED_OTHER`, `SCHED_BATCH`, `SCHED_IDLE`)#

For threads on the CFS, priority is the nice value, ranging from -20 (highest priority) to 19 (lowest priority):

  - id: xxxxx
    affinity:
      - 0
      - 1
    policy: SCHED_OTHER
    priority: -10

SCHED_IDLE is the lowest-priority background class — its threads run only when no other thread on the CPU is runnable. A priority (nice) value is still required, but it has little practical effect.

FIFO scheduler (`SCHED_FIFO`, `SCHED_RR`)#

For threads on the FIFO scheduler, priority ranges from 99 (highest) to 1 (lowest). This range corresponds to the return values of sched_get_priority_max(2) and sched_get_priority_min(2), which on Linux are 99 and 1:

  - id: xxxxx
    affinity:
      - 0
      - 1
    policy: SCHED_FIFO
    priority: 50

EDF scheduler (`SCHED_DEADLINE`)#

For threads on the EDF scheduler, specify runtime, deadline, and period (in nanoseconds) instead of priority:

  - id: xxxxx
    affinity:
      - 0
      - 1
    policy: SCHED_DEADLINE
    runtime: 10000000
    deadline: 10000000
    period: 20000000

Note

SCHED_DEADLINE uses cgroup cpuset for CPU affinity, which requires cgroup v1. See Kernel boot parameter for setup, and note that the configurator must run as root when any group uses SCHED_DEADLINE.

CallbackGroup ID Format#

In the YAML template generated by cie_thread_configurator, CallbackGroup IDs are generated automatically. An ID consists of multiple strings separated by @:

/<node_name>@<Callback1>@<Callback2>...

The first element is the ROS 2 node name including its namespace. Each subsequent element identifies a callback contained in the CallbackGroup. There are four callback types:

Subscription(<topic name>)
Service(<service name>)
Client(<service name>)
Timer(<period in nanoseconds>)

For example:

callback_groups:
  - id: /sample_node@Subscription(/topic_in)
    affinity: ~
    policy: SCHED_OTHER
    priority: 0

  - id: /sample_node@Timer(1333000000)
    affinity: ~
    policy: SCHED_OTHER
    priority: 0

Warning

Timers with the same period cannot be distinguished from one another. If differentiation is needed, slightly adjust one period (for example by 1ns).

Note

rclcpp::Waitable callbacks are not included in the CallbackGroup ID. For backward compatibility, a trailing @Waitable in an existing configuration is ignored when the file is loaded.

non_ros_threads#

Threads that are not part of any ROS 2 executor can also be configured. The fields match callback_groups except that id is the thread name (see Non-ROS Threads for how to create such threads):

Field	Required	Description
`id`	Yes	Thread name (must match the name passed to `spawn_non_ros2_thread`)
`policy`	Yes	Scheduling policy (same options as `callback_groups`)
`priority`	Yes (except `SCHED_DEADLINE`)	Real-time priority or nice value
`affinity`	No	List of CPU cores

non_ros_threads:
  - id: worker_thread_name
    affinity:
      - 4
    policy: SCHED_OTHER
    priority: 0

hardware_info#

Optional section for hardware validation. When present, the configurator compares these values against the current system (via lscpu) at startup and reports an error on mismatch. Prerun mode populates this section automatically.

Field	Source (`lscpu`)	Example
`model_name`	Model name	`Intel(R) Xeon(R) Silver 4216 CPU @ 2.10GHz`
`cpu_family`	CPU family	`6`
`model`	Model	`85`
`threads_per_core`	Thread(s) per core	`1`
`frequency_boost`	Frequency boost	`enabled` / `disabled` (not present on all CPUs)
`cpu_max_mhz`	CPU max MHz	`2101.0000`
`cpu_min_mhz`	CPU min MHz	`800.0000`

Full Example#

hardware_info:
  model_name: Intel(R) Xeon(R) Silver 4216 CPU @ 2.10GHz
  cpu_family: 6
  model: 85
  threads_per_core: 1
  frequency_boost: enabled
  cpu_max_mhz: 2101.0000
  cpu_min_mhz: 800.0000

callback_groups:
  - id: /camera_node@Subscription(/camera/image)
    policy: SCHED_FIFO
    priority: 90
    affinity:
      - 0
      - 1

  - id: /planning_node@Timer(100000000)
    policy: SCHED_DEADLINE
    runtime: 5000000
    deadline: 50000000
    period: 100000000
    affinity:
      - 4

  - id: /logging_node@Subscription(/rosout)
    policy: SCHED_OTHER
    priority: 10

non_ros_threads:
  - id: sensor_driver
    policy: SCHED_FIFO
    priority: 85
    affinity:
      - 5