# rust-libtipc

**Repository Path**: openkylin/rust-libtipc

## Basic Information

- **Project Name**: rust-libtipc
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-16
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# libtipc - 纯 Rust 实现的 TIPC 库

> **用途**：本库供 **TA（Trusted Application）** 使用。**CA（Client Application）**
> 使用 Trusty 官方的 `libc-trusty`（C）或 `libtrusty`（Rust），不需要链接本库。

## 简介

libtipc 是纯 Rust 实现的 TIPC（Trusty IPC）通信库（`#![no_std]` + `alloc`），
用于替换 Trusty 官方的整条 TIPC 栈：

- **替代官方 C 实现**（`libtipc`/`tipc_srv`）：C FFI 符号与官方 C 头文件对齐
- **替代官方 Rust 实现**（`tipc` crate）：Rust API 用法与官方保持一致

提供三层 API：

- **Rust `service` API**：`Handle`、`Manager`、`Service`、`UnbufferedService`，
  用法与官方 `tipc` crate 一致
- **Rust `raw` API**：`EventLoop`、`HandleSetWrapper`，基于 `Arc<Mutex<T>>`，
  适合 RPC 场景
- **C FFI 接口**（`extern "C"`）：导出为 staticlib（`staticlib-shim` 子 crate），
  供 C/C++ TA 调用，兼容 `libtrusty.so` 接口

## 架构

```text
Rust TA                     C TA                    CA (libc-trusty)
  │                           │                          │
  ▼                           ▼                          │
handle / raw / service    c_api (extern "C")      (不使用本库)
  │                           │
  ▼                           ▼
       api (安全包装) ──→ ffi (tipc-syscall)
                            │
                            ▼
                   syscall (内联汇编) → 内核
```

## Feature

| Feature | 默认 | 说明 |
|---------|------|------|
| `x-kernel` | 是 | x-kernel syscall ABI（`aarch64-unknown-linux-musl`）；与 `lk` 互斥 |
| `lk` | 否 | Trusty LK syscall ABI（`aarch64-unknown-trusty`，AOSP 构建）；启用时必须 `--no-default-features` |
| `staticlib_build` | 否 | 静态库构建（内置 `#[panic_handler]`，供 C TA 经 `staticlib-shim` 链接） |
| `trusty-log` | 否 | 启用 `tipc-log`（re-export 为 `trusty_log`），替代官方 trusty-log |
| `peer-id` | 否 | 启用 `tipc-peer-id`（re-export 为 `peer_id`，转发其 `userspace` feature） |

`lk` 与 `x-kernel` 互斥：两个 feature 会混合不同的内核 syscall 号，
同时启用会触发编译错误。

## 构建与测试

```bash
# x-kernel 平台（默认），musl target
cargo build --release --target aarch64-unknown-linux-musl --workspace

# Trusty LK 平台（需 -Zbuild-std；必须 --no-default-features，
# 否则默认 feature x-kernel 与 lk 互斥冲突）
cargo build --release --target aarch64-unknown-trusty --workspace \
    -Zbuild-std=core,alloc --no-default-features --features lk

# 本地开发 & 测试
cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets --target aarch64-unknown-linux-musl
```

## 平台差异

- **handle mmap**：仅 LK 平台支持（4 参 Trusty ABI）。x-kernel 的 `SYS_MMAP`
  遵循标准 Linux 6 参 ABI 且 TIPC handle 不在 VFS 文件表中：
  - `Handle::mmap`（Rust API）返回 `NotSupported`；
  - C FFI 的 `tipc_mmap`/`tipc_munmap` 在 x-kernel 上报告 `MAP_FAILED` (-1)，
    对照官方 `libc-trusty/mman.c` 的失败约定，避免把负 errno 泄露成指针。

  > C FFI 不再以裸名 `mmap`/`munmap` 导出（官方把 `mmap` 符号留给 libc，
  > Rust 侧用 `trusty_sys::mmap` + `_trusty_mmap` 前缀符号）。裸名导出会
  > 劫持链接 std 的 TA 中 libc 的 6 参 `mmap`（std 的 `mmap64` 绑定到 4 参
  > TIPC 封装，flags 落入 `fd` 位，返回非 `MAP_FAILED` 的"成功"指针，随后
  > `mprotect` 触发内核 `address out of range` 导致 std 启动崩溃）。

## 与官方实现的兼容性

### Rust API

- **`Uuid::new_from_string`**：与官方一致返回 `Result<Self, Error>`
  （不再吞掉解析错误返回 `Option`）。
- **消息收发语义**：`recv`/`recv_vectored` 与官方一致，`handles` 参数不要求
  `MAX_MSG_HANDLES` 容量——接收时先写入库内固定 8 槽缓冲，最多回填
  `handles.len()` 个句柄，多余的丢弃；不带句柄的消息可用空数组接收。
  `tipc_send2`/`tipc_recv2` 为官方 iovec 零拷贝实现，不做中间堆缓冲。

### C FFI

- **符号名**：与官方 `tipc_srv.h` 对齐，服务注册导出 `tipc_add_service`；
  旧名 `tipc_add_service_ports` 保留为语义相同的委托别名。
- **回调契约**（与官方 `tipc_srv` 对齐）：
  - `on_message` 为必需回调：`tipc_add_service` 校验 `ops.on_message` 非空，
    缺失时返回 `ERR_INVALID_ARGS`（同官方 `is_valid_tipc_srv_ops`）。
  - 回调返回负值即关闭通道：`on_message`、`on_send_unblocked` 返回负 rc 时
    框架关闭该通道；`on_send_unblocked` 未注册时收到 `SEND_UNBLOCKED` 事件
    同样关闭通道（官方 `tipc_srv.c` 同款语义）。
  - `on_disconnect` 先于通道关闭：HUP 时先回调 `on_disconnect`，
    再由框架执行关闭（不要求 C 调用者自行 close）。
  - 不可恢复错误直接终止进程：通道关闭时将句柄从 handle set 移除失败时
    视为不可恢复状态（残留条目会向已释放上下文派发事件），框架 panic
    （`panic = "abort"`，与官方 `abort()` 行为一致）。

## 许可证

Apache-2.0 · Copyright 2026 KylinSoft Co., Ltd.