YAML Specification#
Complete reference for the thread configuration file used by agnocast_cie_thread_configurator.
Top-level Structure#
```yaml hardware_info: # Optional: validated at startup (auto-generated by --prerun) model_name: "..." cpu_family: "..."
rt_throttling: # Optional: validated against kernel settings period_us: 1000000 runtime_us: 950000
callback_groups: # Required: list of CallbackGroup configurations - id: ... ...
non_ros_threads: # Optional: list of non-ROS thread configurations - name: ... ... ```
callback_groups#
Each entry configures one CallbackGroup's thread:
| Field | Required | Description |
|---|---|---|
id |
Yes | CallbackGroup identifier (auto-generated by --prerun) |
policy |
Yes | Scheduling policy |
priority |
Yes (except SCHED_DEADLINE) |
Thread priority or nice value |
affinity |
No | List of CPU cores to pin the thread to |
domain_id |
No | ROS domain ID (defaults to the current domain) |
runtime |
SCHED_DEADLINE only |
Maximum execution time per period (ns) |
period |
SCHED_DEADLINE only |
Period length (ns) |
deadline |
SCHED_DEADLINE only |
Relative deadline from start of period (ns) |
CallbackGroup ID Format#
The id is auto-generated and composed of the node name followed by callback identifiers separated by @:
/<node_name>@<Callback1>@<Callback2>...
Callback identifiers include: Subscription(<topic>), Timer(<period_ns>), Service(<name>), Client(<name>).
Tip
Use the --prerun mode to discover the exact IDs for your application rather than constructing them manually.
Warning
If a node has multiple CallbackGroups with timers of the same period, their auto-generated IDs will collide. To avoid this, slightly offset the timer periods (e.g., 100ms and 100ms + 1ns).
Scheduling Policies#
| Policy | Priority | Description |
|---|---|---|
SCHED_FIFO |
1–99 (99 = highest) | Real-time, first-in-first-out |
SCHED_RR |
1–99 (99 = highest) | Real-time, round-robin |
SCHED_OTHER |
-20–19 (nice value) | Default Linux scheduler |
SCHED_BATCH |
-20–19 (nice value) | Batch processing |
SCHED_IDLE |
-20–19 (nice value) | Lowest priority (nice value has no practical effect) |
SCHED_DEADLINE |
N/A | Deadline-based (requires runtime, period, deadline) |
SCHED_DEADLINE#
For SCHED_DEADLINE, specify runtime, period, and deadline (in nanoseconds) instead of priority:
yaml
callback_groups:
- id: /my_node/my_deadline_group@Timer
policy: SCHED_DEADLINE
runtime: 1000000 # 1 ms
period: 10000000 # 10 ms
deadline: 10000000 # 10 ms
affinity: [2]
Note
SCHED_DEADLINE uses cgroup cpuset for CPU affinity, which requires cgroup v1. See Kernel boot parameter for setup.
Note
SCHED_DEADLINE configuration is applied after all other CallbackGroups have been configured.
non_ros_threads#
Threads not managed by the executor can also be configured. See Non-ROS Threads for how to use this feature in your application.
| Field | Required | Description |
|---|---|---|
name |
Yes | Thread name string |
policy |
Yes | Scheduling policy (same options as callback_groups) |
priority |
Yes (except SCHED_DEADLINE) |
Thread priority or nice value |
affinity |
No | List of CPU cores |
rt_throttling#
Optional section to validate that the kernel's RT throttling settings match expectations:
| Field | Description |
|---|---|
period_us |
Expected value of kernel.sched_rt_period_us |
runtime_us |
Expected value of kernel.sched_rt_runtime_us |
The configurator reports an error at startup if the current kernel values don't match. These values must be pre-configured via /etc/sysctl.d/ (see RT Throttling).
hardware_info#
Optional section for hardware validation. If present, the configurator compares these values against the current system (via lscpu) and reports an error on mismatch. The --prerun mode automatically populates this section.
| Field | Source (lscpu field) |
Example |
|---|---|---|
model_name |
Model name | "Intel(R) Core(TM) i9-12900K" |
cpu_family |
CPU family | "6" |
model |
Model | "151" |
threads_per_core |
Thread(s) per core | "2" |
frequency_boost |
Frequency boost | "enabled" or "disabled" (not all CPUs) |
cpu_max_mhz |
CPU max MHz | "5200.0000" |
cpu_min_mhz |
CPU min MHz | "800.0000" |
Full Example#
```yaml hardware_info: model_name: "Intel(R) Core(TM) i9-12900K" cpu_family: "6" model: "151" threads_per_core: "2" cpu_max_mhz: "5200.0000" cpu_min_mhz: "800.0000"
rt_throttling: period_us: 1000000 runtime_us: 950000
callback_groups: - id: /camera_node/image_cb_group@Subscription(/camera/image) policy: SCHED_FIFO priority: 90 affinity: [0, 1]
- id: /lidar_node/pointcloud_cb_group@Subscription(/lidar/points) policy: SCHED_FIFO priority: 85 affinity: [2, 3]
- id: /planning_node/planner_cb_group@Timer(100000000) policy: SCHED_DEADLINE runtime: 5000000 period: 100000000 deadline: 50000000 affinity: [4]
- id: /logging_node/default_cb_group@Subscription(/rosout) policy: SCHED_OTHER priority: 10
non_ros_threads: - name: sensor_driver policy: SCHED_FIFO priority: 95 affinity: [5] ```