Skip to content

Translation pending. This page is currently available in Chinese.

A20OS Native ABI:IPC 与事件子系统设计

本文档定义 Native ABI 的 IPC 与事件通知机制,涵盖双向类型化消息通道(Channel)与统一异步事件队列(Event Queue)的数据结构、协议与系统调用接口。


1. 设计概览

Native ABI 提供两个互补的 IPC 原语。Channel 是同步/异步消息传递,支持 handle 传递,用于 RPC、请求-响应和数据流。Event Queue 的目标是成为统一事件等待机制并替代 epoll/signalfd/timerfd 的组合;当前已接入 channel、timer、task 退出、用户态驱动 IRQ、socket/pipe readiness、signal delivery 和文件系统路径事件。event_watch 默认边沿触发,可选 A20_WATCH_LEVEL 对非 vfile 类型在 park 前直接查对象就绪位(file/pipe/socket 一类 vfile-backed 对象走 park 失败后的 readiness/poll 子系统);普通 file fd 仍无 readiness 生产者,event_watch_fs 支持目录及直接子项名称前缀 watch(不递归),因此还不是 epoll/signalfd 的完整替代。

两者都基于 handle:创建后返回 handle,操作通过 handle 进行,权限通过 rights 控制。


2. Channel(消息通道)

2.1 模型

Channel 是一条双向端对端的消息管道。创建时产生两个 endpoint handle,分别给通信双方。

sequenceDiagram
    autonumber
    participant ProcA as 进程 A
    participant Kernel as 内核 Channel 队列
    participant ProcB as 进程 B

    Note over ProcA,ProcB: channel_create() 生成一对端点句柄 (ep0, ep1)
    ProcA->>Kernel: channel_send(ep0, 请求数据, 附带句柄)
    Kernel->>ProcB: channel_recv(ep1) 唤醒并交付数据与转移句柄
    ProcB->>Kernel: channel_send(ep1, 响应数据)
    Kernel->>ProcA: channel_recv(ep0) 唤醒并获取应答结果

2.2 数据结构

#define A20_CH_MAX_DATA    65536   /* 单条消息最大 64KB */
#define A20_CH_MAX_HANDLES 8       /* 单条消息最多传递 8 个 handle */

typedef struct a20_ch_message {
    uint32_t data_len;             /* 数据长度 */
    uint32_t handle_count;         /* 附带 handle 数量 */
    uint8_t  data[];               /* 变长数据 */
    /* 紧跟 handle 信息(内核内部) */
} a20_ch_message_t;

typedef struct a20_channel_ep {
    refcount_t              refcount;
    spinlock_t              lock;
    wait_queue_t            waiters;        /* 等待消息的线程 */
    struct a20_channel_ep  *peer;           /* 对端 endpoint */
    int                     peer_closed;    /* 对端是否已关闭 */

    /* 本端接收队列(单链 FIFO) */
    a20_ch_message_t       *msg_head;
    a20_ch_message_t       *msg_tail;
    uint32_t                msg_cap;        /* 队列容量 */
    uint32_t                msg_count;      /* 当前消息数 */
    uint32_t                total_data;     /* 当前缓冲数据总量 */
    a20_channel_type_t     *chan_type;      /* NULL 或指向本端副本 */
    a20_channel_type_t      chan_type_storage;
} a20_channel_ep_t;

2.3 Channel 类型签名(Typed Channel)

Channel 可以选择性地声明类型签名,内核在 send/recv 时强制执行类型约束。

// 通道类型签名
typedef struct a20_channel_type {
    uint32_t version;            // 结构体版本
    uint32_t send_handle_types;  // bitmask: 可发送的 handle 类型
    uint32_t recv_handle_types;  // bitmask: 可接收的 handle 类型
    uint32_t max_data_size;      // 最大字节负载(0 = 使用 A20_CH_MAX_DATA)
    uint32_t max_handles;        // 单条消息最大 handle 数(0 = 使用 A20_CH_MAX_HANDLES)
    uint32_t flags;
    // A20_CHAN_TYPE_ORDERED (1<<0): FIFO 顺序声明(当前 channel 本身即 FIFO)
    // A20_CHAN_TYPE_STRICT  (1<<1): 严格类型声明(当前 typed channel 始终严格检查)
} a20_channel_type_t;

// 类型 bit 位(与 a20_object_type_t 对齐)
#define A20_CHAN_TYPE_FILE     (1u << A20_OBJ_FILE)
#define A20_CHAN_TYPE_SOCKET   (1u << A20_OBJ_SOCKET)
#define A20_CHAN_TYPE_CHANNEL  (1u << A20_OBJ_CHANNEL_ENDPOINT)
#define A20_CHAN_TYPE_PIPE     (1u << A20_OBJ_PIPE_ENDPOINT)
#define A20_CHAN_TYPE_EVENTQ   (1u << A20_OBJ_EVENT_QUEUE)
#define A20_CHAN_TYPE_TIMER    (1u << A20_OBJ_TIMER)
#define A20_CHAN_TYPE_SHM      (1u << A20_OBJ_MEMORY)
#define A20_CHAN_TYPE_TASK     (1u << A20_OBJ_TASK)
#define A20_CHAN_TYPE_NS       (1u << A20_OBJ_NAMESPACE)
#define A20_CHAN_TYPE_ANY      0xFFFFFFFF  // 不限制类型

a20_channel_type_t 是由版本化 a20_channel_create_args_t 指针引用的固定子结构,目前以 version 开头而不单独携带 size;创建入口只接受 version 0/1,并将整份已知布局复制到内核。后续若需要追加字段,应先新增 version 并在 create 入口显式按版本复制,不能直接扩大 version 1 的读取长度。

类型约束在 send/recv 两侧分别强制执行。send_handle_types 要求 channel_send 时每个被传输的 handle 的对象类型都在此 bitmask 中;recv_handle_types 要求 channel_recv 时从消息中取出的 handle 的对象类型在此 bitmask 中。max_data_size / max_handles 在创建时把 0 或超出全局上限的值归一化为 64KB / 8,send 时强制检查。类型检查失败返回 A20_ERR_TYPE_MISMATCH。

a20_channel_send() 调用 ch_check_send_types() 检查 send_handle_types bitmask;a20_channel_recv() 在取出消息后调用 ch_check_recv_types() 检查 recv_handle_types bitmask。两者均在 kernel/ipc/a20_channel.c 中实现。

这套约束的设计目的是让内核强制执行 IPC 通信的结构约定,而不是只依赖用户态协议(如 FIDL)。被攻破的进程因此无法向 channel 发送错误类型的 handle,系统管理员可以静态分析哪些进程对之间可以传输哪些类型的资源,形式化证明也可以建立在通道类型之上(定理 2.1-2.3,见 docs/zh/research/04-typed-channels.md)。

2.4 Channel 创建

typedef struct a20_channel_create_args {
    uint32_t size;
    uint32_t version;
    uint32_t msg_capacity;        /* 队列容量提示 */
    uint32_t flags;
    a20_channel_type_t *type;     /* 可选:通道类型签名(NULL = 无类型约束) */
    a20_handle_t out_endpoints[2]; /* 输出:两个 endpoint handle */
} a20_channel_create_args_t;

int64_t channel_create(a20_channel_create_args_t *args);

创建过程先分配两个 a20_channel_ep_t 并让它们互指(peer)。若 type != NULL,类型签名分别复制到两个 endpoint 的内嵌存储,以避免共享生命周期问题。接着在调用者的 handle table 中分配两个 handle,各获得 READ | WRITE | STAT | DUP | TRANSFER 权限,然后返回两个 endpoint handle。type == NULL 时行为与无类型约束的 channel 完全一致,保持向后兼容。

实现状态:已接入。 sys_a20_channel_create 已读取 args.type,不再硬编码 NULL;SDK 提供 a20_channel_create_typed()。

2.4 Send 协议(两阶段锁)

int64_t channel_send(a20_msg_send_args_t *args);

两阶段锁分离:发送方和接收方的 handle table 不同时加锁。

阶段 1:预验证(锁发送方 HT)
1.1 lookup channel handle → 验证 WRITE 权限
1.2 对每个要传递的 handle:lookup → 验证 TRANSFER 权限
1.3 对每个 handle:refcount_inc(原子操作)
1.4 构造 a20_ch_message(拷贝数据,记录 handle 对象信息)
1.5 解锁发送方 HT

阶段 2:投递(锁接收方 peer endpoint)
2.1 spin_lock(&peer->lock)
2.2 检查 peer_closed、队列满等条件
2.3 将消息追加到 peer->msg_queue
2.4 wake_one(&peer->waiters)(唤醒等待的接收线程)
2.5 解锁 peer

错误处理分三种情况。阶段 1 失败时所有 refcount_inc 回滚(refcount_dec)并返回错误;阶段 2 队列满时非阻塞返回 WOULD_BLOCK,阻塞模式则等待空间;对端已关闭返回 CANCELED,同时释放消息和 handle 引用。

默认模式为阻塞;a20_msg_send_args_t.flags 设置 A20_MSG_NONBLOCK 时,队列满立即返回 WOULD_BLOCK。阻塞实现使用 tokenized Park/Wake,并以 wait-queue key 区分等待消息的接收者与等待空间的发送者。

2.5 Recv 协议

int64_t channel_recv(a20_msg_recv_args_t *args);
1. lookup channel handle → 验证 READ 权限
2. `recv_begin` 获取 `ep->lock`
3. 检查 msg_count > 0:
   - 是:取出队头消息
   - 否:默认阻塞等待;`A20_MSG_NONBLOCK` 立即返回 `WOULD_BLOCK`
4. 在仍持有 endpoint lock 时调用 `a20_handle_reserve_many` 预留全部接收槽位
5. 预留成功后才由 `recv_finish` 出队;失败则 `recv_abort` 解锁并返回 `NO_SPACE`,消息保持排队
6. 将消息中的 `(object, type, rights, expiry_tick, remaining_ops, temporal_flags, security_label)` 提交到预留槽位
7. 拷贝数据与新 handle 编号到用户缓冲区;唤醒等待空间的发送方

2.6 Partial Delivery 状态机

接收方 handle table 空间不足时,当前实现禁止部分投递:

正常:recv 开始 → 预留全部 handle 槽位 → 出队 → commit(消息完成)
NO_SPACE:接收方 handle table 满 → 预留失败 → recv 返回 NO_SPACE,消息保持排队

部分投递被明确排除。reserve-many → dequeue → commit 保证接收方 HT 空间不足时整个 recv 返回 NO_SPACE,消息留在队列中;commit 对已预留槽位不再失败。不存在 PARTIAL/ROLLED_BACK 中间态。

2.7 Handle Transfer 语义

当 handle 通过 channel 传递时:

$$\rho_{recv} = \rho_{send} \cap \rho_{transfer}$$

  • $\rho_{send}$:发送方对原始 handle 的权限
  • $\rho_{transfer}$:发送方在 send 调用中指定的权限(未指定则为 $\rho_{send}$)
  • $\rho_{recv}$:接收方获得的权限

这是共享语义,不是移动语义:发送方在 send 后仍持有原 handle,对象的引用计数增加,从而避免了“send 后 handle 消失”的惊讶行为。

消息同时携带源 handle 的时态约束和安全标签。接收方安装时原样继承,不能将过期时间、操作预算或标签重置为更宽松值(06-security.md §6.4)。

2.8 Channel 关闭

当一端 endpoint 被关闭(handle_close 或进程退出):

  1. refcount_dec:如果不是最后引用,只是减少计数
  2. 如果是最后引用:
  3. 设置 peer->peer_closed = true
  4. 唤醒对端所有等待线程(它们收到 CANCELED)
  5. 释放本端未读消息和 handle 引用
  6. 释放 endpoint 结构

3. Event Queue(事件队列)

3.1 模型

Event Queue 是 Native ABI 的统一等待机制目标。当前只有已接入生产者的事件会汇聚到队列;“所有可观察对象”是目标状态,不是现状。

graph TD
    subgraph EventQueue["事件队列容器 (Event Queue)"]
        subgraph WatchList["关注列表 (Watch List)"]
            W1["Timer 句柄: EXPIRED"]
            W2["Task 句柄: EXITED"]
            W3["Channel 句柄: MSG_READY | PEER_CLOSED"]
            W4["Device IRQ: SIGNALED"]
        end

        subgraph PendingRing["就绪事件环形缓冲 (Pending Ring)"]
            E1["就绪事件 1"] --> E2["就绪事件 2"] --> En["..."]
        end

        subgraph Waiters["阻塞等待队列 (Waiters Queue)"]
            T1["线程 (阻塞于 event_wait)"]
        end
    end

    WatchList -.->|异步事件触发| PendingRing
    PendingRing -.->|唤醒交付| Waiters

file/socket/pipe readiness 与 signal delivery 尚不在当前生产者集合中。

3.2 数据结构

typedef struct a20_watch_entry {
    a20_handle_t    target_handle;  /* 被观察对象的 handle 编号 */
    void           *target_object;  /* 被观察对象的内核指针 */
    uint16_t        target_type;    /* 被观察对象类型 */
    uint64_t        event_mask;     /* 关注的事件类型位图 */
    uint64_t        user_data;      /* 用户数据,原样返回 */
    struct a20_watch_entry *next;
} a20_watch_entry_t;

typedef struct a20_pending_event {
    a20_handle_t    source;         /* 产生事件的 handle */
    uint32_t        type;           /* 事件类型 */
    uint64_t        events;         /* 触发的事件位图 */
    uint64_t        user_data;      /* 从 watch entry 复制 */
    uint64_t        data0, data1, data2;
} a20_pending_event_t;

typedef struct a20_eventq {
    refcount_t       refcount;
    spinlock_t       lock;
    wait_queue_t     waiters;

    a20_watch_entry_t *watches;     /* 注册的观察列表 */
    uint32_t           watch_count;

    a20_pending_event_t *ring;      /* 环形缓冲区 */
    uint32_t            ring_cap;
    uint32_t            ring_head;
    uint32_t            ring_tail;
    uint32_t            ring_count;
} a20_eventq_t;

3.3 可观察事件类型

索引 常量 对象类型 说明 当前事件源
0 A20_EVENT_READABLE file/socket/pipe 数据可读 socket、pipe 已接入;普通 file fd 未接入
1 A20_EVENT_WRITABLE file/socket/pipe 缓冲区可写 socket、pipe 已接入;普通 file fd 未接入
2 A20_EVENT_ERROR file/socket I/O 错误 socket 已接入
3 A20_EVENT_CLOSED object/channel 对象关闭 channel endpoint、socket 已接入
4 A20_EVENT_CONNECTION socket 新连接到达 socket 已接入
5 A20_EVENT_ACCEPT_READY socket 可接受连接 socket 已接入
6 A20_EVENT_EXPIRED timer 定时器到期 已接入
7 A20_EVENT_EXITED task/thread 任务退出 task 已接入
8 A20_EVENT_MESSAGE_READY channel 有消息可接收 已接入
9 A20_EVENT_PEER_CLOSED channel 对端关闭 已接入
10 A20_EVENT_SIGNALED device/task/thread 用户态驱动 IRQ 已屏蔽并待确认;signal delivery 复用同一事件,signo 走 data0,TASK/THREAD 两类 watch 都通知 已接入

事件掩码使用 A20_EVENT_MASK(index) = 1ull << index。索引 16..19 的 A20_EVENT_FS_*(CREATE/DELETE/MODIFY/RENAME)不走本表:它们由 event_watch_fs 按 vnode 键投递,变更名放在事件的 fs_name 字段(char[32],超长截断;FS_MODIFY 的生产点不传名字,该字段为空),详见 09-native-abi-deepening.md。普通 file fd 的 READABLE/WRITABLE 目前没有生产者,vfs 只发 FS 类事件。

3.4 操作

event_queue_create

int64_t event_queue_create(a20_event_queue_create_args_t *args);

创建 eventq 结构,分配环形缓冲区(容量由 capacity_hint 决定,默认 256),返回 eventq handle。

event_watch

int64_t event_watch(a20_event_watch_args_t *args);
  1. 验证 queue handle(类型 eventq,READ 权限)
  2. 验证 target handle(任意类型)
  3. 创建 watch_entry,追加到 queue 的 watch list
  4. 注册到全局反向索引(object → watch_entry 列表)

重复 watch 同一 target:更新 event_mask 和 user_data,不创建新 entry。

event_wait

int64_t event_wait(a20_event_wait_args_t *args);
  1. 验证 queue handle(READ 权限)
  2. spin_lock(&eq->lock)
  3. 检查 ring_count > 0:
  4. 是:从 ring buffer 取出最多 min(max_events, 64) 个事件,拷贝到用户缓冲区
  5. 否:基于 tokenized Park/Wake 阻塞等待(timeout_ns = 0 时直接返回 WOULD_BLOCK,A20_TIMEOUT_INFINITE 无限等待,有限相对超时返回 TIMED_OUT)
  6. 解锁
  7. 返回事件数量

event_cancel

int64_t event_cancel(a20_handle_t queue, a20_handle_t target);

从 queue 的 watch list 中移除 target 对应的 watch_entry,并从全局反向索引中移除。

3.5 事件分发机制

内核中任何产生事件的地方调用 a20_event_notify:

void a20_event_notify(void *target_object, uint16_t target_type,
                      uint32_t event_type, uint64_t data0, uint64_t data1) {
    // 通过全局反向索引找到所有 watch 了 target_object 的 event queue
    for each eventq that watches target_object {
        spin_lock(&eq->lock);
        // 检查 event_mask 是否匹配
        // 追加到 ring buffer
        // wake_one(&eq->waiters)
        spin_unlock(&eq->lock);
    }
}

全局 hash table object_watches: void* → [a20_watch_entry*] 让事件产生时能以 O(1) 找到所有相关的 event queue。

3.6 FIFO 顺序保证

同一对象的事件按产生顺序入队。Ring buffer 保证 FIFO:

$$e_1 \text{ produced before } e_2 \implies e_1 \text{ dequeued before } e_2$$

跨对象的顺序不保证。

3.7 Ring 满时的行为

当前 a20_event_notify() 在 ring 满时保留已排队的旧事件、丢弃本次新事件,并仍唤醒一个 waiter。EventQ 不会自动重新查询 target 的电平状态,因此不能宣称一般的“事件不丢失”保证;需要电平语义的调用方必须依赖对象自身状态或后续通知。


4. Event Queue Cleanup 协议

4.1 触发场景

场景 调用路径 清理资源
handle_close(eq) close → refcount_dec → eventq_destroy watch list + ring + 反向索引
task_exit(持有 eq) 遍历 HT → close 所有 handle 同上
被监控对象销毁 object_destroy → eventq_on_object_destroy 从 watch list 移除 entry

4.2 Event Queue 销毁

void a20_eventq_destroy(a20_eventq_t *eq) {
    // 步骤 1:清理 watch list + 反向索引
    a20_watch_entry_t *w = eq->watches;
    while (w) {
        object_watches_remove(w->target_object, w);
        a20_watch_entry_t *next = w->next;
        kfree(w);
        w = next;
    }

    // 步骤 2:唤醒等待线程(返回 CANCELED)
    wait_queue_wake_all(&eq->waiters, 0, PROC_WAKE_EVENT);

    // 步骤 3:释放 ring buffer
    kfree(eq->ring);

    // 步骤 4:释放 eventq
    kfree(eq);
}

eventq_destroy 在 HT lock 释放后执行,这一点是安全的:refcount = 0 后没有其他线程持有 eq 的 handle。

4.3 被监控对象销毁

void a20_eventq_on_object_destroy(void *object, uint16_t object_type) {
    a20_watch_entry_list_t *list = object_watches_lookup(object, object_type);
    for each watch_entry w in list {
        spin_lock(&w->owner_queue->lock);
        linked_list_remove(&w->owner_queue->watches, w);
        w->owner_queue->watch_count--;
        spin_unlock(&w->owner_queue->lock);
        kfree(w);
    }
    object_watches_remove_all(object);
}

5. 与 POSIX 的对比

POSIX 机制 Native ABI 对应设计 当前状态与边界
pipe() channel_create() channel 已支持消息与 handle 传递,但不是 POSIX 字节流的无差别替代
SCM_RIGHTS (sendmsg) channel_send(handles) 已实现显式权限降级,不需要辅助数据
epoll_create/ctl/wait event_queue_create/watch/wait 替代目标;socket/pipe readiness 生产者已接入,普通 file fd 仍无生产者,因此不能承担通用 fd 多路复用
signalfd EventQ signal event 替代目标;signal 生产者已接入(A20_EVENT_SIGNALED,signo 走 data0),task EXITED 另表示任务生命周期事件,二者不是同一语义
timerfd event_watch(timer, EXPIRED) timer handle 与到期事件已接入
eventfd channel 信号消息 channel 可发送零字节消息,但语义不等同 Linux eventfd 计数器
SysV msgget/msgsnd/msgrcv channel 无全局 key,权限通过 handle 控制
POSIX mq_open/mq_send/mq_recv channel 无需文件系统路径,handle 即标识