Zircon 系统接口评分准则

Zircon 系统接口表示为 libzircon.so vDSO API Surface。

属于接口的函数必须具有以 zx_ 开头的名称 和预处理器宏的名称必须以 ZX_ 开头。类型定义为 接口的一部分的名称必须以 zx_ 开头，以 _t 结尾。

接口中的每个函数都必须以 Markdown 格式记录 文件（位于 /docs/zircon/syscalls/）中， 链接自 /docs/zircon/syscalls.md。

函数名称

函数的名称必须完全由小写字母和 并且符合以下语法：

zx_<noun>_<verb>{_<direct-object>}

例如：

zx_handle_close, zx_channel_write, zx_object_signal_peer

通常，名词是内核对象类型，但也可以是其他名词，例如 clock 或 ticks，并且没有对应的内核对象。其他 函数使用更抽象的名词，例如 system 或 status。

名词和动词不得包含下划线（以免混淆 语法）。名词和动词都应是单个英文单词，但使用首字母缩略词（或者 缩写）。

直接对象可以包含下划线。

一些函数执行复合操作。在这种情况下，函数可能 通过串联组件操作的名称来命名。

有些函数对多种类型的内核对象运行，在这种情况下，名词是 是一种更为抽象的对象类型。例如，带有名词 object 的函数 可作用于大多数内核对象和函数，使用名词 task 作用于 作业、进程和线程

类型

使用 zx_status_t 表示成功和失败。

使用固定大小的整数类型。函数不得使用 short、int 或 unsigned long（或类似类型）。请改用 int16_t、 int32_t和uint64_t。

针对缓冲区长度、元素大小和元素计数使用 size_t。

使用 void* 可指向调用方地址空间中任意类型的指针。使用 zx_vaddr_t / zx_paddr_t（适用于可能位于其他地址空间的地址）。

为超时使用 zx_time_t，它必须表示为 以纳秒为单位的单调时钟时基。在以下情况 设置绝对截止时间没有意义（例如，计时器延迟），请使用 zx_duration_t 表示以纳秒为单位的时间量，没有具体的 时基。

参数

接收器

绝大多数函数都处理句柄，句柄是对内核的引用 对象（其类型与函数名称中的 noun 匹配）。此标识名是 这些函数的第一个参数称为接收器。

为接收器使用名称 handle。

对象创建函数（例如 zx_channel_create、zx_event_create）不能 接受一个句柄参数。这些函数隐式地对当前数据集运行 过程。

选项参数

函数通常包含一个 options 参数，允许使用影响 操作，并留出空间，以便将更多标记添加到未来 修订版本

为 options 参数使用类型 uint32_t 和名称 options。

如果存在，options 形参必须是 接收器句柄或总体的第一个参数（如果函数没有 接收器。

并非所有函数都需要 options 参数。

各个选项值必须定义为预处理器宏， 数字字面量转换为 uint32_t。选项必须是位标志，可以 使用按位 | 运算符合并。

句柄

如果某个函数被赋予了句柄作为参数，该函数必须 始终使用相应句柄或从不使用，但以下情况除外：

  • 如果该函数接受 options 形参，则其可能具有 非默认选项，以避免在各种错误情况下使用句柄。

  • 如果该函数不接受 options 形参，则可以避免 使用方处理是否返回 ZX_ERR_SHOULD_WAIT。

包含数据、计数/大小和/或实际值的缓冲区

始终伴随有计数或大小（类型为 size_t）的数组或缓冲区， 包括字符串。如果函数写入缓冲区，则该函数必须 具有一个 out 参数，该参数可返回所写入数据的数量或大小。

对于读写样式的操作，指向缓冲区的指针为 然后是缓冲区计数或大小，以及如果短时间读取或写入 可能，out 参数提供成功时的实际计数或大小：

zx_status_t zx_socket_write(zx_handle_t handle, uint32_t options,
                            const void* buffer, size_t size, size_t* actual);

如果有多个缓冲区，则会显示缓冲区、长度和输出参数。 以便按照一致的顺序交错显示例如，请参阅 zx_channel_read：

zx_status_t zx_channel_read(zx_handle_t handle, uint32_t options,
                            void* bytes, zx_handle_t* handles,
                            uint32_t num_bytes, uint32_t num_handles,
                            uint32_t* actual_bytes, uint32_t* actual_handles);

输出

out 参数是由函数写入的标量值。例如， 该函数通过写入 uint32_t 来返回 CPU 数量，该函数有一个输出 参数。如果该函数填充客户端提供的缓冲区，则该缓冲区 不是一个输出参数。

输出参数始终位于参数列表的末尾。

out 参数不能同时是 in 参数。例如，如果一个函数 有一个 out 参数，它通过该参数返回 缓冲区，则该函数不得同时使用该参数来接收 缓冲区的长度。

返回值类型

绝大多数函数的返回值类型为 zx_status_t， 成功时为 ZX_OK，失败时为 ZX_ERR_...。

不要通过 zx_status_t 返回其他值，例如使用 正值范围。而应使用 out 参数。

其他返回值类型可用于不会失败的函数。例如： zx_thread_exit 始终无法退出线程且返回类型为 void。 同样，zx_clock_get_monotonic 也无法获取当前时间， zx_time_t 的返回值类型。

特定于函数的规则

zx_object_get_property 与 zx_object_get_info

您可以通过两种类似的机制公开对象的相关数据： zx_object_get_property和zx_object_get_info。最好通过 zx_object_get_property如果 (a) 可以使用 zx_object_set_property，或者 (b) 该媒体资源存在于多种类型的 对象的操作。在其他情况下，请考虑将数据 zx_object_get_info 主题。