nros_platform/board/entry.rs
1//! [`BoardEntry`] — Phase 212.N.1.
2//!
3//! The single boot-driver trait every Entry pkg `main.rs` invokes:
4//!
5//! ```ignore
6//! fn main() {
7//! let _ = <MyBoard as BoardEntry>::run(|runtime| {
8//! run_plan(runtime) // codegen-emitted (212.N.4)
9//! });
10//! }
11//! ```
12//!
13//! `run` owns the full lifecycle:
14//!
15//! 1. [`super::BoardInit::init_hardware`]
16//! 2. [`super::TransportBringup::init_transport`] (if implemented)
17//! 3. [`super::NetworkWait::wait_link_up`] (if implemented)
18//! 4. Open executor, build `RuntimeCtx`, invoke `setup(runtime)`.
19//! 5. Spin executor to completion (or termination signal).
20//! 6. [`super::BoardExit::exit_success`] / `exit_failure`.
21//!
22//! The exact body lives in the family driver crates (212.N.2); the
23//! trait here pins the signature so codegen + user Entry pkg can
24//! call it without knowing the family.
25
26use super::runtime::RuntimeCtx;
27
28/// Deploy-metadata overlay threaded from `nros::main!()` into the board's
29/// boot config (issue #48 cause 1).
30///
31/// The `nros::main!()` macro reads the Entry pkg's
32/// `[package.metadata.nros.deploy.<board>]` block at expansion time and bakes
33/// the present keys here. Each field is `None` when the deploy block omitted
34/// it, so the board overlays only the supplied values onto its own
35/// `Config::default()` (the firmware's compiled-in default stays the source of
36/// truth for everything the deploy block does not name).
37///
38/// Boards whose `BoardEntry::run` ignores network/locator config (POSIX hosts,
39/// RTIC/Embassy MCUs that take their transport elsewhere) inherit the default
40/// [`BoardEntry::run_with_deploy`] body, which drops the overlay and calls
41/// [`BoardEntry::run`] — so adding a *network* field here never touches those
42/// boards. The exception is [`node_name`](DeployOverlay::node_name): hosted
43/// boards override `run_with_deploy` to apply it to the boot config (issue #98),
44/// since the ROS graph node name is a launch identity, not a network knob.
45#[derive(Clone, Copy, Default, Debug)]
46pub struct DeployOverlay {
47 /// `locator = "tcp/10.0.2.2:7451"` — the zenoh/RMW endpoint the firmware
48 /// dials. `None` → keep the board default.
49 pub locator: Option<&'static str>,
50 /// `ip = "10.0.2.15"` — static guest IP. `None` → keep the board default.
51 pub ip: Option<[u8; 4]>,
52 /// `gateway = "10.0.2.2"` — default route. `None` → keep the board default.
53 pub gateway: Option<[u8; 4]>,
54 /// `netmask = "255.255.255.0"`. `None` → keep the board default.
55 pub netmask: Option<[u8; 4]>,
56 /// `domain_id = 0` — ROS 2 domain. `None` → keep the board default.
57 pub domain_id: Option<u32>,
58 /// `transport = "xrce"` — select a board custom transport that must be
59 /// installed BEFORE the linked RMW registers (e.g. an XRCE-over-UART vtable).
60 /// `None` → the board's default transport. Honored by
61 /// [`BoardEntry::setup_transport`] (phase-244.D1).
62 pub transport: Option<&'static str>,
63 /// The ROS graph node name for the primary session, baked from the launch
64 /// file's single `<node name=…>` / `system.toml` `[[component]].name` (issue
65 /// #98). `None` → the board default (`from_env()`'s `"node"`). Only set by
66 /// `nros::main!` when the launch declares exactly one node — multiple nodes
67 /// share one primary session, so naming it after one component would be
68 /// wrong (per-node naming is the deferred multi-node piece). Applied to the
69 /// boot `ExecutorConfig` by the board, so unlike `locator` this IS honored on
70 /// hosted boards (locator stays env-driven; node name is a launch identity).
71 pub node_name: Option<&'static str>,
72 /// Issue #101 / RFC-0045 — the patchable baked boot-config static
73 /// (`.nros_boot_config`), emitted by `nros::main!` for embedded targets and
74 /// read by the board to resolve node_name/locator/domain. `None` on hosted /
75 /// when the macro emits no static.
76 pub boot_config: Option<&'static nros_platform_api::BakedBootConfig>,
77}
78
79/// Per-board boot driver.
80///
81/// Implementations live in the family driver crates
82/// (`nros-board-posix`, `nros-board-freertos`, …). Per-board crates
83/// (`nros-board-mps2-an385-freertos`, …) plug the family.
84pub trait BoardEntry: super::Board {
85 /// Drive the full boot → user-closure → exit flow.
86 ///
87 /// `setup` receives a `&mut RuntimeCtx` with overlay knobs from
88 /// the launch file / CLI args. Returning `Err` from `setup` makes
89 /// `run` route to [`super::BoardExit::exit_failure`]; `Ok`
90 /// proceeds to executor spin + clean exit.
91 ///
92 /// **Returns `Result`, not `!`.** The legacy
93 /// `nros-board-common::board_init::BoardEntry::run` diverged;
94 /// 212.N keeps the option to return so unit tests can drive it
95 /// in a hosted process without `exit()` killing the test
96 /// harness. Production boards still call `exit_*` from inside
97 /// `run`'s body after spin returns.
98 fn run<F, E>(setup: F) -> Result<(), E>
99 where
100 F: FnOnce(&mut RuntimeCtx<'_>) -> Result<(), E>,
101 E: core::fmt::Debug;
102
103 /// Boot like [`run`](Self::run) but apply a deploy-metadata overlay to the
104 /// board's boot config first (issue #48 cause 1).
105 ///
106 /// The default body **ignores** `deploy` and forwards to
107 /// [`run`](Self::run); boards that compile a network/locator config (the
108 /// FreeRTOS / bare-metal firmware boards) override it to overlay the
109 /// supplied fields onto their `Config::default()`. `nros::main!()` calls
110 /// this (not `run`) for `target_os = "none"` OwnedSpin targets so the
111 /// `[package.metadata.nros.deploy.<board>]` block stops being inert.
112 fn run_with_deploy<F, E>(_deploy: &DeployOverlay, setup: F) -> Result<(), E>
113 where
114 F: FnOnce(&mut RuntimeCtx<'_>) -> Result<(), E>,
115 E: core::fmt::Debug,
116 {
117 Self::run(setup)
118 }
119
120 /// phase-271 (issue #110) — boot like [`run_with_deploy`](Self::run_with_deploy)
121 /// but size the executor's callback table + arena to the entry's OWN declared
122 /// topology (`max_cbs` / `max_sched_contexts`, from the entry's
123 /// `[package.metadata.nros.entry]`), instead of the workspace-global
124 /// `NROS_EXECUTOR_MAX_CBS` build const.
125 ///
126 /// Sizes are plain `usize`s (not `nros::ExecutorSizing`) because
127 /// `nros-platform` sits below `nros`; the hosted board converts them. A
128 /// `max_sched_contexts` of `0` means "use the build default". The **default
129 /// body IGNORES the sizing** and forwards to
130 /// [`run_with_deploy`](Self::run_with_deploy), so every board except the
131 /// hosted (posix) one — which opens via `Executor::open` and could grow its
132 /// arena — is byte-identical; the posix board overrides this to
133 /// `Executor::open_sized`. `nros::main!()` emits this (instead of
134 /// `run_with_deploy`) only when the entry declares `max_callbacks`.
135 fn run_with_deploy_sized<F, E>(
136 deploy: &DeployOverlay,
137 _max_cbs: usize,
138 _max_sched_contexts: usize,
139 setup: F,
140 ) -> Result<(), E>
141 where
142 F: FnOnce(&mut RuntimeCtx<'_>) -> Result<(), E>,
143 E: core::fmt::Debug,
144 {
145 Self::run_with_deploy(deploy, setup)
146 }
147
148 /// **Custom-transport install seam.** Install a board-specific transport
149 /// selected by `deploy.transport`, BEFORE the linked RMW registers
150 /// (phase-244.D1).
151 ///
152 /// `nros::main!()` always emits a `setup_transport` call (gated on
153 /// `target_os = "none"`) immediately before `__register_linked_rmw()`,
154 /// so that the vtable is in place before the XRCE backend registers —
155 /// the ordering `set_custom_transport_ops` requires.
156 ///
157 /// **This method is intentionally kept** — it is not dead code. The
158 /// **default no-op** is correct for every board whose transport is
159 /// registered automatically (Zenoh, native sockets, etc.). The only
160 /// current override is **`nros-board-mps2-an385`** with the
161 /// `xrce-transport` feature, which installs an XRCE-over-UART vtable
162 /// when `deploy.transport == Some("xrce")`. Future boards that need to
163 /// pre-register a custom transport vtable should override this method in
164 /// the same pattern.
165 ///
166 /// Failures are the board's to handle (it owns `exit_failure`).
167 fn setup_transport(_deploy: &DeployOverlay) {}
168}