Skip to content

Translation pending. This page is currently available in Chinese.

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 中标记新增。