此文件由运行于截然不同环境的 Zig 代码共享:
- 在主机计算机上运行的构建运行器。
- 在浏览器中运行的构建系统网页界面 Wasm 代码。
- 与单元测试一起编译的
libfuzzer。
这些组件都在某种程度上通过 ABI 交互:
- 构建运行器通过 WebSocket 连接与网页界面通信。
- 构建运行器通过共享内存映射文件与
libfuzzer通信。
std.Build.abi.BuildStatus
容器
构建运行器当前的整体状态。
与 Web 界面 main.js:updateBuildStatus 中的索引保持同步。
字段
idle
watching
running
fuzz_init
std.Build.abi.check
函数
fn check(comptime T: type) void
参数
T: type
std.Build.abi.fuzz
命名空间
专门涉及模糊测试器接口的 ABI 部分。
TestOneUidfuzzer_initfuzzer_coveragefuzzer_unslide_addressfuzzer_mainrunner_test_runrunner_test_namerunner_start_input_pollerrunner_stop_input_pollerrunner_futex_waitrunner_futex_wakerunner_broadcast_inputfuzzer_receive_inputfuzzer_set_testfuzzer_new_inputfuzzer_start_testfuzzer_intfuzzer_eosfuzzer_bytesfuzzer_sliceSliceMutSliceWeightsWeightLimitKindSeenPcsHeaderMmapInputHeaderSourceIndexHeaderCoverageUpdateHeaderEntryPointHeaderCoverage
std.Build.abi.fuzz.Coverage
容器
由 lib/fuzzer 发送给 test_runner,用于获取 当前内存映射输入文件的信息,以及先前 模糊测试运行的累计统计信息。
字段
id: u64
runs: u64
unique: u64
seen: u64
std.Build.abi.fuzz.CoverageUpdateHeader
容器
WebSocket 服务器到客户端。
每当已覆盖源码位置集合更新时发送。
尾随:
- 每个 source_locations_len 对应一位,存储在 u64 元素中。
字段
std.Build.abi.fuzz.CoverageUpdateHeader.trailing
常量
std.Build.abi.fuzz.EntryPointHeader
容器
WebSocket 服务器->客户端。
每当入口点集合更新时发送。
尾随内容:
- 每个 locsLen() 对应一个 source_locations 的 u32 索引
字段
tag: ToClientTag = .fuzz_entry_points
locs_len_raw: [3]u8
std.Build.abi.fuzz.EntryPointHeader.init
函数
pub fn init(locs_len: u24) EntryPointHeader
参数
locs_len: u24
std.Build.abi.fuzz.EntryPointHeader.locsLen
函数
pub fn locsLen(hdr: EntryPointHeader) u24
参数
hdr: EntryPointHeader
std.Build.abi.fuzz.fuzzer_bytes
函数
pub extern fn fuzzer_bytes(uid: Uid, out: MutSlice, weights: Weights) void
参数
std.Build.abi.fuzz.fuzzer_coverage
函数
必须先调用 fuzzer_init。
pub extern fn fuzzer_coverage() Coverage
std.Build.abi.fuzz.fuzzer_eos
函数
pub extern fn fuzzer_eos(uid: Uid, weights: Weights) bool
参数
std.Build.abi.fuzz.fuzzer_init
函数
pub extern fn fuzzer_init(cache_dir_path: Slice) void
参数
cache_dir_path: Slice
std.Build.abi.fuzz.fuzzer_int
函数
pub extern fn fuzzer_int(uid: Uid, weights: Weights) u64
参数
std.Build.abi.fuzz.fuzzer_main
函数
执行全部模糊测试工作,并选择要运行的测试。
必须先调用 fuzzer_init。
pub extern fn fuzzer_main( n_tests: u32, seed: u32, limit_kind: LimitKind, amount_or_instance: u64, ) void
参数
std.Build.abi.fuzz.fuzzer_new_input
函数
必须从测试函数内部调用,且该测试函数须先调用 fuzzer_set_test。
pub extern fn fuzzer_new_input(bytes: Slice) void
参数
bytes: Slice
std.Build.abi.fuzz.fuzzer_receive_input
函数
必须先调用 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
函数
必须在测试函数内调用
pub extern fn fuzzer_set_test(test_one: TestOne) void
参数
test_one: TestOne
std.Build.abi.fuzz.fuzzer_slice
函数
pub extern fn fuzzer_slice( uid: Uid, buf: MutSlice, len_weights: Weights, byte_weights: Weights, ) u32
参数
std.Build.abi.fuzz.fuzzer_start_test
函数
必须从测试函数内部调用,且该测试函数须先调用 fuzzer_set_test。
pub extern fn fuzzer_start_test() void
std.Build.abi.fuzz.fuzzer_unslide_address
函数
pub extern fn fuzzer_unslide_address(addr: usize) usize
参数
addr: usize
std.Build.abi.fuzz.LimitKind
容器
字段
forever
iterations
std.Build.abi.fuzz.MmapInputHeader
容器
字段采用小端序
字段
pc_digest: u64 align(4)
instance_id: u32
test_i: u32
len: u32
std.Build.abi.fuzz.MutSlice
容器
字段
ptr: [*]u8
len: usize
std.Build.abi.fuzz.MutSlice.fromSlice
函数
pub fn fromSlice(s: []u8) MutSlice
参数
s: []u8
std.Build.abi.fuzz.MutSlice.toSlice
函数
pub fn toSlice(s: MutSlice) []u8
参数
s: MutSlice
std.Build.abi.fuzz.runner_broadcast_input
函数
pub extern fn runner_broadcast_input(test_i: u32, bytes: Slice) void
参数
test_i: u32
bytes: Slice
std.Build.abi.fuzz.runner_futex_wait
函数
返回是否已发出取消信号。
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
函数
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
函数
pub extern fn runner_start_input_poller() void
std.Build.abi.fuzz.runner_stop_input_poller
函数
pub extern fn runner_stop_input_poller() void
std.Build.abi.fuzz.runner_test_name
函数
pub extern fn runner_test_name(i: u32) Slice
参数
i: u32
std.Build.abi.fuzz.runner_test_run
函数
pub extern fn runner_test_run(i: u32) void
参数
i: u32
std.Build.abi.fuzz.SeenPcsHeader
容器
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
函数
pub fn headerEnd(header: *const SeenPcsHeader) []const usize
参数
header: *const SeenPcsHeader
std.Build.abi.fuzz.SeenPcsHeader.pcAddrs
函数
pub fn pcAddrs(header: *const SeenPcsHeader) []const usize
参数
header: *const SeenPcsHeader
std.Build.abi.fuzz.SeenPcsHeader.seenBits
函数
pub fn seenBits(header: *const SeenPcsHeader) []const usize
参数
header: *const SeenPcsHeader
std.Build.abi.fuzz.SeenPcsHeader.seenElemsLen
函数
pub fn seenElemsLen(pcs_len: usize) usize
参数
pcs_len: usize
std.Build.abi.fuzz.SeenPcsHeader.trailing
常量
用于编译期断言。提供一种在指定位置 触发编译错误的机制。
std.Build.abi.fuzz.Slice
容器
字段
ptr: [*]const u8
len: usize
std.Build.abi.fuzz.Slice.fromSlice
函数
pub fn fromSlice(s: []const u8) Slice
参数
s: []const u8
std.Build.abi.fuzz.Slice.toSlice
函数
pub fn toSlice(s: Slice) []const u8
参数
s: Slice
std.Build.abi.fuzz.SourceIndexHeader
容器
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
类型
返回是否指示了 error.SkipZigTest
std.Build.abi.fuzz.Uid
容器
用于跨运行识别相关请求的唯一值
字段
kind: enum(u1) { int, bytes }
hash: u31
std.Build.abi.fuzz.Uid.hashmap_ctx
命名空间
std.Build.abi.fuzz.Uid.hashmap_ctx.eql
函数
pub fn eql(_: @This(), a: Uid, b: Uid, _: usize) bool
参数
std.Build.abi.fuzz.Uid.hashmap_ctx.hash
函数
pub fn hash(_: @This(), u: Uid) u32
参数
_: @This()
u: Uid
std.Build.abi.fuzz.Weight
容器
提高这些值被模糊测试器选中的概率。
weight 应用于范围内每个值,而非均匀分摊至
整个范围,且必须非零。
一组权重的总和不得超过 2^64,且 必须非零。
字段
min: u64包含端点
max: u64包含端点
weight: u64
std.Build.abi.fuzz.Weight.intFromValue
函数
使用 inline 传播编译期性
inline fn intFromValue(x: anytype) u64
std.Build.abi.fuzz.Weight.rangeAtMost
函数
使用 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
函数
使用 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
函数
使用 inline 传播编译期性
pub inline fn value(T: type, x: T, weight: u64) Weight
参数
T: type
x: T
weight: u64
std.Build.abi.fuzz.Weights
容器
字段
ptr: [*]const Weight
len: usize
std.Build.abi.fuzz.Weights.fromSlice
函数
pub fn fromSlice(s: []const Weight) Weights
参数
s: []const Weight
std.Build.abi.fuzz.Weights.toSlice
函数
pub fn toSlice(s: Weights) []const Weight
参数
s: Weights
std.Build.abi.Hello
容器
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
容器
字段
time_report: bool是否启用时间报告。
_: u15 = 0
std.Build.abi.Rebuild
容器
字段
tag: ToServerTag = .rebuild
std.Build.abi.StatusUpdate
容器
WebSocket 服务器到客户端。
表示构建状态已更改。
字段
tag: ToClientTag = .status_update
new: BuildStatus
std.Build.abi.std
别名
别名目标 std
std.Build.abi.StepUpdate
容器
WebSocket 服务器到客户端。
表示步骤状态发生变化。
字段
tag: ToClientTag = .step_update
step_idx: u32 align(1)
bits: packed struct(u8) {
status: Status,
_: u6 = 0,
}
std.Build.abi.StepUpdate.Status
容器
与网页界面 main.js:updateStepStatus 中的索引保持同步。
字段
pending
wip
success
failure
std.Build.abi.time_report
命名空间
专门涉及时间报告接口的 ABI 部分。
std.Build.abi.time_report.CompileResult
容器
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
容器
字段
use_llvm: bool
_: u7 = 0
std.Build.abi.time_report.CompileResult.Stats
容器
字段
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
常量
Stats
std.Build.abi.time_report.GenericResult
容器
WebSocket 服务器->客户端。
在 Step 完成后发送,提供该步骤的执行耗时。
字段
std.Build.abi.time_report.RunTestResult
容器
WebSocket:服务器到客户端。
Zig 测试可执行文件的 Step.Run 完成后发送,提供测试时间报告。
尾随数据:
- 每个
tests_len对应:test_ns: u64,运行该测试所用纳秒数。
- 每个
tests_len对应:name,以零结尾的 UTF-8 字符串。
字段
std.Build.abi.ToClientTag
容器
服务器发往客户端的所有 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
容器
类似于 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),
};
};