nros/

sizes.rs

//! Single source of truth for FFI opaque-storage sizes.
//!
//! Each `export_size!` invocation produces two artefacts:
//!
//! * `pub const FOO_SIZE: usize = core::mem::size_of::<T>();` — a normal
//!   Rust const suitable for in-crate `const _: () = assert!(...)` checks and
//!   direct use by `no_std` consumers.
//! * `pub static __NROS_SIZE_FOO: [u8; FOO_SIZE] = [0; FOO_SIZE];` — an
//!   array-sized static whose *symbol storage size* in the compiled rlib
//!   equals `FOO_SIZE`. `nros-c`/`nros-cpp` build scripts read the sizes out
//!   via [`nros_sizes_build::extract_sizes`](../../../nros-sizes-build/index.html)
//!   to derive opaque-storage macros for the generated C/C++ headers.
//!
//! # The markers exist ONLY in the size probe's own build (issue 1765)
//!
//! The statics, and the `__NROS_SIZE_FN_*` fn-pointer markers beside them, are
//! compiled only under `feature = "ffi-size-markers"`. Exactly one party
//! requests that feature: the nested probe cargo behind
//! `nros-build-helpers::shared::probe_nros_sizes`, which builds `nros` in its
//! OWN target directory. No shipped dep-site enables it, and `build.rs` makes
//! enabling it outside the probe a compile error.
//!
//! It used to be requested on `nros-c`'s and `nros-cpp`'s `nros` dependency,
//! so the markers were part of the linked staticlib: `#[no_mangle]` immutable
//! statics, which a staticlib exports and the board linker scripts place in
//! `.text`. Every C/C++ image paid the SUM of the probed sizes in flash, as
//! zero bytes (111,252 B of a 587,256 B FreeRTOS C zenoh talker), and once
//! phase-382 W3' carved the parameter store into `EXECUTOR_SIZE`, a second
//! 280 KB copy of the store. The `pub const`s are unaffected: they are what
//! in-crate asserts and `no_std` consumers read, and a const occupies nothing.
//!
//! Feature gating follows the rest of the crate: the statics only exist when
//! an RMW backend (`rmw-zenoh` / `rmw-xrce` / `rmw-cyclonedds` / `rmw-cffi`) is
//! active, which is exactly the condition under which the `Rmw*` type
//! aliases resolve. Workspace-level `cargo check` without any RMW feature
//! sees this module as empty.

#[cfg(feature = "rmw-cffi")]
mod rmw_sizes {
    use crate::internals::{
        RmwPublisher, RmwServiceClient, RmwServiceServer, RmwSession, RmwSubscriber,
    };

    // Phase 77.25: per-name v0-mangled markers so the probe works
    // under fat LTO. Each call to `export_size!(NAME = Ty)` expands to
    // a distinct generic fn `__nros_size_NAME<const N: usize>` plus a
    // monomorphised fn-pointer static. The monomorphisation's v0
    // mangled symbol name contains both the name ("NAME") *and* the
    // const-generic value (the size) — e.g. demangles as
    // `nros::sizes::rmw_sizes::__nros_size_PUBLISHER_SIZE::<48>`.
    // Symbol names survive LTO because the linker still needs them,
    // even when the object file is LLVM bitcode and `object::parse`
    // can't read symbol byte sizes. The original `__NROS_SIZE_<NAME>`
    // static kept for backwards-compat is also emitted for consumers
    // that still walk the legacy path.
    #[doc(hidden)]
    pub mod _size_markers {}

    macro_rules! export_size {
        ($vis:vis $name:ident = $ty:ty) => {
            $vis const $name: usize = core::mem::size_of::<$ty>();
            // issue 1765 — every marker is `cfg`'d on the probe-only feature,
            // not merely `cfg_attr(.., used)`. A `#[no_mangle]` static is
            // EXPORTED from a staticlib whether or not it is `#[used]`, so the
            // attribute alone never kept one out of an image.
            // `check-size-markers-unlinked` holds every item here to this.
            pastey::paste! {
                #[cfg(feature = "ffi-size-markers")]
                #[used]
                #[unsafe(no_mangle)]
                #[doc(hidden)]
                pub static [<__NROS_SIZE_ $name>]: [u8; $name] = [0u8; $name];

                #[cfg(feature = "ffi-size-markers")]
                #[doc(hidden)]
                #[allow(non_snake_case)]
                #[inline(never)]
                pub fn [<__nros_size_ $name>]<const N: usize>() -> usize { N }

                #[cfg(feature = "ffi-size-markers")]
                #[used]
                #[doc(hidden)]
                pub static [<__NROS_SIZE_FN_ $name>]: fn() -> usize =
                    [<__nros_size_ $name>]::<{ $name }>;
            }
        };
    }

    export_size!(pub SESSION_SIZE        = RmwSession);
    export_size!(pub PUBLISHER_SIZE      = RmwPublisher);
    export_size!(pub SUBSCRIBER_SIZE     = RmwSubscriber);
    export_size!(pub SERVICE_CLIENT_SIZE = RmwServiceClient);
    export_size!(pub SERVICE_SERVER_SIZE = RmwServiceServer);

    // Phase 122.3.c.3 — L1 polling-mode Raw* handles. Defaults to
    // `DEFAULT_RX_BUF_SIZE` on each const-generic slot, which is
    // exactly the value `nros-c::config::MESSAGE_BUFFER_SIZE` resolves
    // to (both derive from `NROS_SUBSCRIPTION_BUFFER_SIZE` via
    // `nros-node`'s build.rs). nros-c's build.rs reads these probe
    // values and emits the matching `*_OPAQUE_U64S` macros into the
    // per-build variant header so C struct `_opaque` storage agrees
    // with the Rust struct layout. Without this probe, cbindgen
    // ships a `_OPAQUE_U64S = 1` placeholder which silently
    // truncates the C-side `_opaque` slot.
    export_size!(pub RAW_SUBSCRIPTION_SIZE   = nros_node::RawSubscription);
    export_size!(pub RAW_SERVICE_SERVER_SIZE = nros_node::RawServiceServer);
    export_size!(pub RAW_SERVICE_CLIENT_SIZE = nros_node::RawServiceClient);

    // Phase 122.3.c.6 — typeless action `*Core` types are the raw
    // L1 polling-mode entities (typed `ActionServer<A>` / `ActionClient<A>`
    // wrap them with serdes glue). Default const generics resolve to
    // `DEFAULT_RX_BUF_SIZE` (= `MESSAGE_BUFFER_SIZE` in nros-c) and
    // `MAX_GOALS = 4`, matching the L2 callback path.
    export_size!(pub RAW_ACTION_SERVER_SIZE = nros_node::ActionServerCore);
    export_size!(pub RAW_ACTION_CLIENT_SIZE = nros_node::ActionClientCore);

    // phase-271 — the C/C++ `_opaque` executor buffer holds the `Executor<'static>`
    // header AND the per-entry storage backing carved from the same buffer, so it
    // must be sized for the combined `#[repr(C)]` layout, not bare `Executor`.
    export_size!(pub EXECUTOR_SIZE       = nros_node::ExecutorInlineStorage);

    // issue 0961 — the STACK requirement is a different number from the one
    // above, and reusing that one would overstate it. `EXECUTOR_SIZE` is the
    // executor value PLUS its carved backing, which is what the caller's
    // `_opaque` buffer must hold; the backing lives wherever the caller put
    // that buffer (`.bss` for a static holder) and never lands on the stack.
    // What lands on the stack is the bare value: `open_in` builds one in its
    // frame and returns it, and `nros_cpp_init` holds the returned value
    // before writing it into the caller's storage — the same value, moved
    // twice, which is why the check derived from this is `2 x`.
    //
    // On a 320 KiB part the overstatement would be a build error refusing an
    // image that fits, so the two numbers stay separate rather than one being
    // reused for both jobs.
    export_size!(pub EXECUTOR_VALUE_SIZE = nros_node::Executor<'static>);
    export_size!(pub GUARD_CONDITION_SIZE = nros_node::GuardCondition);
    export_size!(pub LIFECYCLE_CTX_SIZE  = nros_node::lifecycle::LifecyclePollingNodeCtx);
    // Phase 91.C: nros-c's `ActionServerInternal` embeds this nros-node
    // type as a typed field. cbindgen (which can't recurse into deps)
    // emits the field as `ActionServerRawHandle handle;` referencing a
    // type it cannot define. nros-c's build.rs reads this size and emits
    // an opaque type-compatible declaration into nros_config_generated.h
    // so the cbindgen output is self-contained.
    export_size!(pub ACTION_SERVER_RAW_HANDLE_SIZE = nros_node::ActionServerRawHandle);

    // Layout-mirror struct for `nros_c::action::ActionServerInternal`.
    // ActionServerInternal lives in the `nros-c` crate, so it can't be
    // referenced from `nros` directly. This mirror has the same `#[repr(C)]`
    // field shape and therefore the same byte size. nros-c asserts at compile
    // time that `size_of::<ActionServerInternal>() ==
    // size_of::<ActionServerInternalLayout>()`.
    //
    // phase-487 W4 removed five fields from both: a second copy of the
    // server's callback record (`c_goal_callback`, `c_cancel_callback`,
    // `c_accepted_callback`, `c_context`) and `server_ptr`, which pointed back
    // to the struct containing it. The trampolines read the server's own
    // record now.
    use core::ffi::c_void;

    #[repr(C)]
    #[doc(hidden)]
    pub struct ActionServerInternalLayout {
        pub handle: nros_node::ActionServerRawHandle,
        pub executor_ptr: *mut c_void,
    }
    export_size!(pub ACTION_SERVER_INTERNAL_SIZE = ActionServerInternalLayout);

    // Layout-mirrors for nros-cpp's `CppActionServer` and `CppActionClient`.
    //
    // Same approach as `ActionServerInternalLayout` above: nros-cpp's
    // wrapper structs live in a downstream crate but their byte sizes can
    // be reconstructed from the field shape. This eliminates the
    // hand-math in `nros-cpp/build.rs` (was Phase 87.11).
    //
    // The C++-side `nros::ActionServer<A>` / `nros::ActionClient<A>`
    // classes hold opaque storage sized to these probe values. nros-cpp
    // asserts `size_of::<CppActionServer>() == size_of::<CppActionServerLayout>()`
    // (and the same for CppActionClient) so any field-shape drift in the
    // real wrapper trips the build immediately.

    type CppGoalCallbackLayout =
        unsafe extern "C" fn(*const [u8; 16], *const u8, usize, *mut c_void) -> i32;
    type CppCancelCallbackLayout = unsafe extern "C" fn(*const [u8; 16], *mut c_void) -> i32;
    // issue 0796 — the C++ callback tier's accepted-goal hook (`CppAcceptedCallback`).
    type CppAcceptedCallbackLayout = unsafe extern "C" fn(*const [u8; 16], *mut c_void);

    // Byte-shape mirror of one of `nros-cpp`'s `nros_cpp_qos_t` policy enums
    // (`nros_cpp_qos_reliability_t` et al). These are `#[repr(C)]` fieldless
    // enums, so their width follows the *target C ABI*: `c_int` (4 bytes) on
    // x86_64, but **1 byte on ARM EABI** (`armv7a-nuttx-eabihf` defaults to
    // `-fshort-enums`). Mirroring them as `c_int` (the pre-fix shape) over-sized
    // the qos block by 12 bytes on ARM and tripped the `CppActionServer`
    // layout assert. A `#[repr(C)]` enum here tracks the same short-enum width
    // on every target. Variant count is irrelevant to width while ≤ 255 (all
    // four real enums have ≤ 4 variants), so one placeholder mirrors all four.
    #[repr(C)]
    #[doc(hidden)]
    pub enum CppQosEnumLayout {
        A = 0,
        B = 1,
    }

    // Phase 193.4b: byte-shape mirror of `nros-cpp`'s `nros_cpp_qos_t`
    // (4 C-ABI enums + `c_int` depth + 3×u32 + u8). The action server now
    // stores the create-time QoS until registration; the real
    // `CppActionServer` field-shape assert keeps this in sync.
    #[repr(C)]
    #[doc(hidden)]
    pub struct CppQosLayout {
        pub reliability: CppQosEnumLayout,
        pub durability: CppQosEnumLayout,
        pub history: CppQosEnumLayout,
        pub liveliness_kind: CppQosEnumLayout,
        pub depth: core::ffi::c_int,
        pub deadline_ms: u32,
        pub lifespan_ms: u32,
        pub liveliness_lease_ms: u32,
        pub avoid_ros_namespace_conventions: u8,
    }

    // Phase 87.6 thin-wrapper: `action_name` / `type_name` / `type_hash`
    // buffers moved to the C++ `nros::ActionServer<A>` class.
    // Phase 104.C.9.b: `node_id` field added so action create→register
    // can route through the per-Node session.
    // Phase 193.4b: `qos` field added so create-time QoS reaches the three
    // underlying service servers at register time.
    #[repr(C)]
    #[doc(hidden)]
    pub struct CppActionServerLayout {
        pub handle: Option<nros_node::ActionServerRawHandle>,
        pub goal_cb: Option<CppGoalCallbackLayout>,
        pub cancel_cb: Option<CppCancelCallbackLayout>,
        pub accepted_cb: Option<CppAcceptedCallbackLayout>,
        pub cb_ctx: *mut c_void,
        pub node_id: u8,
        pub _reserved: [u8; 7],
        pub qos: CppQosLayout,
    }
    export_size!(pub CPP_ACTION_SERVER_SIZE = CppActionServerLayout);

    type CppActionGoalResponseCb = Option<unsafe extern "C" fn(bool, *const [u8; 16], *mut c_void)>;
    type CppActionFeedbackCb =
        Option<unsafe extern "C" fn(*const [u8; 16], *const u8, usize, *mut c_void)>;
    type CppActionResultCb =
        Option<unsafe extern "C" fn(*const [u8; 16], i32, *const u8, usize, *mut c_void)>;

    #[repr(C)]
    #[doc(hidden)]
    pub struct CppActionClientCallbacksLayout {
        pub goal_response: CppActionGoalResponseCb,
        pub feedback: CppActionFeedbackCb,
        pub result: CppActionResultCb,
        pub context: *mut c_void,
    }

    // Phase 87.6 thin-wrapper: `action_name` buffer moved to the C++
    // `nros::ActionClient<A>` class.
    #[repr(C)]
    #[doc(hidden)]
    pub struct CppActionClientLayout {
        pub callbacks: CppActionClientCallbacksLayout,
        pub arena_entry_index: i32,
        pub executor_ptr: *mut c_void,
    }
    export_size!(pub CPP_ACTION_CLIENT_SIZE = CppActionClientLayout);
}

#[cfg(feature = "rmw-cffi")]
pub use rmw_sizes::*;