A20OS Native ABI:错误码与返回约定¶
本文档定义 Native ABI 的统一错误码体系、返回值约定及向 POSIX errno 的映射规则。
1. 返回值约定¶
所有 native syscall 返回 a20_status_t(int64_t):
>= 0 成功。具体含义视 syscall 而定:
- 大部分操作返回 0 表示成功
- 某些操作返回非负值(如 handle 编号,通过 out 字段返回)
< 0 错误。返回值为 -A20_ERR_* 的负数形式
Native ABI 的错误码不要求等于 Linux errno。兼容层可以在 libc 或 shim 中映射到 POSIX errno。
2. 错误码定义¶
#define A20_OK 0 /* 成功 */
#define A20_ERR_PERM 1 /* 权限不足(非 handle rights,而是 UID/GID 等) */
#define A20_ERR_NO_ENTRY 2 /* 路径组件不存在 */
#define A20_ERR_INTERRUPTED 3 /* 操作被信号中断 */
#define A20_ERR_IO 4 /* I/O 错误 */
#define A20_ERR_BAD_HANDLE 5 /* handle 无效或已关闭 */
#define A20_ERR_NO_MEMORY 6 /* 内存不足 */
#define A20_ERR_ACCESS 7 /* handle rights 不足 */
#define A20_ERR_FAULT 8 /* 用户指针无效 */
#define A20_ERR_BUSY 9 /* 资源忙(如 channel 满) */
#define A20_ERR_EXISTS 10 /* 文件已存在 */
#define A20_ERR_NOT_SUPPORTED 11 /* 操作不支持 */
#define A20_ERR_INVALID_ARGUMENT 12 /* 参数无效(含保留位非零) */
#define A20_ERR_NO_SPACE 13 /* handle table 满或磁盘满 */
#define A20_ERR_NOT_DIR 14 /* 路径中非目录组件 */
#define A20_ERR_IS_DIR 15 /* 期望文件但得到目录 */
#define A20_ERR_NOT_EMPTY 16 /* 目录非空 */
#define A20_ERR_NAME_TOO_LONG 17 /* 文件名过长 */
#define A20_ERR_WOULD_BLOCK 18 /* 非阻塞操作无法立即完成 */
#define A20_ERR_TIMED_OUT 19 /* 操作超时 */
#define A20_ERR_CANCELED 20 /* 操作被取消 */
#define A20_ERR_PROTOCOL 21 /* 协议错误 */
#define A20_ERR_RANGE 22 /* 参数超出范围 */
#define A20_ERR_TYPE_MISMATCH 23 /* typed channel 的 handle 类型/大小越界 */
#define A20_ERR_NOT_FOUND 24 /* 对象未找到(如 event_cancel 的 target) */
#define A20_ERR_EXPIRED 25 /* 时态能力已过期(访问 EXPIRED 状态的 handle) */
#define A20_ERR_NODE_UNREACHABLE 26 /* 集群:无路由、链路 DOWN、TTL 耗尽、未 set_self */
#define A20_ERR_CLUSTER_TIMEOUT 27 /* 集群:远程 CALL 超 deadline / 建链超时 */
#define A20_ERR_REMOTE_CLOSED 28 /* 集群:对端端点已关闭 */
#define A20_ERR_CLUSTER_UNSUPPORTED 29 /* 集群:跨机 handle/捐赠、MCU 分片/广播、HELLO 哈希冲突 */
#define A20_ERR_BROKEN_PIPE 30
#define A20_ERR_NOT_SOCKET 31
#define A20_ERR_PROTOCOL_OPTION 32
#define A20_ERR_ADDRESS_IN_USE 33
#define A20_ERR_ADDRESS_NOT_AVAILABLE 34
#define A20_ERR_CONNECTION_REFUSED 35
#define A20_ERR_CONNECTION_RESET 36
#define A20_ERR_NOT_CONNECTED 37
#define A20_ERR_ALREADY_CONNECTED 38
#define A20_ERR_IN_PROGRESS 39
#define A20_ERR_ALREADY_IN_PROGRESS 40
#define A20_ERR_NETWORK_UNREACHABLE 41
#define A20_ERR_HOST_UNREACHABLE 42
#define A20_ERR_MESSAGE_TOO_LARGE 43
#define A20_ERR_ILLEGAL_SEEK 44
#define A20_ERR_NOT_TERMINAL 45
#define A20_ERR_OVERFLOW 46
#define A20_ERR_NO_LOCKS 47
#define A20_ERR_DEADLOCK 48
26–29 是集群子系统追加的四个码(docs/zh/cluster/01-abi.md)。每个码只对应一个触发场景,禁止混用,这样远端失败才能无歧义地映射回原因。
30–48 为 Native 1.1 新增的对象/网络/范围状态,仍使用 A20 自己的编号。 Linux errno 只在 libc 映射;新增细分错误的旧调用者处理规则见运行时扩展 §2。
3. 错误码分类¶
3.1 权限类¶
| 错误码 | 触发场景 |
|---|---|
A20_ERR_PERM |
UID/GID 权限不足(如 kill 其他用户的进程) |
A20_ERR_ACCESS |
handle rights 不足(如对只读 handle 执行 write) |
两者区分:PERM 是传统 POSIX 权限问题,ACCESS 是 capability rights 问题。Native ABI 中大部分权限检查使用 ACCESS。
3.2 Handle 类¶
| 错误码 | 触发场景 |
|---|---|
A20_ERR_BAD_HANDLE |
handle 编号超出范围、已关闭、或 entry 为空 |
A20_ERR_NO_SPACE |
handle table 达到当前 task 配额(默认 4096,可配置但绝对容量上限为 65536),或接收消息时无法一次预留全部 handle |
3.3 参数类¶
| 错误码 | 触发场景 |
|---|---|
A20_ERR_INVALID_ARGUMENT |
参数值非法、flag 保留位非零、结构体 version 未知 |
A20_ERR_FAULT |
用户态指针指向无效地址 |
A20_ERR_RANGE |
offset/size 超出合法范围 |
3.4 资源类¶
| 错误码 | 触发场景 |
|---|---|
A20_ERR_NO_MEMORY |
内核内存分配失败 |
A20_ERR_NO_ENTRY |
文件/目录不存在 |
A20_ERR_EXISTS |
创建文件但已存在 |
A20_ERR_BUSY |
对象处于显式 busy 状态;channel 满在阻塞模式等待、在 nonblock 模式返回 WOULD_BLOCK,普通锁竞争不会直接暴露为该错误 |
3.5 I/O 类¶
| 错误码 | 触发场景 |
|---|---|
A20_ERR_IO |
磁盘/设备 I/O 错误 |
A20_ERR_INTERRUPTED |
阻塞操作被中断 |
A20_ERR_WOULD_BLOCK |
非阻塞模式下的 EAGAIN 等价 |
A20_ERR_TIMED_OUT |
超时到期 |
A20_ERR_CANCELED |
操作被显式取消 |
3.6 协议类¶
| 错误码 | 触发场景 |
|---|---|
A20_ERR_PROTOCOL |
网络协议错误、channel 协议违反 |
A20_ERR_NOT_SUPPORTED |
操作不被当前对象类型支持 |
A20_ERR_CLUSTER_UNSUPPORTED |
集群:请求的跨机语义在 v0 不支持(handle 传递、时间片捐赠、MCU 档分片/广播、RELIABLE 协商失败) |
3.7 集群类¶
| 错误码 | 触发场景 |
|---|---|
A20_ERR_NODE_UNREACHABLE |
目标节点无路由、链路判定 DOWN、TTL 耗尽,或本节点尚未 cluster_set_self |
A20_ERR_CLUSTER_TIMEOUT |
远程 channel_call 超过 deadline,或建链超时 |
A20_ERR_REMOTE_CLOSED |
收到对端 CLOSE,或已知对端句柄已释放 |
4. 错误处理策略¶
4.1 原子性保证¶
对声明为原子的管理操作,返回错误后应保持可重试且不留下半安装对象。这是目标契约,不泛化到所有 I/O syscall。
I/O、批量操作以及 A20_ERR_INTERRUPTED/A20_ERR_TIMED_OUT 可能部分完成,应通过 out_count 等输出字段判断。各 syscall 的具体提交点以对应子系统文档和实现为准。
4.2 与 POSIX errno 的映射¶
兼容层(POSIX shim)需要将 native 错误码映射到 POSIX errno:
A20_OK → 0 (no error)
A20_ERR_PERM → EPERM
A20_ERR_NO_ENTRY → ENOENT
A20_ERR_INTERRUPTED → EINTR
A20_ERR_IO → EIO
A20_ERR_BAD_HANDLE → EBADF
A20_ERR_NO_MEMORY → ENOMEM
A20_ERR_ACCESS → EACCES
A20_ERR_FAULT → EFAULT
A20_ERR_BUSY → EBUSY
A20_ERR_EXISTS → EEXIST
A20_ERR_NOT_SUPPORTED → ENOSYS
A20_ERR_INVALID_ARGUMENT → EINVAL
A20_ERR_NO_SPACE → ENOSPC
A20_ERR_NOT_DIR → ENOTDIR
A20_ERR_IS_DIR → EISDIR
A20_ERR_NOT_EMPTY → ENOTEMPTY
A20_ERR_NAME_TOO_LONG → ENAMETOOLONG
A20_ERR_WOULD_BLOCK → EAGAIN / EWOULDBLOCK
A20_ERR_TIMED_OUT → ETIMEDOUT
A20_ERR_CANCELED → ECANCELED
A20_ERR_PROTOCOL → EPROTO
A20_ERR_RANGE → ERANGE
四个集群码(26–29)在 POSIX 兼容层没有对应项,v0 不映射:A20_ERR_NODE_UNREACHABLE 与 ENETUNREACH 语义相近但触发条件更宽,A20_ERR_REMOTE_CLOSED 无 POSIX 对应。兼容层应原样透传而非折叠成通用码,否则调用方无法区分本机语义与远程语义。
4.3 扩展规则¶
新错误码只能追加,已定义错误码的语义不能改变。现有语义过于宽泛时,应定义新错误码并在 abi_minor 中标记新增。