跳转至

A20OS Native ABI:类型与结构体定义

本文档定义 Native ABI 的核心数据类型、结构体内存布局与二进制接口规范。运行时扩展与版本规则见运行时扩展规范,对象权限模型见 security.md,句柄生命周期见 handle.md。


1. 基础类型

Native ABI 固定使用小端(little-endian)、补码整数(two's complement)、显式宽度类型(explicit-width types)。

typedef uint32_t a20_handle_t;     /* 进程本地 handle 编号 */
typedef uint64_t a20_rights_t;     /* 14 位权限位域 */
typedef uint64_t a20_flags_t;      /* 操作标志位 */
typedef int64_t  a20_status_t;     /* 返回状态(>= 0 成功,< 0 错误) */
typedef uint64_t a20_time_ns_t;    /* 纳秒时间戳 */
typedef uint64_t a20_off_t;        /* 文件偏移量 */
typedef uint64_t a20_size_t;       /* 大小 */
typedef uint64_t a20_vaddr_t;      /* 虚拟地址 */

指针大小由 a20_abi_info.pointer_bits 指示,处理函数读取实际指针宽度。64 位架构使用 64 位用户指针;32 位用户态和 MCU Native 实验端口使用独立 ABI profile。更详细的 ISA/调用约定、内存模型与接口可用性由 execution_info 查询;MCU 已接入公共 futex/atomic32/匿名堆,尚未提供完整 abi_info 与句柄接口。


2. ABI 头约定

所有 syscall 参数结构体以 a20_abi_header_t 开头:

typedef struct a20_abi_header {
    uint32_t size;      /* 结构体实际大小(字节) */
    uint32_t version;   /* 结构体版本号 */
} a20_abi_header_t;

演进规则

  1. 用户传入的 size 必须覆盖其所声明 version 的完整必需前缀;当前所有 version-1 结构体均要求 size >= sizeof(struct),拒绝通过零填充补齐必需字段。
  2. 用户传入的 size 大于内核支持结构体大小时,内核只读取已知字段。
  3. 新字段只能追加并提高 version;旧 version 的最小 size 必须在该 version 引入时固定。
  4. 目标规则是未知 flag 保留位必须为 0,否则返回 A20_ERR_INVALID_ARGUMENT。当前实现并不统一:futex、typed channel 等入口会拒绝未知位,handle_dup、vm_map 和部分 namespace/wait 路径仍忽略或保存相应字段。

这些规则使 ABI 可以在不破坏旧程序的情况下扩展。内核通过 size 和 version 确定调用方使用的结构体版本。


3. Core / ABI 结构体

a20_abi_info_t — ABI 查询结果

typedef struct a20_abi_info {
    uint32_t size;
    uint32_t version;
    uint32_t abi_major;          /* 主版本号,不兼容变更时递增 */
    uint32_t abi_minor;          /* 次版本号,兼容新增功能时递增 */
    uint32_t abi_patch;          /* 补丁版本号,仅 bugfix */
    uint32_t pointer_bits;       /* 指针宽度(32 或 64) */
    uint32_t page_size;          /* 页大小(字节) */
    uint32_t handle_bits;        /* handle 编号宽度(32) */
    uint64_t feature_bits[4];    /* 可选能力位图 */
    uint64_t syscall_bitmap_addr;/* 用户地址:支持的 syscall 位图 */
    uint64_t syscall_bitmap_size;/* 位图大小(字节) */
} a20_abi_info_t;

当前 abi_info 填充版本、指针/页/handle 宽度以及 feature bits;syscall_bitmap_addr 和 syscall_bitmap_size 仍保持清零,调用方不能用这两个保留字段枚举登记入口。


4. Handle 操作结构体

a20_handle_dup_args_t — handle 复制

typedef struct a20_handle_dup_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t source;         /* 源 handle */
    uint32_t flags;              /* 保留;调用方应置 0,当前内核未校验 */
    a20_rights_t rights_mask;    /* 请求的权限子集 */
    a20_handle_t out_handle;     /* 输出:新 handle */
    uint32_t reserved;
} a20_handle_dup_args_t;

rights_mask 必须是源 handle rights 的子集,否则返回 A20_ERR_ACCESS。

a20_handle_info_t — handle 查询结果

typedef struct a20_handle_info {
    uint32_t size;
    uint32_t version;
    uint32_t object_type;        /* A20_OBJ_* 类型常量 */
    uint32_t state;              /* 对象状态 */
    a20_rights_t rights;         /* 当前 handle 的权限 */
    uint64_t object_id_hint;     /* 调试用,不保证全局稳定 */
    uint64_t flags;              /* 对象属性标志 */
} a20_handle_info_t;

a20_control_args_t — 通用对象控制

typedef struct a20_control_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t handle;         /* 目标 handle */
    uint32_t namespace_id;       /* 命令所属的对象协议 */
    uint32_t command;            /* 具体命令 */
    uint64_t in_ptr;             /* 输入缓冲区(用户指针) */
    uint64_t in_size;            /* 输入大小 */
    uint64_t out_ptr;            /* 输出缓冲区(用户指针) */
    uint64_t out_size;           /* 输出缓冲区容量 */
    uint64_t out_actual;         /* 输出:实际写入字节数 */
} a20_control_args_t;

规则:namespace_id 表明命令属于哪个对象协议;命令结构也必须版本化;通用操作应优先设计成明确 syscall,不滥用 control。

handle_control 命令 — 类型化控制(无 ioctl shim)

handle_control(handle, op, arg0, arg1) 的 op 定义与版本化参数结构体见 03-handle.md §2.7。要点:Native ABI 无通用 ioctl;所有携带数据的 op 用 {size, version} 版本化结构体(a20_handle_temporal_args_t、a20_winsize_args_t、a20_ctl_int_args_t、a20_ctl_flags_args_t),并遵循 E-APPEND 演进规则。

#define A20_HANDLE_CTRL_SET_TEMPORAL   2u  /* arg0 = a20_handle_temporal_args_t* */
#define A20_HANDLE_CTRL_GET_TEMPORAL   3u  /* arg0 = a20_handle_temporal_args_t* */
#define A20_HANDLE_CTRL_SET_LABEL      4u  /* arg0 = a20_ctl_int_args_t*(仅可上调) */
#define A20_HANDLE_CTRL_CHDIR          5u  /* directory handle -> 当前 cwd */
#define A20_HANDLE_CTRL_GET_WINSIZE    6u  /* arg0 = a20_winsize_args_t*(out) */
#define A20_HANDLE_CTRL_SET_WINSIZE    7u  /* arg0 = a20_winsize_args_t*(in) */
#define A20_HANDLE_CTRL_TCFLUSH        8u  /* arg0 = a20_ctl_int_args_t*(queue) */
#define A20_HANDLE_CTRL_SET_FLAGS      9u  /* arg0 = a20_ctl_flags_args_t* */

/* 时态能力控制(03-handle.md §2.6,06-security.md §6)。
 * SET 仅可增强(non-refreshability):flag 只能添加不能清除,
 * expiry 只能提前,remaining_ops 只能减少。 */
typedef struct a20_handle_temporal_args {
    uint32_t size;
    uint32_t version;
    uint64_t expiry_ns;      /* 绝对 CLOCK_MONOTONIC 纳秒;0 = 无过期 */
    uint32_t remaining_ops;  /* OP_COUNT flag 置位时的操作预算;0 = 已耗尽 */
    uint32_t temporal_flags; /* A20_TEMPORAL_* */
} a20_handle_temporal_args_t;

5. Task / Thread 结构体

a20_spawn_handle_t — spawn 传递的 handle

typedef struct a20_spawn_handle {
    a20_handle_t handle;         /* 要传递的 handle */
    a20_rights_t rights;         /* 0 = inherit all; otherwise source subset */
    uint32_t target_slot;        /* Native fd: 64 + fd; otherwise optional */
    uint32_t flags;              /* 保留 */
} a20_spawn_handle_t;

a20_task_spawn_args_t — 进程创建

typedef struct a20_task_spawn_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t image;          /* 可执行文件或 image 对象 */
    a20_handle_t root_dir;       /* 根目录 handle */
    a20_handle_t cwd_dir;        /* 工作目录 handle */
    a20_handle_t event_queue;    /* 默认事件队列 handle */
    uint64_t argv;               /* char*[] */
    uint64_t envp;               /* char*[] */
    uint32_t argc;
    uint32_t envc;
    uint64_t handles;            /* a20_spawn_handle_t[] */
    uint32_t handle_count;
    uint32_t flags;
    a20_handle_t out_task;       /* 输出:新进程的 task handle */
} a20_task_spawn_args_t;

a20_thread_create_args_t — 线程创建

typedef struct a20_thread_create_args {
    uint32_t size;
    uint32_t version;
    uint64_t entry;              /* 入口函数地址 */
    uint64_t arg;                /* 入口参数 */
    uint64_t stack_base;         /* 16 字节对齐的栈顶(高地址) */
    uint64_t stack_size;         /* 栈大小 */
    uint64_t tls_base;           /* TLS 基址 */
    uint32_t flags;
    a20_handle_t out_thread;     /* 输出:新线程 handle */
    /* v1 append(E-APPEND):sched_flags 非零时在 publish 前应用 */
    uint32_t sched_flags;        /* A20_SCHED_POLICY | A20_SCHED_PRIORITY */
    int32_t  sched_policy;       /* A20_SCHED_NORMAL/FIFO/RR */
    int32_t  sched_priority;     /* RT 优先级 1..99 */
    uint32_t reserved0;
} a20_thread_create_args_t;

#define A20_THREAD_CREATE_V1_SIZE 56U

size 为 56(原始版本)时仍被接受,调度字段按 0 处理;新调用方传完整结构即可在子线程发布前设置策略与优先级。

线程入口是接收 arg 的本机 C 函数,必须显式调用 thread_exit,不能返回。调用者在所有 ISA 上提供 16 字节对齐的栈顶;架构入口负责本机调用约定所需的偏移,例如 x86-64 在直接函数入口预留 8 字节,使 RSP 模 16 为 8。此规则仅用于 Native thread_create,不修改 Linux clone 或进程启动。

a20_task_status_t — 进程退出状态

typedef struct a20_task_status {
    uint32_t size;
    uint32_t version;
    uint32_t reason;             /* 退出原因 */
    int32_t  exit_code;          /* 退出码 */
    uint64_t user_time_ns;       /* 用户态 CPU 时间 */
    uint64_t kernel_time_ns;     /* 内核态 CPU 时间 */
} a20_task_status_t;

6. Memory 结构体

a20_vm_alloc_args_t — 匿名内存分配

typedef struct a20_vm_alloc_args {
    uint32_t size;
    uint32_t version;
    uint64_t addr_hint;          /* 建议地址,0 表示内核选择 */
    uint64_t length;             /* 分配大小(字节) */
    uint32_t prot;               /* 保护标志(R/W/X) */
    uint32_t flags;              /* 分配标志 */
    uint64_t out_addr;           /* 输出:分配到的地址 */
} a20_vm_alloc_args_t;

a20_vm_map_args_t — 文件/共享内存映射

typedef struct a20_vm_map_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t source;         /* 源对象 handle(MEMORY/FILE/DEVICE),A20_HANDLE_NULL = 匿名 */
    uint32_t _pad;
    uint64_t addr_hint;          /* 建议地址 */
    uint64_t length;             /* 映射长度 */
    uint64_t offset;             /* 源对象内偏移 */
    uint32_t prot;               /* 保护标志 */
    uint32_t flags;              /* 映射标志 */
    uint64_t out_addr;           /* 输出:映射到的地址 */
} a20_vm_map_args_t;

a20_vm_share_args_t — 内存共享导出

该结构是保留的地址区间导出布局。当前 vm_share syscall 实际签名是 (vmo_handle, target_task, rights),只复制已有 A20_OBJ_MEMORY handle;不会按 addr/length 反查并导出映射。

typedef struct a20_vm_share_args {
    uint32_t size;
    uint32_t version;
    uint64_t addr;               /* 要共享的地址 */
    uint64_t length;             /* 共享长度 */
    a20_rights_t rights;         /* 导出权限 */
    a20_handle_t out_handle;     /* 输出:共享内存对象 handle */
} a20_vm_share_args_t;

7. Filesystem / Path 结构体

a20_path_open_args_t — 路径打开

typedef struct a20_path_open_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t dir;            /* 基目录 handle */
    uint32_t flags;              /* 打开标志 */
    a20_rights_t rights;         /* 请求的权限 */
    uint64_t path;               /* const char*:路径 */
    uint64_t path_len;           /* 路径长度,0 表示 nul-terminated */
    uint32_t mode;               /* 创建模式 */
    uint32_t reserved;
    a20_handle_t out_handle;     /* 输出:打开的文件 handle */
} a20_path_open_args_t;

a20_path_create_args_t — 创建文件系统节点

typedef struct a20_path_create_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t dir;            /* 父目录 handle */
    uint32_t node_type;          /* 节点类型(file/dir/socket/device) */
    uint64_t path;               /* const char* */
    uint64_t path_len;
    uint32_t mode;               /* 创建模式 */
    uint32_t flags;
    a20_rights_t rights;         /* 请求的权限 */
    a20_handle_t out_handle;     /* 输出:新节点的 handle */
} a20_path_create_args_t;

a20_iovec_t / a20_io_args_t — I/O 操作

typedef struct a20_iovec {
    uint64_t base;               /* 缓冲区基址 */
    uint64_t len;                /* 缓冲区长度 */
} a20_iovec_t;

typedef struct a20_io_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t handle;         /* 目标 handle */
    uint32_t flags;              /* I/O 标志 */
    uint64_t iov;                /* a20_iovec_t[] */
    uint32_t iov_count;
    uint32_t reserved;
    uint64_t offset;             /* 偏移量,支持 A20_OFFSET_CURRENT */
    uint64_t out_count;          /* 输出:实际传输字节数 */
} a20_io_args_t;

a20_stat_t — 文件属性

typedef struct a20_stat {
    uint32_t size;
    uint32_t version;
    uint64_t dev;                /* 设备号 */
    uint64_t ino;                /* inode 号 */
    uint32_t mode;               /* 文件模式 */
    uint32_t nlink;              /* 硬链接数 */
    uint32_t uid;
    uint32_t gid;
    uint64_t size_bytes;         /* 文件大小 */
    uint64_t blocks;             /* 块数 */
    uint64_t atime_ns;           /* 访问时间 */
    uint64_t mtime_ns;           /* 修改时间 */
    uint64_t ctime_ns;           /* 元数据变更时间 */
} a20_stat_t;

8. Event / IPC 结构体

a20_event_queue_create_args_t — 创建事件队列

typedef struct a20_event_queue_create_args {
    uint32_t size;
    uint32_t version;
    uint32_t capacity_hint;      /* 容量提示 */
    uint32_t flags;
    a20_handle_t out_queue;      /* 输出:事件队列 handle */
} a20_event_queue_create_args_t;

a20_event_watch_args_t — 注册事件关注

typedef struct a20_event_watch_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t queue;          /* 事件队列 handle */
    a20_handle_t target;         /* 被观察的 handle */
    uint64_t event_mask;         /* 关注的事件位图 */
    uint64_t user_data;          /* 用户关联数据 */
} a20_event_watch_args_t;

a20_pending_event_t / a20_event_wait_args_t — 等待事件

typedef struct a20_pending_event {
    a20_handle_t source;         /* 产生事件的 handle */
    uint32_t type;               /* 事件类型(A20_EVENT_* 索引) */
    uint64_t events;             /* 触发的事件位图 = 1ull << type */
    uint64_t user_data;          /* 注册时的 user_data */
    uint64_t data0, data1, data2;/* 事件相关数据 */
} a20_pending_event_t;

/* 可观察事件类型(05-ipc.md §3.3);事件掩码为 1ull << 类型 */
#define A20_EVENT_READABLE        0u   /* file/socket/pipe:可读 */
#define A20_EVENT_WRITABLE        1u   /* file/socket/pipe:可写 */
#define A20_EVENT_ERROR           2u   /* file/socket:I/O 错误 */
#define A20_EVENT_CLOSED          3u   /* 对象被关闭 */
#define A20_EVENT_CONNECTION      4u   /* socket:新连接到达 */
#define A20_EVENT_ACCEPT_READY    5u   /* socket:可 accept */
#define A20_EVENT_EXPIRED         6u   /* timer:到期 */
#define A20_EVENT_EXITED          7u   /* task/thread:退出 */
#define A20_EVENT_MESSAGE_READY   8u   /* channel:有消息可接收 */
#define A20_EVENT_PEER_CLOSED     9u   /* channel:对端关闭 */
#define A20_EVENT_MASK(ev)        (1ull << (ev))

typedef struct a20_event_wait_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t queue;          /* 事件队列 handle */
    uint32_t _pad;
    uint64_t events;             /* a20_pending_event_t[] 输出缓冲区 */
    uint32_t max_events;         /* 缓冲区容量(内核上限 64) */
    uint32_t _pad2;
    uint64_t timeout_ns;         /* 相对超时(纳秒):0 = 不等待,
                                  * A20_TIMEOUT_INFINITE = 无限等待 */
    uint32_t flags;              /* 保留 */
    uint32_t out_count;          /* 输出:实际事件数 */
} a20_event_wait_args_t;

event_wait 在队列为空时默认**阻塞**(tokenized Park/Wake),timeout_ns == 0 退化为轮询(空队列返回 A20_ERR_WOULD_BLOCK),超时返回 A20_ERR_TIMED_OUT。当前产生事件的对象:channel(MESSAGE_READY/PEER_CLOSED/CLOSED)、timer(EXPIRED)、task 退出(EXITED);file/socket 的 READABLE/WRITABLE 等事件源尚未接入。

a20_msg_send_args_t / a20_msg_recv_args_t — 消息通道

typedef struct a20_msg_send_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t channel;        /* 通道端点 handle */
    uint32_t _pad;
    uint64_t data;               /* 消息字节缓冲区 */
    uint32_t data_len;           /* 字节数(上限 64KB) */
    uint32_t flags;              /* A20_MSG_* */
    uint64_t handles;            /* a20_handle_t[]:要传递的 handle */
    uint32_t handle_count;       /* 传递的 handle 数量(上限 8) */
    uint64_t transfer_rights;    /* a20_rights_t[] 每 handle 权限上限,0 = 源权限 */
} a20_msg_send_args_t;

typedef struct a20_msg_recv_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t channel;        /* 通道端点 handle */
    uint32_t _pad;
    uint64_t data_buf;           /* 接收缓冲区 */
    uint32_t data_buf_len;       /* 缓冲区容量 */
    uint32_t _pad2;
    uint64_t handle_buf;         /* a20_handle_t[]:接收 handle 缓冲区 */
    uint32_t handle_buf_count;   /* handle 缓冲区容量 */
    uint32_t flags;              /* A20_MSG_*(原 _pad3 字段,布局不变) */
    uint64_t out_data_len;       /* 输出:实际接收字节数 */
    uint32_t out_handle_count;   /* 输出:实际接收 handle 数 */
    uint64_t out_rights_buf;     /* a20_rights_t[]:每个接收 handle 的权限 */
} a20_msg_recv_args_t;

#define A20_MSG_NONBLOCK   (1u << 0)  /* 不阻塞,无法立即完成时返回 WOULD_BLOCK */

channel_send 在对端队列满时默认阻塞,channel_recv 在队列空时默认阻塞;传 A20_MSG_NONBLOCK 退化为非阻塞。接收方 handle table 空间不足时 channel_recv 返回 A20_ERR_NO_SPACE,消息留在队列中(不做部分投递,05-ipc.md §2.6)。


9. Network 结构体

a20_net_socket_args_t — 创建套接字

typedef struct a20_net_socket_args {
    uint32_t size;
    uint32_t version;
    int32_t domain;              /* 地址族(AF_INET 等) */
    int32_t type;                /* 套接字类型 */
    int32_t protocol;            /* 协议 */
    a20_rights_t rights;         /* 请求的权限 */
    a20_handle_t out_socket;     /* 输出:套接字 handle */
} a20_net_socket_args_t;

a20_net_addr_t — 网络地址

typedef struct a20_net_addr {
    uint16_t family;             /* AF_INET / AF_INET6 */
    uint16_t port;
    uint32_t _pad;
    uint8_t  addr[16];           /* IPv4 使用前 4 字节 */
} a20_net_addr_t;

不直接承诺 Linux sockaddr 布局;调用方通过 syscall 参数中的地址长度区分有效字段。


10. Timer 结构体

a20_timer_create_args_t — 创建定时器

typedef struct a20_timer_create_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t event_queue;    /* 事件队列 handle(到期事件投递目标) */
    uint64_t user_data;          /* 事件关联数据 */
    uint32_t flags;
    a20_handle_t out_timer;      /* 输出:定时器 handle */
} a20_timer_create_args_t;

Timer 是 handle,可被 event queue watch,不需要复制 POSIX timer id + signal delivery 模型。创建后通过 timer_set(timer, absolute_deadline_ns, interval_ns) 设置单次或周期到期时间;到期投递 A20_EVENT_EXPIRED,不投递 SIGALRM。


11. Extended I/O 结构体

a20_transfer_args_t — 零拷贝传输

splice / sendfile / copy_file_range / tee 共用一套语义,传输模式由 flags 区分。

/* 传输标志 */
#define A20_TRANSFER_PEEK       0x0001u   /* 不推进源偏移(tee 语义) */

typedef struct a20_transfer_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t source;          /* 源 handle(仅文件/设备支持 seek) */
    a20_handle_t dest;            /* 目标 handle(仅文件/设备支持 seek) */
    uint32_t flags;               /* A20_TRANSFER_* */
    uint64_t source_offset;       /* 源偏移,A20_OFFSET_CURRENT 表示当前位置 */
    uint64_t dest_offset;         /* 目标偏移,A20_OFFSET_CURRENT 表示当前位置 */
    uint64_t length;              /* 传输字节数 */
    uint64_t out_transferred;     /* 输出:实际传输字节数 */
} a20_transfer_args_t;

source_offset/dest_offset 为 A20_OFFSET_CURRENT(UINT64_MAX)时使用当前位置。权限检查上,source 需要 READ | TRANSFER,dest 需要 WRITE | TRANSFER。目前只支持 flags == 0(consume,推进源偏移)和 A20_TRANSFER_PEEK(tee,不推进源偏移)两种模式;其余保留标志位必须为零。


12. Metadata 结构体

a20_set_meta_args_t — 文件元数据修改

chmod / chown / utimes 也共用一套语义,要修改哪些字段由 flags 指定。

/* 元数据修改标志 */
#define A20_SET_META_MODE      (1u << 0)  /* 修改 mode(chmod) */
#define A20_SET_META_OWNER     (1u << 1)  /* 修改 uid/gid(chown) */
#define A20_SET_META_ATIME     (1u << 2)  /* 修改访问时间 */
#define A20_SET_META_MTIME     (1u << 3)  /* 修改修改时间 */
#define A20_SET_META_CTIME     (1u << 4)  /* 修改状态变更时间 */
#define A20_SET_META_TRUNCATE  (1u << 5)  /* 截断文件到指定大小(ftruncate) */
#define A20_SET_META_ALLOCATE  (1u << 6)  /* 预分配空间(fallocate) */

typedef struct a20_set_meta_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t handle;          /* 目标文件 handle */
    uint32_t flags;               /* A20_SET_META_* 组合 */
    uint32_t mode;                /* 新 mode(flags 含 MODE 时有效) */
    uint32_t uid;                 /* 新 uid(flags 含 OWNER 时有效) */
    uint32_t gid;                 /* 新 gid(flags 含 OWNER 时有效) */
    uint64_t atime_ns;            /* 新 atime(纳秒) */
    uint64_t mtime_ns;            /* 新 mtime(纳秒) */
    uint64_t ctime_ns;            /* 新 ctime(纳秒) */
    uint64_t truncate_size;       /* 截断大小(flags 含 TRUNCATE 时有效) */
    uint64_t allocate_size;       /* 预分配大小(flags 含 ALLOCATE 时有效) */
} a20_set_meta_args_t;

Linux 把 fchmod/fchmodat/fchown/fchownat/utimensat/ftruncate/fallocate 拆成 7+ 个独立 syscall,A20 收成一个 handle_set_meta:一次调用可同时修改多个字段,减少 syscall 次数,只动 flags 指定的字段,未指定的字段不受影响。路径版本(fchmodat 等)需要调用者先 path_open 拿到 handle,再调用 handle_set_meta。


13. Extended Attribute 结构体

a20_xattr_args_t — 扩展属性操作

/* xattr 标志 */
#define A20_XATTR_CREATE    0x0001u   /* 仅创建,已存在则报错 */
#define A20_XATTR_REPLACE   0x0002u   /* 仅替换,不存在则报错 */

typedef struct a20_xattr_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t handle;          /* 目标 handle */
    uint32_t _pad;
    uint64_t name;                /* const char*:属性名 */
    uint32_t name_len;            /* 属性名长度,0 表示 nul-terminated */
    uint32_t _pad2;
    uint64_t value;               /* void*:值缓冲区 */
    uint64_t value_len;           /* 值大小(set 时为输入,get 时为缓冲区容量) */
    uint32_t flags;               /* A20_XATTR_* */
} a20_xattr_args_t;

a20_xattr_list_args_t — 列出扩展属性

typedef struct a20_xattr_list_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t handle;          /* 目标 handle */
    uint32_t _pad;
    uint64_t buf;                 /* char*:输出缓冲区,包含 nul-terminated 的名称列表 */
    uint64_t buf_len;             /* 缓冲区容量 */
    uint64_t out_len;             /* 输出:实际需要的总大小 */
} a20_xattr_list_args_t;

14. Scheduling 结构体

a20_sched_args_t — 调度参数

priority / policy / affinity / scheduler 等调度参数集中在一处。

/* 调度策略(task_set_sched / thread_create 使用) */
#define A20_SCHED_NORMAL    0
#define A20_SCHED_FIFO      1
#define A20_SCHED_RR        2

/* 调度标志 */
#define A20_SCHED_POLICY        (1u << 0)
#define A20_SCHED_PRIORITY      (1u << 1)
#define A20_SCHED_AFFINITY      (1u << 2)
#define A20_SCHED_NICE          (1u << 3)
/* task_set_sched-only:RT 优先级继承捐赠/恢复 */
#define A20_SCHED_DONATE        (1u << 4)
#define A20_SCHED_UNDONATE      (1u << 5)

typedef struct a20_sched_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t task;            /* 目标 task/thread handle */
    uint32_t flags;               /* 指定要设置/查询的字段 */
    int32_t  policy;              /* 调度策略 */
    int32_t  priority;            /* 静态优先级(1-99 for FIFO/RR) */
    int32_t  nice;                /* nice 值(-20..19 for OTHER) */
    uint64_t affinity;            /* CPU 亲和性位图 */
    uint64_t affinity_size;       /* 亲和性位图大小(字节) */
} a20_sched_args_t;

Linux 的 sched_setparam/sched_getparam/sched_setscheduler/sched_getscheduler/sched_setaffinity/sched_getaffinity/setpriority/getpriority/sched_setattr/sched_getattr 是 10 个独立 syscall,A20 收成 task_set_sched 与 task_get_sched 两个 syscall,通过 flags 组合指定要操作的调度参数。task_get_sched 复用同一个 args struct,由内核填充请求的字段。

A20_SCHED_DONATE/A20_SCHED_UNDONATE 是 task_set_sched 的内部操作:DONATE 把目标提升到至少 priority 并在首次捐赠时保存 base 策略/优先级/nice;priority 为 0 时使用调用者当前的有效 RT 优先级(链式捐赠);UNDONATE 恢复该快照。它们是内核 RT PI 的 ABI,不是普通应用设置优先级的方式。

task 为 A20_HANDLE_NULL 时表示调用者自己(仅 set/get;捐赠仍需要目标 handle)。没有创建者发放 handle 的初始线程可以调用 task_self 在自己的句柄表里安装一个,用于 PI 目标或跨线程查询。

sched_lock — per-task 调度器锁

int64_t sched_lock(int32_t mode, int32_t depth);

mode 为 A20_SCHED_LOCK_ACQUIRE(0) / RELEASE(1) / RESTORE(2),返回操作前的深度。它是 osKernelLock 的内核实现:深度非零时,syscall 返回点和 IRQ 返回点的抢占会被推迟,释放到 0 时立即消费 pending reschedule。它只推迟调度器抢占,不屏蔽中断。


15. Resource Limits 结构体

task_get_limits(task, out) / task_set_limits(task, in) 使用 abi/native/resource.h 中的聚合 a20_resource_limits_t(handles/channels/threads/memory 四个上限)。下述 a20_rlimit_args_t 是按 POSIX resource 编号细分的保留布局,当前 syscall 入口尚未使用它。

a20_rlimit_args_t — 资源限制

/* 资源类型 */
#define A20_RLIMIT_CPU       0    /* CPU 时间(秒) */
#define A20_RLIMIT_DATA      2    /* 数据段大小 */
#define A20_RLIMIT_STACK     3    /* 栈大小 */
#define A20_RLIMIT_CORE      4    /* core 文件大小 */
#define A20_RLIMIT_NOFILE    7    /* 打开文件/handle 数 */
#define A20_RLIMIT_AS        9    /* 地址空间大小 */
#define A20_RLIMIT_NICE     13    /* nice 优先级上限 */
#define A20_RLIMIT_RTPRIO   14    /* 实时优先级上限 */

typedef struct a20_rlimit_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t task;            /* 目标 task handle,A20_HANDLE_NULL 表示当前 task */
    uint32_t resource;            /* A20_RLIMIT_* */
    uint64_t cur;                 /* 当前软限制 */
    uint64_t max;                 /* 硬限制上限 */
} a20_rlimit_args_t;

a20_rusage_t — 资源使用量

typedef struct a20_rusage {
    uint64_t user_time_ns;        /* 用户态 CPU 时间 */
    uint64_t sys_time_ns;         /* 内核态 CPU 时间 */
    uint64_t max_rss;             /* 最大驻内存集大小 */
    uint64_t page_faults;         /* page fault 总数 */
    uint64_t io_read;             /* I/O 读取计数 */
    uint64_t io_write;            /* I/O 写入计数 */
} a20_rusage_t;

a20_rusage_t 是 syscall 输出载荷,不单独携带 {size, version};调用方通过对应查询 syscall 的 ABI 版本确定布局。


16. Extended Memory 结构体

a20_vm_remap_args_t — 内存重映射

/* remap 标志 */
#define A20_REMAP_MAY_MOVE     0x0001u   /* 允许内核移动映射到新地址 */
#define A20_REMAP_EXACT        0x0002u   /* 必须映射到指定地址 */

typedef struct a20_vm_remap_args {
    uint32_t size;
    uint32_t version;
    uint64_t old_addr;            /* 现有映射地址 */
    uint64_t old_size;            /* 现有映射大小 */
    uint64_t new_addr_hint;       /* 建议新地址 */
    uint64_t new_size;            /* 新大小 */
    uint32_t flags;               /* A20_REMAP_* */
    uint64_t out_addr;            /* 输出:实际映射地址 */
} a20_vm_remap_args_t;

a20_vm_object_args_t — 创建匿名内存对象

等价于 Linux memfd_create,但返回 A20 handle。

/* 内存对象标志 */
#define A20_VM_OBJ_CLOEXEC     0x0001u
#define A20_VM_OBJ_ALLOW_SEAL  0x0002u
#define A20_VM_OBJ_HUGETLB     0x0004u

typedef struct a20_vm_object_args {
    uint32_t size;
    uint32_t version;
    uint64_t size_bytes;          /* 初始大小 */
    uint32_t flags;               /* 当前实现传给 VMO options */
    a20_handle_t out_handle;      /* 输出:内存对象 handle */
} a20_vm_object_args_t;

创建的内存对象可通过 vm_map 映射到地址空间,通过 handle_dup、vm_share 或 channel 传递分享。flags 当前作为 VMO options 保存,但命名、seal、hugetlb 和用户态 resize 控制入口尚未实现;不能把相应 flag 名称视为完整功能。


17. Extended Filesystem 结构体

typedef struct a20_path_link_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t old_dir;         /* 源文件所在目录 handle */
    a20_handle_t new_dir;         /* 目标目录 handle */
    uint64_t old_path;            /* const char*:源文件路径 */
    uint32_t old_path_len;
    uint64_t new_path;            /* const char*:链接路径 */
    uint32_t new_path_len;
    uint32_t flags;               /* 保留 */
} a20_path_link_args_t;
typedef struct a20_path_symlink_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t dir;             /* 创建链接的父目录 handle */
    uint64_t target;              /* const char*:链接目标 */
    uint32_t target_len;
    uint64_t linkpath;            /* const char*:链接路径 */
    uint32_t linkpath_len;
} a20_path_symlink_args_t;
typedef struct a20_path_readlink_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t dir;             /* 父目录 handle */
    uint64_t path;                /* const char*:链接路径 */
    uint32_t path_len;
    uint64_t buf;                 /* char*:输出缓冲区 */
    uint64_t buf_len;             /* 缓冲区容量 */
    uint64_t out_len;             /* 输出:实际写入字节数 */
} a20_path_readlink_args_t;

a20_path_resolve_args_t — 路径解析

与 faccessat / readlinkat 对应的检查类操作集中到路径解析。

/* 解析标志 */
#define A20_RESOLVE_ACCESS     0x0000u   /* 检查可访问性(faccessat) */
#define A20_RESOLVE_EXISTS     0x0001u   /* 仅检查存在性 */
#define A20_RESOLVE_NOFOLLOW   0x0002u   /* 不跟随符号链接 */

typedef struct a20_path_resolve_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t dir;             /* 基目录 handle */
    uint64_t path;                /* const char*:目标路径 */
    uint64_t path_len;
    uint32_t flags;               /* A20_RESOLVE_* */
    uint32_t mode;                /* access 检查的模式(R_OK/W_OK/X_OK) */
    a20_handle_t out_handle;      /* 输出:解析后的 handle(可选) */
} a20_path_resolve_args_t;

a20_fs_stat_t — 文件系统统计

typedef struct a20_fs_stat {
    uint32_t size;
    uint32_t version;
    uint64_t total_blocks;        /* 总块数 */
    uint64_t free_blocks;         /* 空闲块数 */
    uint64_t available_blocks;    /* 非特权用户可用块数 */
    uint64_t total_files;         /* 总 inode 数 */
    uint64_t free_files;          /* 空闲 inode 数 */
    uint64_t block_size;          /* 块大小 */
    uint64_t max_name_len;        /* 最大文件名长度 */
    uint64_t fs_id;               /* 文件系统标识 */
    uint32_t fs_type;             /* 文件系统类型 */
    uint32_t flags;               /* 文件系统特性标志 */
} a20_fs_stat_t;

a20_dirent_t — 目录项

path_readdir 返回的目录项结构。内核将底层 vfs_dirent64 翻译为此格式。

typedef struct a20_dirent {
    uint32_t type;                /* 文件类型(VFS d_type) */
    uint32_t name_len;            /* 文件名实际长度 */
    char     name[256];           /* 以 NUL 结尾的文件名 */
} a20_dirent_t;

a20_fs_mount_args_t — 挂载文件系统

/* 挂载标志 */
#define A20_MOUNT_RDONLY       0x0001u
#define A20_MOUNT_NOSUID       0x0002u
#define A20_MOUNT_NODEV        0x0004u
#define A20_MOUNT_NOEXEC       0x0008u
#define A20_MOUNT_REMOUNT      0x0010u
#define A20_MOUNT_BIND         0x0020u

typedef struct a20_fs_mount_args {
    uint32_t size;
    uint32_t version;
    uint64_t source;              /* const char*:设备/源路径 */
    uint32_t source_len;
    uint32_t reserved0;
    uint64_t target;              /* const char*:挂载点路径 */
    uint32_t target_len;
    uint32_t reserved1;
    uint64_t fs_type;             /* const char*:文件系统类型名 */
    uint32_t fs_type_len;
    uint32_t flags;               /* A20_MOUNT_* */
} a20_fs_mount_args_t;

18. Extended Network 结构体

a20_net_socketpair_args_t — 创建套接字对

typedef struct a20_net_socketpair_args {
    uint32_t size;
    uint32_t version;
    uint32_t domain;              /* 地址族 */
    uint32_t type;                /* 套接字类型 */
    uint32_t protocol;            /* 协议 */
    uint32_t flags;
    a20_rights_t rights;          /* 两个端点的请求权限 */
    a20_handle_t out_socket0;     /* 输出:端点 0 */
    a20_handle_t out_socket1;     /* 输出:端点 1 */
} a20_net_socketpair_args_t;

net_getname 标志

#define A20_NET_NAME_LOCAL     0x0000u   /* 获取本地地址(getsockname) */
#define A20_NET_NAME_PEER      0x0001u   /* 获取对端地址(getpeername) */

19. Security Context 结构体

a20_security_context_t — 安全上下文

A20 的安全上下文同时支持原生 capability 模型和 POSIX 兼容身份。

/* 安全上下文标志 */
#define A20_SEC_SET_UID        0x0001u
#define A20_SEC_SET_GID        0x0002u
#define A20_SEC_SET_GROUPS     0x0004u
#define A20_SEC_SET_CAPS       0x0008u

/* POSIX 兼容能力位 */
#define A20_POSIX_CAP_CHOWN         0
#define A20_POSIX_CAP_DAC_OVERRIDE  1
#define A20_POSIX_CAP_DAC_READ_SEARCH 2
#define A20_POSIX_CAP_FOWNER        3
#define A20_POSIX_CAP_FSETID        4
#define A20_POSIX_CAP_KILL          5
#define A20_POSIX_CAP_SETGID        6
#define A20_POSIX_CAP_SETUID        7
#define A20_POSIX_CAP_SETPCAP       8
#define A20_POSIX_CAP_NET_BIND_SERVICE 9
#define A20_POSIX_CAP_NET_RAW       10
#define A20_POSIX_CAP_SYS_ADMIN     11

typedef struct a20_security_context {
    uint32_t size;
    uint32_t version;
    int32_t uid;
    int32_t euid;
    int32_t gid;
    int32_t egid;
    int32_t ngroups;
    int32_t _pad;
    uint64_t groups;              /* int[]:补充组 ID 数组 */
    uint64_t cap_effective;       /* POSIX capability 位图 */
    uint64_t namespace_mask;      /* 所属 namespace 掩码 */
    a20_rights_t effective_rights;/* 当前有效 rights 集合 */
    uint32_t flags;               /* A20_SEC_SET_*(set 时有效) */
    uint32_t label;               /* 0=L, 1=M, 2=H */
} a20_security_context_t;

security_get_context 查询当前完整的身份和权限状态,security_set_context 只修改 flags 指定的字段,作用类似 setuid/setgid/setgroups 的统一接口。修改 uid/gid 需要对应的 POSIX capability 或 A20 rights。A20 原生字段(effective_rights, namespace_mask)是只读的,由内核根据 handle 权限和 namespace 推导;label 只能上调。


20. System 结构体

a20_system_info_t — 系统信息

uname / sysinfo 的返回值合并到同一个结构体。

typedef struct a20_system_info {
    uint32_t size;
    uint32_t struct_version;
    /* uname 等价 */
    char     sysname[64];         /* 操作系统名 */
    char     nodename[64];        /* 网络节点名 */
    char     release[64];         /* 内核版本 */
    char     version[64];         /* 构建版本 */
    char     machine[64];         /* 硬件架构 */
    /* sysinfo 等价 */
    uint64_t total_ram;           /* 总物理内存 */
    uint64_t free_ram;            /* 空闲物理内存 */
    uint64_t total_swap;          /* 总交换空间 */
    uint64_t free_swap;           /* 空闲交换空间 */
    uint16_t num_procs;           /* 进程数 */
    uint16_t _pad;
    uint32_t configured_cpus;     /* 配置 CPU 数 */
    uint32_t online_cpus;         /* 在线 CPU 数 */
    uint32_t current_cpu;         /* 当前 CPU */
    uint32_t page_size;           /* 页大小 */
    uint64_t uptime_ns;           /* 系统运行时间(纳秒) */
} a20_system_info_t;

system_reboot 命令

#define A20_REBOOT_HALT        0   /* 停机 */
#define A20_REBOOT_POWER_OFF   1   /* 关电源 */
#define A20_REBOOT_RESTART     2   /* 重启 */
#define A20_REBOOT_RESTART2    3   /* 重启到指定模式(arg 指定) */

21. Event Watch FS 结构体

a20_event_watch_fs_args_t — 文件系统变更通知

/* 文件系统事件标志 */
#define A20_FS_EVENT_ACCESS     0x00000001u
#define A20_FS_EVENT_MODIFY     0x00000002u
#define A20_FS_EVENT_ATTRIB     0x00000004u
#define A20_FS_EVENT_CLOSE_WRITE 0x00000008u
#define A20_FS_EVENT_CLOSE_NOWRITE 0x00000010u
#define A20_FS_EVENT_OPEN       0x00000020u
#define A20_FS_EVENT_MOVED_FROM 0x00000040u
#define A20_FS_EVENT_MOVED_TO   0x00000080u
#define A20_FS_EVENT_CREATE     0x00000100u
#define A20_FS_EVENT_DELETE     0x00000200u
#define A20_FS_EVENT_DELETE_SELF 0x00000400u
#define A20_FS_EVENT_MOVE_SELF  0x00000800u

#define A20_FS_EVENT_ISDIR      0x40000000u   /* 事件发生在目录上 */

typedef struct a20_event_watch_fs_args {
    uint32_t size;
    uint32_t version;
    a20_handle_t queue;           /* 事件队列 handle */
    a20_handle_t dir;             /* 监控目录 handle */
    uint64_t path;                /* const char*:监控路径(相对于 dir) */
    uint32_t path_len;
    uint32_t event_mask;          /* A20_FS_EVENT_* 组合 */
    uint64_t user_data;           /* 事件关联数据 */
} a20_event_watch_fs_args_t;

Linux 的 inotify_init/inotify_add_watch/inotify_rm_watch 是独立于 epoll 的子系统;A20 把文件系统事件**统一纳入现有 event_queue 框架**,event_watch_fs 向已有事件队列注册文件系统关注。目标实现要求变更事件通过 event_wait 返回 a20_pending_event_t。当前实现仅把 dir 注册为普通 watch 目标,路径过滤与 VFS 事件源尚未实现,所以本结构体目前是最小占位契约。取消关注用 event_cancel(queue, dir),当前没有独立 out_watch handle。


22. Sync 结构体

futex 是**用户地址上的同步原语,不是内核对象**,因此不分配 handle、不携带 rights。这与 Zircon zx_futex_wait/zx_futex_wake 的定位一致:支持用户硬件原子的 profile 可以在无竞争路径使用原子指令;通用应用也可使用 Native atomic32 系统调用。

早期草案(startup.md §4.4.4)曾考虑用 event_queue 承担互斥等待,但 event_queue 缺少"投递事件到队列"的用户语义,且每个竞争锁都需要一个内核 handle,成本与语义都不合适,Sync 分区因此回归地址型 futex。无竞争路径可使用用户态 CAS;跨 MCU 的通用路径使用 atomic32,不以性能作为首轮目标。慢路径通过 futex_wait/futex_wake 进入内核,复用内核 futex 等待表。跨进程共享内存(vm_share 导出的 VMO)上的 futex 字同样有效,等待键同时匹配虚拟地址与物理页。

#define A20_TIMEOUT_INFINITE  ((uint64_t)-1)  /* futex_wait 无限等待 */

typedef struct a20_futex_wait_args {
    uint32_t size;
    uint32_t version;
    uint64_t addr;          /* 用户态 32 位 futex 字地址,必须 4 字节对齐 */
    uint32_t expected;      /* 期望值;*addr != expected 时立即返回 A20_ERR_WOULD_BLOCK */
    uint32_t flags;         /* 保留,必须为 0 */
    uint64_t timeout_ns;    /* 相对超时(纳秒),A20_TIMEOUT_INFINITE 表示无限等待 */
} a20_futex_wait_args_t;

typedef struct a20_futex_wake_args {
    uint32_t size;
    uint32_t version;
    uint64_t addr;          /* 用户态 32 位 futex 字地址 */
    uint32_t count;         /* 最多唤醒的等待者数量,必须 >= 1 */
    uint32_t flags;         /* 保留,必须为 0 */
    uint32_t out_woken;     /* 输出:实际唤醒数量 */
    uint32_t reserved;
} a20_futex_wake_args_t;

错误映射:A20_ERR_WOULD_BLOCK(值不匹配)、A20_ERR_TIMED_OUT(超时)、A20_ERR_FAULT(地址无效)、A20_ERR_INVALID_ARGUMENT(对齐/flag 错误)、A20_ERR_INTERRUPTED(被中断)。

能力发现:abi_info.feature_bits[0] 的 bit 2 表示 Sync (0x0B00) 分区可用。

atomic32(0x0B02)使用以下固定 40 B 结构,所有操作均顺序一致; LOAD=0、STORE=1、EXCHANGE=2、COMPARE_EXCHANGE=3。

typedef struct a20_atomic32_args {
    uint32_t size, version;
    uint64_t addr;
    uint32_t operation, expected, desired, flags;
    uint32_t observed, exchanged;
} a20_atomic32_args_t;

observed 是观察到的旧值,CAS 成功时 exchanged=1,其他情况为 0。abi_info.feature_bits[0] bit 3 与 execution_info 的 ATOMIC32 位分别公布接口可用性。地址权限、超时与副作用错误语义及跨平台实现见公共应用同步。

abi_info.feature_bits[0] bit 4(A20_ABI_FEATURE_LINUX_EXEC)表示当前 BOTH 构建提供 Native 根任务通过 exec 替换为 Linux ABI 程序的能力,feature_test(4) 返回 0;纯 Native 返回 NOT_SUPPORTED。该索引与execution_info 位图分开编号。使用与生命周期见统一应用执行。