Zig Hello World 示例

📁 源码位置: samples/libraries/zig/helloworld 查看源码

功能说明

该示例用于验证 ARCS SDK 当前的 Zig 支持已经可以正常工作。工程通过 C 入口调用 Zig 导出的函数，在 Zig 侧完成日志初始化并输出多条日志，用于确认 Zig 代码能够被成功编译、链接并在板端运行。

硬件连接

无需额外外设连接。

串口输出：

  • 使用默认日志串口

  • 波特率请以当前板级 syslog 配置为准

示例步骤

  1. C 入口打印 Zig 测试启动日志

  2. 调用 Zig 导出的 zig_hello_main()

  3. Zig 侧执行 arcs.log.init()

  4. 通过 arcs.log.info() 和 scoped logger 输出日志

  5. 返回执行结果给 C 入口并打印 PASS/FAIL

编译

重要提示：在编译前，请先确认您使用的开发板型号。SDK 目前支持以下开发板：

  • arcs_evb - ARCS EVB 评估板

  • arcs_mini - ARCS Mini 开发板

根据您的开发板型号，选择对应的编译命令：

在 SDK 根目录执行编译:

# 使用 arcs_evb 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_evb

# 或使用 arcs_mini 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_mini

Note

确保已安装对应的工具链。

建议将示例路径替换为：

./build.sh -C -S samples/libraries/zig/helloworld -DBOARD=arcs_evb

烧录

编译完成后，使用 SDK tools 目录下的 cskburn 工具烧录固件:

./tools/burn/cskburn -s /dev/ttyUSB0 -b 3000000 0x0 build/arcs.bin -C arcs

Note

烧录参数说明：

  • -s /dev/ttyUSB0：串口设备路径，需要根据实际情况修改 - Linux 系统：通常是 /dev/ttyUSB0 或 /dev/ttyACM0 - 可通过 ls /dev/tty* 命令查看可用串口设备 - 不同开发板或 USB 转串口芯片可能使用不同的设备名

  • -b 3000000：烧录波特率（3Mbps）

  • 0x0：烧录起始地址

  • build/arcs.bin：编译生成的固件路径

  • -C arcs：芯片类型

注意事项：

  • 确保开发板已正确连接到电脑

  • 如果无法识别串口设备，请检查 USB 连接线是否正常，或尝试其他 USB 端口

预期输出

成功运行后，可看到类似输出：

=== Zig Language Support Test ===
Calling zig_hello_main()...
Hello from Zig on ARCS SDK!
Zig language support is working!
zig-hello: Zig version running on RISC-V ARCS SoC
zig-hello: Log system initialized successfully
Zig function returned successfully (ret=0)
=== Zig Test PASSED ===

核心 API

API

说明

zig_hello_main()

Zig 侧导出的 C 可调用入口函数

arcs.log.init()

初始化 Zig 日志系统

arcs.log.info()

输出普通日志

arcs.log.scoped()

创建带标签的 scoped logger

关键代码

1. Zig 入口函数

const arcs = @import("arcs");

export fn zig_hello_main() callconv(.C) i32 {
    arcs.log.init() catch return -1;
    arcs.log.info("Hello from Zig on ARCS SDK!", .{});
    return 0;
}

2. C 调用 Zig 导出函数

extern int zig_hello_main(void);

int main(int argc, char **argv)
{
    return zig_hello_main();
}

注意事项

  • 模板用途: 该示例是最小接入示例，适合作为后续 Zig sample 的模板

  • 工具链依赖: 工程依赖本机已安装 Zig 编译器，否则配置阶段会直接失败

  • 能力来源: @import("arcs") 的能力由 labs/zig/adapter/src/root.zig 统一导出

  • CI 判定: 真机验证建议以最终串口口令 === Zig Test PASSED === 作为成功条件，而不是只匹配中间日志