本文汇总Ultrascan在标准Hyperscan C API基础上新增的公开接口,按主题分为以下三章:
- 通用字节码API:
fat_hs_*系列接口。 - Grey配置API:进程级编译参数设置与复位接口。
- 正则匹配反馈优化技术API:运行期采集、反馈生成及反馈编译接口。
所有接口均可通过公共头文件hs.h引入。本文不重复介绍hs_compile()、hs_scan()等
上游通用接口;使用这些接口时,应同时参考公共头文件中的注释和上游API文档。
说明: “正则匹配反馈优化技术”是V5.8.0版本 新增的反馈闭环能力,与历史已有的“假阳性阻断技术”是两个独立特性。本文不会以新名称 替代历史特性的名称或说明。
- API返回类型为
hs_error_t。成功通常返回HS_SUCCESS;参数错误返回HS_INVALID; 编译错误通常返回HS_COMPILER_ERROR并通过hs_compile_error_t提供详情。 - 编译失败后,调用者应使用
hs_free_compile_error()释放非空的编译错误对象。 - 文中标记为opaque的对象只能通过对应API创建、传递和释放,调用者不得访问其内部布局。
- 除非接口明确转移所有权,输入对象的所有权仍归调用者。
本文命令沿用安装指南中的固定目录布局:
- Ultrascan源码:
/opt/Ultrascan - 默认静态库构建目录:
/opt/Ultrascan/build - Debug构建目录:
/opt/Ultrascan/build-debug - 反馈优化构建目录:
/opt/Ultrascan/build-feedback
通用字节码将x86和AArch64字节码封装在同一个fat_hs_database_t对象中,适用于一次
编译后向两类平台分发的场景。fat_hs_database_t是opaque类型:
typedef struct fat_hs_database fat_hs_database_t;| 分类 | API | 说明 |
|---|---|---|
| 编译 | fat_hs_compile |
编译单个正则表达式。 |
| 编译 | fat_hs_compile_multi |
编译多个正则表达式。 |
| 编译 | fat_hs_compile_ext_multi |
使用扩展参数编译多个正则表达式。 |
| 编译 | fat_hs_compile_lit |
编译单个纯字面量。 |
| 编译 | fat_hs_compile_lit_multi |
编译多个纯字面量。 |
| 生命周期 | fat_hs_free_database |
释放通用字节码数据库。 |
| 序列化 | fat_hs_serialize_database |
将通用数据库序列化为字节流。 |
| 反序列化 | fat_hs_deserialize_database |
分配并反序列化通用数据库。 |
| 反序列化 | fat_hs_deserialize_database_at |
在调用者提供的内存中反序列化。 |
| 查询 | fat_hs_database_size |
查询内存中通用数据库的大小。 |
| 查询 | fat_hs_serialized_database_size |
查询序列化数据反序列化后所需空间。 |
| 查询 | fat_hs_database_info |
查询数据库版本和模式信息。 |
编译一个正则表达式,生成同时包含x86和AArch64字节码的通用数据库。
hs_error_t HS_CDECL fat_hs_compile(
const char *expression, unsigned int flags, unsigned int mode,
const hs_platform_info_t *platform, fat_hs_database_t **db,
hs_compile_error_t **error);| 参数 | 说明 |
|---|---|
expression |
以NUL结尾的正则表达式,不能为空。表达式中不包含分隔符和内嵌标志。 |
flags |
作用于该表达式的HS_FLAG_*标志。多个标志可按位或。 |
mode |
数据库模式。必须选择HS_MODE_BLOCK、HS_MODE_STREAM或HS_MODE_VECTORED之一,并可组合适用的模式标志。 |
platform |
可选目标平台信息;为NULL时按当前主机平台生成数据库。 |
db |
非空输出参数。成功时返回通用数据库;失败时置为NULL。调用者使用fat_hs_free_database()释放成功返回的对象。 |
error |
非空输出参数。编译失败时返回错误详情;调用者使用hs_free_compile_error()释放非空对象。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
编译成功。 |
HS_COMPILER_ERROR |
db、error或表达式参数不合法,模式或平台参数不合法,或表达式解析、编译失败。 |
HS_ARCH_ERROR |
库以FAT_RUNTIME构建且运行平台不支持SSSE3。 |
编译多个正则表达式,生成通用数据库。
hs_error_t HS_CDECL fat_hs_compile_multi(
const char *const *expressions, const unsigned int *flags,
const unsigned int *ids, unsigned int elements, unsigned int mode,
const hs_platform_info_t *platform, fat_hs_database_t **db,
hs_compile_error_t **error);| 参数 | 说明 |
|---|---|
expressions |
以NUL结尾的正则表达式数组,不能为空。数组包含elements个元素。 |
flags |
每个表达式对应的HS_FLAG_*标志数组;可为NULL,表示全部标志为0。 |
ids |
每个表达式对应的ID数组;可为NULL,表示使用默认ID。 |
elements |
表达式数量,必须大于0。 |
mode |
数据库模式。必须选择HS_MODE_BLOCK、HS_MODE_STREAM或HS_MODE_VECTORED之一,并可组合适用的模式标志。 |
platform |
可选目标平台信息;为NULL时按当前主机平台生成数据库。 |
db |
非空输出参数。成功时返回通用数据库;失败时置为NULL。调用者使用fat_hs_free_database()释放成功返回的对象。 |
error |
非空输出参数。编译失败时返回错误详情;调用者使用hs_free_compile_error()释放非空对象。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
编译成功。 |
HS_COMPILER_ERROR |
db、error、表达式数组或elements参数不合法,模式或平台参数不合法,或任一表达式解析、编译失败。 |
HS_ARCH_ERROR |
库以FAT_RUNTIME构建且运行平台不支持SSSE3。 |
使用扩展参数编译多个正则表达式,生成通用数据库。
hs_error_t HS_CDECL fat_hs_compile_ext_multi(
const char *const *expressions, const unsigned int *flags,
const unsigned int *ids, const hs_expr_ext_t *const *ext,
unsigned int elements, unsigned int mode,
const hs_platform_info_t *platform, fat_hs_database_t **db,
hs_compile_error_t **error);| 参数 | 说明 |
|---|---|
expressions |
以NUL结尾的正则表达式数组,不能为空。数组包含elements个元素。 |
flags |
每个表达式对应的HS_FLAG_*标志数组;可为NULL,表示全部标志为0。 |
ids |
每个表达式对应的ID数组;可为NULL,表示使用默认ID。 |
ext |
每个表达式对应的hs_expr_ext_t指针数组;可为NULL,单个数组元素也可为NULL。调用期间由调用者保持有效。 |
elements |
表达式数量,必须大于0。 |
mode |
数据库模式。必须选择HS_MODE_BLOCK、HS_MODE_STREAM或HS_MODE_VECTORED之一,并可组合适用的模式标志。 |
platform |
可选目标平台信息;为NULL时按当前主机平台生成数据库。 |
db |
非空输出参数。成功时返回通用数据库;失败时置为NULL。调用者使用fat_hs_free_database()释放成功返回的对象。 |
error |
非空输出参数。编译失败时返回错误详情;调用者使用hs_free_compile_error()释放非空对象。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
编译成功。 |
HS_COMPILER_ERROR |
db、error、表达式数组、扩展参数、elements、模式或平台参数不合法,或任一表达式解析、编译失败。 |
HS_ARCH_ERROR |
库以FAT_RUNTIME构建且运行平台不支持SSSE3。 |
编译一个纯字面量表达式,生成通用数据库。该接口不按正则语法解释字节内容。
hs_error_t HS_CDECL fat_hs_compile_lit(
const char *expression, unsigned flags, const size_t len,
unsigned mode, const hs_platform_info_t *platform,
fat_hs_database_t **db, hs_compile_error_t **error);| 参数 | 说明 |
|---|---|
expression |
纯字面量字节序列,不能为空;数据可包含\0。 |
flags |
作用于该字面量的HS_FLAG_*标志。 |
len |
expression的字节长度,接口只读取此前len个字节。 |
mode |
数据库模式。必须选择HS_MODE_BLOCK、HS_MODE_STREAM或HS_MODE_VECTORED之一,并可组合适用的模式标志。 |
platform |
可选目标平台信息;为NULL时按当前主机平台生成数据库。 |
db |
非空输出参数。成功时返回通用数据库;失败时置为NULL。调用者使用fat_hs_free_database()释放成功返回的对象。 |
error |
非空输出参数。编译失败时返回错误详情;调用者使用hs_free_compile_error()释放非空对象。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
编译成功。 |
HS_COMPILER_ERROR |
db、error、字面量、长度、模式或平台参数不合法,或编译失败。 |
HS_ARCH_ERROR |
库以FAT_RUNTIME构建且运行平台不支持SSSE3。 |
编译多个纯字面量表达式,生成通用数据库。
hs_error_t HS_CDECL fat_hs_compile_lit_multi(
const char *const *expressions, const unsigned *flags,
const unsigned *ids, const size_t *lens, unsigned elements,
unsigned mode, const hs_platform_info_t *platform,
fat_hs_database_t **db, hs_compile_error_t **error);| 参数 | 说明 |
|---|---|
expressions |
纯字面量字节序列数组,不能为空。数组包含elements个元素,各元素可包含\0。 |
flags |
每个字面量对应的HS_FLAG_*标志数组;可为NULL,表示全部标志为0。 |
ids |
每个字面量对应的ID数组;可为NULL,表示使用默认ID。 |
lens |
每个字面量的字节长度数组,不能为空。数组与expressions一一对应,lens[i]指定从expressions[i]读取的字节数;字面量可包含\0,接口只读取前lens[i]个字节。 |
elements |
字面量数量,必须大于0。 |
mode |
数据库模式。必须选择HS_MODE_BLOCK、HS_MODE_STREAM或HS_MODE_VECTORED之一,并可组合适用的模式标志。 |
platform |
可选目标平台信息;为NULL时按当前主机平台生成数据库。 |
db |
非空输出参数。成功时返回通用数据库;失败时置为NULL。调用者使用fat_hs_free_database()释放成功返回的对象。 |
error |
非空输出参数。编译失败时返回错误详情;调用者使用hs_free_compile_error()释放非空对象。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
编译成功。 |
HS_COMPILER_ERROR |
db、error、字面量数组、长度数组、elements、模式或平台参数不合法,或任一字面量编译失败。 |
HS_ARCH_ERROR |
库以FAT_RUNTIME构建且运行平台不支持SSSE3。 |
释放由通用字节码编译或分配式反序列化接口返回的数据库。
hs_error_t HS_CDECL fat_hs_free_database(fat_hs_database_t *db);| 参数 | 说明 |
|---|---|
db |
待释放的通用数据库;可为NULL。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
数据库已释放,或db为NULL。 |
HS_INVALID |
db非空但不是有效的通用数据库对象。 |
将内存中的通用数据库序列化为连续字节流。
hs_error_t HS_CDECL fat_hs_serialize_database(
const fat_hs_database_t *db, char **bytes, size_t *length);| 参数 | 说明 |
|---|---|
db |
待序列化的通用数据库,必须有效且按要求对齐。 |
bytes |
非空输出参数。成功时返回由misc allocator分配的序列化缓冲区;默认分配器下可使用free()释放,配置自定义misc allocator时应使用相应释放函数。 |
length |
非空输出参数。成功时返回bytes指向缓冲区的长度。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
序列化成功。 |
HS_INVALID |
db、bytes或length为空,或数据库魔数无效。 |
HS_BAD_ALIGN |
db未按要求对齐。 |
HS_DB_VERSION_ERROR |
数据库版本与当前库不匹配。 |
HS_NOMEM |
misc allocator未能分配输出缓冲区。 |
HS_BAD_ALLOC |
misc allocator返回的缓冲区未满足对齐要求。 |
分配内存并从序列化字节流重构通用数据库。
hs_error_t HS_CDECL fat_hs_deserialize_database(
const char *bytes, const size_t length, fat_hs_database_t **db);| 参数 | 说明 |
|---|---|
bytes |
通用数据库的序列化字节流,不能为空。 |
length |
bytes指向字节流的长度。 |
db |
非空输出参数。成功时返回新数据库;失败时置为NULL。调用者使用fat_hs_free_database()释放成功返回的对象。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
反序列化成功。 |
HS_INVALID |
bytes或db为空,字节流格式、长度、数据库魔数或校验和无效。 |
HS_DB_VERSION_ERROR |
字节流中的数据库版本与当前库不匹配。 |
HS_NOMEM |
database allocator未能分配数据库内存。 |
HS_BAD_ALLOC |
database allocator返回的内存未满足对齐要求。 |
在调用者提供的内存中从序列化字节流重构通用数据库。
hs_error_t HS_CDECL fat_hs_deserialize_database_at(
const char *bytes, const size_t length, fat_hs_database_t *db);| 参数 | 说明 |
|---|---|
bytes |
通用数据库的序列化字节流,不能为空。 |
length |
bytes指向字节流的长度。 |
db |
调用者预分配的输出内存,不能为空且至少按8字节对齐。所需空间先通过fat_hs_serialized_database_size()查询;内存所有权始终归调用者,不得调用fat_hs_free_database()释放。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
反序列化成功。 |
HS_INVALID |
bytes或db为空,字节流格式、长度、数据库魔数或校验和无效。 |
HS_BAD_ALIGN |
db未按8字节对齐。 |
HS_DB_VERSION_ERROR |
字节流中的数据库版本与当前库不匹配。 |
查询内存中通用数据库占用的空间大小。
hs_error_t HS_CDECL fat_hs_database_size(
const fat_hs_database_t *db, size_t *size);| 参数 | 说明 |
|---|---|
db |
待查询的通用数据库。 |
size |
非空输出参数。成功时返回数据库所占字节数。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
查询成功。 |
HS_INVALID |
db或size为空,或数据库魔数无效。 |
HS_DB_VERSION_ERROR |
数据库版本与当前库不匹配。 |
查询序列化通用数据库反序列化所需的内存空间。
hs_error_t HS_CDECL fat_hs_serialized_database_size(
const char *bytes, const size_t length, size_t *size);| 参数 | 说明 |
|---|---|
bytes |
通用数据库的序列化字节流。 |
length |
bytes指向字节流的长度。 |
size |
非空输出参数。成功时返回fat_hs_deserialize_database_at()所需的内存大小。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
查询成功。 |
HS_INVALID |
字节流为空、长度或格式无效,或size为空。 |
HS_DB_VERSION_ERROR |
字节流中的数据库版本与当前库不匹配。 |
查询通用数据库的版本和模式信息。
hs_error_t HS_CDECL fat_hs_database_info(
const fat_hs_database_t *db, char **info);| 参数 | 说明 |
|---|---|
db |
待查询的通用数据库,必须有效且按要求对齐。 |
info |
非空输出参数。成功时返回由misc allocator分配的NUL结尾信息字符串;默认分配器下可使用free()释放,配置自定义misc allocator时应使用相应释放函数。失败时置为NULL。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
查询成功。 |
HS_INVALID |
db或info为空,db未按要求对齐,或数据库魔数无效。 |
HS_NOMEM |
misc allocator未能分配信息字符串。 |
HS_BAD_ALLOC |
misc allocator返回的内存未满足对齐要求。 |
下面的示例编译一个通用数据库并将其序列化。实际跨平台部署时,可以直接使用hsdump -U生成文件,并由支持通用字节码的工具加载。
#include <stdio.h>
#include <stdlib.h>
#include "hs.h"
int main(void) {
fat_hs_database_t *db = NULL;
hs_compile_error_t *compile_error = NULL;
char *bytes = NULL;
size_t length = 0;
hs_error_t err = fat_hs_compile("teakettle", 0, HS_MODE_BLOCK, NULL,
&db, &compile_error);
if (err != HS_SUCCESS) {
fprintf(stderr, "compile failed: %s\n",
compile_error ? compile_error->message : "unknown error");
hs_free_compile_error(compile_error);
return 1;
}
err = fat_hs_serialize_database(db, &bytes, &length);
if (err != HS_SUCCESS || length == 0) {
fprintf(stderr, "serialize failed: %d\n", err);
free(bytes);
fat_hs_free_database(db);
return 1;
}
puts("fat database serialized successfully");
free(bytes); /* 仅适用于默认misc allocator. */
fat_hs_free_database(db);
return 0;
}将代码保存为/opt/Ultrascan/fat_example.c。以下命令直接使用新生成的静态库,
无需安装Ultrascan。应先按照安装指南完成默认静态库编译,
并确认库文件已经生成:
test -f /opt/Ultrascan/build/lib/libhs.a && \
ls -lh /opt/Ultrascan/build/lib/libhs.a命令成功时,输出中应包含/opt/Ultrascan/build/lib/libhs.a;文件大小和时间会随构建环境变化。例如:
-rw-r--r-- 1 root root 25M Sep 30 12:00 /opt/Ultrascan/build/lib/libhs.a
cc -std=c99 \
-I/opt/Ultrascan/src \
/opt/Ultrascan/fat_example.c \
/opt/Ultrascan/build/lib/libhs.a \
-lstdc++ -lm -pthread \
-o /opt/Ultrascan/build/fat_example
/opt/Ultrascan/build/fat_example正确输出:
fat database serialized successfully
Grey是编译器内部优化参数集合。公开API允许应用在进程内显式设置这些参数,
取代旧的config.txt隐式读取方式。Ultrascan不再搜索或读取config.txt;
如需覆盖默认值,必须在编译API之前主动调用本章接口。
设置进程级Grey覆盖字符串。设置成功后,后续构造Grey配置的编译调用都会读取这份配置,直到再次设置或复位。
hs_error_t HS_CDECL hs_set_grey_overrides(const char *overrides);| 参数 | 说明 |
|---|---|
overrides |
格式为key:value;key:value;...。传入NULL或空字符串等价于复位。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
字符串有效,已保存新配置;NULL或空字符串也返回成功。 |
HS_INVALID |
存在未知key、缺少冒号、非数字或越界数值等格式错误;原有全局配置保持不变。调试用途的help输入也会被拒绝。 |
使用约束:
- key必须是
applyGreyOverrides()白名单中的布尔或数值字段。常用示例包括allowLily、allowNeoFdr、limitPatternCount和limitPatternLength;并非Grey结构中的所有字段 都可公开覆盖。 - value按无符号整数解析。布尔开关建议只使用
0或1,不要传入负数。 - 解析不会自动去除key中的空白字符;建议始终使用紧凑格式。
- 配置存储由互斥锁保护,但配置是进程级共享状态。为保证同一批编译结果可复现,应在启动阶段设置,并避免与编译调用并发修改。
- 每次成功调用都会整体替换上一份覆盖字符串,不会自动与上一次设置合并。
清除进程级Grey覆盖,使后续编译恢复使用代码中的硬编码默认值。
hs_error_t HS_CDECL hs_reset_grey_overrides(void);| 参数 | 说明 |
|---|---|
| 无 | 该接口无参数。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
覆盖已清除;重复调用也安全。 |
下面的用例演示Grey覆盖的完整调用顺序:先设置allowLily、allowNeoFdr和
limitPatternCount,再编译规则,最后释放数据库并复位进程级覆盖,避免影响同一进程
的后续编译。该用例用于验证配置字符串可被接受并参与编译,不用于观测具体引擎选择结果。
#include <stdio.h>
#include "hs.h"
int main(void) {
hs_database_t *db = NULL;
hs_compile_error_t *compile_error = NULL;
hs_error_t err = hs_set_grey_overrides(
"allowLily:1;allowNeoFdr:1;limitPatternCount:100000;");
if (err != HS_SUCCESS) {
fprintf(stderr, "invalid Grey overrides\n");
return 1;
}
err = hs_compile("abc", 0, HS_MODE_BLOCK, NULL, &db, &compile_error);
if (err != HS_SUCCESS) {
fprintf(stderr, "compile failed: %s\n",
compile_error ? compile_error->message : "unknown error");
} else {
puts("Grey compile succeeded");
}
hs_free_compile_error(compile_error);
hs_free_database(db);
hs_reset_grey_overrides();
return err == HS_SUCCESS ? 0 : 1;
}将代码保存为/opt/Ultrascan/grey_example.c。以下命令直接使用新生成的静态库,
无需安装Ultrascan。先确认默认静态库已经生成:
test -f /opt/Ultrascan/build/lib/libhs.a && \
ls -lh /opt/Ultrascan/build/lib/libhs.a命令成功时,输出中应包含/opt/Ultrascan/build/lib/libhs.a;文件大小和时间会随构建环境变化。例如:
-rw-r--r-- 1 root root 25M Sep 30 12:00 /opt/Ultrascan/build/lib/libhs.a
随后执行:
cc -std=c99 \
-I/opt/Ultrascan/src \
/opt/Ultrascan/grey_example.c \
/opt/Ultrascan/build/lib/libhs.a \
-lstdc++ -lm -pthread \
-o /opt/Ultrascan/build/grey_example
/opt/Ultrascan/build/grey_example正确输出:
Grey compile succeeded
仓库中的示例程序和主要编译工具已接入同一公开API:
| 程序 | 参数 |
|---|---|
examples/simplegrep |
-G OVERRIDES |
examples/pcapscan |
-G OVERRIDES |
examples/patbench |
-g OVERRIDES |
hsdump |
-G OVERRIDES |
hsbench、hscheck、hscollider、hspgo |
-G OVERRIDES |
命令行参数仅负责在进程内调用hs_set_grey_overrides();它不会创建或修改config.txt。
正则匹配反馈优化技术建立反馈闭环:先编译baseline数据库,然后进行运行期采样, 再生成feedback,最后使用feedback编译新数据库。运行期collector统计多模fragment 触发与最终上报之间的关系,feedback筛选高浪费fragment,编译器在保证匹配语义不变 的前提下避开相应的低效候选路径。
完整能力当前仅支持AArch64,并且默认关闭。构建时显式开启:
mkdir -p /opt/Ultrascan/build-feedback
cd /opt/Ultrascan/build-feedback
cmake .. -DHS_ENABLE_FP_FEEDBACK=ON
make -j- 在非AArch64平台设置
HS_ENABLE_FP_FEEDBACK=ON会在CMake配置阶段报错。 - 关闭能力时公共符号仍然存在,以保持链接兼容。各接口在此状态下的精确返回值在对应API小节中说明。
- 普通编译和扫描应继续调用不带
_with_feedback或_with_collector后缀的原接口。
typedef struct hs_fp_collector hs_fp_collector_t;
typedef struct hs_fp_feedback hs_fp_feedback_t;hs_fp_collector_t绑定一个具体baseline数据库并累积运行期计数。它借用数据库,不延长数据库生命周期。hs_fp_feedback_t保存独立的坏fragment身份副本,可在collector及baseline数据库释放后继续用于反馈编译。
| 常量 | 值 | 说明 |
|---|---|---|
HS_FP_TABLE_UNKNOWN |
0 | 未知表。 |
HS_FP_TABLE_FLOATING |
1 | floating表。 |
HS_FP_TABLE_EOD_ANCHORED |
2 | EOD anchored表。 |
HS_FP_TABLE_SMALL_BLOCK |
3 | small-block表。 |
HS_FP_TABLE_DELAY_REBUILD |
4 | 保留值,不采集也不用于反馈编译。 |
HS_FP_TABLE_ANCHORED |
5 | 保留值,不采集也不用于反馈编译。 |
| 常量 | 值 | 说明 |
|---|---|---|
HS_FP_ENGINE_UNKNOWN |
0 | 未知引擎类型。 |
HS_FP_ENGINE_NOODLE |
1 | Noodle类型标识。 |
HS_FP_ENGINE_FDR |
2 | FDR类型标识。 |
HS_FP_ENGINE_NEO_FDR |
3 | NeoFDR类型标识。 |
HS_FP_ENGINE_HAO |
4 | 为保持公开ABI完整性保留的引擎类型标识。 |
HS_FP_ENGINE_TEDDY |
5 | Teddy类型标识。 |
| 常量 | 值 | 说明 |
|---|---|---|
HS_FP_FRAGMENT_FLAG_NOCASE |
0x01 |
fragment不区分大小写。 |
HS_FP_FRAGMENT_FLAG_NORUNS |
0x02 |
fragment带NORUNS属性。 |
HS_FP_FRAGMENT_FLAG_MASKED |
0x04 |
fragment带mask/cmp约束。 |
typedef struct hs_fp_feedback_params {
unsigned int flags;
unsigned long long min_trigger_count;
unsigned long long min_false_positive_count;
unsigned long long min_false_positive_rate;
unsigned long long min_waste_share;
unsigned int max_bad_fragments;
} hs_fp_feedback_params_t;flags指定哪些字段覆盖默认值:
| Flag | 生效字段 | 默认值宏 | 默认值 |
|---|---|---|---|
HS_FP_FEEDBACK_PARAM_MIN_TRIGGER_COUNT |
min_trigger_count |
HS_FP_FEEDBACK_DEFAULT_MIN_TRIGGER_COUNT |
1000 |
HS_FP_FEEDBACK_PARAM_MIN_FALSE_POSITIVE_COUNT |
min_false_positive_count |
HS_FP_FEEDBACK_DEFAULT_MIN_FALSE_POSITIVE_COUNT |
1000 |
HS_FP_FEEDBACK_PARAM_MIN_FALSE_POSITIVE_RATE |
min_false_positive_rate |
HS_FP_FEEDBACK_DEFAULT_MIN_FALSE_POSITIVE_RATE |
99% |
HS_FP_FEEDBACK_PARAM_MIN_WASTE_SHARE |
min_waste_share |
HS_FP_FEEDBACK_DEFAULT_MIN_WASTE_SHARE |
5% |
HS_FP_FEEDBACK_PARAM_MAX_BAD_FRAGMENTS |
max_bad_fragments |
HS_FP_FEEDBACK_DEFAULT_MAX_BAD_FRAGMENTS |
0,表示不限制 |
比率字段使用HS_FP_FEEDBACK_RATE_SCALE(值为1000000000000ULL)缩放。例如
99%表示为990000000000ULL。params == NULL或零初始化结构使用全部默认值。
启用前四个阈值后,字段值为0表示不限制该项;显式启用MAX_BAD_FRAGMENTS时,
其值必须大于0。
以下定义仅用于hs_fp_collector_to_feedback_with_dump()。生成feedback时,库可通过
汇总回调输出整体统计,并通过fragment回调逐项输出fragment统计和入选状态,便于
记录日志或导出CSV。回调只提供观察结果,不参与feedback筛选,也不转移任何对象的
所有权。
typedef struct hs_fp_fragment_info {
unsigned long long key;
unsigned int table;
unsigned int engine;
unsigned int flags;
const unsigned char *bytes;
size_t length;
const unsigned char *mask;
const unsigned char *cmp;
size_t mask_length;
unsigned long long trigger_count;
unsigned long long true_trigger_count;
unsigned long long false_positive_count;
} hs_fp_fragment_info_t;
typedef struct hs_fp_feedback_dump_summary {
unsigned int fragment_count;
unsigned int bad_fragment_count;
unsigned long long trigger_count;
unsigned long long true_trigger_count;
unsigned long long false_positive_count;
} hs_fp_feedback_dump_summary_t;
typedef void(HS_CDECL *hs_fp_feedback_dump_summary_handler)(
const hs_fp_feedback_dump_summary_t *summary, void *context);
typedef void(HS_CDECL *hs_fp_feedback_dump_fragment_handler)(
const hs_fp_fragment_info_t *fragment, unsigned int selected,
void *context);
typedef struct hs_fp_feedback_dump_callbacks {
hs_fp_feedback_dump_summary_handler on_summary;
hs_fp_feedback_dump_fragment_handler on_fragment;
} hs_fp_feedback_dump_callbacks_t;hs_fp_fragment_info_t字段:
| 字段 | 说明 |
|---|---|
key |
用于dump、日志和跨编译观察的稳定fragment key。 |
table |
HS_FP_TABLE_*值,也是反馈编译精确身份的一部分。 |
engine |
HS_FP_ENGINE_*值,仅用于分类和观察。 |
flags |
HS_FP_FRAGMENT_FLAG_*位图。 |
bytes/length |
fragment二进制内容及长度,不保证以NUL结尾。 |
mask/cmp/mask_length |
可选mask/cmp约束;无约束时长度为0,指针可为NULL。 |
trigger_count |
前端fragment触发次数。 |
true_trigger_count |
触发后直接产生至少一次最终上报的次数;一次触发产生多个上报仍只计一次。 |
false_positive_count |
未直接产生最终上报的触发次数。 |
hs_fp_feedback_dump_summary_t汇总本次采样窗口内可映射到metadata且实际触发过的
known fragment:fragment_count为明细数,bad_fragment_count为入选feedback
的数量,其余三个字段分别汇总trigger、true-trigger和false-positive计数。
selected != 0表示该fragment已进入本次feedback。回调参数及bytes、mask、
cmp指针只在回调期间有效;如需持久化,必须在回调中复制。
为指定baseline数据库创建运行期反馈collector。collector借用数据库,数据库必须在 collector释放前保持有效;同一collector不支持多线程并发写。
hs_error_t HS_CDECL hs_fp_collector_create(
const hs_database_t *db, hs_fp_collector_t **collector);| 参数 | 说明 |
|---|---|
db |
已编译的baseline数据库。 |
collector |
非空输出参数。启用特性时成功返回新collector;失败或特性未启用时置为NULL。调用者使用hs_fp_collector_free()释放成功返回的对象。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
功能已启用时创建成功。 |
HS_INVALID |
功能已启用时,collector == NULL、数据库为空、数据库魔数错误或字节码未按要求对齐;功能未启用时,仅在collector == NULL时返回该值。 |
HS_DB_VERSION_ERROR |
功能已启用时,数据库版本与当前库不匹配。 |
HS_NOMEM |
功能已启用时,分配collector或计数器失败。 |
HS_ARCH_ERROR |
功能未启用且collector有效时,将*collector置为NULL并返回该值。 |
清空collector的累计计数,但保留其与baseline数据库的绑定。
hs_error_t HS_CDECL hs_fp_collector_reset(hs_fp_collector_t *collector);| 参数 | 说明 |
|---|---|
collector |
待复位的collector。启用特性时不能为空。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
功能已启用时复位成功。 |
HS_INVALID |
功能已启用且collector == NULL。 |
HS_ARCH_ERROR |
功能未启用时,不校验collector,直接返回该值。 |
将同一数据库创建的多个collector合并为新collector。输入collector不会被释放或复位。
hs_error_t HS_CDECL hs_fp_collector_merge(
hs_fp_collector_t *const *collectors, unsigned int count,
hs_fp_collector_t **collector);| 参数 | 说明 |
|---|---|
collectors |
待合并的collector数组,不能为空。所有元素必须非空,且必须由完全相同的数据库对象创建。 |
count |
collectors中的对象数量,必须大于0。 |
collector |
非空输出参数。启用特性时成功返回新的合并collector;失败或特性未启用时置为NULL。调用者使用hs_fp_collector_free()释放成功返回的对象。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
功能已启用时合并成功。 |
HS_INVALID |
功能已启用时,collectors == NULL、count == 0、collector == NULL、任一输入collector为空,或输入来自不同数据库对象;功能未启用时,仅在collector == NULL时返回该值。 |
HS_DB_VERSION_ERROR |
功能已启用时,新collector创建时关联数据库版本与当前库不匹配。 |
HS_NOMEM |
功能已启用时,分配新collector或计数器失败。 |
HS_ARCH_ERROR |
功能未启用且collector有效时,将*collector置为NULL并返回该值。 |
释放collector。NULL安全。
hs_error_t HS_CDECL hs_fp_collector_free(hs_fp_collector_t *collector);| 参数 | 说明 |
|---|---|
collector |
待释放的collector;可为NULL。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
无论特性是否启用、collector是否为NULL,均返回成功。 |
从collector生成用于反馈编译的feedback对象。调用会提交pending计数,但不会复位 collector;转换期间不得并发写入同一collector。无fragment入选时,成功返回的 feedback仍然有效。
hs_error_t HS_CDECL hs_fp_collector_to_feedback(
hs_fp_collector_t *collector, const hs_fp_feedback_params_t *params,
hs_fp_feedback_t **feedback);| 参数 | 说明 |
|---|---|
collector |
有效的反馈collector。 |
params |
可选筛选参数。传入NULL或零初始化结构时使用默认阈值。 |
feedback |
非空输出参数。启用特性时成功返回feedback;失败或特性未启用时置为NULL。调用者使用hs_fp_feedback_free()释放成功返回的对象。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
功能已启用时,feedback生成成功。 |
HS_INVALID |
功能已启用时,collector == NULL、feedback == NULL、筛选参数的flags包含未知位、已启用的max_bad_fragments为0,或已启用的比例阈值大于HS_FP_FEEDBACK_RATE_SCALE;功能未启用时,仅在feedback == NULL时返回该值。 |
HS_NOMEM |
功能已启用时,分配统计报告或feedback失败。 |
HS_ARCH_ERROR |
功能未启用且feedback有效时,将*feedback置为NULL并返回该值。 |
从collector生成feedback,并可同步输出汇总和fragment dump信息。回调只提供观察结果,不参与筛选,也不转移对象所有权。
hs_error_t HS_CDECL hs_fp_collector_to_feedback_with_dump(
hs_fp_collector_t *collector, const hs_fp_feedback_params_t *params,
const hs_fp_feedback_dump_callbacks_t *callbacks, void *context,
hs_fp_feedback_t **feedback);| 参数 | 说明 |
|---|---|
collector |
有效的反馈collector。 |
params |
可选筛选参数。传入NULL或零初始化结构时使用默认阈值。 |
callbacks |
可选dump回调集合;为NULL时不输出dump。on_summary和on_fragment可分别为NULL。 |
context |
原样传递给dump回调的用户上下文;callbacks == NULL时不使用。 |
feedback |
非空输出参数。启用特性时成功返回feedback;失败或特性未启用时置为NULL。调用者使用hs_fp_feedback_free()释放成功返回的对象。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
功能已启用时,feedback生成成功。 |
HS_INVALID |
功能已启用时,collector == NULL、feedback == NULL、筛选参数的flags包含未知位、已启用的max_bad_fragments为0,或已启用的比例阈值大于HS_FP_FEEDBACK_RATE_SCALE;功能未启用时,仅在feedback == NULL时返回该值。 |
HS_NOMEM |
功能已启用时,分配统计报告或feedback失败。 |
HS_ARCH_ERROR |
功能未启用且feedback有效时,将*feedback置为NULL并返回该值。 |
释放feedback对象。NULL安全。
hs_error_t HS_CDECL hs_fp_feedback_free(hs_fp_feedback_t *feedback);| 参数 | 说明 |
|---|---|
feedback |
待释放的feedback;可为NULL。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
无论特性是否启用、feedback是否为NULL,均返回成功。 |
使用feedback编译多个正则表达式。当前没有single、literal或fat数据库的反馈编译变体。
hs_error_t HS_CDECL hs_compile_multi_with_feedback(
const char *const *expressions, const unsigned int *flags,
const unsigned int *ids, unsigned int elements, unsigned int mode,
const hs_platform_info_t *platform, const hs_fp_feedback_t *feedback,
hs_database_t **db, hs_compile_error_t **error);| 参数 | 说明 |
|---|---|
expressions |
以NUL结尾的正则表达式数组。 |
flags |
每个表达式对应的HS_FLAG_*标志数组;可为NULL,表示全部标志为0。 |
ids |
每个表达式对应的ID数组;可为NULL,表示使用默认ID。 |
elements |
表达式数量,必须大于0。 |
mode |
数据库模式。必须选择HS_MODE_BLOCK、HS_MODE_STREAM或HS_MODE_VECTORED之一,并可组合适用的模式标志。 |
platform |
可选目标平台信息;为NULL时按当前主机平台生成数据库。 |
feedback |
可选反馈对象。启用特性时为NULL等价于对应的普通multi编译;库只在调用期间读取,不接管所有权。 |
db |
输出参数。成功时返回新数据库;失败或特性未启用时置为NULL。调用者使用hs_free_database()释放成功返回的对象。 |
error |
输出参数。编译失败时返回错误详情;调用者使用hs_free_compile_error()释放非空对象。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
功能已启用时编译成功。 |
HS_COMPILER_ERROR |
功能已启用时,编译参数、模式或平台参数不合法,或表达式解析、编译失败;详情通过error返回。 |
HS_NOMEM |
功能已启用时,创建或复制反馈编译上下文失败。 |
HS_ARCH_ERROR |
功能未启用时,即使feedback == NULL也返回该值;db置为NULL,error非空时返回错误详情。 |
使用feedback和扩展参数编译多个正则表达式。
hs_error_t HS_CDECL hs_compile_ext_multi_with_feedback(
const char *const *expressions, const unsigned int *flags,
const unsigned int *ids, const hs_expr_ext_t *const *ext,
unsigned int elements, unsigned int mode,
const hs_platform_info_t *platform, const hs_fp_feedback_t *feedback,
hs_database_t **db, hs_compile_error_t **error);| 参数 | 说明 |
|---|---|
expressions |
以NUL结尾的正则表达式数组。 |
flags |
每个表达式对应的HS_FLAG_*标志数组;可为NULL,表示全部标志为0。 |
ids |
每个表达式对应的ID数组;可为NULL,表示使用默认ID。 |
ext |
每个表达式对应的hs_expr_ext_t指针数组;可为NULL,单个数组元素也可为NULL。调用期间由调用者保持有效。 |
elements |
表达式数量,必须大于0。 |
mode |
数据库模式。必须选择HS_MODE_BLOCK、HS_MODE_STREAM或HS_MODE_VECTORED之一,并可组合适用的模式标志。 |
platform |
可选目标平台信息;为NULL时按当前主机平台生成数据库。 |
feedback |
可选反馈对象。启用特性时为NULL等价于对应的普通扩展multi编译;库只在调用期间读取,不接管所有权。 |
db |
输出参数。成功时返回新数据库;失败或特性未启用时置为NULL。调用者使用hs_free_database()释放成功返回的对象。 |
error |
输出参数。编译失败时返回错误详情;调用者使用hs_free_compile_error()释放非空对象。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
功能已启用时编译成功。 |
HS_COMPILER_ERROR |
功能已启用时,编译参数、扩展参数、模式或平台参数不合法,或表达式解析、编译失败;详情通过error返回。 |
HS_NOMEM |
功能已启用时,创建或复制反馈编译上下文失败。 |
HS_ARCH_ERROR |
功能未启用时,即使feedback == NULL也返回该值;db置为NULL,error非空时返回错误详情。 |
执行块模式扫描,同时向collector记录运行期触发信息。匹配语义和回调行为与hs_scan()一致。
hs_error_t HS_CDECL hs_scan_with_collector(
const hs_database_t *db, const char *data, unsigned int length,
unsigned int flags, hs_scratch_t *scratch,
match_event_handler onEvent, void *context,
hs_fp_collector_t *collector);| 参数 | 说明 |
|---|---|
db |
块模式数据库,且必须与collector绑定同一个数据库对象。 |
data |
待扫描数据,不能为空。 |
length |
data的字节长度。 |
flags |
扫描标志,当前保留供将来使用。 |
scratch |
与db兼容的每线程scratch空间。 |
onEvent |
可选匹配回调;为NULL时不输出匹配。 |
context |
原样传递给onEvent的用户上下文。 |
collector |
与db绑定的有效collector。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
功能已启用时扫描成功;本次pending计数已提交。 |
HS_SCAN_TERMINATED |
功能已启用时,匹配回调请求停止;本次pending计数已提交。 |
HS_INVALID |
功能已启用时,collector、数据库、数据或scratch无效,或数据库与collector不匹配。 |
HS_DB_VERSION_ERROR |
功能已启用时,数据库版本与当前库不匹配。 |
HS_DB_MODE_ERROR |
功能已启用时,数据库不是块模式。 |
HS_SCRATCH_IN_USE |
功能已启用时,scratch正在被其他调用使用。 |
HS_UNKNOWN_ERROR |
功能已启用时,扫描期间发生内部匹配错误。 |
HS_ARCH_ERROR |
功能未启用时,直接返回该值,不执行扫描。 |
执行vectored模式扫描,同时向collector记录运行期触发信息。匹配语义和回调行为与hs_scan_vector()一致。
hs_error_t HS_CDECL hs_scan_vector_with_collector(
const hs_database_t *db, const char *const *data,
const unsigned int *length, unsigned int count, unsigned int flags,
hs_scratch_t *scratch, match_event_handler onEvent, void *context,
hs_fp_collector_t *collector);| 参数 | 说明 |
|---|---|
db |
vectored模式数据库,且必须与collector绑定同一个数据库对象。 |
data |
待扫描数据块指针数组,不能为空。 |
length |
各数据块长度数组,不能为空。 |
count |
数据块数量。 |
flags |
扫描标志,当前保留供将来使用。 |
scratch |
与db兼容的每线程scratch空间。 |
onEvent |
可选匹配回调;为NULL时不输出匹配。 |
context |
原样传递给onEvent的用户上下文。 |
collector |
与db绑定的有效collector。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
功能已启用时扫描成功;本次pending计数已提交。 |
HS_SCAN_TERMINATED |
功能已启用时,匹配回调请求停止;本次pending计数已提交。 |
HS_INVALID |
功能已启用时,collector、数据库、数据数组、长度数组或scratch无效,或数据库与collector不匹配。 |
HS_DB_VERSION_ERROR |
功能已启用时,数据库版本与当前库不匹配。 |
HS_DB_MODE_ERROR |
功能已启用时,数据库不是vectored模式。 |
HS_SCRATCH_IN_USE |
功能已启用时,scratch正在被其他调用使用。 |
HS_UNKNOWN_ERROR |
功能已启用时,扫描期间发生内部匹配错误。 |
HS_ARCH_ERROR |
功能未启用时,直接返回该值,不执行扫描。 |
执行streaming模式扫描,同时向collector记录运行期触发信息。匹配语义和回调行为与
hs_scan_stream()一致;stream close和reset阶段产生的EOD工作不会计入collector。
hs_error_t HS_CDECL hs_scan_stream_with_collector(
hs_stream_t *id, const char *data, unsigned int length,
unsigned int flags, hs_scratch_t *scratch,
match_event_handler onEvent, void *context,
hs_fp_collector_t *collector);| 参数 | 说明 |
|---|---|
id |
已打开的stream对象;其数据库/Rose实例必须与collector绑定的对象相同。 |
data |
待扫描数据,不能为空。 |
length |
data的字节长度。 |
flags |
扫描标志,当前保留供将来使用。 |
scratch |
与stream兼容的每线程scratch空间。 |
onEvent |
可选匹配回调;为NULL时不输出匹配。 |
context |
原样传递给onEvent的用户上下文。 |
collector |
与stream绑定同一Rose实例的有效collector。 |
返回值:
| 返回值 | 说明 |
|---|---|
HS_SUCCESS |
功能已启用时扫描成功;本次pending计数已提交。 |
HS_SCAN_TERMINATED |
功能已启用时,匹配回调请求停止;本次pending计数已提交。 |
HS_INVALID |
功能已启用时,id、collector、数据或scratch无效,或stream与collector不匹配;功能未启用时,id == NULL也返回该值。 |
HS_SCRATCH_IN_USE |
功能已启用时,scratch正在被其他调用使用。 |
HS_UNKNOWN_ERROR |
功能已启用时,扫描期间发生内部匹配错误;已记录的部分计数不会回滚。 |
HS_ARCH_ERROR |
功能未启用且id有效时,直接返回该值,不执行扫描。 |
下面的C用例使用块模式完成baseline编译、采集、生成feedback和反馈编译。示例要求
链接在AArch64上使用HS_ENABLE_FP_FEEDBACK=ON构建的库。
#include <stdio.h>
#include <string.h>
#include "hs.h"
static int on_match(unsigned int id, unsigned long long from,
unsigned long long to, unsigned int flags, void *ctx) {
(void)id; (void)from; (void)to; (void)flags; (void)ctx;
return 0;
}
int main(void) {
const char *expressions[] = {"foo"};
unsigned int flags[] = {0};
unsigned int ids[] = {1};
hs_expr_ext_t ext0 = {0};
const hs_expr_ext_t *ext[] = {&ext0};
hs_fp_feedback_params_t params = {0};
hs_database_t *baseline = NULL, *optimized = NULL;
hs_compile_error_t *compile_error = NULL;
hs_scratch_t *scratch = NULL;
hs_fp_collector_t *collector = NULL;
hs_fp_feedback_t *feedback = NULL;
hs_error_t err;
int rc = 1;
/* 使前端literal可以触发,而最终表达式因min_offset不满足而不上报。 */
ext0.flags = HS_EXT_FLAG_MIN_OFFSET;
ext0.min_offset = 10;
err = hs_compile_ext_multi(expressions, flags, ids, ext, 1,
HS_MODE_BLOCK, NULL, &baseline,
&compile_error);
if (err != HS_SUCCESS) goto cleanup;
if (hs_alloc_scratch(baseline, &scratch) != HS_SUCCESS) goto cleanup;
if (hs_fp_collector_create(baseline, &collector) != HS_SUCCESS)
goto cleanup;
err = hs_scan_with_collector(baseline, "foo", 3, 0, scratch,
on_match, NULL, collector);
if (err != HS_SUCCESS) goto cleanup;
params.flags = HS_FP_FEEDBACK_PARAM_MIN_TRIGGER_COUNT |
HS_FP_FEEDBACK_PARAM_MIN_FALSE_POSITIVE_COUNT |
HS_FP_FEEDBACK_PARAM_MIN_FALSE_POSITIVE_RATE |
HS_FP_FEEDBACK_PARAM_MIN_WASTE_SHARE;
params.min_trigger_count = 1;
params.min_false_positive_count = 1;
params.min_false_positive_rate = 0;
params.min_waste_share = 0;
err = hs_fp_collector_to_feedback(collector, ¶ms, &feedback);
if (err != HS_SUCCESS) goto cleanup;
err = hs_compile_ext_multi_with_feedback(
expressions, flags, ids, ext, 1, HS_MODE_BLOCK, NULL, feedback,
&optimized, &compile_error);
if (err != HS_SUCCESS) goto cleanup;
puts("feedback-compiled database created");
rc = 0;
cleanup:
if (rc && compile_error) {
fprintf(stderr, "compile error: %s\n", compile_error->message);
}
hs_free_compile_error(compile_error);
hs_fp_feedback_free(feedback);
hs_fp_collector_free(collector);
hs_free_scratch(scratch);
hs_free_database(optimized);
hs_free_database(baseline);
return rc;
}将代码保存为/opt/Ultrascan/feedback_example.c。该用例要求先在AArch64上使用
本章构建命令开启HS_ENABLE_FP_FEEDBACK。以下命令直接使用新生成的静态库,无需
安装Ultrascan。先确认支持反馈能力的静态库已经生成:
test -f /opt/Ultrascan/build-feedback/lib/libhs.a && \
ls -lh /opt/Ultrascan/build-feedback/lib/libhs.a命令成功时,输出中应包含/opt/Ultrascan/build-feedback/lib/libhs.a;文件大小和时间会随构建环境变化。例如:
-rw-r--r-- 1 root root 25M Sep 30 12:00 /opt/Ultrascan/build-feedback/lib/libhs.a
随后执行:
cc -std=c99 \
-I/opt/Ultrascan/src \
/opt/Ultrascan/feedback_example.c \
/opt/Ultrascan/build-feedback/lib/libhs.a \
-lstdc++ -lm -pthread \
-o /opt/Ultrascan/build-feedback/feedback_example
/opt/Ultrascan/build-feedback/feedback_example正确输出:
feedback-compiled database created
完整工具化流程请参考快速入门中的hspgo章节。
| 文档版本 | 发布日期 | 修改说明 |
|---|---|---|
| 01 | 2026-09-30 | 第一次正式发布。 |