rmw_cyclonedds 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rmw_cyclonedds
版本：1.3.4（Humble），子包 1 个，构建类型 ament_cmake，语言 C++，许可证 Apache 2.0，质量等级 QL2。

rmw_cyclonedds_cpp 是 ROS 2 面向 Eclipse CycloneDDS 的 RMW 实现，将标准 rmw_* C API 映射到 Cyclone 的 DDS C API（dds/dds.h）及底层 DDSI serdata/sertype 插件接口。Humble 上常与 rmw_fastrtps_cpp 并列可选；启用共享内存时需 Cyclone 编译 SHM 支持并配置 CYCLONEDDS_URI。

外部依赖：DDS 本体在独立仓库 eclipse-cyclonedds/cyclonedds。未找到 CycloneDDS CMake 包时，本包 跳过编译。

1. 总体认识

1.1 核心职责

1.2 在 ROS 2 栈中的位置

1.3 与 CycloneDDS 的边界

1
2
3
4
5
6

rcl → rmw_cyclonedds_cpp
        ├── rmw_node.cpp          # RMW 语义、实体生命周期、wait、graph
        ├── serdata.cpp / serdes  # DDSI 样本封装与 CDR 缓冲
        ├── TypeSupport2.cpp      # introspection → CDR 读写器
        └── dds_* API               # Participant/Writer/Reader/WaitSet
              └── Cyclone DDSI      # RTPS、发现、可选 SHM 传输

2. 包结构与构建

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

rmw_cyclonedds/
├── README.md
├── shared_memory_support.md        # iceoryx / RouDi 使用说明
└── rmw_cyclonedds_cpp/
    ├── package.xml
    ├── CMakeLists.txt
    ├── cmake/get_rmw_cyclonedds_output_filter.cmake
    └── src/
        ├── rmw_node.cpp            # ★ 主实现 (~5511 行)
        ├── serdata.cpp / serdata.hpp
        ├── serdes.cpp / serdes.hpp
        ├── TypeSupport.cpp / TypeSupport2.cpp / *.hpp
        ├── Serialization.cpp       # CDR cursor 引擎
        ├── demangle.cpp
        ├── u16string.cpp             # wstring 序列化辅助
        ├── exception*.cpp
        ├── rmw_get_network_flow_endpoints.cpp
        └── rmw_cyclonedds_topic.idl  # 占位 IDL（dummy topic）

2.1 依赖（package.xml）

1
2
3
4
5
6
7
8

rmw_cyclonedds_cpp
├── cyclonedds              # libddsc（必需）
├── iceoryx_binding_c       # 仅当 Cyclone 启用 SHM 时链接
├── rmw / rmw_dds_common
├── rcutils / rcpputils
├── rosidl_runtime_c
├── rosidl_typesupport_introspection_c/cpp
└── tracetools              # 追踪点

Typesupport 注册：

1
2
3

register_rmw_implementation(
  "c:rosidl_typesupport_c:rosidl_typesupport_introspection_c"
  "cpp:rosidl_typesupport_cpp:rosidl_typesupport_introspection_cpp")

与 FastRTPS/Connext 不同，不注册 rosidl_typesupport_fastrtps_*。

2.2 条件编译：共享内存

1
2
3
4
5

get_target_property(_cyclonedds_has_shm CycloneDDS::ddsc SHM_SUPPORT_IS_AVAILABLE)
if(_cyclonedds_has_shm)
  find_package(iceoryx_binding_c REQUIRED)
  target_link_libraries(... iceoryx_binding_c)
endif()

启用后定义 DDS_HAS_SHM，开放 loan API 与 iceoryx chunk 路径。

3. 全局状态与 Domain 管理

3.1 全局单例 Cdds（gcdds()）

1
2
3
4
5
6
7
8
9

struct Cdds {
  std::mutex lock;
  std::mutex domains_lock;
  std::map<dds_domainid_t, CddsDomain> domains;

  /* 空 waitset 时 attach 永不触发的 guard，避免 Cyclone 无实体时立即返回 */
  dds_entity_t gc_for_empty_waitset;
  std::unordered_set<CddsWaitset *> waitsets;
};

• CddsDomain：每个 ROS domain id 一份，含 localhost_only、refcount、domain_handle。
• localhost-only：创建 domain 时在 CYCLONEDDS_URI 前注入 "localhost" 网络接口配置。
• 同一 domain 内所有 node 的 localhost_only 必须一致，否则创建失败。

3.2 rmw_context_impl_t

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

struct rmw_context_impl_s {
  rmw_dds_common::Context common;
  dds_domainid_t domain_id;
  dds_entity_t ppant;           // DomainParticipant
  rmw_gid_t ppant_gid;

  dds_entity_t rd_participant;  // DCPS builtin readers
  dds_entity_t rd_subscription;
  dds_entity_t rd_publication;

  dds_entity_t dds_pub;         // 共用 DDS Publisher
  dds_entity_t dds_sub;         // 共用 DDS Subscriber

  size_t node_count;
  std::mutex initialization_mutex;
  bool is_shutdown;
  uint32_t client_service_id;
};

3.3 生命周期时序

与 Connext RMW 类似，Participant 在首个 node 创建时初始化：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

rmw_init()
  └── 仅分配 rmw_context_impl_t，拷贝 init_options（不创建 DDS 实体）

rmw_create_node()  [首个 node]
  └── rmw_context_impl_t::init()
        ├── check_create_domain()     # 必要时 dds_create_domain
        ├── dds_create_participant()
        ├── DCPSParticipant/Publication/Subscription readers
        ├── dds_create_publisher/subscriber
        ├── create_publisher/subscription("ros_discovery_info")
        ├── discovery_thread_start()
        └── graph_cache.add_node + publish

rmw_destroy_node()  [最后一个 node]
  └── rmw_context_impl_t::fini() → tear down participant / domain

rmw_shutdown 仅设 is_shutdown=true；rmw_context_fini 要求已 shutdown，释放 impl。

4. 实体内部结构

rmw_*_t->data 指向上述结构；implementation_identifier = "rmw_cyclonedds_cpp"。

5. Topic 命名

前缀（namespace_prefix.hpp）：

make_fqtopic(prefix, name, suffix, qos) 组装 DDS topic 名；avoid_ros_namespace_conventions 时跳过 rt 前缀。

内部 graph topic：ros_discovery_info（ParticipantEntitiesInfo，TRANSIENT_LOCAL）。

demangle.cpp 提供 topic/type 名还原，供 graph API 返回 ROS 语义字符串。

6. 类型系统与序列化

6.1 设计思路

Cyclone RMW 不使用 rosidl_typesupport_fastrtps_*，而是：

1. 通过 introspection（C 或 C++）获取 MessageMembers / MessageMember 元数据；
2. TypeSupport2.hpp 构建 StructValueType 类型树；
3. Serialization.cpp 的 CDRCursor 按 OMG CDR 规则读写；
4. serdata_rmw 继承 ddsi_serdata，持有 CDR 字节流或 iceoryx chunk 指针。

6.2 sertype_rmw / serdata_rmw

1
2
3
4
5
6
7
8
9
10
11
12
13

struct sertype_rmw : ddsi_sertype {
  CddsTypeSupport type_support;
  bool is_request_header;   // service 请求类型带 header
  std::unique_ptr<const BaseCDRWriter> cdr_writer;
  bool is_fixed;
  std::mutex serialize_lock;
};

class serdata_rmw : public ddsi_serdata {
  size_t m_size;
  std::unique_ptr<byte[]> m_data;  // 前 4 字节：CDR encapsulation
  // SHM: iox_chunk, iox_subscriber 等
};

Service 请求/响应包装：

1
2

typedef struct cdds_request_header { uint64_t guid; int64_t seq; } cdds_request_header_t;
typedef struct cdds_request_wrapper { cdds_request_header_t header; void * data; } cdds_request_wrapper_t;

这是 非标准 basic RPC 变体（header 布局与 Connext extended / Fast-DDS 不同），导致 默认情况下 service 难以跨 rmw 厂商互通（Connext 需 RMW_CONNEXT_CYCLONE_COMPATIBILITY_MODE）。

6.3 Typesupport 选择

get_typesupport() 优先 introspection C，其次 C++：

1
2

get_message_typesupport_handle(type_supports, rosidl_typesupport_introspection_c__identifier)
// fallback: rosidl_typesupport_introspection_cpp::typesupport_identifier

6.4 rmw_serialize / rmw_deserialize

在 rmw_node.cpp 中调用 serdes 与 TypeSupport 模块，格式字符串 "cdr"（rmw_get_serialization_format()）。

7. 发布与订阅数据路径

7.1 常规发布

1
2
3
4

rmw_publish()
  → CddsPublisher::write path
  → 序列化 ros_message → serdata_rmw
  → dds_writecdr(writer, serdata)  或 dds_write

7.2 常规 take

1
2
3
4

rmw_take() / rmw_take_with_info()
  → dds_take / dds_takecdr
  → 反序列化 serdata → ros_message
  → message_info_from_sample_info()

7.3 共享内存与 Loan（DDS_HAS_SHM）

当 Cyclone 启用 iceoryx 且消息为 fixed-size 时：

未编译 SHM 时，上述 API 返回 RMW_RET_UNSUPPORTED。

配置见仓库 shared_memory_support.md：需 CYCLONEDDS_URI 启用 SharedMemory、运行 iox-roudi 等。

7.4 自包含类型检测

is_type_self_contained() 决定是否设置 can_loan_messages / is_loaning_available（无 string/动态数组等）。

8. Service / Client

8.1 创建逻辑（create_client_service）

• Service：sub 收 rq/...Request，pub 发 rr/...Reply
• Client：pub 发 rq/...Request，sub 收 rr/...Reply
• 各端创建带 is_request_header=true 的 sertype_rmw
• Writer/Reader QoS user_data 写入 serviceid= / clientid= 十六进制串，用于配对

8.2 请求-响应路径

1
2
3
4
5
6
7
8
9
10

rmw_send_request()
  → 填充 cdds_request_header { guid, seq }
  → dds_write(client.pub, &wrap)

rmw_take_request() / rmw_take_response()
  → dds_take → 解析 wrap.header
  → 重建 rmw_request_id_t（writer_guid + publication_handle + seq）

rmw_send_response()
  → 同 send_request，使用 service 侧 publisher

rmw_service_server_is_available 通过 matched endpoints + user_data 检查 client reader 是否就绪。

9. Graph 与 Discovery

9.1 初始化（rmw_context_impl_s::init 内）

与 Connext/FastRTPS 新实现一致：

1. 创建 ros_discovery_info pub/sub（ParticipantEntitiesInfo）
2. 创建 graph guard_condition
3. 启动 discovery 线程

9.2 Discovery 线程（discovery_thread）

WaitSet 监听：

• rd_participant → handle_DCPSParticipant
• rd_publication → handle_DCPSPublication
• rd_subscription → handle_DCPSSubscription
• common.sub → handle_ParticipantEntitiesInfo
• 退出 guard condition

更新 rmw_dds_common::GraphCache，必要时 rmw_publish 广播本地变更。

9.3 Node 创建时的 graph 更新

1
2
3

std::lock_guard<std::mutex> guard(common->node_update_mutex);
auto participant_msg = common->graph_cache.add_node(common->gid, name, namespace_);
rmw_publish(common->pub, &participant_msg, ...);

锁保证 update + publish 原子性，避免交错消息覆盖。

9.4 Graph API

rmw_get_node_names、rmw_get_topic_names_and_types、rmw_get_publishers_info_by_topic 等均在 rmw_node.cpp 后半部分，读取 graph_cache 并 demangle。

10. Wait Set 与 rmw_wait

10.1 空 WaitSet 问题

Cyclone 在 waitset 无任何 condition 时会立即返回。RMW 创建全局 dummy guard condition（永不 trigger）并 attach 到每个 waitset，使空 wait 能正确阻塞。

10.2 rmw_wait 流程

1. 检查 ws->inuse（禁止同一 waitset 并发 wait）
2. 若 subscription/guard/service/client/event 数组变化 → waitset_detach 后重新 attach
3. Subscription/Service/Client 使用 ReadCondition（rdcondh）
4. dds_waitset_wait + timeout
5. 未就绪条目在 rcl 传入的数组中置 NULL

Event 通过 gather_event_entities 收集 status condition 并 attach。

11. QoS

11.1 ROS → DDS

create_readwrite_qos() / rmw_duration_to_dds() 映射：

• history / depth
• reliability（RELIABLE / BEST_EFFORT）
• durability（VOLATILE / TRANSIENT_LOCAL）
• deadline / lifespan / liveliness

11.2 DDS → ROS

dds_qos_to_rmw_qos()、get_readwrite_qos() 用于 rmw_publisher_get_actual_qos 等。

11.3 兼容性检查

1
2
3

rmw_qos_profile_check_compatible(...) {
  return rmw_dds_common::qos_profile_check_compatible(...);
}

11.4 Cyclone 配置

运行时行为大量受 CYCLONEDDS_URI 影响（发现 peer、追踪日志、SHM、网卡选择等），见 README 与 Cyclone 手册。

12. 事件与回调

12.1 支持的事件

mask_map 映射 rmw 事件到 DDS status：

• RMW_EVENT_*_QOS_INCOMPATIBLE
• RMW_EVENT_*_DEADLINE_MISSED
• RMW_EVENT_LIVELINESS_*
• RMW_EVENT_MESSAGE_LOST

12.2 两种通知机制

1. Wait 路径：rmw_take_event 读取 status
2. Callback 路径：rmw_*_set_on_new_message_callback、rmw_event_set_callback 使用 DDS listener + user_callback_data_t 计数

13. 安全（SROS2）

1
2
3

#if DDS_HAS_SECURITY && DDS_HAS_PROPERTY_LIST_QOS
#define RMW_SUPPORT_SECURITY 1
#endif

configure_qos_for_security() 在创建 participant 时设置 security 相关 QoS property；enforce 模式下失败则 init 中止。依赖 Cyclone 编译时启用 security。

Participant user_data 写入 enclave=...; 供 graph 使用。

14. 日志与追踪

• rmw_set_log_severity → dds_set_log_mask(DDS_LC_*) 映射 rcutils 级别
• tracetools：关键路径插入 LTTng 追踪点（与 ROS 2 全局 tracing 集成）
• get_rmw_cyclonedds_output_filter.cmake：注册控制台输出过滤正则（网卡选择警告）

15. 未实现或受限功能

16. 与 rmw_dds_common 的协作

Cyclone 实现是 rmw_dds_common 的主要消费者之一，graph 协议与 FastRTPS/Cyclone/Connext 新版对齐。

17. 互操作说明

18. 调试建议

1. 确认 RMW：ros2 doctor --report 或检查 RMW_IMPLEMENTATION=rmw_cyclonedds_cpp。
2. Discovery 问题：配置 CYCLONEDDS_URI 静态 peer；用 Cyclone ddsperf sanity 排除网络层。
3. 大消息延迟：增大 Linux net.core.rmem_max（README 推荐）。
4. Graph 空：检查 ros_discovery_info 与 DCPS reader 是否创建成功；看 discovery 线程是否运行。
5. SHM：确认 RouDi 运行、QoS 符合 shared_memory_support.md 限制。
6. Cyclone 跟踪：CYCLONEDDS_URI='<Tracing><Verbosity>trace</>...'。

19. 推荐阅读顺序

1. rmw_node.cpp 前 450 行 — 全局 struct、identifier、日志
2. rmw_context_impl_s::init（~1160 行） — Participant + discovery 初始化
3. create_publisher / create_cdds_publisher — topic + sertype 创建
4. serdata.hpp + serdata.cpp — DDSI 样本与 SHM
5. TypeSupport2.hpp + Serialization.cpp — CDR 序列化核心
6. discovery_thread + graph 回调 — 图更新
7. rmw_wait（~4037 行） — waitset 语义
8. Service 段（~4550 行） — cdds_request_wrapper
9. Cyclone 上游 — dds_create_*、ddsi_serdata API
10. shared_memory_support.md — 零拷贝配置

20. 小结

rmw_cyclonedds 是 单包、单主文件 型 RMW 实现，特点鲜明：

• 对上：完整覆盖 Humble RMW 契约（loan/network flow 等部分可选）；
• 对下：深度集成 Cyclone DDSI serdata 插件，序列化走 自研 introspection CDR；
• 横向：通过 rmw_dds_common 统一 ROS graph；
• 性能：可选 iceoryx 共享内存实现 fixed 类型零拷贝；
• 注意：Service RPC 使用 自定义 inline header，跨厂商调用需额外兼容配置。

Humble 默认 RMW 仍为 Fast-DDS，选用 Cyclone 需显式 export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp 并在构建时确保 cyclonedds 包可用。

rmw_dds_common 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rmw_dds_common
版本：1.6.0（Humble），子包 1 个，构建类型 ament_cmake，语言 C++，许可证 Apache 2.0，质量等级 QL1。

rmw_dds_common 是 ROS 2 中 DDS 系 RMW 实现的共享 C++ 库：提供 ROS Graph 缓存、跨进程节点发现消息、QoS 兼容性检查 与 GID/安全/时间 等工具。它 不 直接调用 DDS API，也不实现 rmw_* 符号；各 rmw_*_cpp 在 init/graph 路径中嵌入并驱动本库。

设计背景：ROS 2 Node Discovery (design #250)

1. 总体认识

1.1 核心职责

1.2 在 ROS 2 栈中的位置

关键区分：本库是 库（library），不是 RMW 实现；链接 librmw_dds_common.so 不会提供 rmw_init。

2. 包结构与构建

1
2
3
4
5
6
7
8
9
10

rmw_dds_common/
└── rmw_dds_common/
    ├── msg/                          # rosidl 消息定义
    │   ├── Gid.msg
    │   ├── NodeEntitiesInfo.msg
    │   └── ParticipantEntitiesInfo.msg
    ├── include/rmw_dds_common/       # 6 个头文件
    ├── src/                          # 5 个 .cpp（~1646 行）
    ├── test/                         # gmock + benchmark
    └── docs/FEATURES.md

2.1 依赖（package.xml）

1
2
3
4
5
6

rmw_dds_common
├── rmw                    # rmw_gid_t、qos、topic_endpoint_info 等
├── rcutils                # 分配器、日志、字符串
├── rcpputils              # 文件系统（security）
├── rosidl_runtime_cpp     # 生成消息 C++ 类型
└── rosidl_default_generators

2.2 构建产物

1
2
3
4
5
6
7
8
9
10
11
12

rosidl_generate_interfaces(${PROJECT_NAME}
  "msg/Gid.msg"
  "msg/NodeEntitiesInfo.msg"
  "msg/ParticipantEntitiesInfo.msg")

add_library(${PROJECT_NAME}_library SHARED
  src/gid_utils.cpp
  src/graph_cache.cpp
  src/qos.cpp
  src/security.cpp
  src/time_utils.cpp)
# OUTPUT_NAME → librmw_dds_common.so

库 PUBLIC 链接 rmw::rmw 与生成的 rosidl_typesupport_cpp 目标。

3. 发现消息（rosidl）

3.1 消息层次

1
2
3
4
5
6
7

ParticipantEntitiesInfo
├── Gid gid                              # DDS Participant 的 rmw_gid
└── NodeEntitiesInfo[] node_entities_info_seq
        ├── string node_namespace
        ├── string node_name
        ├── Gid[] reader_gid_seq         # 该节点拥有的 DataReader
        └── Gid[] writer_gid_seq         # 该节点拥有的 DataWriter

1
2

# Gid.msg — 与 rmw_gid_t.data 对齐（24 字节）
char[24] data

3.2 传播路径（由各 RMW 实现 wiring）

1
2
3
4
5
6
7
8

本地 rmw_create_node / create_publisher
  → GraphCache::add_node / associate_writer
  → 返回 ParticipantEntitiesInfo
  → rmw_publish("ros_discovery_info", msg)

远端 rmw_take("ros_discovery_info")
  → GraphCache::update_participant_entities(msg)
  → 合并 node ↔ endpoint GID 映射

DDS builtin topic（DCPSPublication/Subscription/Participant）则通过 add_reader / add_writer 填充 topic 名、类型名、QoS，与 ROS 层 node 关联 正交——GraphCache 将两路信息合并后回答 graph 查询。

4. GraphCache 数据模型

4.1 三张内部表

1
2
3
4
5
6

class GraphCache {
  EntityGidToInfo data_writers_;      // gid → EntityInfo
  EntityGidToInfo data_readers_;
  ParticipantToNodesMap participants_; // gid → ParticipantInfo
  std::mutex mutex_;
};

EntityGidToInfo 使用 Compare_rmw_gid_t 作为 map 键（按 24 字节 lexicographical 比较）。

4.2 更新 API 分组

graph_cache.hpp 将方法分为四组：

4.3 变更回调

1
2
3

graph_cache.set_on_change_callback([]() {
  rmw_trigger_guard_condition(graph_guard_condition);
});

RMW 实现注册回调，在 graph 变化时唤醒 rcl wait set（用于 ros2 topic list 等刷新）。

5. GraphCache 工作流程

5.1 本地节点创建（典型时序）

5.2 本地 Publisher 创建

1
2
3
4

create_publisher()
  → GraphCache::add_writer(writer_gid, topic, type, participant_gid, qos)  // DDS 侧信息
  → GraphCache::associate_writer(writer_gid, participant_gid, node_name, ns) // 挂到 node
  → 返回 ParticipantEntitiesInfo → publish

5.3 远端更新

1
2
3

take(ros_discovery_info)
  → GraphCache::update_participant_entities(msg)
  → 覆盖 participants_[gid].node_entities_info_seq

5.4 introspection 查询

• get_names_and_types：遍历 data_writers_/data_readers_，经 demangle 回调 还原 ROS topic/type 名，聚合为 rmw_names_and_types_t。
• get_node_names：遍历 participants_ 中所有 NodeEntitiesInfo。
• get_writers/readers_info_by_topic：按 DDS topic 名过滤 entity，填充 rmw_topic_endpoint_info_t（含 node 名、namespace、GID、QoS）。

Demangle 由 RMW 实现注入（DemangleFunctionT），本库不硬编码 rt/ 前缀规则。

6. Context 结构

1
2
3
4
5
6
7
8
9
10
11
12
13

namespace rmw_dds_common {
struct Context {
  rmw_gid_t gid;                        // 本 Participant 的 GID
  rmw_publisher_t * pub;                // 发布 ParticipantEntitiesInfo
  rmw_subscription_t * sub;             // 订阅 ros_discovery_info
  GraphCache graph_cache;
  std::mutex node_update_mutex;         // update + publish 互斥
  std::thread listener_thread;          // 由 RMW 创建，非本库
  std::atomic_bool thread_is_running;
  rmw_guard_condition_t * listener_thread_gc;
  rmw_guard_condition_t * graph_guard_condition;
};
}

本库只定义结构体，不创建线程或 DDS 实体。rmw_cyclonedds_cpp / rmw_connextdds 在 context init 时：

1. 创建 internal pub/sub on ros_discovery_info
2. 启动 listener/discovery 线程处理 builtin + ParticipantEntitiesInfo
3. 将 graph_guard_condition 注册到 GraphCache 回调

7. GID 工具（gid_utils）

1
2
3

void convert_gid_to_msg(const rmw_gid_t * gid, msg::Gid * msg_gid) {
  std::memcpy(&msg_gid->data, gid->data, RMW_GID_STORAGE_SIZE);
}

implementation_identifier 字段 不 进入 msg，仅在 rmw_gid_t 全结构中使用。

8. QoS 兼容性（qos.cpp）

实现 rmw_qos_profile_check_compatible 的共享逻辑，被 Cyclone/Connext/FastRTPS RMW 转发调用。

8.1 判定级别

8.2 主要 ERROR 规则（节选）

WARNING 包括 history depth 小于订阅需求等。reason 缓冲区可选，用 _append_to_buffer 拼接人类可读说明。

9. 安全工具（security.cpp）

1
2
3
4

bool get_security_files(
  const std::string & prefix,
  const std::string & secure_root,
  std::unordered_map<std::string, std::string> & result);

在 secure_root（SROS2 enclave 目录）查找 必需 文件：

可选：CRL → crl.pem。缺失任一必需文件则返回 false 并清空 result。RMW 将 result 映射到 DDS Security QoS property。

10. 时间工具（time_utils.cpp）

DDS IDL Duration_t / Time_t 在 C 绑定中为 32 位 sec/nsec。clamp_rmw_time_to_dds_time：

1. 将 nsec 归一化到 < 1s
2. 若总时长超过 INT_MAX 秒，截断到 INT_MAX sec + (10^9-1) nsec 并打 debug 日志

各 RMW 在 ROS QoS → DDS QoS 转换时调用，避免静默溢出。

11. 线程安全与锁

GraphCache 方法自身已加锁；RMW 在 publish 发现消息前额外持有 node_update_mutex，防止交错更新导致远端 cache 状态不一致（见 Cyclone rmw_create_node 注释）。

12. 测试

启用 RCUTILS_ENABLE_FAULT_INJECTION 测试分配失败路径。

13. RMW 实现集成要点

以 rmw_cyclonedds_cpp 为例（Connext 结构类似）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

struct rmw_context_impl_s {
  rmw_dds_common::Context common;
  // ... DDS handles ...
};

// init 时
common.pub = create_publisher(..., "ros_discovery_info", ...);
common.sub = create_subscription(..., "ros_discovery_info", ...);
common.gid = ppant_gid;

// create_node 时
std::lock_guard<std::mutex> guard(common.node_update_mutex);
auto msg = common.graph_cache.add_node(common.gid, name, namespace_);
rmw_publish(common.pub, &msg, ...);

// DCPS 回调
graph_cache.add_writer(gid, dds_topic, dds_type, participant_gid, qos);

// graph API
return common.graph_cache.get_node_names(..., demangle_fn);

Fast-DDS RMW 对 GraphCache 的采用程度较低，但 QoS 检查 与 security 文件 仍复用本库。

14. 与 rmw 包的分工

15. 调试建议

1. Graph 不完整：确认 ros_discovery_info pub/sub 存在；检查 update_participant_entities 是否被调用。
2. topic list 与 echo 不一致：可能是 demangle 回调未剥离 rt/；或 DDS 侧 add_writer 与 ROS 侧 associate_writer 未配对。
3. QoS 兼容误报：阅读 reason 字符串；对照 qos.cpp 规则。
4. Security 启动失败：用 get_security_files 检查 enclave 目录六文件是否齐全。
5. 打印 cache 状态：operator<<(ostream, GraphCache) 可 dump 内部 map（调试构建）。

16. 推荐阅读顺序

1. docs/FEATURES.md — 功能清单
2. msg/*.msg — 发现协议数据结构
3. include/rmw_dds_common/context.hpp — RMW 嵌入字段
4. graph_cache.hpp API 分组 — 理解四路更新
5. graph_cache.cpp — add_node / associate_writer / get_names_and_types
6. qos.cpp — QoS 兼容规则
7. gid_utils.cpp — GID 互转
8. 下游 rmw_cyclonedds_cpp/src/rmw_node.cpp — discovery 线程如何喂 GraphCache
9. 设计文档 ros2/design#250

17. 小结

rmw_dds_common 是 ROS 2 DDS RMW 之间的“图与发现公共层”：

• 对上：为 rmw_get_node_names、ros2 topic list 等提供统一的缓存与查询；
• 对下：通过标准 msg 在 Participant 间同步 Node ↔ Endpoint 映射，并与 DDS builtin 发现互补；
• 横向：QoS、GID、Security、Time 工具避免在 Cyclone/Connext/FastRTPS 中重复实现。

理解本库是阅读 rmw_cyclonedds、rmw_connextdds graph 代码的前提；其本身 不包含 DDS 传输，仅维护 ROS 语义层面的分布式图。

rmw_fastrtps 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rmw_fastrtps
版本：6.2.10（Humble），子包 3 个，构建类型 ament_cmake，语言 C++，许可证 Apache 2.0，质量等级 QL2。

rmw_fastrtps 是 ROS 2 面向 eProsima Fast-DDS 的 RMW 实现族，将标准 rmw_* C API 映射到 Fast-DDS 的 DDS C++ API（fastdds/dds/*）及 RTPS 层。Humble 上它是 默认 RMW（get_default_rmw_implementation() 优先 rmw_fastrtps_cpp）；也可选用 rmw_fastrtps_dynamic_cpp。

外部依赖：DDS 本体在独立仓库 eProsima/Fast-DDS（Humble 对应 2.6.x），序列化依赖 Fast-CDR。

1. 总体认识

1.1 核心职责

1.2 在 ROS 2 栈中的位置

1.3 与 Fast-DDS 的边界

1
2
3
4
5
6
7
8
9
10

rcl → rmw_fastrtps_cpp / rmw_fastrtps_dynamic_cpp
        │ extern "C" rmw_*()          ← 薄包装，传 implementation identifier
        └── rmw_fastrtps_shared_cpp::__rmw_*()
              ├── CustomParticipantInfo / CustomPublisherInfo / CustomSubscriberInfo
              ├── ParticipantListener → rmw_dds_common::GraphCache（RTPS 发现）
              ├── listener_thread → ros_discovery_info take
              ├── TypeSupport → Fast-CDR serialize/deserialize
              └── Fast-DDS API
                    DomainParticipant / DataWriter / DataReader / WaitSet
                          └── Fast-DDS RTPS（UDPv4 + SharedMem）

2. 三包结构与构建

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

rmw_fastrtps/
├── README.md                       # 环境变量、XML QoS、零拷贝说明
├── rmw_fastrtps_shared_cpp/        # ★ 共享实现（非 RMW 注册包）
│   ├── include/rmw_fastrtps_shared_cpp/
│   │   ├── rmw_common.hpp          # 全部 __rmw_* 声明
│   │   ├── rmw_context_impl.hpp    # rmw_context_impl_s 定义
│   │   ├── custom_participant_info.hpp  # ParticipantListener + GraphCache
│   │   ├── TypeSupport.hpp         # TopicDataType 抽象基类
│   │   └── custom_*_info.hpp       # pub/sub/service/client 私有数据
│   └── src/
│       ├── participant.cpp         # create_participant、QoS/安全/传输
│       ├── listener_thread.cpp     # ros_discovery_info 后台线程
│       ├── rmw_wait.cpp            # Fast-DDS WaitSet
│       ├── rmw_publish.cpp / rmw_take.cpp
│       ├── rmw_request.cpp / rmw_response.cpp  # Service RPC
│       ├── qos.cpp                 # rmw ↔ DDS QoS 映射
│       └── TypeSupport_impl.cpp    # serialize/deserialize 通用逻辑
├── rmw_fastrtps_cpp/               # 默认 RMW（静态 typesupport）
│   ├── src/
│   │   ├── rmw_*.cpp               # extern "C" 薄包装
│   │   ├── init_rmw_context_impl.cpp  # 首 node 时 lazy init
│   │   ├── publisher.cpp / subscription.cpp  # 实体创建 + TypeSupport
│   │   ├── type_support_common.cpp # message_type_support_callbacks_t
│   │   └── rmw_service.cpp / rmw_client.cpp
│   └── CMakeLists.txt              # register_rmw_implementation
└── rmw_fastrtps_dynamic_cpp/       # introspection RMW
    ├── src/
    │   ├── type_support_registry.cpp  # 运行时 TypeSupport 引用计数
    │   └── （其余镜像 rmw_fastrtps_cpp 结构）
    └── CMakeLists.txt

2.1 依赖（package.xml 摘要）

1
2
3
4
5
6
7
8
9
10

rmw_fastrtps_cpp
├── fastrtps / fastcdr / fastrtps_cmake_module
├── rmw / rmw_dds_common / rmw_fastrtps_shared_cpp
├── rosidl_typesupport_fastrtps_c/cpp     ← 仅 static 包
├── rcutils / rcpputils / tracetools
└── member_of_group: rmw_implementation_packages

rmw_fastrtps_dynamic_cpp
├── （同上，但 typesupport 换为 rosidl_typesupport_introspection_c/cpp）
└── 不依赖 rosidl_typesupport_fastrtps_*

3. 双实现 + identifier 模式

3.1 两个 RMW identifier

每个 handle（rmw_node_t、rmw_publisher_t 等）的 implementation_identifier 必须与传入的 identifier 一致，否则返回 RMW_RET_INCORRECT_RMW_IMPLEMENTATION。

3.2 薄包装 → 共享实现

rmw_fastrtps_cpp 中典型模式：

1
2
3
4
5
6

// rmw_fastrtps_cpp/src/rmw_publisher.cpp
rmw_ret_t rmw_publish(const rmw_publisher_t * publisher, const void * ros_message, ...)
{
  return rmw_fastrtps_shared_cpp::__rmw_publish(
    eprosima_fastrtps_identifier, publisher, ros_message, allocation);
}

共享库中校验 identifier 并执行 Fast-DDS 调用：

1
2
3
4
5
6

// rmw_fastrtps_shared_cpp/src/rmw_publish.cpp
RMW_CHECK_TYPE_IDENTIFIERS_MATCH(
  publisher, publisher->implementation_identifier, identifier, ...);
auto info = static_cast<CustomPublisherInfo *>(publisher->data);
SerializedData data{false, const_cast<void *>(ros_message), info->type_support_impl_};
info->data_writer_->write(&data);

3.3 差异仅在 TypeSupport 与实体创建

4. Context 与 Participant 生命周期

4.1 rmw_context_impl_s

定义于 rmw_fastrtps_shared_cpp/include/rmw_fastrtps_shared_cpp/rmw_context_impl.hpp：

1
2
3
4
5
6
7

struct rmw_context_impl_s {
  void * common;              // rmw_dds_common::Context*
  void * participant_info;    // CustomParticipantInfo*
  std::mutex mutex;
  uint64_t count;             // 引用计数（按 node 计数）
  bool is_shutdown;
};

4.2 初始化时序

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

rmw_init(options, context)
  ├── 设置 implementation_identifier、actual_domain_id
  ├── 分配 context->impl（此时尚未创建 Participant）
  └── 拷贝 init_options

rmw_create_node(context, ...)     ← 第一个 node 触发 heavyweight init
  └── increment_context_impl_ref_count(context)   [rmw_fastrtps_cpp/init_rmw_context_impl.cpp]
        ├── 若 count==0 → init_context_impl()
        │     ├── new rmw_dds_common::Context
        │     ├── create_participant() → CustomParticipantInfo + ParticipantListener
        │     ├── create_publisher/subscription on "ros_discovery_info"
        │     ├── create graph_guard_condition
        │     ├── run_listener_thread()
        │     └── graph_cache.set_on_change_callback → trigger GC
        └── count++

rmw_destroy_node(...)
  └── decrement_context_impl_ref_count()   [shared/init_rmw_context_impl.cpp]
        ├── 若 count→0：join listener、destroy discovery pub/sub、destroy participant
        └── delete rmw_dds_common::Context

rmw_shutdown(context) → is_shutdown = true
rmw_context_fini(context) → 要求 count==0 且已 shutdown

设计要点：Participant 与 graph 基础设施 按 context 懒加载，首个 rmw_create_node 时才创建 Fast-DDS 实体；多 node 共享同一 DomainParticipant。

4.3 create_participant 关键行为

participant.cpp 中 create_participant()：

Participant 内还预创建 Publisher 与 Subscriber 对象（entity_creation_mutex_ 保护后续 topic/writer/reader 创建）。

5. Graph 与 rmw_dds_common

5.1 双通道更新 GraphCache

通道 1 — 应用层 discovery topic

• Topic：ros_discovery_info（avoid_ros_namespace_conventions=true）
• 消息：rmw_dds_common::msg::ParticipantEntitiesInfo
• Publisher QoS：TRANSIENT_LOCAL + KEEP_LAST depth=1
• Subscriber QoS：KEEP_ALL
• listener_thread 循环 __rmw_wait + __rmw_take，忽略本 participant 的 GID

通道 2 — Fast-DDS 扩展 listener

ParticipantListener（custom_participant_info.hpp）重写：

• on_participant_discovery → 解析 user_data 中 enclave，graph_cache.add/remove_participant
• on_subscriber_discovery / on_publisher_discovery → graph_cache.add/remove_entity（含 QoS）

节点增删时在 __rmw_create_node / __rmw_destroy_node 中加锁发布 ParticipantEntitiesInfo（node_update_mutex 保证 publish 原子性）。

5.2 Graph Guard Condition

graph_cache.set_on_change_callback 注册 lambda，在图变化时 __rmw_trigger_guard_condition(graph_guard_condition)，供 rmw_node_get_graph_guard_condition 使用。

6. TypeSupport 与序列化

6.1 抽象基类

TypeSupport 继承 eprosima::fastdds::dds::TopicDataType：

1
2
3
4
5

struct SerializedData {
  bool is_cdr_buffer;   // true → data 指向 FastBuffer/Cdr
  void * data;
  const void * impl;    // typesupport callbacks 或 introspection members
};

• serialize() / deserialize() 在 TypeSupport_impl.cpp 中实现，根据 is_cdr_buffer 分支
• 普通 publish：is_cdr_buffer=false，impl 指向 message_type_support_callbacks_t 或 introspection members

6.2 静态 typesupport（rmw_fastrtps_cpp）

type_support_common.cpp：

• set_members() 读取 ROSIDL_TYPESUPPORT_FASTRTPS_* 宏判断 plain/bounded
• serializeROSmessage() 调用编译期生成的 callbacks->cdr_serialize
• is_plain() 决定 Data Sharing / loan 能力

6.3 动态 typesupport（rmw_fastrtps_dynamic_cpp）

TypeSupportRegistry（单例 + 引用计数）：

• get_message_type_support() / get_request_type_support() / get_response_type_support()
• 支持 rosidl_typesupport_introspection_c 与 _cpp
• 进程退出时 ~TypeSupportRegistry() 清理残留

适用场景：运行时切换消息类型、工具链不生成 fastrtps typesupport 的包；性能通常低于静态路径。

7. Publisher / Subscription 数据路径

7.1 创建流程（以 publisher 为例）

rmw_fastrtps_cpp/src/publisher.cpp → create_publisher()：

1. 校验 topic 名、QoS、require_unique_network_flow_endpoints
2. map_ros_to_dds() 生成 topic/type 名（rt/ 前缀、ros2msg/ros2srv 等）
3. 构造包内 TypeSupport，注册到 participant
4. rmw_qos_to_dds_attributes() + XML profile 加载（按 topic 名匹配 profile_name）
5. 创建 Topic + DataWriter + 可选 PubListener
6. 填充 CustomPublisherInfo，设置 publisher_gid
7. can_loan_messages = has_data_sharing && type_support->is_plain()

7.2 发布

7.3 接收

rmw_take.cpp（~558 行）：

• DataReader::take → deserializeROSmessage 或 loaned 路径
• 支持 rmw_take_with_info（publication handle 等）
• ignore_local_publications 在 init 时设为 true（注释：fastrtps 尚未完整实现该选项语义）

7.4 实体私有结构

均继承或组合 CustomEventInfo，支持 QoS/liveliness/deadline 事件。

8. Service / Client（Extended RPC）

Fast-DDS 使用 DDS 扩展 WriteParams 关联 request/response，与 Connext extended 模式互操作。

8.1 Client 发请求

rmw_request.cpp — __rmw_send_request：

1
2
3

wparams.related_sample_identity().writer_guid() = info->reader_guid_;
info->request_writer_->write(&data, wparams);
*sequence_id = (high << 32) | low;  // 来自 sample_identity

8.2 Service 收请求 / 发响应

• __rmw_take_request：从 request reader take，读取 related_sample_identity 填入 rmw_service_info_t
• __rmw_send_response：设置 wparams.related_sample_identity() 指向原 request

8.3 Client 收响应

__rmw_take_response：校验 related_sample_identity.writer_guid 匹配 client 的 reader/writer GUID，再反序列化。

互操作：与 Cyclone basic header 不兼容；与 Connext extended 可互通。跨 RMW service 调用需统一 RPC 映射。

9. Wait Set 与 rmw_wait

rmw_wait.cpp 使用 Fast-DDS WaitSet：

1. 遍历 subscriptions / clients / services / events，attach 各 StatusCondition
2. 若已有 untaken sample（get_first_untaken_info）→ skip_wait=true
3. attach guard conditions（含 graph GC、listener thread GC）
4. wait_set->wait() 或 wait(timeout)
5. 未就绪条目在 rcl 数组中置 NULL

WaitSet 存储于 rmw_wait_set_t->data（eprosima::fastdds::dds::WaitSet*）。

10. QoS 与环境变量

10.1 默认 Fast-DDS 策略（非 XML 模式）

10.2 环境变量

10.3 XML Profile 匹配规则

• Publisher/Subscription：profile_name = 最终 topic 名（含 namespace，FQN 以 / 开头时不拼 namespace）
• Service：profile_name="service" 或 mangled 服务名
• Client：profile_name="client" 或 mangled 服务名
• 回退：is_default_profile="true"

10.4 ROS ↔ DDS 映射

qos.cpp / rmw_qos.cpp：

• rmw_qos_to_dds_attributes() 创建实体时使用
• rtps_qos_to_rmw_qos() 供 ParticipantListener 写入 graph
• rmw_qos_profile_check_compatible() 委托 rmw_dds_common::qos_profile_check_compatible()

11. Loaned Message 与零拷贝

11.1 启用条件

1
2

// publisher.cpp / rmw_take.cpp
can_loan_messages = has_data_sharing && type_support_->is_plain();

需同时满足：

1. XML 中 Data Sharing 为 AUTOMATIC 或 ON（且 RMW_FASTRTPS_USE_QOS_FROM_XML=1）
2. 消息类型为 plain（POD，静态 typesupport 由 ROSIDL_TYPESUPPORT_FASTRTPS_PLAIN_TYPE 判定）

11.2 API 路径

11.3 传输层

默认 builtin transports：UDPv4（跨主机）+ SharedMem（同主机）。零拷贝 pipeline = Loan API + Data Sharing；仅 SHM transport 不等同于零拷贝。

Humble 上 plain 类型仍需 XML 启用 Data Sharing；Iron 及以后对 POD 要求放宽（见仓库 README）。

12. 事件、安全与追踪

12.1 RMW 事件

通过 CustomEventInfo + DataWriterListener / DataReaderListener 收集：

• RMW_EVENT_*_QOS_INCOMPATIBLE
• RMW_EVENT_*_DEADLINE_MISSED
• RMW_EVENT_LIVELINESS_*
• RMW_EVENT_MESSAGE_LOST

rmw_event.cpp + event_helpers.hpp 实现 rmw_take_event 与 callback 注册。

12.2 安全（SROS2）

participant.cpp 在 HAVE_SECURITY 且提供 security_root_path 时：

• 使用 rmw_dds_common::get_security_files() 解析证书路径
• 配置 PropertyPolicy（PKI-DH、AES-GCM-GMAC、Access-Permissions）
• rmw_security_logging.cpp 处理安全日志属性

12.3 追踪

关键路径插入 tracetools 追踪点（如 TRACEPOINT(rmw_publish, ...)）。

12.4 特性查询

rmw_features.cpp 当前仅声明支持：

• RMW_FEATURE_MESSAGE_INFO_PUBLICATION_SEQUENCE_NUMBER

13. 未实现或受限功能

14. 与 rmw_dds_common 的协作

Fast-DDS 实现与 Cyclone/Connext 新版共用同一 graph 协议，保证 ros2 topic list / ros2 node info 等工具跨 RMW 一致。

15. 互操作说明

16. 调试建议

1. 确认 RMW：echo $RMW_IMPLEMENTATION 或 ros2 doctor --report；默认应为 rmw_fastrtps_cpp。
2. Discovery 问题：检查防火墙与 multicast；localhost_only 时仅 127.0.0.1 + SHM。
3. Graph 空：确认 ros_discovery_info pub/sub 创建成功；listener_thread 是否运行；enclave user_data 是否解析。
4. QoS 不符预期：用 rmw_publisher_get_actual_qos；检查 RMW_FASTRTPS_USE_QOS_FROM_XML 与 XML profile 名是否匹配 topic。
5. 零拷贝不生效：确认 can_loan_messages、Data Sharing XML、消息是否 plain。
6. Fast-DDS 日志：通过 Fast-DDS 自身日志配置（Consumer 等）排查 RTPS 层。

17. 推荐阅读顺序

1. 仓库 README.md — 环境变量、XML 示例、零拷贝
2. rmw_fastrtps_cpp/src/rmw_init.cpp + init_rmw_context_impl.cpp — context 懒加载与 discovery 拓扑
3. custom_participant_info.hpp — ParticipantListener 与 graph 关系
4. listener_thread.cpp — ros_discovery_info 消费循环
5. rmw_fastrtps_cpp/src/publisher.cpp — 实体创建、XML QoS、loan 标志
6. TypeSupport.hpp + TypeSupport_impl.cpp — 序列化核心
7. rmw_publish.cpp / rmw_take.cpp — 数据平面
8. rmw_request.cpp / rmw_response.cpp — Service RPC
9. rmw_wait.cpp — WaitSet 语义
10. type_support_registry.cpp（dynamic 包）— 运行时 typesupport
11. Fast-DDS 上游文档 — Data Sharing、XML profiles、PublishMode

18. 小结

rmw_fastrtps 是 Humble 默认 RMW，采用 三包分层 设计：

• 对上：rmw_fastrtps_cpp / rmw_fastrtps_dynamic_cpp 导出完整 rmw_* API，差异仅在 typesupport 策略；
• 对中：rmw_fastrtps_shared_cpp 集中实现 __rmw_*，避免双倍维护 wait/graph/service 逻辑；
• 对下：映射到 Fast-DDS 2.6.x + Fast-CDR，利用 SharedMem、Data Sharing、extended RPC 等 eProsima 扩展；
• 横向：通过 rmw_dds_common 统一 ROS graph，与 Cyclone/Connext 工具链对齐。

选用 rmw_fastrtps_dynamic_cpp 可换运行时 introspection，但生产环境通常保留默认 rmw_fastrtps_cpp 以获得编译期 typesupport 性能。高级调优依赖 RMW_FASTRTPS_* 环境变量 与 FASTRTPS_DEFAULT_PROFILES_FILE XML 组合，而非仅 ROS QoS API。

rmw_implementation 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rmw_implementation
子包数量：2

1. 定位

rmw 实现代理包：RMW_IMPLEMENTATION 环境变量或 ament 默认选择具体 rmw 后端，对上层透明链接。

2. 子包列表

3. 核心组件

含 rmw_implementation 与 test_rmw_implementation。CMake 导出 get_default_rmw_implementation()。

4. 在 ROS 2 Humble 栈中的关系

见 ros2总览.md 分层图。

5. 推荐阅读顺序

1. 阅读各子包 package.xml 2. 入口源码 3. 下游依赖方

6. 小结

rmw_implementation 为含 2 个子包的源码树，是 ROS 2 Humble 发行版的一部分。

rmw 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/rmw
版本：6.1.2（Humble），子包 2 个，构建类型 ament_cmake，语言 C，许可证 Apache 2.0。

rmw（ROS Middleware Interface）是 ROS 2 中间件抽象层：在 RCL 与具体 DDS 实现之间定义统一的 C API 契约。rcl / rclcpp / rclpy 只依赖 rmw.h 中的符号名，运行时通过 rmw_implementation 代理库链接到 rmw_cyclonedds_cpp、rmw_fastrtps_cpp 等后端。

本仓库的关键定位：rmw 包提供 头文件 API 声明 + 与实现无关的公共工具实现（校验、QoS 字符串、init 零初始化、graph 辅助结构体等）。rmw_create_publisher、rmw_wait、rmw_init 等 核心中间件操作在本仓库仅声明，实现在各 rmw_*_cpp 包中。

设计文档参考：ROS Middleware Interface

1. 总体认识

1.1 核心职责

1.2 在 ROS 2 栈中的位置

1.3 API 声明 vs 实现分离

这是阅读 rmw 源码时最容易混淆的一点：

CMakeLists.txt 中 add_library(rmw ...) 只编译 20 个 .c 文件，不包含任何 DDS 调用。链接 librmw.so 的应用若直接调用 rmw_init 会得到 undefined symbol，必须通过 rmw_implementation 或具体后端包提供实现。

2. 子包结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

rmw/
├── rmw/                              # 核心 API 包 ★
│   ├── include/rmw/                  # 51 个头文件
│   │   ├── rmw.h                     # 主 API（~3214 行）
│   │   ├── types.h                   # 核心句柄与 QoS 类型
│   │   ├── init.h / init_options.h   # 生命周期
│   │   ├── get_*.h                   # Graph introspection
│   │   ├── events_statuses/          # QoS/存活事件状态结构
│   │   └── impl/cpp/                 # C++ 辅助（demangle 等）
│   ├── src/                          # 20 个 .c（~10K 行含注释）
│   └── cmake/                        # configure_rmw_library、register_rmw_implementation
└── rmw_implementation_cmake/         # CMake 宏包
    └── cmake/
        ├── get_available_rmw_implementations.cmake
        └── get_default_rmw_implementation.cmake

2.1 依赖关系（rmw/package.xml）

1
2
3

rmw
├── rcutils               # 错误链、分配器、日志级别映射、字符校验
└── rosidl_runtime_c      # typesupport 相关类型（build_export）

运行时 不 依赖任何 DDS 库；DDS 依赖在各 rmw_*_cpp 包中。

3. 句柄设计模式

几乎所有 RMW 实体采用相同的 type-erased handle 模式：

1
2
3
4
5
6
7

typedef struct rmw_publisher_s {
  const char * implementation_identifier;  // 如 "rmw_cyclonedds_cpp"
  void * data;                             // 后端私有结构指针
  const char * topic_name;                 // ROS 图可见名
  rmw_publisher_options_t options;
  bool can_loan_messages;
} rmw_publisher_t;

同类结构：rmw_node_t、rmw_subscription_t、rmw_service_t、rmw_client_t、rmw_guard_condition_t、rmw_wait_set_t、rmw_event_t。

3.1 分配器辅助（src/allocators.c）

后端实现创建实体时可复用本仓库提供的 句柄内存分配：

• rmw_node_allocate() / rmw_node_free()
• rmw_publisher_allocate() / rmw_publisher_free()
• 以及 subscription、service、client、guard_condition、wait_set 的对称函数

底层使用 rcutils 默认分配器，保证各实现一致的句柄布局。

4. 生命周期：init / context / shutdown

4.1 核心类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// init_options.h — 传入 rmw_init() 的配置
typedef struct rmw_init_options_s {
  uint64_t instance_id;
  const char * implementation_identifier;
  size_t domain_id;                        // RMW_DEFAULT_DOMAIN_ID = 0
  rmw_security_options_t security_options;
  rmw_localhost_only_t localhost_only;
  char * enclave;                          // SROS2 密钥库路径名
  rmw_init_options_impl_t * impl;          // 后端私有
  rcutils_allocator_t allocator;
} rmw_init_options_t;

// init.h — rmw_init() 成功后持有
typedef struct rmw_context_s {
  uint64_t instance_id;
  const char * implementation_identifier;
  rmw_init_options_t options;
  size_t actual_domain_id;
  rmw_context_impl_t * impl;
} rmw_context_t;

4.2 本仓库提供的零初始化

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// src/init.c
rmw_context_t rmw_get_zero_initialized_context(void) {
  return (const rmw_context_t){ .instance_id = 0, .impl = NULL };
}

// src/init_options.c
rmw_init_options_t rmw_get_zero_initialized_init_options(void) {
  return (const rmw_init_options_t){
    .domain_id = RMW_DEFAULT_DOMAIN_ID,
    .localhost_only = RMW_LOCALHOST_ONLY_DEFAULT,
    .security_options = rmw_get_default_security_options(),
    // ...
  };
}

4.3 实现侧必须提供的函数（仅声明）

rcl_init() 调用链：rcl_init → rmw_init_options_init → 设置 enclave/domain → rmw_init → 保存 rmw_context_t 到 rcl_context_t。

5. rmw.h 主 API 分组

rmw/include/rmw/rmw.h 是单一入口，按功能可划分为：

Graph 相关 API 还分散在独立头文件中（见第 8 节）。

6. QoS 体系

6.1 rmw_qos_profile_t

1
2
3
4
5
6
7
8
9
10
11

typedef struct rmw_qos_profile_s {
  enum rmw_qos_history_policy_e history;       // KEEP_LAST / KEEP_ALL
  size_t depth;
  enum rmw_qos_reliability_policy_e reliability; // RELIABLE / BEST_EFFORT
  enum rmw_qos_durability_policy_e durability;   // VOLATILE / TRANSIENT_LOCAL
  struct rmw_time_s deadline;
  struct rmw_time_s lifespan;
  enum rmw_qos_liveliness_policy_e liveliness;
  struct rmw_time_s liveliness_lease_duration;
  bool avoid_ros_namespace_conventions;          // 跳过 rt 前缀
} rmw_qos_profile_t;

时间字段使用 RMW_DURATION_UNSPECIFIED / RMW_DURATION_INFINITE 表示“用实现默认”或“无限”。

6.2 预设 Profile（qos_profiles.h）

rcl 层将这些 profile 映射到 rcl_qos_profile_t，再传给 rmw_create_publisher。

6.3 QoS 字符串转换（src/qos_string_conversions.c）

本仓库 完整实现 policy 枚举 ↔ 字符串互转，供 CLI、日志、测试使用：

• rmw_qos_reliability_policy_to_str / _from_str
• rmw_qos_durability_policy_to_str / _from_str
• rmw_qos_history_policy_to_str / _from_str
• rmw_qos_liveliness_policy_to_str / _from_str
• rmw_qos_policy_kind_to_str / rmw_qos_policy_kind_from_str

7. Wait Set 与 rmw_wait 契约

7.1 相关类型

1
2
3
4
5
6
7
8
9
10

typedef struct rmw_subscriptions_s {
  size_t subscriber_count;
  void ** subscribers;    // 指向 rmw_subscription_t->data
} rmw_subscriptions_t;

typedef struct rmw_wait_set_s {
  const char * implementation_identifier;
  rmw_guard_conditions_t * guard_conditions;
  void * data;
} rmw_wait_set_t;

还有对称的 rmw_services_t、rmw_clients_t、rmw_events_t、rmw_guard_conditions_t。

7.2 rmw_wait 语义（实现在后端）

1
2
3
4
5
6
7
8

rmw_ret_t rmw_wait(
  rmw_subscriptions_t * subscriptions,
  rmw_guard_conditions_t * guard_conditions,
  rmw_services_t * services,
  rmw_clients_t * clients,
  rmw_events_t * events,
  rmw_wait_set_t * wait_set,
  const rmw_time_t * wait_timeout);

契约要点（摘自 rmw.h 文档）：

1. 调用前：数组中非 NULL 条目表示要等待的实体；NULL 条目无效。
2. 调用后：未触发的实体对应数组项被设为 NULL；触发的保留原指针。
3. 返回值：RMW_RET_OK（有就绪）、RMW_RET_TIMEOUT（超时）、RMW_RET_INVALID_ARGUMENT。
4. 线程安全：同一 wait_set 不可并发 wait；同一实体不可被多个 wait_set 并发 wait。
5. 所有实体须属于与 wait_set 相同的 rmw_context。

7.3 rcl 层如何使用

1
2
3
4
5
6
7
8

rcl_wait_set_t
  ├── rmw_subscriptions_t   ← 从 rcl_subscription_t 收集
  ├── rmw_guard_conditions_t ← timer、graph、用户 guard
  ├── rmw_services_t / rmw_clients_t
  └── rmw_events_t

rcl_wait() → rmw_wait() → 后端 DDS WaitSet / waitset
返回后 rcl 扫描 NULL 位，标记哪些 subscription/timer 就绪

8. Graph Introspection API

除 rmw.h 中的 rmw_get_node_names、rmw_count_publishers 外，专用头文件定义更丰富的图 API：

辅助数据结构在本仓库实现：

• rmw_names_and_types_t — src/names_and_types.c（init/fini/check_zero）
• rmw_topic_endpoint_info_t — src/topic_endpoint_info.c（set topic_type、gid、qos 等）
• rmw_topic_endpoint_info_array_t — src/topic_endpoint_info_array.c

9. 命名校验（本仓库完整实现）

ROS 2 图命名规则在 RMW 层统一校验，供 rcl 与后端共用：

每个校验函数返回 RMW_RET_OK + validation_result 枚举（非错误码），并提供 *_validation_result_string() 人类可读描述。

示例（topic 校验入口）：

1
2
3
4

rmw_ret_t rmw_validate_full_topic_name(
  const char * topic_name,
  int * validation_result,
  size_t * invalid_index);

10. 事件（Events）

10.1 事件类型（event.h）

10.2 状态结构（events_statuses/）

incompatible_qos.h、liveliness_changed.h 等定义 DDS 事件计数的 C 结构，与 rmw_take_event（后端实现）配合。

10.3 本仓库实现

• rmw_get_zero_initialized_event() — src/event.c
• rmw_event_fini() — 重置为零结构（不释放 impl，impl 由后端管理）

rmw_publisher_event_init、rmw_subscription_event_init、rmw_take_event 等 仅声明。

11. 安全与网络选项

11.1 Security（src/security_options.c）

1
2
3
4

rmw_security_options_t rmw_get_default_security_options(void);
rmw_ret_t rmw_security_options_set_root_path(...);
rmw_ret_t rmw_security_options_copy(...);
rmw_ret_t rmw_security_options_fini(...);

与 SROS2 集成：enclave + security_root_path 指向密钥库。具体 DDS Security 插件加载在各后端。

11.2 Localhost / Domain

• domain_id.h — RMW_DEFAULT_DOMAIN_ID（0），隔离不同 ROS 域
• localhost.h — RMW_LOCALHOST_ONLY_DEFAULT 等，限制仅本机通信

12. 消息路径辅助类型

rmw_get_zero_initialized_message_info() 在 src/types.c 实现。

12.1 Loaned Message

API 在 rmw.h 中声明；can_loan_messages 标志由 rmw_create_publisher/subscription 设置。是否支持取决于后端与 typesupport（Fast-DDS 支持较好）。

12.2 Serialize / Deserialize

1
2
3
4
5
6
7
8
9

rmw_ret_t rmw_serialize(
  const void * ros_message,
  const rosidl_message_type_support_t * type_support,
  rmw_serialized_message_t * serialized_message);

rmw_ret_t rmw_deserialize(
  const rmw_serialized_message_t * serialized_message,
  const rosidl_message_type_support_t * type_support,
  void * ros_message);

实现通常委托给 rosidl_typesupport_* 的 CDR 序列化，再经 DDS 发送。

13. 错误处理

error_handling.h 薄封装 rcutils 线程局部错误链：

1
2
3
4
5
6

#define RMW_SET_ERROR_MSG(msg) RCUTILS_SET_ERROR_MSG(msg)
#define RMW_SET_ERROR_MSG_WITH_FORMAT_STRING(...) \
  RCUTILS_SET_ERROR_MSG_WITH_FORMAT_STRING(__VA_ARGS__)
rmw_error_string_t rmw_get_error_string(void);
bool rmw_error_is_set(void);
void rmw_reset_error(void);

13.1 返回码（ret_types.h）

src/convert_rcutils_ret_to_rmw_ret.c 提供 rmw_convert_rcutils_ret_to_rmw_ret()，供后端统一转换 rcutils 返回值。

13.2 断言宏（sanity_checks.c / macros.h）

RMW_CHECK_ARGUMENT_FOR_NULL、RMW_CHECK_TYPE_IDENTIFIERS_MATCH 等在后端实现中广泛使用，保证跨实现一致的错误报告。

14. 特性查询（features.h）

1
2
3
4
5
6

typedef enum rmw_feature_e {
  RMW_FEATURE_MESSAGE_INFO_PUBLICATION_SEQUENCE_NUMBER,
  RMW_FEATURE_MESSAGE_INFO_RECEPTION_SEQUENCE_NUMBER,
} rmw_feature_t;

bool rmw_feature_supported(rmw_feature_t feature);  // 后端实现

用于上层判断 rmw_message_info_t 中 sequence number 字段是否可靠填充。

15. src/ 模块一览

16. rmw_implementation_cmake

16.1 枚举可用实现

get_available_rmw_implementations(var)：

1. 从 ament index 读取 rmw_typesupport 资源（排除 rmw_implementation 代理包本身）
2. 可通过环境变量 RMW_IMPLEMENTATIONS 或 CMake 变量过滤
3. 结果写入 ${var} 列表

16.2 选择默认实现

get_default_rmw_implementation(var)：

1. 若未设置 RMW_IMPLEMENTATION（CMake 或环境变量）：
   • 优先 rmw_fastrtps_cpp
   • 否则取字母序第一个
2. 若已设置：验证其在可用列表中，find_package 该包
3. Humble 上默认编译链接 Fast-DDS，不是 CycloneDDS（除非显式设置 RMW_IMPLEMENTATION=rmw_cyclonedds_cpp）

16.3 注册实现（register_rmw_implementation.cmake）

各后端 CMakeLists.txt 调用：

1
2
3

register_rmw_implementation(
  "c:rosidl_typesupport_introspection_c"
  "cpp:rosidl_typesupport_introspection_cpp")

向 ament index 写入：

• rmw_typesupport — 所有 typesupport 包名
• rmw_typesupport_c / rmw_typesupport_cpp — 分语言列表

17. 构建与导出

cmake/configure_rmw_library.cmake 设置：

• RMW_BUILDING_DLL（Windows 导出）
• 默认 symbol visibility hidden，仅 RMW_PUBLIC 导出

rmw-extras.cmake + ament_export_* 导出 librmw 与 include 路径。

18. 数据路径（端到端）

18.1 发布

18.2 订阅

1
2
3
4

rmw_take(sub, msg, &taken, alloc)
  → 后端 DataReader take
  → rosidl 反序列化到 ros_message
  → 填充 rmw_message_info_t（时间戳、GID 等）

变体：rmw_take_with_info、rmw_take_serialized_message、rmw_take_loaned_message、rmw_take_sequence。

18.3 等待

1
2
3
4
5
6

rcl_wait(wait_set, timeout)
  → 组装 rmw_subscriptions_t / guard_conditions / services / clients / events
  → rmw_wait(...)
  → 后端 waitset wait
  → 未就绪句柄置 NULL
  → rcl 标记对应实体 ready

18.4 Service

1
2
3

Client: rmw_send_request  → DDS request writer
Server: rmw_take_request  → 处理 → rmw_send_response
Client: rmw_take_response

19. 与 rcl 的职责对比

20. 相关仓库

21. 推荐阅读顺序

1. rmw/types.h — 掌握所有句柄与 QoS 类型（~650 行）
2. rmw/init.h + init_options.h — 理解 context 生命周期契约
3. rmw/rmw.h — 按 pub/sub/wait/graph 分段阅读（不必一次读完 3200 行）
4. rmw/src/validate_full_topic_name.c — 看本仓库“有实现”代码的风格
5. rmw_implementation_cmake/get_default_rmw_implementation.cmake — 理解构建默认后端
6. rmw_implementation 仓库 — 符号如何转发到具体后端
7. 任选一后端 — 如 rmw_cyclonedds_cpp 中 rmw_create_publisher / rmw_wait 实现
8. rmw_dds_common — graph 与 GID 共享逻辑

22. 小结

rmw 仓库是 ROS 2 可插拔中间件 的 契约层 + 公共工具库：

• 对上：为 rcl 提供稳定 C ABI 与一致的类型定义；
• 对下：不绑定任何 DDS，具体通信由 rmw_*_cpp 实现；
• 本仓库源码价值：理解 ROS 2 中间件 接口设计（句柄、wait 语义、QoS、graph API）以及 跨实现共享逻辑（命名校验、QoS 字符串、init 默认值）；
• 调试通信问题：沿 rcl_ret_t → rmw_ret_t → rmw_get_error_string() 向下追至具体后端。

换 DDS 只需安装并选择对应 rmw_*_cpp 实现，rcl / rclcpp / rclpy 无需修改。

ros2_tracing 源码详细分析

工作区路径：/home/cp/work2/ros2Learn/ros2_humble/src/ros2/ros2_tracing
版本：4.1.2（Humble），子包 8 个，许可证 Apache 2.0，tracetools 质量等级 QL1。

ros2_tracing 是 ROS 2 的 LTTng 追踪框架：在 rcl / rclcpp / rmw 等核心栈插入 tracepoint，提供会话配置工具（CLI / launch），并支持用 Babeltrace 读取 CTF 轨迹做测试与分析。

平台限制：当前 仅支持 Linux + LTTng（LTTng-UST 用户态追踪；可选内核追踪需 lttng-modules-dkms）。
分析/visualization 在独立仓库 tracetools_analysis。

1. 总体认识

1.1 核心职责

1.2 在 ROS 2 栈中的位置

关键设计：插桩代码 始终链接 tracetools；是否产生轨迹取决于 运行时 是否启动 LTTng session 并 enable 对应 event。未配置 session 时 tracepoint 开销极低（LTTng-UST fast path 几乎无系统调用）。

1.3 数据流概览

1
2
3
4
5
6
7
8
9
10
11

编译期:
  rclcpp/rcl/rmw 源码 #include tracetools/tracetools.h
  → 链接 libtracetools.so
  → tp_call.h 生成 LTTng provider "ros2" 的 TRACEPOINT_EVENT

运行期:
  ros2 trace / Trace launch action
  → lttng.create + enable events (ros2:rcl_publish 等)
  → lttng.start
  → 用户启动节点 → tracepoint 写入 UST buffer → CTF 文件
  → tracetools_read / tracetools_analysis 解析

2. 仓库结构

1
2
3
4
5
6
7
8
9
10
11
12

ros2_tracing/
├── README.md                    # 构建、ros2 trace、launch 示例、实时性说明
├── doc/design_ros_2.md          # ★ 设计文档：tracepoint 语义、分层表
├── tracing.repos                # 可选 vendoring
├── tracetools/                  # ★ C/C++ 插桩库（QL1）
├── tracetools_trace/            # LTTng session 管理
├── tracetools_launch/           # Launch Trace action
├── tracetools_read/             # Babeltrace 读取
├── tracetools_test/             # TraceTestCase 测试基类
├── ros2trace/                   # ros2cli 扩展
├── test_tracetools/             # ping/pong 等可执行 + Python 单测
└── test_tracetools_launch/      # launch 集成测试

3. 包 tracetools：插桩核心

3.1 构建与开关

CMakeLists.txt 关键选项：

Windows 上默认 TRACETOOLS_DISABLED=ON。

检测逻辑：

1
2
3
4
5

pkg_check_modules(LTTNG lttng-ust)
if(LTTNG_FOUND)
  set(TRACETOOLS_LTTNG_ENABLED TRUE)
endif()
configure_file(config.h.in → config.h)  # TRACETOOLS_DISABLED / TRACETOOLS_LTTNG_ENABLED

运行时检查：

1
2
3

ros2 run tracetools status
# Tracing enabled   ← TRACETOOLS_LTTNG_ENABLED 且未 DISABLED
# Tracing disabled

3.2 三层头文件

3.3 TRACEPOINT 宏机制

启用 LTTng 时，调用链为：

1
2
3

TRACEPOINT(rcl_publish, publisher_handle, message);
  → ros_trace_rcl_publish(...)           // tracetools.c 中实现
    → tracepoint(ros2, rcl_publish, ...) // LTTng UST

禁用时：

1

#define TRACEPOINT(...) ((void)(0))

tracetools.c 在 TRACETOOLS_LTTNG_ENABLED 下 #include "tracetools/tp_call.h"，用 CONDITIONAL_TP 包装每个函数。

3.4 LTTng Event 命名

Python 侧 tracepoints.py 与 LTTng 注册名一致：

1
2
3
4
5
6

ros2:rcl_init
ros2:rcl_node_init
ros2:rmw_publisher_init
...
ros2:callback_start
ros2:rclcpp_executor_execute

共 28 个 ROS tracepoint（Humble），覆盖 init / pub-sub / service / timer / lifecycle / executor / callback。

3.5 Tracepoint 分层与关联字段

设计目标（见 doc/design_ros_2.md）是用 指针 handle 在层间关联对象，用 message 指针 跟踪消息在 rclcpp→rcl→rmw 的传播。

Executor 相关：

• rclcpp_executor_get_next_ready — 开始取 ready executable
• rclcpp_executor_wait_for_work — wait 阶段（带 timeout ns）
• rclcpp_executor_execute — 执行某 rcl handle（timer/subscription）

Callback 相关：

• rclcpp_callback_register — 注册 demangled 符号（需 -rdynamic）
• callback_start / callback_end — 回调边界；is_intra_process 标记 intra-process

3.6 符号解析（-rdynamic）

utils.cpp 通过 dladdr + abi::__cxa_demangle 解析回调函数名，供 rclcpp_callback_register 写入 trace。

CMake 在 LTTng 启用时默认：

1
2

target_link_libraries(tracetools "-rdynamic")
ament_export_link_flags("-rdynamic")

若链接时去掉 -rdynamic，符号可能变为 UNKNOWN。

3.7 下游插桩位置（核心栈，非本仓库）

插桩散布在 ROS 2 核心包，例如：

所有上述包 package.xml 中 exec_depend/build_depend tracetools。

4. 包 tracetools_trace：LTTng 会话管理

4.1 模块结构

1
2
3
4
5
6
7
8
9
10
11

tracetools_trace/
├── trace.py              # init/fini 入口（交互式 press enter）
└── tools/
    ├── lttng.py          # 门面：is_lttng_installed, lttng_init/fini
    ├── lttng_impl.py     # ★ setup/start/stop/destroy
    ├── lttng_stub.py     # 无 lttng 模块时的 stub
    ├── names.py          # DEFAULT_EVENTS_ROS/KERNEL, DEFAULT_CONTEXT
    ├── tracepoints.py    # ros2:* 字符串常量
    ├── args.py           # CLI 参数解析
    ├── path.py           # ROS_TRACE_DIR / ~/.ros/tracing
    └── signals.py        # SIGINT 时 fini session

4.2 lttng_impl.setup() 流程

1. 若无 lttng-sessiond → lttng-sessiond --daemonize
2. 若启用 kernel events → lttng list -k 检查内核追踪器
3. lttng.create(session_name, full_path) — 输出 CTF 目录
4. 创建 UST domain（BUFFER_PER_UID）+ channel ros2
5. 可选 KERNEL domain + channel kchan
6. _enable_events — 每个 event 类型 EVENT_TRACEPOINT
7. _add_context — pid/tid/procname 等

Channel 调优（偏实时友好，见 README）：

4.3 默认启用事件

names.DEFAULT_EVENTS_ROS = tracepoints.py 中全部 28 个 ROS event。

DEFAULT_EVENTS_KERNEL（ros2 trace -k 时可追加）示例：

• sched_switch, kmem_mm_page_*, power_cpu_frequency

4.4 轨迹目录

优先级（README 与 path.get_tracing_directory()）：

1. $ROS_TRACE_DIR（非空）
2. $ROS_HOME/tracing（ROS_HOME 默认 ~/.ros）

Session 名默认 session-YYYYMMDDHHMMSS（path.append_timestamp）。

5. 包 ros2trace：ros2 trace CLI

1
2
3
4
5

# ros2trace/command/trace.py
class TraceCommand(CommandExtension):
    def main(...):
        init(session_name=..., ros_events=..., kernel_events=..., ...)
        fini(session_name=...)

CLI 参数（args.py）：

典型用法：

1
2
3
4

ros2 trace                    # 默认全部 ROS tracepoint
ros2 trace -k sched_switch    # 附加内核 event
ros2 trace -u                 # 仅内核/无 ROS（若再配合 -k）
# 另一终端运行节点，回到 trace 终端按 Enter 停止

trace.py 的 init() 在开始前 input('press enter to start...')，fini() 在 input('press enter to stop...') 后 destroy session — 交互式 录制。

6. 包 tracetools_launch：Launch 集成

6.1 Trace Action

1
2
3

# example.launch.py
Trace(session_name='my-tracing-session'),
Node(package='test_tracetools', executable='test_ping', ...),

生命周期：

1. execute() → _setup() → lttng.lttng_init(...) + lttng.start
2. 注册 OnShutdown → _destroy() → lttng_fini
3. 返回 LdPreload 子 action 列表（按需 LD_PRELOAD UST helper）

Launch 前端：@expose_action('trace')，支持 Python / XML / YAML（events-ust, events-kernel, context-fields 等）。

6.2 LdPreload 与 UST helper

当 UST event 列表匹配特定 pattern 时自动 preload：

通过 whereis -b 查找 .so 路径，追加 LD_PRELOAD 环境变量。

6.3 与 ros2 trace 对比

7. 包 tracetools_read：读取 CTF

1
2
3
4

from tracetools_read.trace import get_trace_events

events = get_trace_events('/path/to/session-xxx')
# List[DictEvent]: {'_name', '_timestamp', ...fields}

• 使用 Babeltrace 1.x Python API（babeltrace.TraceCollection）
• add_traces_recursive(path, 'ctf')
• 过滤 CTF 元数据字段（packet_size, stream_id 等）

辅助函数（tracetools_read/__init__.py）：get_event_name, get_field, get_procname 等。

8. 包 tracetools_test：测试基础设施

8.1 TraceTestCase

自动化流程（case.py）：

1. run_and_trace() — 创建 LTTng session → 启动指定 package 的 nodes → 停止
2. get_trace_events() 读 CTF
3. 断言：event 集合、时间戳、procname、handle 指针有效性、字段类型
4. tearDown() 删除 trace 目录（除非 TRACETOOLS_TEST_DEBUG 非空）

8.2 test_tracetools 用法示例

1
2
3
4
5
6
7
8
9

class TestPublisher(TraceTestCase):
    def __init__(self, *args):
        super().__init__(
            *args,
            session_name_prefix='session-test-publisher',
            events_ros=[tp.rcl_publisher_init, tp.rmw_publish, ...],
            package='test_tracetools',
            nodes=['test_publisher'],
        )

覆盖：publisher、subscription、service、timer、executor、lifecycle、intra-process 等场景。

9. 构建与部署

9.1 依赖安装（Ubuntu）

1
2
3
4

sudo apt install lttng-tools liblttng-ust-dev python3-babeltrace python3-lttng
# 可选内核追踪:
sudo apt install lttng-modules-dkms
sudo groupadd -r tracing && sudo usermod -aG tracing $USER

9.2 从源码启用 tracing

若先装了 ROS 二进制再装 LTTng，需重编至少到 tracetools：

1
2
3

colcon build --packages-up-to tracetools --cmake-force-configure
source install/setup.bash
ros2 run tracetools status

9.3 完全禁用

1

colcon build --cmake-args "-DTRACETOOLS_DISABLED=ON"

核心栈仍包含 TRACEPOINT 调用，但编译为空操作，不链接 LTTng。

10. 与分析工具的关系

本仓库 不负责 统计/可视化；设计文档指向 tracetools_analysis：

• 读取 CTF / 构建 callback 时长、消息年龄、调度干扰等指标
• 可与 kernel events（sched_switch 等）联合分析

数据契约即 tp_call.h 中的 CTF 字段 + context 字段。

11. 实时性说明

LTTng-UST 面向生产环境低延迟追踪（README 引用的 RA-L 论文）。默认 channel 配置已采用：

• discard 模式（不阻塞业务线程写缓冲）
• read timer 而非 switch timer（减少 write() syscall）
• 较小 sub-buffer 数量

进一步实时调优（手动 URCU 注册、sub-buffer 大小等）需直接使用 LTTng API；ros2 trace / Trace action 尚未 暴露全部 channel 参数（见 issue #129）。

12. 环境变量与配置

13. 扩展插桩指南

在自定义包中添加 tracing（摘自 design doc）：

1. package.xml 添加 depend tracetools
2. #include "tracetools/tracetools.h"
3. 在合适位置调用已有 TRACEPOINT(...) 或
4. 在 tp_call.h + tracetools.h + tracetools.c 增加新 event（需改 tracetools 包并 release）
5. 在 tracepoints.py / DEFAULT_EVENTS_ROS 注册 LTTng 名
6. 用 tracetools_test.TraceTestCase 验证

用户态 generic tracepoint 可直接使用 LTTng lttng_ust_tracepoint API，不必经过 tracetools 宏。

14. 调试建议

1. 确认编译启用：ros2 run tracetools status
2. 确认 session 在跑：lttng list
3. 无 event：检查 enable 的 event 名是否为 ros2:*；节点是否用带 tracing 的 overlay 构建
4. 空 trace 目录：session 未 start、或进程 domain 与 session 不匹配
5. 符号 UNKNOWN：检查 -rdynamic、回调是否为 lambda 且无 target<>
6. 读 trace 失败：安装 python3-babeltrace，路径是否为 session 根目录
7. 内核 event 失败：用户是否在 tracing 组、是否加载 lttng-modules

15. 推荐阅读顺序

1. 仓库 README.md — 构建、CLI、launch 快速上手
2. doc/design_ros_2.md — tracepoint 语义与分层表
3. tracetools/include/tracetools/tracetools.h — 全部 API
4. tracetools/include/tracetools/tp_call.h — CTF 字段定义
5. tracetools/src/tracetools.c — 宏到 LTTng 的桥接
6. tracetools_trace/tools/lttng_impl.py — session 创建细节
7. tracetools_launch/action.py — Launch 生命周期 + LD_PRELOAD
8. tracetools_test/case.py — 如何写 trace 单测
9. test_tracetools/test/test_publisher.py — 字段断言示例
10. 核心栈插桩点 — rclcpp/executor.cpp, rmw_fastrtps/rmw_publish.cpp 等

16. 小结

ros2_tracing 将 ROS 2 运行时行为映射为 LTTng CTF 轨迹，形成「插桩 → 会话 → 存储 → 读取/分析」完整链路：

• tracetools：稳定 C API + LTTng provider ros2，被 rcl/rclcpp/rmw 硬依赖（可编译为空操作）；
• tracetools_trace + ros2trace：交互式 ros2 trace 会话管理；
• tracetools_launch：与 launch 同生命周期自动 tracing，并智能 LD_PRELOAD；
• tracetools_read / tracetools_test：CTF 消费与回归测试。