You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
docs: stop advertising Terra in the public tree - #217
Terra is private and not ready to be public, so this removes horus's pointers to it, without breaking manifests that already use the legacy key.
Removed
The link to github.com/softmata/terra and the "Terra HAL" name from README.md, examples/README.md, examples/driver_integration/{README.md,main.rs,horus.toml}.
The driver examples now use the unified use = "..." source key (the fallback chain reads it first).
The stale hint "Call register!() or terra_horus::register_all() first" — terra_horus is not a horus dependency. New text names register_driver!(). The horus-docs page that quotes the message is updated in a paired docs PR.
Terra-named prose in horus_core/src/drivers/mod.rs, horus_manager/src/{manifest,cargo_gen,native_sync}.rs, commands/{pkg,run/features}.rs.
Kept, deliberately
The legacy terra = "..." manifest key still parses (DriverTableConfig::terra + horus_core's fallback chain) and keeps its tests, because existing horus.toml files use it. What changed is only the wording: the schema and docs describe it as "legacy driver shortname", not by product name.
A paired horus-docs PR updates the quoted error string, the "Terra HAL" wording and regenerates public/schema/horus.toml.schema.json from this change. It should merge after this one.
Terra's repository is private and not ready to be public, so horus should
not point users at it. Removed:
- the link to github.com/softmata/terra and the "Terra HAL" name from the
README, examples/README.md and the driver_integration docs and comments
- the driver examples now use the unified `use = "..."` source key
- the stale "Call register!() or terra_horus::register_all() first" hint
(that function is not part of horus); the docs page that quotes the
message is updated separately in horus-docs
- Terra-named prose in horus_core/horus_manager comments
Kept deliberately: the legacy `terra = "..."` manifest key still parses
(DriverTableConfig::terra and horus_core's fallback chain) with its tests,
because existing horus.toml files use it. Its schema/doc descriptions now
read "legacy driver shortname" instead of naming Terra.
Blocking metrics: median, p99/median. Report-only: p95, p99, p99.9, p99.99, max, max_jitter, p99.9/median, ns/msg. Tail metrics past p99.9 are advisory on a shared runner — one host preemption owns max.
Raw benchmark output
99.1 23548.0 | 996 100
leg A->B (apparent) 1000000 98.1 138.2 198.3 1090.1 10066.5 46242.6 | 998 100
leg B->A (apparent) 1000000 101.8 141.9 212.2 282.6 8677.4 28083.0 | 951 99
responder turnaround 1000000 29.9 30.3 40.1 40.1 160.3 23162.2 | 222 99
------------------------------------------------------------------------------------------------------------------------------------------
samples=1000000 warmup=200000 transferred=2000000 lost=0 invalid(TSC-skew)=0 poll cost=12.3 ns window=0.380 s
measured window: minor_faults=0 major_faults=0 ctx_switches vol=75 invol=5
core freq cpu3 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
core freq cpu1 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
cross-core TSC offset theta_hat = -1.8 ns (clock B - clock A). The `one-way, offset-free` row does not depend on it.
== cross-process ping-pong -- ONE-WAY LATENCY (2 processes, 2 topics, 1 role per handle) ==
json metric key: `Topic_cross_process_oneway_pingpong` (identity used by the CI gate: `Topic_cross_process_oneway_pingpong@1024B`)
payload Probe1k = 1024 B (POD=true) | ring capacity 256 slots | topology 1P/1C | cpu3 <-> cpu1 | pid 7559 <-> pid 7569
------------------------------------------------------------------------------------------------------------------------------------------
metric (ns) n min median p99 p99.9 p99.99 max | n>p99.9 n>p99.99
------------------------------------------------------------------------------------------------------------------------------------------
one-way, offset-free 1000000 195.0 270.3 400.3 1307.3 10674.1 85129.7 | 1000 100
round trip (RTT) 1000000 430.6 571.2 831.3 2754.8 21569.5 170290.0 | 1000 100
RTT halved (one-way) 1000000 215.3 285.6 415.7 1377.4 10784.7 85145.0 | 1000 100
leg A->B (apparent) 1000000 168.5 248.6 438.8 1260.7 20054.5 169917.5 | 999 99
leg B->A (apparent) 1000000 182.0 282.1 452.7 622.8 10951.8 32621.0 | 997 100
responder turnaround 1000000 29.9 30.3 40.1 40.1 160.3 24103.9 | 475 100
------------------------------------------------------------------------------------------------------------------------------------------
samples=1000000 warmup=200000 transferred=2000000 lost=0 invalid(TSC-skew)=0 poll cost=38.8 ns window=0.671 s
measured window: minor_faults=0 major_faults=0 ctx_switches vol=132 invol=3
core freq cpu3 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
core freq cpu1 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
cross-core TSC offset theta_hat = -16.8 ns (clock B - clock A). The `one-way, offset-free` row does not depend on it.
== cross-process paced stream -- ONE-WAY LATENCY (10000 ns publish period, publisher -> subscriber, direct) ==
json metric key: `Topic_cross_process_oneway_paced_stream` (identity used by the CI gate: `Topic_cross_process_oneway_paced_stream@64B`)
payload Probe64 = 64 B (POD=true) | ring capacity 256 slots | topology 1P/1C | cpu3 <-> cpu1 | pid 7559 <-> pid 7571
------------------------------------------------------------------------------------------------------------------------------------------
metric (ns) n min median p99 p99.9 p99.99 max | n>p99.9 n>p99.99
------------------------------------------------------------------------------------------------------------------------------------------
one-way (assumes TSC coherence) 200000 112.0 152.1 402.4 3768.5 15199.5 35165.7 | 200 20
------------------------------------------------------------------------------------------------------------------------------------------
samples=200000 warmup=20000 transferred=200000 lost=0 invalid(TSC-skew)=0 poll cost=8.6 ns window=2.000 s
measured backlog: 0.02 messages deep on the median sample (ring holds 256); delivered 100.0% of transferred
measured window: minor_faults=0 major_faults=0 ctx_switches vol=393 invol=16
core freq cpu3 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
core freq cpu1 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
this row assumes cross-core TSC coherence; theta_hat measured in the ping-pong at this size = -1.8 ns (add to correct).
== cross-process paced stream -- ONE-WAY LATENCY (10000 ns publish period, publisher -> subscriber, direct) ==
json metric key: `Topic_cross_process_oneway_paced_stream` (identity used by the CI gate: `Topic_cross_process_oneway_paced_stream@1024B`)
payload Probe1k = 1024 B (POD=true) | ring capacity 256 slots | topology 1P/1C | cpu3 <-> cpu1 | pid 7559 <-> pid 7574
------------------------------------------------------------------------------------------------------------------------------------------
metric (ns) n min median p99 p99.9 p99.99 max | n>p99.9 n>p99.99
------------------------------------------------------------------------------------------------------------------------------------------
one-way (assumes TSC coherence) 200000 192.2 252.3 643.2 4900.8 14728.9 23364.2 | 200 20
------------------------------------------------------------------------------------------------------------------------------------------
samples=200000 warmup=20000 transferred=200000 lost=0 invalid(TSC-skew)=0 poll cost=20.0 ns window=2.000 s
measured backlog: 0.03 messages deep on the median sample (ring holds 256); delivered 100.0% of transferred
measured window: minor_faults=0 major_faults=0 ctx_switches vol=393 invol=14
core freq cpu3 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
core freq cpu1 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
this row assumes cross-core TSC coherence; theta_hat measured in the ping-pong at this size = -16.8 ns (add to correct).
== cross-process unpaced stream -- QUEUE DELAY / BACKPRESSURE, NOT LATENCY (publisher unthrottled; each sample includes its wait in the ring) ==
!! Every number in this block is a PUBLISH-TO-RECEIVE DELAY that INCLUDES
!! time spent waiting in the ring. It is a backpressure/throughput figure.
!! Do not quote it as an IPC latency; that is the exact mistake the retired
!! `Topic_cross_process` metric shipped for months. Read `measured backlog`
!! below: ~1 message means the subscriber kept up and no queue formed.
json metric key: `Topic_cross_process_unpaced_queue_delay` (identity used by the CI gate: `Topic_cross_process_unpaced_queue_delay@64B`)
payload Probe64 = 64 B (POD=true) | ring capacity 256 slots | topology 1P/1C | cpu3 <-> cpu1 | pid 7559 <-> pid 7577
------------------------------------------------------------------------------------------------------------------------------------------
metric (ns) n min median p99 p99.9 p99.99 max | n>p99.9 n>p99.99
------------------------------------------------------------------------------------------------------------------------------------------
publish->receive incl. queue 200000 102.2 142.3 222.0 5010.8 8717.5 42248.8 | 200 19
------------------------------------------------------------------------------------------------------------------------------------------
samples=200000 warmup=20000 transferred=200000 lost=0 invalid(TSC-skew)=0 poll cost=23.7 ns window=0.021 s
measured backlog: 1.38 messages deep on the median sample (ring holds 256); delivered 100.0% of transferred
measured window: minor_faults=0 major_faults=0 ctx_switches vol=4 invol=0
core freq cpu3 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
core freq cpu1 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
this row assumes cross-core TSC coherence; theta_hat measured in the ping-pong at this size = -1.8 ns (add to correct).
SUMMARY — one row per published JSON metric (nanoseconds, wall clock)
------------------------------------------------------------------------------------------------------------------------------------------
json metric key what it measures n median p99 p99.9 p99.99 max
------------------------------------------------------------------------------------------------------------------------------------------
Topic_cross_process_oneway_pingpong@64B ONE-WAY latency 1000000 139.8 190.1 675.9 7588.9 23527.7
Topic_cross_process_oneway_pingpong@1024B ONE-WAY latency 1000000 270.3 400.3 1307.3 10674.1 85129.7
Topic_cross_process_oneway_paced_stream@64B ONE-WAY latency 200000 152.1 402.4 3768.5 15199.5 35165.7
Topic_cross_process_oneway_paced_stream@1024B ONE-WAY latency 200000 252.3 643.2 4900.8 14728.9 23364.2
Topic_cross_process_unpaced_queue_delay@64B QUEUE DELAY (not latency) 200000 142.3 222.0 5010.8 8717.5 42248.8
------------------------------------------------------------------------------------------------------------------------------------------
Instrumentation is INCLUDED in every figure and never subtracted.
`Topic_cross_process_oneway_pingpong` is the true one-way figure: it assumes
nothing about cross-core TSC synchronisation and excludes the responder's turnaround.
`RTT halved (one-way)` in the per-scenario tables is a ROUND TRIP DIVIDED BY TWO; it is
the row to compare against any competitor publishing a halved ping-pong.
`Topic_cross_process_unpaced_queue_delay` is a BACKPRESSURE figure: it includes
however long the message waited in the ring, so it scales with the achieved backlog
(printed in its scenario block) and is NOT a latency.
A figure without its payload size, ring depth and topology is not comparable to anything.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! THE SAME WARNINGS AGAIN — they apply to every number above
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! CPU governor is ?/?, not `performance`. RDTSC is a wall clock while the work costs a fixed number of CORE cycles, so every nanosecond below scales with a frequency the governor is free to change. iceoryx2's maintainers measured ~300 ns of difference from the governor alone.
!! No isolcpus= on the kernel command line: the benchmark cores are shared with everything else on this box. The involuntary context-switch count in each scenario block is the mechanism behind the far tail.
!! paced_stream (64 B) `one-way (assumes TSC coherence)`: p99.99 rests on 20 observations. Below ~100 exceedances it is a max wearing a percentile's name; +/-5% needs ~400 (--iterations 4000000).
!! paced_stream (1024 B) `one-way (assumes TSC coherence)`: p99.99 rests on 20 observations. Below ~100 exceedances it is a max wearing a percentile's name; +/-5% needs ~400 (--iterations 4000000).
!! unpaced_queue (64 B): measured backlog is only 1.38 messages — the subscriber kept up, so the ring never filled and `Topic_cross_process_unpaced_queue_delay` is NOT a backpressure figure on this run. It is a publish-to-receive delay with no queueing in it, and it is still not a latency (see the paced and ping-pong rows for that).
!! unpaced_queue (64 B) `publish->receive incl. queue`: p99.99 rests on 19 observations. Below ~100 exceedances it is a max wearing a percentile's name; +/-5% needs ~400 (--iterations 4000000).
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Gate report written to /home/runner/work/horus/horus/benchmarks/gate-reports/cross_process-2.json
keys: Topic_cross_process_oneway_pingpong@64B, Topic_cross_process_oneway_pingpong@1024B, Topic_cross_process_oneway_paced_stream@64B, Topic_cross_process_oneway_paced_stream@1024B, Topic_cross_process_unpaced_queue_delay@64B
NOTE: `Topic_cross_process` is retired. A baseline window that still holds it
will report it as missing and fail the gate until the window is refreshed —
that is intended, and is why the key was not silently reused.
Raw samples are omitted (pass --raw-in-json, or --raw-dir for a lossless cycle dump).
6 warning(s) apply to these numbers and are NOT in this file; use --detail-json.
╔══════════════════════════════════════════════════════════════════╗
║ HORUS Robotics Message Types Benchmark ║
╠══════════════════════════════════════════════════════════════════╣
║ Testing real-world robotics message latency (REP 2014) ║
╚══════════════════════════════════════════════════════════════════╝
Platform: AMD EPYC 7763 64-Core Processor (4 cores)
Iterations: 50000
Warmup: 5000
╔═════════════════════════════════════════════════════════════════════════════╗
║ Message Type │ Size (bytes) │ Typical Rate │ Use Case ║
╠═════════════════════════════════════════════════════════════════════════════╣
║ CmdVel │ 16 │ 1000+ Hz │ Velocity control commands ║
║ Imu │ 296 │ 500+ Hz │ IMU sensor fusion ║
║ LaserScan │ 1480 │ 10-40 Hz │ 2D lidar navigation ║
║ JointCommand │ 1032 │ 500+ Hz │ Manipulator control ║
╚═════════════════════════════════════════════════════════════════════════════╝
[Topic] Running benchmarks — timing tx.send() enqueue cost only
(cross-thread consumer drains in the background; no sample
waits for delivery, so these are NOT end-to-end latencies)
─────────────────────────────────────────────────
CmdVel 16 bytes │ median: 40ns │ p99: 69ns │ CV: 2.8298
Imu 304 bytes │ median: 40ns │ p99: 89ns │ CV: 1.3134
LaserScan 1480 bytes │ median: 89ns │ p99: 150ns │ CV: 2.4791
JointCommand 928 bytes │ median: 80ns │ p99: 130ns │ CV: 1.9344
╔══════════════════════════════════════════════════════════════════════════════════════════╗
║ SUMMARY BY MESSAGE TYPE — send() ENQUEUE COST, not end-to-end latency ║
╠══════════════════════════════════════════════════════════════════════════════════════════╣
║ Message │ Size │ Median (ns) │ p99 (ns) │ CV │ Misses │ Sustained rate ║
╠══════════════════════════════════════════════════════════════════════════════════════════╣
║ CmdVel │ 16 │ 40 │ 69 │ 2.8298 │ 0 │ 5.90 M msg/s ║
║ Imu │ 304 │ 40 │ 89 │ 1.3134 │ 0 │ 3.62 M msg/s ║
║ LaserScan │ 1480 │ 89 │ 150 │ 2.4791 │ 0 │ 1.45 M msg/s ║
║ JointCommand │ 928 │ 80 │ 130 │ 1.9344 │ 0 │ 2.93 M msg/s ║
╚══════════════════════════════════════════════════════════════════════════════════════════╝
Sustained rate is wall-clock over the measured loop, so it includes the batch
drain-waits. It is a publish rate for this producer/consumer pair, not a bus limit.
╔══════════════════════════════════════════════════════════════════╗
║ REAL-TIME SUITABILITY ANALYSIS ║
╠══════════════════════════════════════════════════════════════════╣
║ These gates grade the p99 of the send() ENQUEUE COST against one ║
║ whole control period. They are not end-to-end control-loop ║
║ guarantees: a real loop also pays the receive side, the node's ║
║ compute, and the scheduler's jitter, none of which is measured ║
║ here. The headroom is printed so a pass by four orders of ║
║ magnitude cannot be read as a tight result. ║
╠══════════════════════════════════════════════════════════════════╣
║ CmdVel (1kHz control): ~ PASS by 14493x — gate not discriminating (p99=69ns vs 1000000ns)
║ CmdVel (10kHz control): ~ PASS by 1449x — gate not discriminating (p99=69ns vs 100000ns)
║ Imu (500Hz fusion) : ~ PASS by 22472x — gate not discriminating (p99=89ns vs 2000000ns)
║ LaserScan (40Hz lidar) : ~ PASS by 166667x — gate not discriminating (p99=150ns vs 25000000ns)
║ JointCmd (500Hz control): ~ PASS by 15385x — gate not discriminating (p99=130ns vs 2000000ns)
╚══════════════════════════════════════════════════════════════════╝
Results written to: /home/runner/work/horus/horus/benchmarks/gate-reports/robotics-2.json
===== repetition 3/3 =====
HORUS cross-process benchmark — ONE-WAY LATENCY (headline) + unpaced queue delay
Two OS processes on two distinct physical cores over the real Topic SHM transport.
Every handle holds exactly one role, so the `role == Both` same-thread fast path that
produces the repo's headline send-cost figure is never taken. Round-trip rows are
labelled where they are a halved round trip. See the module header for the clock
decomposition and for why the `Topic_cross_process` JSON key was retired.
MACHINE — every nanosecond below is conditional on this block
------------------------------------------------------------------------------------------------------------------------------------------
cpu model : AMD EPYC 7763 64-Core Processor (2 physical / 4 logical cores)
kernel : 6.17.0-1022-azure (x86_64)
benchmark cores : cpu3 = process A (pinger / subscriber), cpu1 = process B (responder / publisher) [DistinctPhysical]
governor : cpu3=n/a cpu1=n/a driver=n/a
scaling range : n/a .. n/a (hw max n/a) turbo_disabled=unknown
clocksource : tsc tsc flags: [tsc, rdtscp, constant_tsc, tsc_reliable, nonstop_tsc]
TSC rate (calibrated) : 2445.515 MHz (0.4089 ns/cycle) — a WALL clock; NOT the core clock
clock instrumentation : 49 cycles = 20.0 ns for serialize()+rdtsc()+rdtscp(), INCLUDED in every sample and never subtracted
transparent_hugepage : [always] madvise never
sched_rt_runtime/period: 950000 / 1000000 us perf_event_paranoid=4
isolcpus=(none) nohz_full=(none) smt_active=1 mlockall(MCL_CURRENT)=true
------------------------------------------------------------------------------------------------------------------------------------------
running ping-pong (one-way latency), 64 B payload ...
running ping-pong (one-way latency), 1024 B payload ...
running paced stream (one-way latency), 64 B payload ...
running paced stream (one-way latency), 1024 B payload ...
running unpaced stream (QUEUE DELAY, not latency), 64 B payload ...
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! READ THIS BEFORE QUOTING ANY NUMBER BELOW
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! CPU governor is ?/?, not `performance`. RDTSC is a wall clock while the work costs a fixed number of CORE cycles, so every nanosecond below scales with a frequency the governor is free to change. iceoryx2's maintainers measured ~300 ns of difference from the governor alone.
!! No isolcpus= on the kernel command line: the benchmark cores are shared with everything else on this box. The involuntary context-switch count in each scenario block is the mechanism behind the far tail.
!! paced_stream (64 B) `one-way (assumes TSC coherence)`: p99.99 rests on 20 observations. Below ~100 exceedances it is a max wearing a percentile's name; +/-5% needs ~400 (--iterations 4000000).
!! paced_stream (1024 B) `one-way (assumes TSC coherence)`: p99.99 rests on 20 observations. Below ~100 exceedances it is a max wearing a percentile's name; +/-5% needs ~400 (--iterations 4000000).
!! unpaced_queue (64 B): measured backlog is only 1.42 messages — the subscriber kept up, so the ring never filled and `Topic_cross_process_unpaced_queue_delay` is NOT a backpressure figure on this run. It is a publish-to-receive delay with no queueing in it, and it is still not a latency (see the paced and ping-pong rows for that).
!! unpaced_queue (64 B) `publish->receive incl. queue`: p99.99 rests on 19 observations. Below ~100 exceedances it is a max wearing a percentile's name; +/-5% needs ~400 (--iterations 4000000).
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
== cross-process ping-pong -- ONE-WAY LATENCY (2 processes, 2 topics, 1 role per handle) ==
json metric key: `Topic_cross_process_oneway_pingpong` (identity used by the CI gate: `Topic_cross_process_oneway_pingpong@64B`)
payload Probe64 = 64 B (POD=true) | ring capacity 256 slots | topology 1P/1C | cpu3 <-> cpu1 | pid 7604 <-> pid 7612
------------------------------------------------------------------------------------------------------------------------------------------
metric (ns) n min median p99 p99.9 p99.99 max | n>p99.9 n>p99.99
------------------------------------------------------------------------------------------------------------------------------------------
one-way, offset-free 1000000 110.0 140.3 185.2 711.1 7293.4 18794.4 | 986 100
round trip (RTT) 1000000 260.5 310.8 400.7 1472.5 15207.8 39001.6 | 995 100
RTT halved (one-way) 1000000 130.2 155.4 200.4 736.2 7603.9 19500.8 | 995 100
leg A->B (apparent) 1000000 87.9 128.0 178.3 1109.8 8713.9 24071.8 | 961 100
leg B->A (apparent) 1000000 122.3 152.5 212.6 343.1 8758.1 37450.6 | 994 100
responder turnaround 1000000 29.9 30.3 40.1 40.1 160.3 38640.5 | 201 94
------------------------------------------------------------------------------------------------------------------------------------------
samples=1000000 warmup=200000 transferred=2000000 lost=0 invalid(TSC-skew)=0 poll cost=12.7 ns window=0.384 s
measured window: minor_faults=0 major_faults=0 ctx_switches vol=75 invol=4
core freq cpu3 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
core freq cpu1 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
cross-core TSC offset theta_hat = -12.3 ns (clock B - clock A). The `one-way, offset-free` row does not depend on it.
== cross-process ping-pong -- ONE-WAY LATENCY (2 processes, 2 topics, 1 role per handle) ==
json metric key: `Topic_cross_process_oneway_pingpong` (identity used by the CI gate: `Topic_cross_process_oneway_pingpong@1024B`)
payload Probe1k = 1024 B (POD=true) | ring capacity 256 slots | topology 1P/1C | cpu3 <-> cpu1 | pid 7604 <-> pid 7614
------------------------------------------------------------------------------------------------------------------------------------------
metric (ns) n min median p99 p99.9 p99.99 max | n>p99.9 n>p99.99
------------------------------------------------------------------------------------------------------------------------------------------
one-way, offset-free 1000000 195.1 265.4 395.4 1407.5 10929.8 18569.1 | 999 100
round trip (RTT) 1000000 420.8 570.8 821.5 2955.2 22050.6 37168.0 | 999 100
RTT halved (one-way) 1000000 210.4 285.4 410.8 1477.6 11025.3 18584.0 | 999 100
leg A->B (apparent) 1000000 168.1 238.4 408.5 1290.1 20405.1 36825.4 | 991 100
leg B->A (apparent) 1000000 182.4 283.0 462.9 1204.7 10361.0 26611.2 | 998 100
responder turnaround 1000000 29.9 30.3 40.1 40.1 240.4 29073.2 | 383 99
------------------------------------------------------------------------------------------------------------------------------------------
samples=1000000 warmup=200000 transferred=2000000 lost=0 invalid(TSC-skew)=0 poll cost=38.0 ns window=0.669 s
measured window: minor_faults=0 major_faults=0 ctx_switches vol=131 invol=2
core freq cpu3 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
core freq cpu1 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
cross-core TSC offset theta_hat = -22.3 ns (clock B - clock A). The `one-way, offset-free` row does not depend on it.
== cross-process paced stream -- ONE-WAY LATENCY (10000 ns publish period, publisher -> subscriber, direct) ==
json metric key: `Topic_cross_process_oneway_paced_stream` (identity used by the CI gate: `Topic_cross_process_oneway_paced_stream@64B`)
payload Probe64 = 64 B (POD=true) | ring capacity 256 slots | topology 1P/1C | cpu3 <-> cpu1 | pid 7604 <-> pid 7616
------------------------------------------------------------------------------------------------------------------------------------------
metric (ns) n min median p99 p99.9 p99.99 max | n>p99.9 n>p99.99
------------------------------------------------------------------------------------------------------------------------------------------
one-way (assumes TSC coherence) 200000 122.3 162.7 473.1 1995.9 13166.6 29576.2 | 200 20
------------------------------------------------------------------------------------------------------------------------------------------
samples=200000 warmup=20000 transferred=200000 lost=0 invalid(TSC-skew)=0 poll cost=8.6 ns window=2.000 s
measured backlog: 0.02 messages deep on the median sample (ring holds 256); delivered 100.0% of transferred
measured window: minor_faults=0 major_faults=0 ctx_switches vol=393 invol=17
core freq cpu3 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
core freq cpu1 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
this row assumes cross-core TSC coherence; theta_hat measured in the ping-pong at this size = -12.3 ns (add to correct).
== cross-process paced stream -- ONE-WAY LATENCY (10000 ns publish period, publisher -> subscriber, direct) ==
json metric key: `Topic_cross_process_oneway_paced_stream` (identity used by the CI gate: `Topic_cross_process_oneway_paced_stream@1024B`)
payload Probe1k = 1024 B (POD=true) | ring capacity 256 slots | topology 1P/1C | cpu3 <-> cpu1 | pid 7604 <-> pid 7618
------------------------------------------------------------------------------------------------------------------------------------------
metric (ns) n min median p99 p99.9 p99.99 max | n>p99.9 n>p99.99
------------------------------------------------------------------------------------------------------------------------------------------
one-way (assumes TSC coherence) 200000 202.4 262.5 803.9 10231.0 22613.6 41227.7 | 200 20
------------------------------------------------------------------------------------------------------------------------------------------
samples=200000 warmup=20000 transferred=200000 lost=0 invalid(TSC-skew)=0 poll cost=20.0 ns window=2.000 s
measured backlog: 0.03 messages deep on the median sample (ring holds 256); delivered 100.0% of transferred
measured window: minor_faults=0 major_faults=0 ctx_switches vol=393 invol=12
core freq cpu3 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
core freq cpu1 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
this row assumes cross-core TSC coherence; theta_hat measured in the ping-pong at this size = -22.3 ns (add to correct).
== cross-process unpaced stream -- QUEUE DELAY / BACKPRESSURE, NOT LATENCY (publisher unthrottled; each sample includes its wait in the ring) ==
!! Every number in this block is a PUBLISH-TO-RECEIVE DELAY that INCLUDES
!! time spent waiting in the ring. It is a backpressure/throughput figure.
!! Do not quote it as an IPC latency; that is the exact mistake the retired
!! `Topic_cross_process` metric shipped for months. Read `measured backlog`
!! below: ~1 message means the subscriber kept up and no queue formed.
json metric key: `Topic_cross_process_unpaced_queue_delay` (identity used by the CI gate: `Topic_cross_process_unpaced_queue_delay@64B`)
payload Probe64 = 64 B (POD=true) | ring capacity 256 slots | topology 1P/1C | cpu3 <-> cpu1 | pid 7604 <-> pid 7622
------------------------------------------------------------------------------------------------------------------------------------------
metric (ns) n min median p99 p99.9 p99.99 max | n>p99.9 n>p99.99
------------------------------------------------------------------------------------------------------------------------------------------
publish->receive incl. queue 200000 122.3 152.5 252.7 3448.8 8858.7 36479.0 | 200 19
------------------------------------------------------------------------------------------------------------------------------------------
samples=200000 warmup=20000 transferred=200000 lost=0 invalid(TSC-skew)=0 poll cost=29.0 ns window=0.021 s
measured backlog: 1.42 messages deep on the median sample (ring holds 256); delivered 100.0% of transferred
measured window: minor_faults=0 major_faults=0 ctx_switches vol=4 invol=0
core freq cpu3 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
core freq cpu1 (measured window only): start=n/a end=n/a min=0MHz max=0MHz mean=0MHz spread=0.00% (n=0)
this row assumes cross-core TSC coherence; theta_hat measured in the ping-pong at this size = -12.3 ns (add to correct).
SUMMARY — one row per published JSON metric (nanoseconds, wall clock)
------------------------------------------------------------------------------------------------------------------------------------------
json metric key what it measures n median p99 p99.9 p99.99 max
------------------------------------------------------------------------------------------------------------------------------------------
Topic_cross_process_oneway_pingpong@64B ONE-WAY latency 1000000 140.3 185.2 711.1 7293.4 18794.4
Topic_cross_process_oneway_pingpong@1024B ONE-WAY latency 1000000 265.4 395.4 1407.5 10929.8 18569.1
Topic_cross_process_oneway_paced_stream@64B ONE-WAY latency 200000 162.7 473.1 1995.9 13166.6 29576.2
Topic_cross_process_oneway_paced_stream@1024B ONE-WAY latency 200000 262.5 803.9 10231.0 22613.6 41227.7
Topic_cross_process_unpaced_queue_delay@64B QUEUE DELAY (not latency) 200000 152.5 252.7 3448.8 8858.7 36479.0
------------------------------------------------------------------------------------------------------------------------------------------
Instrumentation is INCLUDED in every figure and never subtracted.
`Topic_cross_process_oneway_pingpong` is the true one-way figure: it assumes
nothing about cross-core TSC synchronisation and excludes the responder's turnaround.
`RTT halved (one-way)` in the per-scenario tables is a ROUND TRIP DIVIDED BY TWO; it is
the row to compare against any competitor publishing a halved ping-pong.
`Topic_cross_process_unpaced_queue_delay` is a BACKPRESSURE figure: it includes
however long the message waited in the ring, so it scales with the achieved backlog
(printed in its scenario block) and is NOT a latency.
A figure without its payload size, ring depth and topology is not comparable to anything.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! THE SAME WARNINGS AGAIN — they apply to every number above
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! CPU governor is ?/?, not `performance`. RDTSC is a wall clock while the work costs a fixed number of CORE cycles, so every nanosecond below scales with a frequency the governor is free to change. iceoryx2's maintainers measured ~300 ns of difference from the governor alone.
!! No isolcpus= on the kernel command line: the benchmark cores are shared with everything else on this box. The involuntary context-switch count in each scenario block is the mechanism behind the far tail.
!! paced_stream (64 B) `one-way (assumes TSC coherence)`: p99.99 rests on 20 observations. Below ~100 exceedances it is a max wearing a percentile's name; +/-5% needs ~400 (--iterations 4000000).
!! paced_stream (1024 B) `one-way (assumes TSC coherence)`: p99.99 rests on 20 observations. Below ~100 exceedances it is a max wearing a percentile's name; +/-5% needs ~400 (--iterations 4000000).
!! unpaced_queue (64 B): measured backlog is only 1.42 messages — the subscriber kept up, so the ring never filled and `Topic_cross_process_unpaced_queue_delay` is NOT a backpressure figure on this run. It is a publish-to-receive delay with no queueing in it, and it is still not a latency (see the paced and ping-pong rows for that).
!! unpaced_queue (64 B) `publish->receive incl. queue`: p99.99 rests on 19 observations. Below ~100 exceedances it is a max wearing a percentile's name; +/-5% needs ~400 (--iterations 4000000).
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Gate report written to /home/runner/work/horus/horus/benchmarks/gate-reports/cross_process-3.json
keys: Topic_cross_process_oneway_pingpong@64B, Topic_cross_process_oneway_pingpong@1024B, Topic_cross_process_oneway_paced_stream@64B, Topic_cross_process_oneway_paced_stream@1024B, Topic_cross_process_unpaced_queue_delay@64B
NOTE: `Topic_cross_process` is retired. A baseline window that still holds it
will report it as missing and fail the gate until the window is refreshed —
that is intended, and is why the key was not silently reused.
Raw samples are omitted (pass --raw-in-json, or --raw-dir for a lossless cycle dump).
6 warning(s) apply to these numbers and are NOT in this file; use --detail-json.
╔══════════════════════════════════════════════════════════════════╗
║ HORUS Robotics Message Types Benchmark ║
╠══════════════════════════════════════════════════════════════════╣
║ Testing real-world robotics message latency (REP 2014) ║
╚══════════════════════════════════════════════════════════════════╝
Platform: AMD EPYC 7763 64-Core Processor (4 cores)
Iterations: 50000
Warmup: 5000
╔═════════════════════════════════════════════════════════════════════════════╗
║ Message Type │ Size (bytes) │ Typical Rate │ Use Case ║
╠═════════════════════════════════════════════════════════════════════════════╣
║ CmdVel │ 16 │ 1000+ Hz │ Velocity control commands ║
║ Imu │ 296 │ 500+ Hz │ IMU sensor fusion ║
║ LaserScan │ 1480 │ 10-40 Hz │ 2D lidar navigation ║
║ JointCommand │ 1032 │ 500+ Hz │ Manipulator control ║
╚═════════════════════════════════════════════════════════════════════════════╝
[Topic] Running benchmarks — timing tx.send() enqueue cost only
(cross-thread consumer drains in the background; no sample
waits for delivery, so these are NOT end-to-end latencies)
─────────────────────────────────────────────────
CmdVel 16 bytes │ median: 40ns │ p99: 69ns │ CV: 5.6728
Imu 304 bytes │ median: 40ns │ p99: 89ns │ CV: 1.1727
LaserScan 1480 bytes │ median: 89ns │ p99: 150ns │ CV: 0.1727
JointCommand 928 bytes │ median: 80ns │ p99: 130ns │ CV: 1.9221
╔══════════════════════════════════════════════════════════════════════════════════════════╗
║ SUMMARY BY MESSAGE TYPE — send() ENQUEUE COST, not end-to-end latency ║
╠══════════════════════════════════════════════════════════════════════════════════════════╣
║ Message │ Size │ Median (ns) │ p99 (ns) │ CV │ Misses │ Sustained rate ║
╠══════════════════════════════════════════════════════════════════════════════════════════╣
║ CmdVel │ 16 │ 40 │ 69 │ 5.6728 │ 0 │ 5.60 M msg/s ║
║ Imu │ 304 │ 40 │ 89 │ 1.1727 │ 0 │ 3.70 M msg/s ║
║ LaserScan │ 1480 │ 89 │ 150 │ 0.1727 │ 0 │ 0.84 M msg/s ║
║ JointCommand │ 928 │ 80 │ 130 │ 1.9221 │ 0 │ 2.99 M msg/s ║
╚══════════════════════════════════════════════════════════════════════════════════════════╝
Sustained rate is wall-clock over the measured loop, so it includes the batch
drain-waits. It is a publish rate for this producer/consumer pair, not a bus limit.
╔══════════════════════════════════════════════════════════════════╗
║ REAL-TIME SUITABILITY ANALYSIS ║
╠══════════════════════════════════════════════════════════════════╣
║ These gates grade the p99 of the send() ENQUEUE COST against one ║
║ whole control period. They are not end-to-end control-loop ║
║ guarantees: a real loop also pays the receive side, the node's ║
║ compute, and the scheduler's jitter, none of which is measured ║
║ here. The headroom is printed so a pass by four orders of ║
║ magnitude cannot be read as a tight result. ║
╠══════════════════════════════════════════════════════════════════╣
║ CmdVel (1kHz control): ~ PASS by 14493x — gate not discriminating (p99=69ns vs 1000000ns)
║ CmdVel (10kHz control): ~ PASS by 1449x — gate not discriminating (p99=69ns vs 100000ns)
║ Imu (500Hz fusion) : ~ PASS by 22472x — gate not discriminating (p99=89ns vs 2000000ns)
║ LaserScan (40Hz lidar) : ~ PASS by 166667x — gate not discriminating (p99=150ns vs 25000000ns)
║ JointCmd (500Hz control): ~ PASS by 15385x — gate not discriminating (p99=130ns vs 2000000ns)
╚══════════════════════════════════════════════════════════════════╝
Results written to: /home/runner/work/horus/horus/benchmarks/gate-reports/robotics-3.json
Gated against a rolling window of recent main runs. Each metric's band is max(relative, center + k·sigma_observed, absolute floor), so it is derived from the noise the baseline itself measured — where a band is printed wider than the change you care about, this run did not detect a regression and could not have. Thresholds and their reasoning: RegressionPolicy in benchmarks/src/output.rs. Commit: c1ed7e9
The reason will be displayed to describe this comment to others. Learn more.
Copilot review overview
🟡 Changes recommended
The CLI driver feature resolution and horus pkg add --driver path still behave as if terra is the primary key, so manifests using the new use key won’t be handled consistently.
Get a fresh assessment by requesting another Copilot review.
Removes public-facing references to the private “Terra” project across docs and user-facing strings, while preserving compatibility for existing manifests that still use the legacy terra = "..." driver key.
Changes:
Updates public docs/examples to stop mentioning Terra and to use the unified use = "..." driver source key.
Rewords driver/manifest-related comments and docs to describe terra as a legacy shortname rather than a product name.
Updates a driver registry error hint to avoid referencing non-dependencies and point users at driver registration.
File
Description
README.md
Removes Terra link/branding; updates driver example to use = "...".
horus_manager/src/native_sync.rs
Rewords driver dependency generation docs away from Terra framing.
horus_manager/src/manifest.rs
Updates driver config documentation to center the unified use key and mark terra as legacy.
horus_manager/src/commands/run/features.rs
Updates comment about extracting driver name/source from config tables.
horus_manager/src/commands/pkg.rs
Rewords comment about interpreting a provided driver source as a legacy shortname.
horus_manager/src/cargo_gen.rs
Updates docs for driver dependency emission to reflect runtime resolution for use = "...".
horus_core/src/drivers/mod.rs
Updates “no registered types” hint to reference register_driver!() instead of Terra.
examples/README.md
Removes Terra mention from the examples index entry.
examples/driver_integration/README.md
Removes Terra HAL branding; updates examples to use = "..." and “built-in drivers” wording.
examples/driver_integration/main.rs
Updates prose/log messages away from Terra and updates config snippet to use = "...".
examples/driver_integration/horus.toml
Updates example driver entries from terra = "..." to use = "...".
The live tier compares `horus schema`'s output against the pinned docs
tree, and this branch changes the manifest doc comments, so the pin has to
move to the docs commit that republished the schema. ad08246 is the merge
of horus-docs#19; verified from this tree: docs_contract 14,
docs_cli_contract 7, docs_manifest 17 (--include-ignored).
The reason will be displayed to describe this comment to others. Learn more.
Copilot review overview
🔵 Needs a closer look
horus_manager/src/commands/run/features.rs does not handle the new use key when building backend overrides, which can break registry feature resolution for use = "..." driver configs.
DriverConfig::from_manifest ignores the new unified use source key, so a [drivers.NAME] table using use = "..." won't populate config.backends. That changes registry lookups in get_cargo_features_from_drivers() (it will query just driver instead of driver-use_name).
// Config table — extract the driver name from the source keys
config.drivers.push(name.clone());
if let Some(terra) = &cfg.terra {
config.backends.insert(name.clone(), terra.clone());
} else if let Some(package) = &cfg.package {
The term "Built-in drivers" here suggests these drivers are available out of the box, but driver resolution depends on what types have been registered (or what crates you depend on that register them). Wording like "shortname drivers" or "registry-resolved drivers" would better match the behavior.
These table entries also label the drivers as "built-in", which can read as "no extra registration/dependency required". Consider making them consistent with the registry-based resolution model (e.g., "driver nodes" / "shortname drivers").
Source key documentation omits supported crate, pip, exec, and terra keys
horus_manager/src/manifest.rs:876
The doc comment says the only valid source keys are use/package/node, but the struct still supports other source keys (crate, pip, exec, and the legacy terra). This is confusing for schema/docs generation since those keys will still appear/parse.
Built-in driver wording conflicts with registry-based driver loading
horus_manager/src/manifest.rs:883
Calling this a "Built-in driver (pre-installed hardware support)" implies the driver types are always available without extra registration/dependencies, but the loader explicitly errors when nothing is registered and suggests depending on a crate that registers drivers. Consider wording that matches the runtime registry model.
Documentation omits crates.io drivers from Cargo dependency collection
horus_manager/src/native_sync.rs:312
This doc comment says only package drivers generate Cargo deps, but collect_driver_crates() also collects cfg.crate_name (crates.io drivers). The comment should mention both sources to match the behavior.
The hint named the macro but wrote it as register_driver!(), which reads as
a zero-argument call. The macro takes the driver type and its factory; say
so. The docs page that quotes the message is updated separately
(horus-docs#20).
The reason will be displayed to describe this comment to others. Learn more.
Copilot review overview
🔵 Needs a closer look
horus_manager/src/commands/run/features.rs currently ignores the new unified use key for config-table drivers, and horus pkg add --driver still emits the legacy terra key, which can break/undermine the intended behavior and guidance.
horus pkg add --driver still writes the legacy terra = "..." key for shortname drivers. Since the manifest docs now recommend use as the unified key, this command should emit use = "..." (via use_name) and rely on the existing fallback for parsing older manifests.
other => {
// Try as a legacy driver shortname
DriverValue::Config(DriverTableConfig {
terra: Some(other.to_string()),
..DriverTableConfig::default()
})
write_driver_deps comment omits legacy terra support
horus_manager/src/cargo_gen.rs:869
The doc comment for write_driver_deps describes use = "..." but omits that the legacy terra = "..." shortname key is still accepted (and also produces no dependency). This makes the comment misleading for users reading generated Cargo.toml behavior alongside the manifest schema docs.
DriverValue docs omit legacy terra key support
horus_manager/src/manifest.rs:855
This summary bullet implies config tables only accept use/package/node, but DriverTableConfig still supports the legacy terra shortname key (as a fallback for use). Consider calling that out here so the top-level DriverValue docs match the actual parsing behavior.
The comment above collect_driver_crates says "Only package drivers generate Cargo deps", but the function also collects cfg.crate_name (crates.io drivers) as Cargo dependencies. Updating the wording would prevent confusion when reading this alongside manifest schema docs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Terra is private and not ready to be public, so this removes horus's pointers to it, without breaking manifests that already use the legacy key.
Removed
github.com/softmata/terraand the "Terra HAL" name fromREADME.md,examples/README.md,examples/driver_integration/{README.md,main.rs,horus.toml}.use = "..."source key (the fallback chain reads it first).register!()orterra_horus::register_all()first" —terra_horusis not a horus dependency. New text namesregister_driver!(). The horus-docs page that quotes the message is updated in a paired docs PR.horus_core/src/drivers/mod.rs,horus_manager/src/{manifest,cargo_gen,native_sync}.rs,commands/{pkg,run/features}.rs.Kept, deliberately
The legacy
terra = "..."manifest key still parses (DriverTableConfig::terra+ horus_core's fallback chain) and keeps its tests, because existinghorus.tomlfiles use it. What changed is only the wording: the schema and docs describe it as "legacy driver shortname", not by product name.Validation
cargo fmt --all -- --checkcargo check -p horus_core -p horus_managerreadme_contract11 passed,examples_contract10 passed (1 ignored), drivers tests 64 passed, manifest tests 96 passed.Docs side
A paired
horus-docsPR updates the quoted error string, the "Terra HAL" wording and regeneratespublic/schema/horus.toml.schema.jsonfrom this change. It should merge after this one.