rcl_uwvm2_wrapper

这个包是 rcl 之上的原型适配层（rclwasm 的雏形）：

• 上层：用 rcl 创建 node/publisher/subscription，负责 spin/wait、take/publish。
• 下层：用 rmw_uwvm2_wrapper 把 rmw_subscription_set_on_new_message_callback() 等回调变成事件队列，避免在中间件线程里直接执行复杂逻辑。
• wasm：示例里把 string subscription 的回调逻辑交给 uwvm2（WASI wasm）执行，支持：
  • argv（一次性调用，输入从 argv[1]，输出从 stdout 文本）
  • stdio（常驻进程，用 stdin/stdout framed 协议，避免每条消息起进程）

示例可执行文件

rcl_uwvm2_wasi_string_filter

macOS 无 ROS2 先验证（推荐）

你可以先不跑 ROS2，在本机用 uwvm2 把 stdio framed 协议跑通：

• standalone 工具：standalone/uwvm_stdio_client.cpp
• 示例 wasm（均支持 argv + stdio framed + stdio_v1）：
  • Rust：examples/wasi_string_filter_wasm_rs
  • C：examples/wasi_string_filter_wasm_c
  • C++：examples/wasi_string_filter_wasm_cpp
  • Go：examples/wasi_string_filter_wasm_go

standalone 构建与运行见：standalone/README.md 协议草案：docs/rclwasm-stdio-v1.md 论文要点与落地映射：docs/next-gen-ros-runtime.md

wasm 回调 ABI（当前约定）

模式 1：argv（默认）

• 输入：argv[1]（字符串）
• 输出：stdout（文本）；主程序取 stdout 最后一行作为输出
• 特点：最简单，但每条消息都会启动一次 uwvm 进程

模式 2：stdio（常驻 uwvm2 VM）

• 运行方式：启动一次 uwvm --run <wasm>，保持进程常驻
• 协议：每次请求/响应都使用 length-prefixed framing
  • request：u32_le(len) + len 字节 payload
  • response：u32_le(len) + len 字节 payload
• 特点：不需要每条消息启动进程；payload 二进制安全（后续可用于序列化消息/服务请求等）

环境变量：

• RCLWASM_CONFIG: 配置文件路径（见 docs/rclwasm-config-v1.md；支持 [module ...] 分段做 per-wasm 策略）
• RCLWASM_UWVM: uwvm 可执行文件路径（默认使用 uwvm，依赖 PATH）
• RCLWASM_MAX_REQUEST_BYTES: 转发给 wasm 的单次 request payload 上限（bytes；0=禁用；默认 0）
• RCLWASM_MAX_REPLY_BYTES: stdio/stdio_v1 模式下单次回复 payload 上限（默认 4194304）
• RCLWASM_CALL_TIMEOUT_MS: stdio/stdio_v1 模式下单次请求超时（毫秒；0=禁用）
• RCLWASM_ALLOW_REDIRECT: stdio_v1 模式下是否允许 guest 重定向 route（默认 true；禁用后 guest 返回不同 route_id 会被丢弃）
• RCLWASM_UWVM_ARGS: 额外 uwvm 参数（插在 --run 之前；格式：arg0;arg1;arg2）
• RCLWASM_HOT_RELOAD: 0/1/true/false；启用后 stdio/stdio_v1 模式下 wasm 文件变更会自动重启 session
• RCLWASM_MODE: argv|stdio|stdio_v1（默认 argv）
• 规则（两种方式二选一）：
  • 单条规则：
    • RCLWASM_WASM: wasm 文件路径（必填）
    • RCLWASM_IN_TOPIC: 输入 topic（默认 input）
    • RCLWASM_OUT_TOPIC: 输出 topic（默认 output）
    • RCLWASM_ROUTE_ID: stdio_v1 下可选；显式指定 route_id（>0）
  • 多条规则：
    • RCLWASM_RULES: in,out,wasm[,route_id];in2,out2,wasm2[,route_id]

示例：

# 推荐：用配置文件（更可审计）
# export RCLWASM_CONFIG=/path/to/rclwasm.conf

export RCLWASM_UWVM=/Users/liyinan/Documents/MacroModel/src/uwvm2/build/macosx/arm64/release/uwvm
# 可选：把 uwvm2 的 WASI 沙箱参数透传进去（每个 token 用 ';' 分隔）
# export RCLWASM_UWVM_ARGS="--wasip1-noinherit-system-environment;--wasip1-set-fd-limit;32"
# 可选：持久模式下 wasm 文件变化自动重启 uwvm session
# export RCLWASM_HOT_RELOAD=1
export RCLWASM_MODE=argv
export RCLWASM_RULES=/chatter,/chatter_out,/path/to/filter.wasm,1

ros2 run rcl_uwvm2_wrapper rcl_uwvm2_wasi_string_filter

说明：stdio 模式下，wasm 模块需要自己实现循环读写 framing 协议；argv 模式适合先快速跑通逻辑。

stdio_v1 = stdio framed + 额外的 rclwasm v1 内层协议（带 route_id），允许一个 wasm 常驻进程复用多条规则。