跳转到内容
标准库Zig 0.17.0官方原文
源码std/Build/abi.zig

第 1 行

此文件由运行于截然不同环境的 Zig 代码共享:

  • 在主机计算机上运行的构建运行器。
  • 在浏览器中运行的构建系统网页界面 Wasm 代码。
  • 与单元测试一起编译的 libfuzzer。

这些组件都在某种程度上通过 ABI 交互:

  • 构建运行器通过 WebSocket 连接与网页界面通信。
  • 构建运行器通过共享内存映射文件与 libfuzzer 通信。

std.Build.abi.BuildStatus

容器

第 73 行

构建运行器当前的整体状态。 与 Web 界面 main.js:updateBuildStatus 中的索引保持同步。

字段

idle
watching
running
fuzz_init

std.Build.abi.check

函数

第 16 行

fn check(comptime T: type) void

参数

T: type

std.Build.abi.fuzz

命名空间

第 141 行

专门涉及模糊测试器接口的 ABI 部分。

std.Build.abi.fuzz.Coverage

容器

第 431 行

由 lib/fuzzer 发送给 test_runner,用于获取 当前内存映射输入文件的信息,以及先前 模糊测试运行的累计统计信息。

字段

id: u64
runs: u64
unique: u64
seen: u64

std.Build.abi.fuzz.CoverageUpdateHeader

容器

第 399 行

WebSocket 服务器到客户端。

每当已覆盖源码位置集合更新时发送。

尾随:

  • 每个 source_locations_len 对应一位,存储在 u64 元素中。

字段

tag: ToClientTag = .fuzz_coverage_update
_: [7]u8 = @splat(0)
n_runs: u64
unique_runs: u64

std.Build.abi.fuzz.CoverageUpdateHeader.trailing

常量

第 405 行

std.Build.abi.fuzz.EntryPointHeader

容器

第 416 行

WebSocket 服务器->客户端。

每当入口点集合更新时发送。

尾随内容:

  • 每个 locsLen() 对应一个 source_locations 的 u32 索引

字段

tag: ToClientTag = .fuzz_entry_points
locs_len_raw: [3]u8

std.Build.abi.fuzz.EntryPointHeader.init

函数

第 423 行

pub fn init(locs_len: u24) EntryPointHeader

参数

locs_len: u24

std.Build.abi.fuzz.EntryPointHeader.locsLen

函数

第 420 行

pub fn locsLen(hdr: EntryPointHeader) u24

参数

std.Build.abi.fuzz.fuzzer_bytes

函数

第 201 行

pub extern fn fuzzer_bytes(uid: Uid, out: MutSlice, weights: Weights) void

参数

uid: Uid
out: MutSlice
weights: Weights

std.Build.abi.fuzz.fuzzer_coverage

函数

第 164 行

必须先调用 fuzzer_init。

pub extern fn fuzzer_coverage() Coverage

std.Build.abi.fuzz.fuzzer_eos

函数

第 200 行

pub extern fn fuzzer_eos(uid: Uid, weights: Weights) bool

参数

uid: Uid
weights: Weights

std.Build.abi.fuzz.fuzzer_init

函数

第 162 行

pub extern fn fuzzer_init(cache_dir_path: Slice) void

参数

cache_dir_path: Slice

std.Build.abi.fuzz.fuzzer_int

函数

第 199 行

pub extern fn fuzzer_int(uid: Uid, weights: Weights) u64

参数

uid: Uid
weights: Weights

std.Build.abi.fuzz.fuzzer_main

函数

第 170 行

执行全部模糊测试工作,并选择要运行的测试。

必须先调用 fuzzer_init。

pub extern fn fuzzer_main( n_tests: u32, seed: u32, limit_kind: LimitKind, amount_or_instance: u64, ) void

参数

n_tests: u32
seed: u32
limit_kind: LimitKind
amount_or_instance: u64

std.Build.abi.fuzz.fuzzer_new_input

函数

第 195 行

必须从测试函数内部调用,且该测试函数须先调用 fuzzer_set_test。

pub extern fn fuzzer_new_input(bytes: Slice) void

参数

bytes: Slice

std.Build.abi.fuzz.fuzzer_receive_input

函数

第 190 行

必须先调用 fuzzer_main。

与 fuzzer_main 并发调用。若已请求取消则返回。

pub extern fn fuzzer_receive_input(test_i: u32, bytes: Slice) bool

参数

test_i: u32
bytes: Slice

std.Build.abi.fuzz.fuzzer_set_test

函数

第 193 行

必须在测试函数内调用

pub extern fn fuzzer_set_test(test_one: TestOne) void

参数

test_one: TestOne

std.Build.abi.fuzz.fuzzer_slice

函数

第 202 行

pub extern fn fuzzer_slice( uid: Uid, buf: MutSlice, len_weights: Weights, byte_weights: Weights, ) u32

参数

uid: Uid
buf: MutSlice
len_weights: Weights
byte_weights: Weights

std.Build.abi.fuzz.fuzzer_start_test

函数

第 197 行

必须从测试函数内部调用,且该测试函数须先调用 fuzzer_set_test。

pub extern fn fuzzer_start_test() void

std.Build.abi.fuzz.fuzzer_unslide_address

函数

第 165 行

pub extern fn fuzzer_unslide_address(addr: usize) usize

参数

addr: usize

std.Build.abi.fuzz.LimitKind

容器

第 323 行

字段

forever
iterations

std.Build.abi.fuzz.MmapInputHeader

容器

第 365 行

字段采用小端序

字段

pc_digest: u64 align(4)
instance_id: u32
test_i: u32
len: u32

std.Build.abi.fuzz.MutSlice

容器

第 222 行

字段

ptr: [*]u8
len: usize

std.Build.abi.fuzz.MutSlice.fromSlice

函数

第 230 行

pub fn fromSlice(s: []u8) MutSlice

参数

s: []u8

std.Build.abi.fuzz.MutSlice.toSlice

函数

第 226 行

pub fn toSlice(s: MutSlice) []u8

参数

std.Build.abi.fuzz.runner_broadcast_input

函数

第 186 行

pub extern fn runner_broadcast_input(test_i: u32, bytes: Slice) void

参数

test_i: u32
bytes: Slice

std.Build.abi.fuzz.runner_futex_wait

函数

第 184 行

返回是否已发出取消信号。

pub extern fn runner_futex_wait(*const u32, expected: u32) bool

参数

runner_futex_wait: *const u32
expected: u32

std.Build.abi.fuzz.runner_futex_wake

函数

第 185 行

pub extern fn runner_futex_wake(*const u32, waiters: u32) void

参数

runner_futex_wake: *const u32
waiters: u32

std.Build.abi.fuzz.runner_start_input_poller

函数

第 181 行

pub extern fn runner_start_input_poller() void

std.Build.abi.fuzz.runner_stop_input_poller

函数

第 182 行

pub extern fn runner_stop_input_poller() void

std.Build.abi.fuzz.runner_test_name

函数

第 177 行

pub extern fn runner_test_name(i: u32) Slice

参数

i: u32

std.Build.abi.fuzz.runner_test_run

函数

第 176 行

pub extern fn runner_test_run(i: u32) void

参数

i: u32

std.Build.abi.fuzz.SeenPcsHeader

容器

第 331 行

libfuzzer 使用此项,并以其 usize 作为计数值。为匹配 ABI, 将整数设为与 libfuzzer 所用目标相同的大小。

尾随数据:

  • 每个 pc_addr 对应 1 位,元素类型为 usize
  • 每个 pcs_len 对应一个 usize 的 pc_addr

字段

n_runs: usize
unique_runs: usize
pcs_len: usize

std.Build.abi.fuzz.SeenPcsHeader.headerEnd

函数

第 343 行

pub fn headerEnd(header: *const SeenPcsHeader) []const usize

参数

header: *const SeenPcsHeader

std.Build.abi.fuzz.SeenPcsHeader.pcAddrs

函数

第 358 行

pub fn pcAddrs(header: *const SeenPcsHeader) []const usize

参数

header: *const SeenPcsHeader

std.Build.abi.fuzz.SeenPcsHeader.seenBits

函数

第 350 行

pub fn seenBits(header: *const SeenPcsHeader) []const usize

参数

header: *const SeenPcsHeader

std.Build.abi.fuzz.SeenPcsHeader.seenElemsLen

函数

第 354 行

pub fn seenElemsLen(pcs_len: usize) usize

参数

pcs_len: usize

std.Build.abi.fuzz.SeenPcsHeader.trailing

常量

第 338 行

用于编译期断言。提供一种在指定位置 触发编译错误的机制。

std.Build.abi.fuzz.Slice

容器

第 209 行

字段

ptr: [*]const u8
len: usize

std.Build.abi.fuzz.Slice.fromSlice

函数

第 217 行

pub fn fromSlice(s: []const u8) Slice

参数

s: []const u8

std.Build.abi.fuzz.Slice.toSlice

函数

第 213 行

pub fn toSlice(s: Slice) []const u8

参数

s: Slice

std.Build.abi.fuzz.SourceIndexHeader

容器

第 381 行

WebSocket 服务端->客户端。

在模糊测试开始时发送一次,用于指示可用的覆盖率数据。

尾随内容:

  • directories_len 个 std.debug.Coverage.String
  • files_len 个 std.debug.Coverage.File
  • source_locations_len 个 std.debug.Coverage.SourceLocation
  • string_bytes_len 个 u8

字段

tag: ToClientTag = .fuzz_source_index
_: [3]u8 = @splat(0)
directories_len: u32
files_len: u32
source_locations_len: u32
string_bytes_len: u32
start_timestamp: i64 align(4)

根据服务器记录的模糊测试开始时间。

start_n_runs: u64 align(4)

std.Build.abi.fuzz.TestOne

类型

第 143 行

返回是否指示了 error.SkipZigTest

std.Build.abi.fuzz.Uid

容器

第 146 行

用于跨运行识别相关请求的唯一值

字段

kind: enum(u1) { int, bytes }
hash: u31

std.Build.abi.fuzz.Uid.hashmap_ctx

命名空间

第 150 行

std.Build.abi.fuzz.Uid.hashmap_ctx.eql

函数

第 156 行

pub fn eql(_: @This(), a: Uid, b: Uid, _: usize) bool

参数

_: @This()
a: Uid
b: Uid
_: usize

std.Build.abi.fuzz.Uid.hashmap_ctx.hash

函数

第 151 行

pub fn hash(_: @This(), u: Uid) u32

参数

_: @This()
u: Uid

std.Build.abi.fuzz.Weight

容器

第 255 行

提高这些值被模糊测试器选中的概率。

weight 应用于范围内每个值,而非均匀分摊至 整个范围,且必须非零。

一组权重的总和不得超过 2^64,且 必须非零。

字段

min: u64

包含端点

max: u64

包含端点

weight: u64

std.Build.abi.fuzz.Weight.intFromValue

函数

第 263 行

使用 inline 传播编译期性

inline fn intFromValue(x: anytype) u64

std.Build.abi.fuzz.Weight.rangeAtMost

函数

第 303 行

使用 inline 传播编译期性

pub inline fn rangeAtMost(T: type, at_least: T, at_most: T, weight: u64) Weight

参数

T: type
at_least: T
at_most: T
weight: u64

std.Build.abi.fuzz.Weight.rangeLessThan

函数

第 313 行

使用 inline 传播编译期性

pub inline fn rangeLessThan(T: type, at_least: T, less_than: T, weight: u64) Weight

参数

T: type
at_least: T
less_than: T
weight: u64

std.Build.abi.fuzz.Weight.value

函数

第 298 行

使用 inline 传播编译期性

pub inline fn value(T: type, x: T, weight: u64) Weight

参数

T: type
x: T
weight: u64

std.Build.abi.fuzz.Weights

容器

第 235 行

字段

ptr: [*]const Weight
len: usize

std.Build.abi.fuzz.Weights.fromSlice

函数

第 243 行

pub fn fromSlice(s: []const Weight) Weights

参数

s: []const Weight

std.Build.abi.fuzz.Weights.toSlice

函数

第 239 行

pub fn toSlice(s: Weights) []const Weight

参数

s: Weights

std.Build.abi.Hello

容器

第 89 行

WebSocket:服务器到客户端。

WebSocket 连接打开后,服务器发送的第一条消息,提供 服务器、构建图等基本信息。

尾随数据:

  • step_name_len: u32,每个 steps_len 对应一个;
  • step_name: [step_name_len]u8,每个 step_name_len 对应一个;
  • step_status: u8,每四个 steps_len 对应一个;每两位表示一个 StepUpdate.Status,最低有效位优先。

字段

tag: ToClientTag = .hello
status: BuildStatus
flags: Flags
timestamp: i64 align(4)

凡消息含有时间戳,均以自构建开始以来的纳秒数表示。 此字段为采用该形式表示的当前时间戳。

steps_len: u32 align(1)

构建图中从正在运行的顶层步骤可达的步骤数; 即本次构建将执行的步骤总数。 此消息后附各步骤的名称。

std.Build.abi.Hello.Flags

容器

第 104 行

字段

time_report: bool

是否启用时间报告。

_: u15 = 0

std.Build.abi.Rebuild

容器

第 136 行

字段

tag: ToServerTag = .rebuild

std.Build.abi.StatusUpdate

容器

第 113 行

WebSocket 服务器到客户端。

表示构建状态已更改。

字段

tag: ToClientTag = .status_update
new: BuildStatus

std.Build.abi.std

别名

第 9 行

别名目标 std

std.Build.abi.StepUpdate

容器

第 120 行

WebSocket 服务器到客户端。

表示步骤状态发生变化。

字段

tag: ToClientTag = .step_update
step_idx: u32 align(1)
bits: packed struct(u8) {
    status: Status,
    _: u6 = 0,
}

std.Build.abi.StepUpdate.Status

容器

第 128 行

与网页界面 main.js:updateStepStatus 中的索引保持同步。

字段

pending
wip
success
failure

std.Build.abi.time_report

命名空间

第 440 行

专门涉及时间报告接口的 ABI 部分。

std.Build.abi.time_report.CompileResult

容器

第 464 行

WebSocket 服务器到客户端消息。

Step.Compile 完成后发送,提供该步骤的时间报告。

尾随内容:

  • llvm_pass_timings: [llvm_pass_timings_len]u8(ASCII 编码)
  • 每个 files_len 对应:
    • name(以空字符结尾的 UTF-8 字符串)
  • 每个 decls_len 对应:
    • name(以空字符结尾的 UTF-8 字符串)
    • file: u32(此声明所在文件的索引)
    • sema_ns: u64(对此声明进行语义分析所用的纳秒数)
    • codegen_ns: u64(对此声明进行语义分析所用的纳秒数)
    • link_ns: u64(对此声明进行语义分析所用的纳秒数)

字段

tag: ToClientTag = .time_report_compile_result
step_idx: u32 align(1)
flags: Flags
stats: Stats align(1)
ns_total: u64 align(1)
llvm_pass_timings_len: u32 align(1)
files_len: u32 align(1)
decls_len: u32 align(1)

std.Build.abi.time_report.CompileResult.Flags

容器

第 477 行

字段

use_llvm: bool
_: u7 = 0

std.Build.abi.time_report.CompileResult.Stats

容器

第 482 行

字段

n_reachable_files: u32
n_imported_files: u32
n_generic_instances: u32
n_inline_calls: u32
cpu_ns_parse: u64
cpu_ns_astgen: u64
cpu_ns_sema: u64
cpu_ns_codegen: u64
cpu_ns_link: u64
real_ns_files: u64
real_ns_decls: u64
real_ns_llvm_emit: u64
real_ns_link_flush: u64

std.Build.abi.time_report.CompileResult.Stats.init

常量

第 499 行

Stats

std.Build.abi.time_report.GenericResult

容器

第 444 行

WebSocket 服务器->客户端。

在 Step 完成后发送,提供该步骤的执行耗时。

字段

tag: ToClientTag = .time_report_generic_result
step_idx: u32 align(1)
ns_total: u64 align(1)

std.Build.abi.time_report.RunTestResult

容器

第 526 行

WebSocket:服务器到客户端。

Zig 测试可执行文件的 Step.Run 完成后发送,提供测试时间报告。

尾随数据:

  • 每个 tests_len 对应:
    • test_ns: u64,运行该测试所用纳秒数。
  • 每个 tests_len 对应:
    • name,以零结尾的 UTF-8 字符串。

字段

tag: ToClientTag = .time_report_run_test_result
step_idx: u32 align(1)
tests_len: u32 align(1)

std.Build.abi.ToClientTag

容器

第 46 行

服务器发往客户端的所有 WebSocket 消息均以 ToClientTag 字节开头。 此枚举为非穷尽枚举,仅用于避免套接字上传来格式错误的消息时触发 非法行为;未命名的标签属于错误情况,应终止连接。

每个标签都有对应的 extern struct,表示完整消息, 或当消息长度可变时表示消息头。例如,.hello 对应 Hello。

引入标签时,务必添加首字段为 此枚举的对应 extern struct,并在上方 comptime 块中 check 其布局。

字段

hello
status_update
step_update
fuzz_source_index
fuzz_coverage_update
fuzz_entry_points
time_report_generic_result
time_report_compile_result
time_report_run_test_result
_

std.Build.abi.ToServerTag

容器

第 65 行

类似于 ToClientTag,但用于客户端发往服务器的消息。

字段

rebuild
_
源码

std/Build/abi.zig

//! 此文件由运行于截然不同环境的 Zig 代码共享:
//! * 在主机计算机上运行的构建运行器。
//! * 在浏览器中运行的构建系统网页界面 Wasm 代码。
//! * 与单元测试一起编译的 `libfuzzer`。
//!
//! 这些组件都在某种程度上通过 ABI 交互:
//! * 构建运行器通过 WebSocket 连接与网页界面通信。
//! * 构建运行器通过共享内存映射文件与 `libfuzzer` 通信。
const std = @import("std");

// 检查所有 WebSocket 消息类型都不含隐式填充位。这保证绝不在线路上发送
// 任何未定义位,同时有助于验证布局在不同端保持一致,例如
// `std.Build` 中的 Web 服务器与 Wasm 客户端。
comptime {
    const check = struct {
        fn check(comptime T: type) void {
            std.debug.assert(@typeInfo(T) == .@"struct");
            std.debug.assert(@typeInfo(T).@"struct".layout == .@"extern");
            std.debug.assert(std.meta.hasUniqueRepresentation(T));
        }
    }.check;

    // 服务器->客户端
    check(Hello);
    check(StatusUpdate);
    check(StepUpdate);
    check(fuzz.SourceIndexHeader);
    check(fuzz.CoverageUpdateHeader);
    check(fuzz.EntryPointHeader);
    check(time_report.GenericResult);
    check(time_report.CompileResult);

    // 客户端 -> 服务器
    check(Rebuild);
}

/// 服务器发往客户端的所有 WebSocket 消息均以 `ToClientTag` 字节开头。
/// 此枚举为非穷尽枚举,仅用于避免套接字上传来格式错误的消息时触发
/// 非法行为;未命名的标签属于错误情况,应终止连接。
///
/// 每个标签都有对应的 `extern struct`,表示完整消息,
/// 或当消息长度可变时表示消息头。例如,`.hello` 对应 `Hello`。
///
/// 引入标签时,务必添加首字段为
/// 此枚举的对应 `extern struct`,并在上方 `comptime` 块中 `check` 其布局。
pub const ToClientTag = enum(u8) {
    hello,
    status_update,
    step_update,

    // `--fuzz`
    fuzz_source_index,
    fuzz_coverage_update,
    fuzz_entry_points,

    // `--time-report`
    time_report_generic_result,
    time_report_compile_result,
    time_report_run_test_result,

    _,
};

/// 类似于 `ToClientTag`,但用于客户端发往服务器的消息。
pub const ToServerTag = enum(u8) {
    rebuild,

    _,
};

/// 构建运行器当前的整体状态。
/// 与 Web 界面 `main.js:updateBuildStatus` 中的索引保持同步。
pub const BuildStatus = enum(u8) {
    idle,
    watching,
    running,
    fuzz_init,
};

/// WebSocket:服务器到客户端。
///
/// WebSocket 连接打开后,服务器发送的第一条消息,提供
/// 服务器、构建图等基本信息。
///
/// 尾随数据:
/// * `step_name_len: u32`,每个 `steps_len` 对应一个;
/// * `step_name: [step_name_len]u8`,每个 `step_name_len` 对应一个;
/// * `step_status: u8`,每四个 `steps_len` 对应一个;每两位表示一个 `StepUpdate.Status`,最低有效位优先。
pub const Hello = extern struct {
    tag: ToClientTag = .hello,

    status: BuildStatus,
    flags: Flags,

    /// 凡消息含有时间戳,均以自构建开始以来的纳秒数表示。
    /// 此字段为采用该形式表示的当前时间戳。
    timestamp: i64 align(4),

    /// 构建图中从正在运行的顶层步骤可达的步骤数;
    /// 即本次构建将执行的步骤总数。
    /// 此消息后附各步骤的名称。
    steps_len: u32 align(1),

    pub const Flags = packed struct(u16) {
        /// 是否启用时间报告。
        time_report: bool,
        _: u15 = 0,
    };
};
/// WebSocket 服务器到客户端。
///
/// 表示构建状态已更改。
pub const StatusUpdate = extern struct {
    tag: ToClientTag = .status_update,
    new: BuildStatus,
};
/// WebSocket 服务器到客户端。
///
/// 表示步骤状态发生变化。
pub const StepUpdate = extern struct {
    tag: ToClientTag = .step_update,
    step_idx: u32 align(1),
    bits: packed struct(u8) {
        status: Status,
        _: u6 = 0,
    },
    /// 与网页界面 `main.js:updateStepStatus` 中的索引保持同步。
    pub const Status = enum(u2) {
        pending,
        wip,
        success,
        failure,
    };
};

pub const Rebuild = extern struct {
    tag: ToServerTag = .rebuild,
};

/// 专门涉及模糊测试器接口的 ABI 部分。
pub const fuzz = struct {
    /// 返回是否指示了 `error.SkipZigTest`
    pub const TestOne = *const fn () callconv(.c) bool;

    /// 用于跨运行识别相关请求的唯一值
    pub const Uid = packed struct(u32) {
        kind: enum(u1) { int, bytes },
        hash: u31,

        pub const hashmap_ctx = struct {
            pub fn hash(_: @This(), u: Uid) u32 {
                // 可以忽略 `kind`,因为无论何种情况,`hash` 都应唯一
                return u.hash;
            }

            pub fn eql(_: @This(), a: Uid, b: Uid, _: usize) bool {
                return a == b;
            }
        };
    };

    pub extern fn fuzzer_init(cache_dir_path: Slice) void;
    /// 必须先调用 `fuzzer_init`。
    pub extern fn fuzzer_coverage() Coverage;
    pub extern fn fuzzer_unslide_address(addr: usize) usize;

    /// 执行全部模糊测试工作,并选择要运行的测试。
    ///
    /// 必须先调用 `fuzzer_init`。
    pub extern fn fuzzer_main(
        n_tests: u32,
        seed: u32,
        limit_kind: LimitKind,
        amount_or_instance: u64,
    ) void;
    pub extern fn runner_test_run(i: u32) void;
    pub extern fn runner_test_name(i: u32) Slice;
    // 由于运行器拥有 `std.zig.Server` 实例,它还控制
    // 并发 Io 实例,以便取消读取。因此,模糊测试器执行
    // 任何 zig server 或并发操作时,都必须调用运行器。
    pub extern fn runner_start_input_poller() void;
    pub extern fn runner_stop_input_poller() void;
    /// 返回是否已发出取消信号。
    pub extern fn runner_futex_wait(*const u32, expected: u32) bool;
    pub extern fn runner_futex_wake(*const u32, waiters: u32) void;
    pub extern fn runner_broadcast_input(test_i: u32, bytes: Slice) void;
    /// 必须先调用 `fuzzer_main`。
    ///
    /// 与 `fuzzer_main` 并发调用。若已请求取消则返回。
    pub extern fn fuzzer_receive_input(test_i: u32, bytes: Slice) bool;

    /// 必须在测试函数内调用
    pub extern fn fuzzer_set_test(test_one: TestOne) void;
    /// 必须从测试函数内部调用,且该测试函数须先调用 `fuzzer_set_test`。
    pub extern fn fuzzer_new_input(bytes: Slice) void;
    /// 必须从测试函数内部调用,且该测试函数须先调用 `fuzzer_set_test`。
    pub extern fn fuzzer_start_test() void;

    pub extern fn fuzzer_int(uid: Uid, weights: Weights) u64;
    pub extern fn fuzzer_eos(uid: Uid, weights: Weights) bool;
    pub extern fn fuzzer_bytes(uid: Uid, out: MutSlice, weights: Weights) void;
    pub extern fn fuzzer_slice(
        uid: Uid,
        buf: MutSlice,
        len_weights: Weights,
        byte_weights: Weights,
    ) u32;

    pub const Slice = extern struct {
        ptr: [*]const u8,
        len: usize,

        pub fn toSlice(s: Slice) []const u8 {
            return s.ptr[0..s.len];
        }

        pub fn fromSlice(s: []const u8) Slice {
            return .{ .ptr = s.ptr, .len = s.len };
        }
    };

    pub const MutSlice = extern struct {
        ptr: [*]u8,
        len: usize,

        pub fn toSlice(s: MutSlice) []u8 {
            return s.ptr[0..s.len];
        }

        pub fn fromSlice(s: []u8) MutSlice {
            return .{ .ptr = s.ptr, .len = s.len };
        }
    };

    pub const Weights = extern struct {
        ptr: [*]const Weight,
        len: usize,

        pub fn toSlice(s: Weights) []const Weight {
            return s.ptr[0..s.len];
        }

        pub fn fromSlice(s: []const Weight) Weights {
            return .{ .ptr = s.ptr, .len = s.len };
        }
    };

    /// 提高这些值被模糊测试器选中的概率。
    ///
    /// `weight` 应用于范围内每个值,而非均匀分摊至
    /// 整个范围,且必须非零。
    ///
    /// 一组权重的总和不得超过 2^64,且
    /// 必须非零。
    pub const Weight = extern struct {
        /// 包含端点
        min: u64,
        /// 包含端点
        max: u64,
        weight: u64,

        /// 使用 `inline` 传播编译期性
        inline fn intFromValue(x: anytype) u64 {
            const T = @TypeOf(x);
            return switch (@typeInfo(T)) {
                .comptime_int => x,
                .bool => @intFromBool(x),
                .@"enum" => @backingInt(x),
                else => @as(@Int(.unsigned, @bitSizeOf(T)), @bitCast(x)),

                .int => |i| x: {
                    comptime {
                        if (i.signedness == .signed) {
                            @compileError("type does not have a continous range: " ++ @typeName(T));
                        }
                        // 拒绝位宽不是固定值的类型(尤其是 usize),
                        // 因为无法保证其在所有目标上都适合 u64。
                        //
                        // 不使用 std.mem.indexOfScalar,以避免向后分支
                        // 并保留求值分支配额。
                        if (T == usize or T == c_char or T == c_ushort or
                            T == c_uint or T == c_ulong or T == c_ulonglong)
                        {
                            @compileError("type does not have a fixed bitsize: " ++ @typeName(T));
                        }
                    }
                    break :x x;
                },

                .comptime_float,
                .float,
                => @compileError("type does not have a continous range: " ++ @typeName(T)),
                .pointer => @compileError("type does not have a fixed bitsize: " ++ @typeName(T)),
            };
        }

        /// 使用 `inline` 传播编译期性
        pub inline fn value(T: type, x: T, weight: u64) Weight {
            return .{ .min = intFromValue(x), .max = intFromValue(x), .weight = weight };
        }

        /// 使用 `inline` 传播编译期性
        pub inline fn rangeAtMost(T: type, at_least: T, at_most: T, weight: u64) Weight {
            std.debug.assert(intFromValue(at_least) <= intFromValue(at_most));
            return .{
                .min = intFromValue(at_least),
                .max = intFromValue(at_most),
                .weight = weight,
            };
        }

        /// 使用 `inline` 传播编译期性
        pub inline fn rangeLessThan(T: type, at_least: T, less_than: T, weight: u64) Weight {
            std.debug.assert(intFromValue(at_least) < intFromValue(less_than));
            return .{
                .min = intFromValue(at_least),
                .max = intFromValue(less_than) - 1,
                .weight = weight,
            };
        }
    };

    pub const LimitKind = enum(u8) { forever, iterations };

    /// libfuzzer 使用此项,并以其 usize 作为计数值。为匹配 ABI,
    /// 将整数设为与 libfuzzer 所用目标相同的大小。
    ///
    /// 尾随数据:
    /// * 每个 pc_addr 对应 1 位,元素类型为 usize
    /// * 每个 pcs_len 对应一个 usize 的 pc_addr
    pub const SeenPcsHeader = extern struct {
        n_runs: usize,
        unique_runs: usize,
        pcs_len: usize,

        /// 用于编译期断言。提供一种在指定位置
        /// 触发编译错误的机制。
        pub const trailing = .{
            .pc_bits_usize,
            .pc_addr,
        };

        pub fn headerEnd(header: *const SeenPcsHeader) []const usize {
            const ptr: [*]align(@alignOf(usize)) const u8 = @ptrCast(header);
            const header_end_ptr: [*]const usize = @ptrCast(ptr + @sizeOf(SeenPcsHeader));
            const pcs_len = header.pcs_len;
            return header_end_ptr[0 .. pcs_len + seenElemsLen(pcs_len)];
        }

        pub fn seenBits(header: *const SeenPcsHeader) []const usize {
            return header.headerEnd()[0..seenElemsLen(header.pcs_len)];
        }

        pub fn seenElemsLen(pcs_len: usize) usize {
            return (pcs_len + @bitSizeOf(usize) - 1) / @bitSizeOf(usize);
        }

        pub fn pcAddrs(header: *const SeenPcsHeader) []const usize {
            const pcs_len = header.pcs_len;
            return header.headerEnd()[seenElemsLen(pcs_len)..][0..pcs_len];
        }
    };

    /// 字段采用小端序
    pub const MmapInputHeader = extern struct {
        pc_digest: u64 align(4), // 按要求对齐,使头部不含填充
        instance_id: u32,
        test_i: u32,
        len: u32,
    };

    /// WebSocket 服务端->客户端。
    ///
    /// 在模糊测试开始时发送一次,用于指示可用的覆盖率数据。
    ///
    /// 尾随内容:
    /// * directories_len 个 std.debug.Coverage.String
    /// * files_len 个 std.debug.Coverage.File
    /// * source_locations_len 个 std.debug.Coverage.SourceLocation
    /// * string_bytes_len 个 u8
    pub const SourceIndexHeader = extern struct {
        tag: ToClientTag = .fuzz_source_index,
        _: [3]u8 = @splat(0),
        directories_len: u32,
        files_len: u32,
        source_locations_len: u32,
        string_bytes_len: u32,
        /// 根据服务器记录的模糊测试开始时间。
        start_timestamp: i64 align(4),
        start_n_runs: u64 align(4),
    };

    /// WebSocket 服务器到客户端。
    ///
    /// 每当已覆盖源码位置集合更新时发送。
    ///
    /// 尾随:
    /// * 每个 source_locations_len 对应一位,存储在 u64 元素中。
    pub const CoverageUpdateHeader = extern struct {
        tag: ToClientTag = .fuzz_coverage_update,
        _: [7]u8 = @splat(0),
        n_runs: u64,
        unique_runs: u64,

        pub const trailing = .{
            .pc_bits_usize,
        };
    };

    /// WebSocket 服务器->客户端。
    ///
    /// 每当入口点集合更新时发送。
    ///
    /// 尾随内容:
    /// * 每个 locsLen() 对应一个 source_locations 的 u32 索引
    pub const EntryPointHeader = extern struct {
        tag: ToClientTag = .fuzz_entry_points,
        locs_len_raw: [3]u8,

        pub fn locsLen(hdr: EntryPointHeader) u24 {
            return @bitCast(hdr.locs_len_raw);
        }
        pub fn init(locs_len: u24) EntryPointHeader {
            return .{ .locs_len_raw = @bitCast(locs_len) };
        }
    };

    /// 由 lib/fuzzer 发送给 test_runner,用于获取
    /// 当前内存映射输入文件的信息,以及先前
    /// 模糊测试运行的累计统计信息。
    pub const Coverage = extern struct {
        id: u64,
        runs: u64,
        unique: u64,
        seen: u64,
    };
};

/// 专门涉及时间报告接口的 ABI 部分。
pub const time_report = struct {
    /// WebSocket 服务器->客户端。
    ///
    /// 在 `Step` 完成后发送,提供该步骤的执行耗时。
    pub const GenericResult = extern struct {
        tag: ToClientTag = .time_report_generic_result,
        step_idx: u32 align(1),
        ns_total: u64 align(1),
    };

    /// WebSocket 服务器到客户端消息。
    ///
    /// `Step.Compile` 完成后发送,提供该步骤的时间报告。
    ///
    /// 尾随内容:
    /// * `llvm_pass_timings: [llvm_pass_timings_len]u8`(ASCII 编码)
    /// * 每个 `files_len` 对应:
    ///   * `name`(以空字符结尾的 UTF-8 字符串)
    /// * 每个 `decls_len` 对应:
    ///   * `name`(以空字符结尾的 UTF-8 字符串)
    ///   * `file: u32`(此声明所在文件的索引)
    ///   * `sema_ns: u64`(对此声明进行语义分析所用的纳秒数)
    ///   * `codegen_ns: u64`(对此声明进行语义分析所用的纳秒数)
    ///   * `link_ns: u64`(对此声明进行语义分析所用的纳秒数)
    pub const CompileResult = extern struct {
        tag: ToClientTag = .time_report_compile_result,

        step_idx: u32 align(1),

        flags: Flags,
        stats: Stats align(1),
        ns_total: u64 align(1),

        llvm_pass_timings_len: u32 align(1),
        files_len: u32 align(1),
        decls_len: u32 align(1),

        pub const Flags = packed struct(u8) {
            use_llvm: bool,
            _: u7 = 0,
        };

        pub const Stats = extern struct {
            n_reachable_files: u32,
            n_imported_files: u32,
            n_generic_instances: u32,
            n_inline_calls: u32,

            cpu_ns_parse: u64,
            cpu_ns_astgen: u64,
            cpu_ns_sema: u64,
            cpu_ns_codegen: u64,
            cpu_ns_link: u64,

            real_ns_files: u64,
            real_ns_decls: u64,
            real_ns_llvm_emit: u64,
            real_ns_link_flush: u64,

            pub const init: Stats = .{
                .n_reachable_files = 0,
                .n_imported_files = 0,
                .n_generic_instances = 0,
                .n_inline_calls = 0,
                .cpu_ns_parse = 0,
                .cpu_ns_astgen = 0,
                .cpu_ns_sema = 0,
                .cpu_ns_codegen = 0,
                .cpu_ns_link = 0,
                .real_ns_files = 0,
                .real_ns_decls = 0,
                .real_ns_llvm_emit = 0,
                .real_ns_link_flush = 0,
            };
        };
    };

    /// WebSocket:服务器到客户端。
    ///
    /// Zig 测试可执行文件的 `Step.Run` 完成后发送,提供测试时间报告。
    ///
    /// 尾随数据:
    /// * 每个 `tests_len` 对应:
    ///   * `test_ns: u64`,运行该测试所用纳秒数。
    /// * 每个 `tests_len` 对应:
    ///   * `name`,以零结尾的 UTF-8 字符串。
    pub const RunTestResult = extern struct {
        tag: ToClientTag = .time_report_run_test_result,
        step_idx: u32 align(1),
        tests_len: u32 align(1),
    };
};