Haplink HAPLINK HOST · SCRIPT SYNTAX
脚本语法
按读写、逻辑操作、复位、等待、重连查找指令。
基本规则：每行一条语句；支持 #、// 和 /* ... */ 注释。数值用十进制或 0x 十六进制，r0–r7 是脚本临时变量。表中 8/16/32 表示选择访问宽度，[...] 表示可选参数，不输入方括号；apsel 默认为 0。16 / 32 位地址需按 2 / 4 字节对齐。
使用方式：在 Host 前置或后置编辑器中填写，校验后重新生成并注入镜像池。每段最多 49 条指令（含 end()），前后两段字节码合计最多 980 字节。每条成功的非结束指令后默认等待 5 ms；脚本执行上限为 180 秒。遇到错误查看帮助 →
1. 读写
读取或修改目标内存、寄存器；需要调用 Pack 算法时使用 flm 指令。
| 指令写法 | 作用与限制 |
|---|---|
rN = read8/16/32(address[, apsel]) | 读取目标内存或寄存器，保存到 r0–r7。 |
write8/16/32(address, value_or_register[, apsel]) | 直接通过 SWD 写入，值可以是常量或 rN。write(...) 是 write32(...) 的简写。 |
rmw32(address, clear_mask, set_bits[, apsel]) | 按 (原值 & ~clear_mask) | set_bits 修改，再直接 SWD 写回。 |
flm_erase(address) | 调用匹配辅助 FLM 的 EraseSector，擦除地址所在扇区；选项字算法可能擦除整个选项区。 |
flm_write8/16/32(address, value_or_register) | 调用匹配的辅助 FLM 编程；不自动擦除，只支持 APSEL 0，不接受 apsel 参数。 |
write 是 write32 的简写，始终直接通过 SWD 写入。flm_write 不自动擦除；选项区擦除可能影响其他配置，需按芯片手册保存并恢复。
2. 逻辑操作
变量赋值、位运算、条件判断，以及控制脚本是否继续执行。
| 指令写法 | 作用与限制 |
|---|---|
mov(rN, value) | 给临时变量赋值。也支持 r0 = 0x1234、r1 = r0。 |
r1 = r0 | 变量复制、常量赋值和位运算。支持 &、|、^、~、<<、>>；移位范围 0–31，结果按 uint32 截断。只修改脚本变量，不自动写入目标。 |
expect8/16/32(address, mask, expected[, apsel]) | 读取一次并比较掩码范围；不符合预期立即失败。 |
if_eq(rN, mask, expected, label) / if_ne(...) | 根据临时变量的掩码比较结果跳到后面的标签。不能向后循环，不能直接跳到 end()。 |
fail(code) | 主动终止脚本，非零自定义错误值写入日志。 |
end() | 正常结束；可省略，Host 会自动补充。 |
expect 与 if_eq 判断 (实际值 & mask) == (expected & mask)；if_ne 判断不相等。标签写成 matched:，只允许跳到后面的非结束指令。
3. 复位
按目标芯片的要求选择一种复位方式。
| 指令写法 | 作用与限制 |
|---|---|
nreset(hold_ms) | 输出 NRST 脉冲，保持时间 1–30000 ms，必须连接 NRST。 |
sreset() | 通过 SWD 请求目标系统复位，需要 SWD 连接可用。 |
preset(hold_ms) | 断电保持 1–30000 ms 后恢复当前电压；仅适用于烧录器供电。 |
reset(assert) / reset(release) | 兼容写法：拉低 / 释放 NRST，也接受 1 / 0；需自行设置保持时间。 |
复位不会自动重连。NRST 需要接线；preset 仅限烧录器供电，不能控制目标外部电源。保护生效后若 SWD 不可访问，不要再要求通过 SWD 重连或复位。
4. 等待
固定延时，或轮询目标状态直到满足条件。
| 指令写法 | 作用与限制 |
|---|---|
delay(ms) | 等待 0–30000 ms，不能代替 Flash 忙位轮询。 |
poll8/16/32(address, mask, expected, timeout_ms[, apsel]) | 反复读取，直到满足条件或超时；超时范围 1–120000 ms。 |
时间单位为毫秒。poll 判断 (实际值 & mask) == (expected & mask)；等待忙位清零时 expected 填 0。固定延时不能代替状态轮询。
5. 重连
目标复位或短暂断开后，重新建立 SWD 调试连接。
| 指令写法 | 作用与限制 |
|---|---|
reconnect(timeout_ms[, apsel]) | 重建 SWD 调试连接，超时 1–30000 ms；不是 USB 重连，也不会主动暂停 CPU。 |
reconnect(5000) 表示最多用 5000 ms 重建 SWD 连接，不是 USB 重连，也不会主动暂停目标 CPU。复位后可按启动时间先执行 delay(100)，再重连。