rmw_entity.h

Go to the documentation of this file.

#ifndef NROS_RMW_ENTITY_H
#define NROS_RMW_ENTITY_H
 
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#include "nros/rmw_ret.h"   /* the two pure functions below return rmw_ret_t */
 
/* ------------------------------------------------------------------ */
/* QoS profile — full DDS shape (matches `rmw_qos_profile_t`)          */
/* ------------------------------------------------------------------ */
 
/* Policy values carry UPSTREAM's numbering — phase-376 W5/B2.
 *
 * They did not until 2026-08-24, and the disagreement was not academic. Ours
 * were a dense 0/1 pair per policy, which put a DIFFERENT meaning on the same
 * integer:
 *
 *     value | upstream                          | ours (before)
 *     ------|-----------------------------------|-------------------
 *       0   | *_SYSTEM_DEFAULT                  | BEST_EFFORT / VOLATILE / KEEP_LAST
 *       1   | RELIABLE / TRANSIENT_LOCAL / KEEP_LAST | RELIABLE / TRANSIENT_LOCAL / KEEP_ALL
 *
 * so `HISTORY == 1` meant KEEP_LAST to upstream and KEEP_ALL to us — the two
 * opposite answers to the question. Liveliness was worse: MANUAL_BY_NODE and
 * MANUAL_BY_TOPIC were SWAPPED (2 and 3).
 *
 * These values cross the ABI. `rmw_qos_profile_check_compatible` is a name
 * upstream owns and we export, and the cyclonedds backend translates this
 * struct into real DDS QoS that a ROS peer matches against. A caller reasoning
 * in upstream's vocabulary got silently wrong policies. Same argument as W3.d
 * step B for the return codes: where a value crosses the boundary, upstream's
 * numbering is the only one that cannot be wrong.
 *
 * The names keep the `NROS_RMW_` prefix — as the return codes do — because the
 * set is ours to extend, not upstream's to define.
 */
 
#define NROS_RMW_RELIABILITY_SYSTEM_DEFAULT 0
#define NROS_RMW_RELIABILITY_RELIABLE       1
#define NROS_RMW_RELIABILITY_BEST_EFFORT    2
#define NROS_RMW_RELIABILITY_UNKNOWN        3
 
#define NROS_RMW_DURABILITY_SYSTEM_DEFAULT   0
#define NROS_RMW_DURABILITY_TRANSIENT_LOCAL  1
#define NROS_RMW_DURABILITY_VOLATILE         2
#define NROS_RMW_DURABILITY_UNKNOWN          3
 
#define NROS_RMW_HISTORY_SYSTEM_DEFAULT 0
#define NROS_RMW_HISTORY_KEEP_LAST      1
#define NROS_RMW_HISTORY_KEEP_ALL       2
#define NROS_RMW_HISTORY_UNKNOWN        3
 
typedef enum rmw_feature_t {
    RMW_FEATURE_MESSAGE_INFO_PUBLICATION_SEQUENCE_NUMBER = 0,
    RMW_FEATURE_MESSAGE_INFO_RECEPTION_SEQUENCE_NUMBER   = 1,
} rmw_feature_t;
 
typedef int64_t rmw_time_point_value_t;
 
#define RMW_MESSAGE_INFO_SEQUENCE_NUMBER_UNSUPPORTED UINT64_MAX
 
#define RMW_GID_STORAGE_SIZE 24u
 
typedef struct rmw_byte_span_t {
    const uint8_t *data;
    size_t len;
} rmw_byte_span_t;
 
typedef struct rmw_mut_byte_span_t {
    uint8_t *data;
    size_t capacity;
    size_t len;
} rmw_mut_byte_span_t;
 
#define NROS_RMW_TAKE_LEN_UNKNOWN 0
 
typedef struct rmw_message_type_support_t {
    const char *type_name;
    const char *type_hash;
} rmw_message_type_support_t;
 
typedef struct rmw_service_type_support_t {
    const char *type_name;
    const char *type_hash;
} rmw_service_type_support_t;
 
typedef struct rmw_gid_t {
    const char *implementation_identifier;
    uint8_t data[RMW_GID_STORAGE_SIZE];
} rmw_gid_t;
 
 
typedef struct rmw_message_info_t {
    rmw_time_point_value_t source_timestamp;
    rmw_time_point_value_t received_timestamp;
    uint64_t publication_sequence_number;
    uint64_t reception_sequence_number;
    rmw_gid_t publisher_gid;
    bool from_intra_process;
} rmw_message_info_t;
 
typedef enum rmw_liveliness_kind_t {
    NROS_RMW_LIVELINESS_SYSTEM_DEFAULT    = 0,
    NROS_RMW_LIVELINESS_AUTOMATIC         = 1,
    NROS_RMW_LIVELINESS_MANUAL_BY_NODE    = 2,
    NROS_RMW_LIVELINESS_MANUAL_BY_TOPIC   = 3,
    NROS_RMW_LIVELINESS_UNKNOWN           = 4,
} rmw_liveliness_kind_t;
 
typedef struct rmw_qos_profile_t {
    /* ---- 8-byte core, layout-equivalent to the original subset ---- */
    uint8_t  reliability;     
    uint8_t  durability;      
    uint8_t  history;         
    uint8_t  liveliness_kind; 
    uint16_t depth;
    uint16_t _reserved0;      
    /* ---- 16-byte extension (Phase 109) ---- */
    uint32_t deadline_ms;
 
    uint32_t lifespan_ms;
 
    uint32_t liveliness_lease_ms;
 
    uint8_t  avoid_ros_namespace_conventions;
    uint8_t  _reserved1[3];   
} rmw_qos_profile_t;
 
 
/* ====================================================================
 * Phase 376 W4 — the two PURE functions.
 *
 * Plain exported C functions, deliberately NOT vtable slots, and the reason is
 * the campaign's own rule read the other way round: a vtable slot is the
 * mechanism for letting backends DIFFER, and these two must not. Both compute
 * over types this header defines; if two backends disagreed about whether a QoS
 * pair is compatible, or whether two gids name the same entity, that is a
 * DEFECT with as many places to fix it as there are backends.
 *
 * Three supporting reasons:
 *
 *  - The useful call sites have no vtable to dispatch through. QoS
 *    compatibility is wanted at `create_*` time (that is what produces
 *    `NROS_RMW_RET_INCOMPATIBLE_QOS`), in codegen'd validation, and in host
 *    tooling with no session. Neither function takes an entity, so a slot would
 *    force a caller to invent a session — and neither could be called BEFORE a
 *    backend registers, which is exactly when create-time validation runs.
 *
 *  - Upstream is not evidence for a slot. `rmw_qos_profile_check_compatible`
 *    lives in `rmw/qos_profiles.h` and is defined by librmw ITSELF; it appears
 *    in the implementation contract only because each `librmw_*_cpp.so`
 *    statically links librmw and re-exports it. That is plugin packaging, not
 *    semantics, and we load no plugin.
 *
 *  - Precedent: `nros_rmw_cffi_register_named` and friends are declared here
 *    and defined once in Rust with `#[no_mangle]`, so `nros-rmw-abi` stays a
 *    header-only INTERFACE target — no new compiled TU, no new link edge.
 *    (`static inline` was the alternative and is worse: bindgen does not emit
 *    it, so RFC-0054 would force a SECOND Rust implementation, which is the
 *    first reason again.)
 * ==================================================================== */
 
typedef enum rmw_qos_compatibility_type_t {
    RMW_QOS_COMPATIBILITY_OK      = 0,
    RMW_QOS_COMPATIBILITY_WARNING = 1,
    RMW_QOS_COMPATIBILITY_ERROR   = 2,
} rmw_qos_compatibility_type_t;
 
typedef enum nros_rmw_qos_clash_t {
    NROS_RMW_QOS_CLASH_NONE             = 0,
    NROS_RMW_QOS_CLASH_RELIABILITY      = 1u << 0,
    NROS_RMW_QOS_CLASH_DURABILITY       = 1u << 1,
    NROS_RMW_QOS_CLASH_DEADLINE         = 1u << 2,
    NROS_RMW_QOS_CLASH_LIVELINESS_KIND  = 1u << 3,
    NROS_RMW_QOS_CLASH_LIVELINESS_LEASE = 1u << 4,
} nros_rmw_qos_clash_t;
 
rmw_ret_t nros_rmw_qos_incompatibility_mask(
    rmw_qos_profile_t offered, rmw_qos_profile_t requested,
    rmw_qos_compatibility_type_t *compatibility, uint32_t *clash_mask);
 
rmw_ret_t rmw_qos_profile_check_compatible(
    rmw_qos_profile_t publisher_profile, rmw_qos_profile_t subscription_profile,
    rmw_qos_compatibility_type_t *compatibility, char *reason, size_t reason_size);
 
rmw_ret_t rmw_compare_gids_equal(const rmw_gid_t *gid1, const rmw_gid_t *gid2,
    bool *result);
 
typedef enum rmw_log_severity_t {
    RMW_LOG_SEVERITY_UNSET = 0,
    RMW_LOG_SEVERITY_DEBUG = 10,
    RMW_LOG_SEVERITY_INFO  = 20,
    RMW_LOG_SEVERITY_WARN  = 30,
    RMW_LOG_SEVERITY_ERROR = 40,
    RMW_LOG_SEVERITY_FATAL = 50,
} rmw_log_severity_t;
 
typedef enum rmw_endpoint_type_t {
    RMW_ENDPOINT_INVALID      = 0,
    RMW_ENDPOINT_PUBLISHER    = 1,
    RMW_ENDPOINT_SUBSCRIPTION = 2,
} rmw_endpoint_type_t;
 
typedef struct rmw_topic_endpoint_info_t {
    const char *node_name;
    const char *node_namespace;
    const char *topic_type;
    rmw_endpoint_type_t endpoint_type;
    rmw_gid_t endpoint_gid;
    rmw_qos_profile_t qos_profile;
} rmw_topic_endpoint_info_t;
             /* 24 bytes */
 
typedef enum rmw_transport_protocol_t {
    RMW_TRANSPORT_PROTOCOL_UNKNOWN = 0,
    RMW_TRANSPORT_PROTOCOL_UDP     = 1,
    RMW_TRANSPORT_PROTOCOL_TCP     = 2,
    RMW_TRANSPORT_PROTOCOL_COUNT   = 3,
} rmw_transport_protocol_t;
 
typedef enum rmw_internet_protocol_t {
    RMW_INTERNET_PROTOCOL_UNKNOWN = 0,
    RMW_INTERNET_PROTOCOL_IPV4    = 1,
    RMW_INTERNET_PROTOCOL_IPV6    = 2,
    RMW_INTERNET_PROTOCOL_COUNT   = 3,
} rmw_internet_protocol_t;
 
#define RMW_INET_ADDRSTRLEN 48
 
typedef struct rmw_network_flow_endpoint_t {
    rmw_transport_protocol_t transport_protocol;
    rmw_internet_protocol_t  internet_protocol;
    uint16_t                 transport_port;
    uint32_t                 flow_label;
    uint8_t                  dscp;
    char                     internet_address[RMW_INET_ADDRSTRLEN];
} rmw_network_flow_endpoint_t;
 
typedef bool (*rmw_network_flow_endpoint_visit_fn)(void *ctx,
    const rmw_network_flow_endpoint_t *endpoint);
 
typedef void (*rmw_content_filter_visit_fn)(void *ctx,
    const char *expression, const char *const *parameters, size_t parameter_count);
 
#define NROS_RMW_DURATION_INFINITE_MS  UINT32_MAX
 
/* ------------------------------------------------------------------ */
/* Entity options — transport hints (phase-301, issue 0240)           */
/* ------------------------------------------------------------------ */
 
typedef struct rmw_session_property_t {
    const char *key;   
    const char *value; 
} rmw_session_property_t;
 
#define RMW_SESSION_MAX_PROPERTIES 16
 
typedef struct rmw_session_options_t {
    uint8_t localhost_only;
    uint8_t _reserved[7];     
    const char *enclave;
    const rmw_session_property_t *properties;
    size_t property_count; 
} rmw_session_options_t;
 
typedef struct rmw_publisher_options_t {
    uint8_t tx_express;
    uint8_t _reserved[7];     
} rmw_publisher_options_t;
 
typedef struct rmw_subscription_options_t {
    uint32_t rx_buffer_hint;
    uint8_t  _reserved[4];    
} rmw_subscription_options_t;
 
/* ---- Standard QoS profile constants ---- */
/*
 * Compound-literal macros rather than `static const` objects, so a profile is
 * usable in every TU that includes this header with no storage and no
 * initialisation order.
 *
 * **ONE STATEMENT PER PROFILE (phase-428 W10).** Every profile below is a
 * single line through `NROS_RMW_QOS_PROFILE_FROM_POLICIES`, which is the ONLY
 * place the fields that never vary between profiles — `_reserved0`, the three
 * durations, `avoid_ros_namespace_conventions`, `_reserved1` — are written.
 * They used to be written out per profile: 26 constants in one file held in
 * agreement by eye, and the four profiles carrying a concrete liveliness had
 * all drifted the same way while their doc comments asserted the drifted value
 * was upstream's.
 *
 * **The values are UPSTREAM's, and this file is a TRANSCRIPTION of them.** An
 * embedded image cannot include `rmw/qos_profiles.h` and an offline build has
 * no ROS install to read, so the numbers have to live here. That makes them
 * exactly the kind of copy that drifts, so they are not maintained by hand
 * alone: `scripts/check-qos-profile-ssot.py` binds every profile below to the
 * Rust SSoT (`nros_rmw::QoSProfile`'s `QOS_PROFILE_*` constants) and, when a
 * ROS install is resolvable, re-derives both against
 * `<prefix>/include/rmw/rmw/qos_profiles.h`. Edit a value here without the
 * gate agreeing and the gate is what tells you.
 *
 * That named `scripts/check-qos-profile-table.py` from 2026-09-05 to phase-454
 * W1, and NO SUCH SCRIPT EXISTED for any of it. Two gates were written for W10
 * and the duplicate was deleted — correctly, one parser of one table — but this
 * prose kept the deleted name, so the transcription claiming loudest to be
 * checked was the one checked by nothing. W1 wrote the coverage the sentence
 * had been describing, into the gate that survived.
 */
 
#define NROS_RMW_QOS_PROFILE_FROM_POLICIES(rel, dur, hist, dep, live)       \
    ((rmw_qos_profile_t){                                                   \
        .reliability     = NROS_RMW_RELIABILITY_##rel,                      \
        .durability      = NROS_RMW_DURABILITY_##dur,                       \
        .history         = NROS_RMW_HISTORY_##hist,                         \
        .liveliness_kind = NROS_RMW_LIVELINESS_##live,                      \
        .depth           = (dep),                                           \
        ._reserved0      = 0,                                               \
        .deadline_ms     = 0,                                               \
        .lifespan_ms     = 0,                                               \
        .liveliness_lease_ms = 0,                                           \
        .avoid_ros_namespace_conventions = 0,                               \
        ._reserved1      = {0, 0, 0},                                       \
    })
 
/* LIVELINESS IS THE SENTINEL IN EVERY CONCRETE PROFILE — phase-428 W10.
 *
 * `DEFAULT`, `SENSOR_DATA`, `SERVICES_DEFAULT` and `PARAMETERS` carried
 * `NROS_RMW_LIVELINESS_AUTOMATIC` (1) until 2026-09-05, under doc comments
 * reading "`rmw_qos_profile_default`-equivalent … automatic liveliness".
 * Upstream's own initialisers say `RMW_QOS_POLICY_LIVELINESS_SYSTEM_DEFAULT`
 * for all seven profiles, `rmw_qos_profile_unknown` excepted — there is no
 * upstream profile that asks for AUTOMATIC. This is the F2 class: 0829 fixed
 * `SYSTEM_DEFAULT`'s liveliness because that was the profile being looked at,
 * and the four siblings carrying the same wrong value were not swept.
 *
 * THIS CHANGES WHAT A BACKEND COMPILES AGAINST, so what it does to the wire is
 * stated rather than assumed. The two in-tree consumers of a changed macro are
 * `nros-rmw-cyclonedds`'s `create_service` / `create_client`
 * (`NROS_RMW_QOS_PROFILE_SERVICES_DEFAULT` when the caller passes NULL) and
 * `nros-rmw-xrce`'s (same); the cyclone unit tests use `_DEFAULT`.
 *   - cyclonedds: `make_dds_qos` calls `dds_qset_liveliness` only when the kind
 *     is NOT the sentinel (`qos.cpp:99`), so AUTOMATIC(1) set
 *     `DDS_LIVELINESS_AUTOMATIC` + `DDS_INFINITY` explicitly and the sentinel
 *     omits the call — leaving Cyclone's own default, which the DDS spec fixes
 *     at AUTOMATIC with an infinite lease. Same offered QoS on the wire.
 *   - xrce: drops liveliness entirely (it lowers no liveliness field), so the
 *     value is unobservable there either way.
 *   - zenoh: reads no QoS field at all (phase-428 F1).
 * A backend that starts honouring liveliness later sees the correct
 * "middleware's choice" here rather than an unrequested AUTOMATIC.
 */
 
#define NROS_RMW_QOS_PROFILE_DEFAULT                                        \
    NROS_RMW_QOS_PROFILE_FROM_POLICIES(RELIABLE, VOLATILE, KEEP_LAST, 10, SYSTEM_DEFAULT)
 
#define NROS_RMW_QOS_PROFILE_SENSOR_DATA                                    \
    NROS_RMW_QOS_PROFILE_FROM_POLICIES(BEST_EFFORT, VOLATILE, KEEP_LAST, 5, SYSTEM_DEFAULT)
 
#define NROS_RMW_QOS_PROFILE_SERVICES_DEFAULT                               \
    NROS_RMW_QOS_PROFILE_FROM_POLICIES(RELIABLE, VOLATILE, KEEP_LAST, 10, SYSTEM_DEFAULT)
 
#define NROS_RMW_QOS_PROFILE_PARAMETERS                                     \
    NROS_RMW_QOS_PROFILE_FROM_POLICIES(RELIABLE, VOLATILE, KEEP_LAST, 1000, SYSTEM_DEFAULT)
 
#define NROS_RMW_QOS_PROFILE_PARAMETER_EVENTS                               \
    NROS_RMW_QOS_PROFILE_FROM_POLICIES(RELIABLE, VOLATILE, KEEP_LAST, 1000, SYSTEM_DEFAULT)
 
#define NROS_RMW_QOS_PROFILE_SYSTEM_DEFAULT                                 \
    NROS_RMW_QOS_PROFILE_FROM_POLICIES(SYSTEM_DEFAULT, SYSTEM_DEFAULT, SYSTEM_DEFAULT, 0,  \
                                       SYSTEM_DEFAULT)
 
#define NROS_RMW_QOS_PROFILE_UNKNOWN                                        \
    NROS_RMW_QOS_PROFILE_FROM_POLICIES(UNKNOWN, UNKNOWN, UNKNOWN, 0, UNKNOWN)
 
/* ------------------------------------------------------------------ */
/* Which QoS policies a backend honours (issue 1329)                  */
/* ------------------------------------------------------------------ */
 
#define NROS_RMW_QOS_POLICY_RELIABILITY                  (1u << 0)
#define NROS_RMW_QOS_POLICY_DURABILITY_VOLATILE          (1u << 1)
#define NROS_RMW_QOS_POLICY_DURABILITY_TRANSIENT_LOCAL   (1u << 2)
#define NROS_RMW_QOS_POLICY_HISTORY                      (1u << 3)
#define NROS_RMW_QOS_POLICY_DEPTH                        (1u << 4)
#define NROS_RMW_QOS_POLICY_DEADLINE                     (1u << 5)
#define NROS_RMW_QOS_POLICY_LIFESPAN                     (1u << 6)
#define NROS_RMW_QOS_POLICY_LIVELINESS_AUTOMATIC         (1u << 7)
#define NROS_RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC   (1u << 8)
#define NROS_RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_NODE    (1u << 9)
#define NROS_RMW_QOS_POLICY_LIVELINESS_LEASE             (1u << 10)
#define NROS_RMW_QOS_POLICY_AVOID_ROS_NAMESPACE_CONVENTIONS (1u << 11)
 
#define NROS_RMW_QOS_POLICY_NONE                         0u
 
#define NROS_RMW_QOS_POLICY_CORE                                             \
    (NROS_RMW_QOS_POLICY_RELIABILITY | NROS_RMW_QOS_POLICY_DURABILITY_VOLATILE | \
     NROS_RMW_QOS_POLICY_HISTORY | NROS_RMW_QOS_POLICY_DEPTH)
 
/* ------------------------------------------------------------------ */
/* Entity structs                                                     */
/* ------------------------------------------------------------------ */
 
typedef struct rmw_session_t {
    const char *node_name;
    const char *namespace_;
    uint8_t     _reserved[8];
    void       *backend_data;
} rmw_session_t;
 
typedef struct rmw_node_t {
    const char *name;
    const char *namespace_;
    rmw_session_t *session;
    uint8_t _reserved[8];
    void *backend_data;
} rmw_node_t;
 
typedef struct rmw_publisher_t {
    const char    *topic_name;
    const char    *type_name;
    rmw_qos_profile_t qos;
    bool           can_loan_messages;
    uint8_t        _reserved[7];
    void          *backend_data;
} rmw_publisher_t;
 
typedef struct rmw_subscription_t {
    const char    *topic_name;
    const char    *type_name;
    rmw_qos_profile_t qos;
    bool           can_loan_messages;
    uint8_t        _reserved[7];
    void          *backend_data;
} rmw_subscription_t;
 
typedef struct rmw_service_t {
    const char *service_name;
    const char *type_name;
    uint8_t     _reserved[8];
    void       *backend_data;
} rmw_service_t;
 
typedef struct rmw_client_t {
    const char *service_name;
    const char *type_name;
    uint8_t     _reserved[8];
    void       *backend_data;
} rmw_client_t;
 
#endif /* NROS_RMW_ENTITY_H */