跳转至

A20OS Native ABI:用户态启动协议

本文档定义 Native ABI 的用户态程序启动协议、初始上下文结构(a20_start_info_t)与 libc 运行时接入契约。


1. 启动协议

Native 程序不直接继承 Linux auxv 语义。内核在初始用户栈或只读启动信息页提供 a20_start_info_t。

1.1 启动信息结构

typedef struct a20_start_info {
    uint32_t size;
    uint32_t version;

    uint32_t argc;               /* 命令行参数数量 */
    uint32_t envc;               /* 环境变量数量 */
    uint32_t auxc;               /* 辅助向量条目数 */
    uint32_t reserved0;          /* Native spawn fd mapping limit, or zero */

    uint64_t argv;               /* 用户指针:char*[] */
    uint64_t envp;               /* 用户指针:char*[] */
    uint64_t auxv;               /* 用户指针:a20_auxv[] */

    a20_handle_t root_dir;       /* 根目录 handle */
    a20_handle_t cwd_dir;        /* 工作目录 handle */
    a20_handle_t stdin_handle;   /* 标准输入 handle */
    a20_handle_t stdout_handle;  /* 标准输出 handle */
    a20_handle_t stderr_handle;  /* 标准错误 handle */
    a20_handle_t self_task;      /* 当前进程的 task handle */
    a20_handle_t main_thread;    /* 主线程的 thread handle */
    a20_handle_t default_event_queue; /* 默认事件队列 handle */

    uint64_t page_size;          /* 页大小 */
    uint64_t user_clock_freq;    /* 用户态时钟频率 */

    a20_handle_t service_registry; /* well-known 注册表客户端端点,可为 NULL */
    uint32_t _pad_registry;

    /* version 2, appended after the 104-byte v1 prefix */
    uint64_t bootstrap_data;
    uint64_t bootstrap_size;
} a20_start_info_t;

1.2 启动参数设计意图

  • handle 而非 fd:不依赖固定的 fd 0/½ 特殊语义。Native libc 可以把 stdin/stdout/stderr 映射成自己的 fd 表,但内核不假设这一点。
  • self_task:进程可以通过此 handle 查询自身状态、注册退出事件等。需要 A20_RIGHT_WAIT 权限。
  • default_event_queue:字段已保留,但普通 exec/startup 当前可为 A20_HANDLE_NULL,调用方必须处理缺省并自行创建。
  • main_thread:当前早期 startup 路径可能与 self_task 使用同一 handle,而 spawn/exec 路径也可能留空;不能假设总是独立 A20_OBJ_THREAD。
  • service_registry:注册表可用时安装客户端 channel endpoint,否则为 NULL。

1.3 启动流程

内核:
  1. 分配 task 结构,设置 abi_mode = NATIVE
  2. 创建 handle table,分配初始 handle
  3. 准备用户栈,压入 a20_start_info
  4. 将入口地址设为 ELF entry point
  5. 跳转到用户态

用户态入口(crt0):
  1. 从约定位置读取 a20_start_info
  2. 调用 abi_info() 确认 ABI 版本
  3. 初始化 libc(liba20rt/liba20c)
  4. 调用 main(argc, argv, envp)
  5. 返回后调用 task_exit(ret)

1.4 初始 handle 权限

Handle 类型 Rights
root_dir dir READ, STAT, DUP, TRANSFER
cwd_dir dir READ, STAT, DUP
stdin_handle file READ, DUP
stdout_handle file WRITE, DUP
stderr_handle file WRITE, DUP
self_task task WAIT, SIGNAL, STAT, DUP
main_thread thread/当前可与 self_task 同值 当前路径相关,可能为空
default_event_queue eventq 当前普通启动可为空
service_registry channel 注册表可用时安装;否则为空

2. Native libc 分层设计

2.1 三层结构

应用 -> mlibc sysdeps/a20 -> Native syscall
小型程序 -> liba20c -> liba20rt -> Native syscall

当前实现路径:

路径 适用场景 工作量 POSIX 兼容性 状态
从零写 liba20c Phase 0-1,验证最小程序 ~985 行 ISO C 子集 已完成
mlibc sysdeps/a20 较完整 Native libc sysdeps/rtld/构建接入 已接入子集,非完整 POSIX 活跃,RISC-V64/AArch64(见验收记录)
旧 musl bridge 历史参考 user/archive/ 未形成当前可验证完整 POSIX 已归档,不参与构建

2.2 liba20rt — 最小运行时

只提供 syscall wrapper 和基本 handle I/O:

  • a20_syscall(n, args) — 通用 syscall 入口
  • 各 syscall 的内联 wrapper(a20_handle_close(h) 等)
  • a20_start(argc, argv) — crt0 启动代码
  • a20_handle_write_simple(h, buf, len) — 不需要 iovec 的简化写

设计约束上,liba20rt 不依赖任何堆分配,所有操作在栈上完成。

2.2.1 crt0 启动代码(aarch64)

/* crt0_a20.S — Native ABI 程序入口 */
    .global _start
_start:
    /* x0 指向 a20_start_info_t(内核约定) */
    mov     x19, x0                 /* 保存 start_info 指针 */

    /* 确认 ABI 版本 */
    sub     sp, sp, #256
    mov     x0, sp
    /* a20_abi_info(sp) — syscall 0x0000 */
    mov     x8, #0x0000
    svc     #0

    /* 提取 argc, argv, envp */
    ldr     w0, [x19, #8]           /* argc */
    ldr     x1, [x19, #24]          /* argv */
    ldr     x2, [x19, #32]          /* envp */

    /* 初始化 libc(fd 表、堆等) */
    mov     x3, x19                 /* start_info 指针传给 __libc_init */
    bl      __libc_init

    /* 调用 main */
    bl      main

    /* 退出 */
    mov     w0, w0
    /* task_exit(code) — syscall 0x0200 */
    mov     x8, #0x0200
    svc     #0

2.2.2 syscall wrapper 模式

/* a20_syscall.h — syscall 发射层 */

/* 通用 syscall 入口(6 参数) */
static inline int64_t a20_syscall6(uint32_t nr,
    uint64_t a0, uint64_t a1, uint64_t a2,
    uint64_t a3, uint64_t a4, uint64_t a5)
{
    register uint64_t x8 __asm__("x8") = nr;
    register uint64_t x0 __asm__("x0") = a0;
    register uint64_t x1 __asm__("x1") = a1;
    register uint64_t x2 __asm__("x2") = a2;
    register uint64_t x3 __asm__("x3") = a3;
    register uint64_t x4 __asm__("x4") = a4;
    register uint64_t x5 __asm__("x5") = a5;
    __asm__ volatile("svc #0"
        : "+r"(x0)
        : "r"(x8), "r"(x1), "r"(x2), "r"(x3), "r"(x4), "r"(x5)
        : "memory");
    return (int64_t)x0;
}

/* 具名 wrapper 示例 */
#define a20_handle_close(h) \
    a20_syscall6(0x0100, (uint64_t)(h), 0, 0, 0, 0, 0)

#define a20_task_exit(code) \
    a20_syscall6(0x0200, (uint64_t)(int32_t)(code), 0, 0, 0, 0, 0)

/* 复杂 syscall(传结构体指针) */
static inline int64_t a20_handle_read(struct a20_io_args *args) {
    return a20_syscall6(0x0401, (uint64_t)args, 0, 0, 0, 0, 0);
}

2.3 liba20c — 最小 C 库

在 liba20rt 之上提供 ISO C 标准库子集:

类别 函数 实现方式
内存 malloc, free, realloc 基于 vm_alloc,bump allocator 或 slab 分配器
字符串 strlen, strcmp, memcpy, ... 纯用户态实现,无 syscall 依赖
I/O fopen, fread, fwrite, printf 基于 handle + fd→handle 映射表
时间 clock_gettime, time 基于 clock_get syscall
进程 exit, getpid 基于 task_exit, handle_query
环境访问 getenv, setenv 操作 a20_start_info 传入的 envp

2.4 POSIX shim — 兼容层

将 POSIX API 映射到 native handle 模型:

open(path, flags)     → path_open + fd_table_insert
read(fd, buf, n)      → handle_read(fd_table[fd], ...)
write(fd, buf, n)     → handle_write(fd_table[fd], ...)
close(fd)             → handle_close(fd_table[fd]) + fd_table_remove
pipe(fds)             → channel_create + fd_table_insert ×2
socket(domain, type)  → net_socket + fd_table_insert
fork()                → 不支持(返回 ENOSYS)
execve(path, ...)     → 不支持(返回 ENOSYS)

POSIX 中明确不支持的操作(Phase 2 可通过 musl 移植逐步支持):

  • fork() — spawn 模型是 native ABI 的进程创建方式
  • execve() — task_spawn 替代
  • signal() — event queue 替代
  • ioctl() — handle_control 替代
  • epoll_*() — event_queue 替代

Native ABI 不追求盲目全量支持 POSIX 历史包袱,而是优先提供保证确定性与安全性的系统原语。


3. fd ↔ handle 映射

POSIX 用 int fd(小整数,0=stdin),A20 用 a20_handle_t(handle table 索引,也是 uint32_t)。libc 负责在两者之间桥接。

3.1 fd 表数据结构

/* liba20c 内部 fd 表 */
#define A20_FD_INIT_SIZE   32
#define A20_FD_MAX_SIZE    1024

struct a20_fd_entry {
    a20_handle_t  handle;       /* 对应的 A20 handle,A20_HANDLE_NULL = 空闲 */
    uint32_t      flags;        /* O_RDONLY / O_WRONLY / O_RDWR 等 */
    a20_off_t     pos;          /* 文件当前偏移 */
    uint32_t      fd_flags;     /* FD_CLOEXEC 等 */
};

static struct a20_fd_entry *__fd_table;
static int __fd_table_size;      /* 当前容量 */
static int __fd_table_used;      /* 已用数量 */
static spinlock_t __fd_lock;     /* 用户态自旋锁(多线程保护) */

3.2 初始化

/* __libc_init 中调用 */
void __fd_table_init(const a20_start_info_t *si) {
    __fd_table = __bare_alloc(A20_FD_INIT_SIZE * sizeof(struct a20_fd_entry));
    __fd_table_size = A20_FD_INIT_SIZE;
    memset(__fd_table, 0, ...);

    /* fd 0/1/2 映射到 start_info 中的 stdio handle */
    __fd_table[0] = (struct a20_fd_entry){
        .handle = si->stdin_handle, .flags = O_RDONLY };
    __fd_table[1] = (struct a20_fd_entry){
        .handle = si->stdout_handle, .flags = O_WRONLY };
    __fd_table[2] = (struct a20_fd_entry){
        .handle = si->stderr_handle, .flags = O_WRONLY };

    __fd_table_used = 3;
}

3.3 fd 操作函数

/* 分配新 fd(线性扫描找空闲槽位) */
int __fd_alloc(a20_handle_t handle, uint32_t flags) {
    spin_lock(&__fd_lock);
    for (int i = 0; i < __fd_table_size; i++) {
        if (__fd_table[i].handle == A20_HANDLE_NULL) {
            __fd_table[i].handle = handle;
            __fd_table[i].flags = flags;
            __fd_table[i].pos = 0;
            spin_unlock(&__fd_lock);
            return i;
        }
    }
    /* 扩容或返回 EMFILE */
    spin_unlock(&__fd_lock);
    errno = EMFILE;
    return -1;
}

/* fd → handle 查询 */
a20_handle_t __fd_to_handle(int fd) {
    if (fd < 0 || fd >= __fd_table_size)
        return A20_HANDLE_NULL;
    return __fd_table[fd].handle;
}

/* POSIX read() 的实现 */
ssize_t read(int fd, void *buf, size_t count) {
    a20_handle_t h = __fd_to_handle(fd);
    if (h == A20_HANDLE_NULL) { errno = EBADF; return -1; }

    struct a20_iovec iov = { .base = (uint64_t)buf, .len = count };
    struct a20_io_args args = {
        .size = sizeof(args), .version = 1,
        .handle = h,
        .iov = (uint64_t)&iov, .iov_count = 1,
        .offset = A20_OFFSET_CURRENT,   /* 使用内部 pos */
    };
    int64_t ret = a20_handle_read(&args);
    if (ret < 0) { errno = __a20_to_errno(ret); return -1; }
    return (ssize_t)args.out_count;
}

/* POSIX open() 的实现 */
int open(const char *path, int flags, ...) {
    struct a20_path_open_args args = {
        .size = sizeof(args), .version = 1,
        .dir = __cwd_handle,   /* libc 维护的 cwd dir handle */
        .flags = __posix_to_a20_flags(flags),
        .rights = __posix_to_a20_rights(flags),
        .path = (uint64_t)path,
        .path_len = 0,         /* nul-terminated */
        .mode = mode,
    };
    int64_t ret = a20_path_open(&args);
    if (ret < 0) { errno = __a20_to_errno(ret); return -1; }
    return __fd_alloc(args.out_handle, flags);
}

3.4 为什么不直接用 handle 值当 fd?

a20_handle_t 和 int fd 都是 uint32_t,理论上可以省掉映射表。但实际不行:

  1. musl 内部假设 fd 0/½ 是 stdio,很多地方硬编码 fd < 3 的检查,而 handle 值不保证从 0 开始。
  2. fd 的连续性假设:POSIX 保证 dup() 返回最小可用 fd,select() 遍历 0..nfds-1,而 handle 分配是 bitmap 扫描,不一定连续。
  3. close-on-exec 语义:fd 有 FD_CLOEXEC 标志,handle 没有,映射表是放 fd 级别属性的自然位置。
  4. POSIX 约定 open 返回最小可用 fd,handle 分配不保证这个。

所以**映射表是必要的,不能省掉**。


4. 历史 Native-musl 移植方案

本节到第 6 节记录早期方案和估算,路径、代码片段、target triple 与完成状态不代表当前构建。活跃实现是 mlibc sysdeps/a20;当前构建入口见 tools/mk/targets-mlibc.mk。

4.1 为什么选 musl

因素 musl glibc dietlibc uclibc
代码量 ~50K 行 ~180K 行 ~8K 行 ~40K 行
许可证 MIT LGPL BSD LGPL
架构分离 清晰(arch/) 耦合 简单 中等
POSIX 完整性 高 最高 低 中
静态链接 原生支持 臃肿 原生 原生
代码质量 高(统一风格) 混杂 较低 中等

musl 的 arch/<arch>/syscall.h 是唯一的 syscall 发射点。替换这一层就能让上面 48K 行的 POSIX 实现代码在 A20 上运行。

4.2 musl 代码结构分析

musl/
├── arch/
│   ├── aarch64/
│   │   ├── syscall.h         ← 定义 __syscall 宏(SVC #0 指令)
│   │   ├── crt_arch.h        ← crt0 汇编
│   │   ├── pthread_arch.h    ← 线程指针(tp 寄存器)
│   │   └── atomic.h          ← 原子操作(LDXR/STXR)
│   └── ...
├── src/
│   ├── internal/
│   │   ├── syscallops.h      ← 高层 syscall 封装(__sys_open 等)
│   │   └── libc.h            ← 内部数据结构
│   ├── fd/                   ← 文件描述符操作
│   │   ├── open.c            ← open() → __sys_openat(SYS_openat, ...)
│   │   ├── read.c            ← read() → __syscall_cp(SYS_read, ...)
│   │   └── ...
│   ├── thread/               ← pthread 实现
│   ├── signal/               ← 信号实现
│   ├── network/              ← socket 实现
│   ├── stdio/                ← FILE* 实现
│   └── ...                   ← string, stdlib, math, etc.
├── include/                  ← 公共头文件
└── tools/                    ← 构建工具

关键发现是:musl 的 src/fd/open.c 调用 __sys_openat,后者展开为 __syscall(SYS_openat, ...)。SYS_openat 是 Linux syscall 编号,替换为 a20_path_open 就是替换一个宏。

4.3 移植的代码改动清单

6.3.1 新增 arch/a20/(~600 行)

arch/a20/
├── syscall.h              ← A20 syscall 发射宏(~80 行)
├── crt_arch.h             ← A20 启动汇编(~40 行)
├── pthread_arch.h         ← TLS 指针约定(~20 行,复用 aarch64)
├── atomic.h               ← 原子操作(~100 行,复用 aarch64)
├── reloc.h                ← 重定位(~30 行,复用 aarch64)
└── bits/
    └── syscall.h          ← A20 syscall 编号定义(~300 行)

6.3.2 syscall 发射层替换(arch/a20/syscall.h)

/* arch/a20/syscall.h — A20 syscall 发射 */
#ifndef _SYSCALL_H
#define _SYSCALL_H

/* A20 syscall 编号 */
#define __NR_a20_abi_info          0x0000
#define __NR_a20_handle_close      0x0100
#define __NR_a20_handle_dup        0x0101
#define __NR_a20_task_exit         0x0200
#define __NR_a20_task_spawn        0x0201
#define __NR_a20_vm_alloc          0x0300
#define __NR_a20_path_open         0x0400
#define __NR_a20_handle_read       0x0401
#define __NR_a20_handle_write      0x0402
/* ... 全部 142 个(syscall_table.def) */

/* A20 使用相同的 SVC #0 指令,但 x8 放 A20 编号 */
static inline long __syscall0(long nr){
    register long x8 __asm__("x8") = nr;
    register long x0 __asm__("x0");
    __asm__ volatile("svc #0" : "=r"(x0) : "r"(x8) : "memory");
    return x0;
}

static inline long __syscall1(long nr, long a0){
    register long x8 __asm__("x8") = nr;
    register long x0 __asm__("x0") = a0;
    __asm__ volatile("svc #0" : "=r"(x0) : "r"(x8), "0"(x0) : "memory");
    return x0;
}

/* __syscall2 ... __syscall6 类似 */

#endif

6.3.3 syscall 映射层(src/internal/a20_syscallops.c,~800 行)

这一层把 musl 的 __sys_* 函数映射到 A20 syscall:

/* src/internal/a20_syscallops.c — musl → A20 syscall 桥接 */

/* ===== 文件 I/O ===== */

/* musl 调用 __sys_openat(dirfd, path, flags, mode) */
long __sys_openat(int dirfd, const char *path, int flags, int mode){
    struct a20_path_open_args args = {
        .size = sizeof(args), .version = 1,
        .dir = __fd_to_handle(dirfd),
        .flags = __oflag_to_a20(flags),
        .rights = __oflag_to_rights(flags),
        .path = (uint64_t)path, .path_len = 0,
        .mode = mode,
    };
    long ret = __syscall1(__NR_a20_path_open, (long)&args);
    if (ret < 0) return ret;
    return __fd_alloc(args.out_handle, flags);
}

/* musl 调用 __syscall_cp(SYS_read, fd, buf, count) */
/* 需要在 __syscall 宏中做拦截 */
long __a20_read(int fd, void *buf, size_t count){
    a20_handle_t h = __fd_to_handle(fd);
    struct a20_iovec iov = { (uint64_t)buf, count };
    struct a20_io_args args = {
        .size = sizeof(args), .version = 1,
        .handle = h,
        .iov = (uint64_t)&iov, .iov_count = 1,
        .offset = A20_OFFSET_CURRENT,
    };
    long ret = __syscall1(__NR_a20_handle_read, (long)&args);
    if (ret < 0) return ret;
    return (long)args.out_count;
}

/* write, close, lseek, fstat, ... 类似模式 */

/* ===== 进程 ===== */

long __sys_clone(unsigned long flags, ...) {
    /* A20 不支持 raw clone */
    return -ENOSYS;
}

long __sys_execve(const char *path, char **argv, char **envp) {
    /* A20 不支持 execve,返回 ENOSYS */
    return -ENOSYS;
}

/* ===== 网络 ===== */

long __sys_socket(int domain, int type, int protocol) {
    struct a20_net_socket_args args = {
        .size = sizeof(args), .version = 1,
        .domain = domain, .type = type, .protocol = protocol,
        .rights = A20_RIGHT_READ | A20_RIGHT_WRITE,
    };
    long ret = __syscall1(__NR_a20_net_socket, (long)&args);
    if (ret < 0) return ret;
    return __fd_alloc(args.out_socket, 0);
}

/* ===== 信号 ===== */

long __sys_rt_sigaction(int sig, ...) {
    /* A20 无信号。返回成功但什么都不做(桩函数) */
    return 0;
}

long __sys_rt_sigprocmask(int how, ...) {
    return 0;
}

/* kill 映射到 channel 通知或 event 投递 */
long __sys_kill(int pid, int sig) {
    /* 通过 task_kill 发送信号编号作为 reason */
    a20_handle_t task = __pid_to_handle(pid);
    return __syscall2(__NR_a20_task_kill, task, sig);
}

6.3.4 启动代码替换(arch/a20/crt_arch.h)

/* arch/a20/crt_arch.h — 覆盖 musl 默认启动代码 */

/* musl 的 crt0 会调用 __libc_start_main。
 * 我们替换入口点,从 a20_start_info 初始化 */

void __a20_start(const struct a20_start_info *si){
    /* 1. 保存 start_info 指针 */
    __a20_start_info = si;

    /* 2. 确认 ABI 版本 */
    struct a20_abi_info abi;
    a20_abi_info(&abi);
    if (abi.abi_major != A20_ABI_MAJOR) {
        a20_task_exit(127);
    }

    /* 3. 初始化 fd 表 */
    __fd_table_init(si);

    /* 4. 初始化堆 */
    __malloc_init();

    /* 5. 设置 TLS */
    __init_tls();

    /* 6. 调用 musl 的 __libc_start_main */
    __libc_start_main(main, si->argc,
                      (char **)si->argv, _init, _fini, 0);
}

4.4 语义桥接——最难的部分

移植 musl 不只是换 syscall 编号。以下 POSIX 概念和 A20 概念**语义不同**,需要专门的桥接层。

6.4.1 fork/exec → task_spawn

这是最大的语义鸿沟。musl 内部不直接调 fork,但用户程序大量使用。

阶段 1:不支持 fork,只支持 posix_spawn

/* src/process/a20_fork.c */
pid_t fork(void) {
    errno = ENOSYS;
    return -1;
}

pid_t vfork(void) {
    errno = ENOSYS;
    return -1;
}

/* src/process/a20_posix_spawn.c */
int posix_spawn(pid_t *pid, const char *path,
                const posix_spawn_file_actions_t *fa,
                const posix_spawnattr_t *attr,
                char *const argv[], char *const envp[])
{
    /* 1. path_open 可执行文件 */
    struct a20_path_open_args oa = { ... };
    long ret = a20_path_open(&oa);
    int img_fd = oa.out_handle;

    /* 2. 设置 spawn 参数 */
    struct a20_task_spawn_args sa = {
        .image = img_fd,
        .root_dir = __root_dir_handle,
        .cwd_dir = __cwd_dir_handle,
        .argv = argv, .argc = ...,
        .envp = envp, .envc = ...,
    };

    /* 3. 传递 fd 表中的 handle */
    struct a20_spawn_handle handles[32];
    int nh = 0;
    for (int i = 0; i < __fd_table_size; i++) {
        if (__fd_table[i].handle != A20_HANDLE_NULL &&
            !(__fd_table[i].fd_flags & FD_CLOEXEC)) {
            handles[nh++] = (struct a20_spawn_handle){
                .handle = __fd_table[i].handle,
                .rights = 0,       /* inherit all source rights */
                /* Native libc maps fd i to this reserved child slot. */
                .target_slot = 64 + i,
            };
        }
    }
    sa.handles = handles;
    sa.handle_count = nh;

    /* 4. task_spawn */
    ret = a20_task_spawn(&sa);
    if (ret < 0) return __a20_to_errno(ret);

    if (pid) *pid = __handle_to_pid(sa.out_task);
    return 0;
}

阶段 2(可选):fork 模拟

/* src/process/a20_fork_emul.c — 高级 fork 模拟 */
pid_t fork(void){
    /*
     * A20 的 task_spawn 是原子创建+加载。
     * 模拟 fork 需要:
     *
     * 1. task_spawn 当前程序的 ELF(A20_SPAWN_FORK_SELF flag)
     * 2. 内核创建子进程时:
     *    a. COW 复制父进程地址空间
     *    b. 复制 fd 表(handle dup + 相同 slot 号)
     *    c. 复制信号处置、cwd 等
     * 3. 子进程入口点不是 ELF entry,而是 fork 返回点
     * 4. 通过共享内存页传递 fork 上下文(返回值=0, 父 pid 等)
     *
     * 这需要 task_spawn 支持 A20_SPAWN_FORK_SELF flag,
     * 和内核配合做 COW + 状态快照。
     * 实现复杂度高,仅在有明确需求时才做。
     */
    return -ENOSYS;
}

6.4.2 信号 → 事件队列

musl 内部使用信号做以下事情: - SIGCANCEL:pthread 取消机制 - SIGSETXID:setuid/setgid 广播给线程组 - SIGTIMER:POSIX timer 到期通知 - SIGCHLD:子进程退出通知 - 用户注册的信号处理器(sigaction)

桥接策略:信号桩 + 事件模拟

/* src/signal/a20_signal.c */

/* 桩函数——让 musl 编译通过,但不真正实现信号投递 */
int __sigaction(int sig, const struct sigaction *sa,
                struct sigaction *old, size_t masksize)
{
    /* 保存用户注册的 handler(用于 kill/sigqueue 模拟) */
    __signal_handlers[sig] = sa ? *sa : __signal_handlers[sig];
    if (old) *old = __signal_handlers[sig];
    return 0;
}

int raise(int sig) {
    /* 直接调用注册的 handler(同步方式) */
    if (__signal_handlers[sig].sa_handler &&
        __signal_handlers[sig].sa_handler != SIG_IGN &&
        __signal_handlers[sig].sa_handler != SIG_DFL) {
        __signal_handlers[sig].sa_handler(sig);
    }
    return 0;
}

/* kill 通过 channel 或 event 投递信号通知 */
int kill(pid_t pid, int sig) {
    /* 方案 A:通过 task_kill 发送 sig 作为 reason */
    a20_handle_t task = __pid_to_handle(pid);
    return a20_task_kill(task, sig);
}

/* pthread_cancel 不再基于信号 */
void __pthread_cancel_handler(struct __pthread *t) {
    /* 直接设置取消标志位,线程在取消点检查 */
    a_thread->cancel = 1;
    /* 如果线程在 event_wait 中,通过 event_cancel 唤醒 */
    a20_event_cancel(t->event_queue, t->thread_handle);
}

设计边界:Native 的普通通知由运行时在明确定义的检查点处理,不在任意用户指令位置执行处理器。这有利于控制重入和资源清理,但通知延迟取决于检查点分布;内核抢占与强制终止不依赖用户检查点。Linux ABI 保留其异步信号兼容语义。该边界已按项目负责人决定确认为 1.0 范围,详见 Native 信号与通知的设计边界。

6.4.3 pthread → A20 thread

/* src/thread/a20_pthread.c */

int pthread_create(pthread_t *res, const pthread_attr_t *attr,
                   void *(*entry)(void *), void *arg)
{
    struct __pthread *t = malloc(sizeof(*t));

    /* 1. 分配栈 */
    size_t stack_size = attr ? attr->_a_stacksize : DEFAULT_STACK_SIZE;
    struct a20_vm_alloc_args ma = {
        .size = sizeof(ma), .version = 1,
        .length = stack_size,
        .prot = 3, /* RW */
        .flags = 0,
    };
    a20_vm_alloc(&ma);
    t->stack = ma.out_addr;

    /* 2. 分配 TLS */
    size_t tls_size = __tls_size();
    struct a20_vm_alloc_args ta = {
        .size = sizeof(ta), .version = 1,
        .length = tls_size + sizeof(struct pthread),
        .prot = 3,
    };
    a20_vm_alloc(&ta);
    t->tls = ta.out_addr;
    __init_tls_for(t);

    /* 3. 创建 A20 线程 */
    struct a20_thread_create_args ca = {
        .size = sizeof(ca), .version = 1,
        .entry = (uint64_t)__pthread_entry,
        .arg = (uint64_t)t,
        .stack_base = t->stack,
        .stack_size = stack_size,
        .tls_base = t->tls,
        .flags = 0,
    };
    long ret = a20_thread_create(&ca);
    if (ret < 0) { free(t); return ret; }

    t->handle = ca.out_thread;
    t->entry = entry;
    t->arg = arg;
    *res = t;
    return 0;
}

/* 线程入口——包装用户函数 */
static void __pthread_entry(void *arg) {
    struct __pthread *t = arg;
    void *result = t->entry(t->arg);
    __pthread_set_result(t, result);
    /* 通知 joiner */
    if (t->join_event) {
        a20_event_notify(t->join_event);
    }
    a20_thread_exit(0);
}

int pthread_join(pthread_t t, void **res) {
    /* 等待目标线程退出 */
    struct a20_task_status status;
    a20_task_wait(t->handle, 0, &status);
    if (res) *res = t->result;
    return 0;
}

6.4.4 pthread_mutex(futex 替代)

以下 event_queue mutex 是历史草案。当前 Native ABI 已有 futex_wait/futex_wake(0x0B00),活跃 mlibc 线程同步使用 Native futex,不采用该方案。

方案:基于 event_queue 的等待机制

/* src/thread/a20_mutex.c */

/* A20 的轻量级等待机制:
 * 利用 vm_alloc 的 MAP_SHARED 页做原子变量,
 * 用 event_queue 做阻塞等待。 */

/* mutex 内部结构 */
struct a20_mutex_internal {
    _Atomic uint32_t state;      /* 0=unlocked, 1=locked, 2=contended */
    uint32_t type;               /* PTHREAD_MUTEX_NORMAL/RECURSIVE/... */
    uint32_t owner;              /* 持有者 thread id */
    uint32_t count;              /* 递归计数 */
    a20_handle_t wait_queue;     /* 等待队列(lazy 创建) */
};

int pthread_mutex_lock(pthread_mutex_t *pm) {
    struct a20_mutex_internal *m = (void *)&pm->__i;

    /* 快速路径:无竞争 */
    uint32_t expected = 0;
    if (atomic_compare_exchange_strong(&m->state, &expected, 1)) {
        m->owner = __pthread_self()->tid;
        return 0;
    }

    /* 慢路径:有竞争 */
    if (m->wait_queue == A20_HANDLE_NULL) {
        /* lazy 创建等待队列 */
        struct a20_event_queue_create_args eq = { ... };
        a20_event_queue_create(&eq);
        atomic_store(&m->wait_queue, eq.out_queue);
    }

    while (1) {
        /* 标记为 contended */
        atomic_store(&m->state, 2);

        /* 等待唤醒事件 */
        struct a20_event_wait_args ew = {
            .queue = m->wait_queue,
            .max_events = 1,
            .timeout_ns = A20_WAIT_FOREVER,
        };
        a20_event_wait(&ew);

        /* 尝试获取 */
        expected = 0;
        if (atomic_compare_exchange_strong(&m->state, &expected, 2)) {
            m->owner = __pthread_self()->tid;
            return 0;
        }
    }
}

int pthread_mutex_unlock(pthread_mutex_t *pm) {
    struct a20_mutex_internal *m = (void *)&pm->__i;
    m->owner = 0;

    uint32_t state = atomic_load(&m->state);
    if (state == 1) {
        /* 无竞争,直接释放 */
        uint32_t expected = 1;
        if (atomic_compare_exchange_strong(&m->state, &expected, 0))
            return 0;
    }

    /* 有等待者:释放并唤醒一个 */
    atomic_store(&m->state, 0);
    /* 向等待队列投递唤醒事件 */
    struct a20_event ev = { .type = A20_EVENT_WAKEUP };
    a20_event_post(m->wait_queue, &ev);
    return 0;
}

性能上,快速路径(无竞争)是纯用户态原子操作,和 Linux futex 一样快。慢路径走 event_queue syscall,比 futex 多一次间接,但语义更清晰;event_queue 的通知机制避免了 futex 的内核-用户态 hash table 开销。

4.5 工作量估算

模块 新增/修改代码 难度 依赖
arch/a20/syscall.h ~80 行 低 —
arch/a20/crt_arch.h ~40 行 中 启动协议确定
arch/a20/bits/syscall.h ~300 行 低 syscall 编号稳定
syscall 映射层 ~800 行 中 fd 表 + 错误码映射
fd↔handle 映射 ~200 行 低 —
pthread 桥接 ~600 行 高 thread_create + event
mutex/futex 替代 ~400 行 高 event_queue
信号桩 ~300 行 中 —
fork 桩 + posix_spawn ~200 行 中 task_spawn
错误码映射 ~100 行 低 —
总计 ~3020 行 — —

不动的代码是 musl 的 string/、stdlib/、stdio/(底层替换后)、math/、regex/、locale/ 等,共 ~45K 行,完全复用。


5. 编译工具链

5.1 目标 triple

aarch64-unknown-a20elf

因为 A20 和 Linux 在 aarch64 上共享相同的指令集和 ABI(AAPCS64),不需要新的 LLVM/GCC backend。只需要:

  1. 新的 target triple(区分 A20 ELF 和 Linux ELF)
  2. 新的 sysroot(A20 头文件 + musl-a20 + crt0.o + linker script)
  3. gcc/clang spec 文件(覆盖默认链接行为)

5.2 交叉编译流程

# 方式 1:使用 clang(推荐,因为 clang 天然支持交叉编译)
clang --target=aarch64-unknown-a20elf \
      --sysroot=/opt/a20-sysroot \
      -isystem /opt/a20-sysroot/include \
      -L /opt/a20-sysroot/lib \
      -static \
      -o hello hello.c

# 方式 2:使用 gcc(需要构建 a20 target 的 cross-gcc)
aarch64-a20-gcc -static -o hello hello.c

# 方式 3:直接用 musl 的构建系统
cd musl && ./configure --target=aarch64-a20 --prefix=/opt/a20-sysroot && make && make install

5.3 sysroot 结构

/opt/a20-sysroot/
├── include/
│   ├── a20/                    ← A20 Native ABI 头文件
│   │   ├── types.h             ← a20_handle_t, a20_rights_t, ...
│   │   ├── syscall.h           ← syscall 编号 + wrapper
│   │   ├── rights.h            ← 权限位定义
│   │   ├── errno.h             ← A20 错误码
│   │   └── startup.h           ← a20_start_info_t
│   ├── sys/                    ← POSIX 头文件(来自 musl)
│   ├── stdio.h                 ← ISO C 头文件(来自 musl)
│   └── ...
├── lib/
│   ├── crt0.o                  ← A20 启动代码
│   ├── crtbegin.o / crtend.o   ← GCC 构造/析构
│   ├── libc.a                  ← musl-a20 静态库
│   └── liba20rt.a              ← A20 syscall wrappers
├── a20.ld                      ← A20 ELF linker script
└── etc/
    └── a20-abi-version         ← ABI 版本检查

5.4 linker script 关键段

/* a20.ld — A20 Native ELF linker script */
ENTRY(_start)

SECTIONS {
    . = 0x400000 + SIZEOF_HEADERS;
    .text : { *(.text .text.*) }
    .rodata : { *(.rodata .rodata.*) }
    .data : { *(.data .data.*) }
    .bss : { *(.bss .bss.*) *(COMMON) }

    /DISCARD/ : {
        *(.note.*)
        *(.comment)
    }
}

PHDRS {
    PT_LOAD  PT_A20_START_INFO 0x70000001;
}

6. 实施路线图

Phase 0:liba20rt 最小运行时(1-2 周)

目标:能让一个极简程序在 A20 Native ABI 上打印并退出。

/* test_hello.c — Phase 0 测试程序 */
#include <a20/syscall.h>

void _start(const a20_start_info_t *si) {
    const char msg[] = "Hello from A20 Native ABI!\n";
    struct a20_iovec iov = { (uint64_t)msg, sizeof(msg) - 1 };
    struct a20_io_args args = {
        .size = sizeof(args), .version = 1,
        .handle = si->stdout_handle,
        .iov = (uint64_t)&iov, .iov_count = 1,
    };
    a20_handle_write(&args);
    a20_task_exit(0);
}

工作项: - [x] syscall 发射宏(a20_syscall6) - [x] 全部 142 个 syscall 编号定义(syscall_table.def) - [x] crt0 启动汇编(aarch64) - [x] 简单测试:write stdout + exit

Phase 1:liba20c 最小 C 库(2-4 周)

目标:能用标准 C 写程序。

/* test_stdio.c — Phase 1 测试程序 */
#include <stdio.h>
#include <stdlib.h>

int main(int argc, char *argv[]) {
    printf("Hello, argc=%d\n", argc);
    FILE *f = fopen("/test.txt", "w");
    fprintf(f, "A20 Native works!\n");
    fclose(f);
    return 0;
}

工作项: - [x] malloc/free/realloc(liba20c 当前实现) - [x] fd↔handle 映射表 - [x] FILE* 实现(fopen/fread/fwrite/fclose/printf) - [x] POSIX open/read/write/close(基于 fd 表) - [x] string/stdlib(直接复用 musl 代码,0 改动) - [x] errno 映射 - [x] 测试:hello world + 文件读写 + malloc

Phase 2:旧 musl bridge(历史,代码已归档)

目标:能让 busybox 或 dropbear 等真实程序运行。

工作项(全部位于 user/archive/,不参与当前构建): - [x] arch/a20/ 全套(atomic.h, reloc.h, config.a20, syscall.h) - [x] syscall 映射层(a20_syscallops.c,336 行) - [x] pthread → A20 thread 适配(a20_pthread.c,283 行) - [x] mutex → event_queue 适配(a20_mutex.c,312 行) - [x] 信号桥接(a20_signal.c) - [x] fork + posix_spawn via task_spawn(a20_fork.c + a20_posix_spawn.c) - [x] fd 表映射(a20_fdtable.c,313 行) - [x] sysroot 构建 + linker script(build_sysroot.sh + a20.ld) - [x] 集成测试(历史上曾记录"4 套 118 cases host-mode",该套件当前不存在,不得作为现行证据)

Phase 3:POSIX 适配(按需)

目标:支持可映射到 Native 已声明契约的 POSIX 程序;依赖任意执行点异步信号处理器的应用使用 Linux ABI。检查点式适配不等同完整 POSIX 信号兼容。

工作项: - [x] 信号检查点式模拟(内核 task_kill/signal_check/signal_mask + mlibc sigaction/kill/sigprocmask + futex 检查点投递) - [ ] select 的完整语义覆盖(poll 的已接入子集见下文) - [ ] timerfd → A20 timer + event_queue - [ ] inotify → event_watch_fs

当前活跃路线:mlibc sysdeps/a20

  • 静态 libc/sysroot、线程与 Native futex。
  • pipe/poll/socketpair 与 posix_spawn/waitpid 的已接入子集。
  • 将当前 RISC-V64 构建/smoke 扩展为明确的多架构矩阵。

Native 信号遵循检查点式设计边界,完整异步处理器不作为 1.0 待办。fork/exec、真实动态链接与 exec 继承矩阵的实现和验证范围见 运行时现状;构建目标见 tools/mk/targets-mlibc.mk。

关键依赖关系

Phase 0 ──→ Phase 1 ──→ Phase 2 ──→ Phase 3
│            │            │            │
│            │            │            └── 内核: A20_SPAWN_FORK_SELF
│            │            │            └── 运行时: 检查点通知(设计边界)
│            │            √ 已完成    └── 待实现
│            √ 已完成    └── 内核: 全部 142 个 syscall √
√ 已完成    └── 内核: ~15 个基础 syscall √
└── 内核: 启动协议 + abi_info + handle_close + vm_alloc √
          + handle_write + path_open + task_exit √

每个 Phase 可以独立验证,不依赖后续 Phase 的内核功能。


7. Syscall 入口约定

7.1 架构相关调用约定

架构 陷入指令 Syscall 编号 参数 (Arg 0 ~ Arg 5) 返回值
x86_64 int $0x80 rax rdi, rsi, rdx, r10, r8, r9 rax
aarch64 svc #0 x8 x0 ~ x5 x0
riscv64 ecall a7 a0 ~ a5 a0
riscv32 ecall a7 a0 ~ a5 a0
loongarch64 syscall 0 a7 a0 ~ a5 a0
arm32 svc #0 r7 r0 ~ r5 r0
powerpc64 sc r0 r3 ~ r8 r3

7.2 通用约定

  • 完整的 178 个系统调用速查矩阵、参数形式与 C 语言调用示例参见 系统调用手册与调用指南 (syscalls.md)。
  • 所有复杂 syscall 传结构体指针(通过 a20_abi_header_t 声明 size 与 version 版本化)。
  • 简单 syscall(如 handle_close(handle))可以直接通过标量寄存器传参。
  • 返回 a20_status_t(>= 0 成功,< 0 为正数错误码的负值 -A20_ERR_*)。
  • 内核不保留用户态通用临时寄存器(除返回值外;execve 与 task_restore 替换完整上下文)。

8. Native 程序 ELF 要求

Native 程序的 ELF 文件应满足:

  1. Native ELF 使用 PT_A20_START_INFO=0x6a20a200 marker;user/liba20rt/a20-generic.ld 和 user/mlibc/a20-mlibc.ld 已生成该 program header。
  2. 入口点(e_entry)不假设栈内容,只假设 a20_start_info 指针在约定寄存器中。
  3. 静态 liba20rt/liba20c/mlibc 程序不需要 interpreter;内核已有 Native PT_INTERP 栈封装路径,但动态 mlibc/rtld 尚未形成已验证交付。
  4. 不需要 vDSO。所有 syscall 通过直接 trap 进入内核。