Zig 嵌入式开发：交叉编译与 MCU 裸机实践

zig targets
# 输出 JSON，其中 available_libs / abi / cpu_arch 等均可查

const target = b.resolveTargetQuery(.{
    .cpu_arch = .thumb,
    .cpu_model = .{ .explicit = &std.Target.arm.cpu.cortex_m4 },
    .os_tag = .freestanding,
    .abi = .eabihf,
});

// build.zig
const std = @import("std");

pub fn build(b: *std.Build) void {
    const optimize = b.standardOptimizeOption(.{});

    addMcu(b, optimize, "stm32f411", .{
        .cpu_arch = .thumb,
        .cpu_model = .{ .explicit = &std.Target.arm.cpu.cortex_m4 },
        .os_tag = .freestanding,
        .abi = .eabihf,
    }, "src/stm32/main.zig", "src/stm32/linker.ld");

    addMcu(b, optimize, "esp32c3", .{
        .cpu_arch = .riscv32,
        .os_tag = .freestanding,
        .abi = .eabihf,
    }, "src/esp32c3/main.zig", "src/esp32c3/linker.ld");
}

fn addMcu(
    b: *std.Build,
    optimize: std.builtin.OptimizeMode,
    name: []const u8,
    query: std.Target.Query,
    root: []const u8,
    linker: []const u8,
) void {
    const target = b.resolveTargetQuery(query);

    const exe = b.addExecutable(.{
        .name = name,
        .root_source_file = b.path(root),
        .target = target,
        .optimize = optimize,
    });
    exe.setLinkerScript(b.path(linker));
    exe.entry = .{ .symbol = "reset_handler" };
    b.installArtifact(exe);

    // 同时生成 .bin（烧录用）与 .hex（IDE/量产用）
    const bin = exe.addObjCopy(.{ .format = .bin });
    b.getInstallStep().dependOn(&b.addInstallFileWithDir(
        bin.getOutput(), .bin, b.fmt("{s}.bin", .{name}),
    ).step);

    const hex = exe.addObjCopy(.{ .format = .hex });
    b.getInstallStep().dependOn(&b.addInstallFileWithDir(
        hex.getOutput(), .hex, b.fmt("{s}.hex", .{name}),
    ).step);
}

zig build
# zig-out/bin/ 下生成:
#   stm32f411.elf / stm32f411.bin / stm32f411.hex
#   esp32c3.elf / esp32c3.bin / esp32c3.hex

// src/stm32/main.zig
const std = @import("std"); // freestanding 下仅用 comptime/断言

extern const _stack_top: u8;  // 链接脚本符号
extern const _sdata: u8;
extern const _edata: u8;
extern const _sbss: u8;
extern const _ebss: u8;
extern const _etext: u8;

fn exception_loop() callconv(.c) noreturn {
    while (true) {}
}

export fn reset_handler() callconv(.c) noreturn {
    // 1. 复制 .data 初值：Flash(_etext..) -> RAM(_sdata.._edata)
    const data_len = @intFromPtr(&_edata) - @intFromPtr(&_sdata);
    const src: [*]const u8 = @ptrCast(&_etext);
    const dst: [*]u8 = @ptrCast(&_sdata);
    @memcpy(dst[0..data_len], src[0..data_len]);

    // 2. 清零 .bss
    const bss_len = @intFromPtr(&_ebss) - @intFromPtr(&_sbss);
    const bss: [*]u8 = @ptrCast(&_sbss);
    @memset(bss[0..bss_len], 0);

    // 3. 跳转主逻辑
    main();
}

// 向量表：必须位于 .isr_vector 段（链接脚本保证其在 Flash 首）
export var vectors linksection(".isr_vector") = [_]usize{
    @intFromPtr(&_stack_top),   // 初始 MSP
    @intFromPtr(&reset_handler), // Reset
    @intFromPtr(&exception_loop), // NMI
    @intFromPtr(&exception_loop), // HardFault
    // ... 其余异常/中断向量按需填写
};

// 外设基址
const RCC_BASE   = 0x40023800; // 复位与时钟控制
const GPIOA_BASE = 0x40020000; // GPIO 端口 A
const USART2_BASE = 0x40004400;

inline fn reg(comptime base: usize, comptime offset: usize) *volatile u32 {
    return @ptrFromInt(base + offset);
}

comptime {
    // 编译期锁定寄存器地址对齐
    std.debug.assert(@intFromPtr(reg(RCC_BASE, 0x30)) % 4 == 0);
}

fn delay(ms: u32) void {
    var i: u32 = 0;
    while (i < ms * 4000) : (i += 1) {
        asm volatile ("nop");
    }
}

fn main() noreturn {
    // 1. 打开 GPIOA 时钟
    reg(RCC_BASE, 0x30).* |= (1 << 0); // AHB1ENR |= RCC_AHB1ENR_GPIOAEN

    // 2. PA5 设为推挽输出（MODER[11:10] = 01）
    reg(GPIOA_BASE, 0x00).* |= (1 << 10);
    reg(GPIOA_BASE, 0x00).* &= ~(1 << 11);

    // 3. 翻转 ODR bit5 实现闪烁
    while (true) {
        reg(GPIOA_BASE, 0x14).* ^= (1 << 5); // ODR
        delay(200);
    }
}

fn uart_init() void {
    reg(RCC_BASE, 0x40).* |= (1 << 17);  // APB1ENR |= USART2EN
    // 波特率分频：PCLK1=16MHz，115200 → BRR ≈ 8.68 → 取 0x0D6
    reg(USART2_BASE, 0x08).* = 0x0D6;    // BRR
    reg(USART2_BASE, 0x0C).* |= (1 << 13) | (1 << 3) | (1 << 2) | (1 << 0);
    // CR1: UE(13)=1, TE(3)=1, RE(2)=1
}

fn uart_putc(c: u8) void {
    while ((reg(USART2_BASE, 0x00).* & (1 << 7)) == 0) {} // 等 TXE
    reg(USART2_BASE, 0x04).* = c; // DR
}

fn uart_print(msg: []const u8) void {
    for (msg) |c| uart_putc(c);
}

const SYSTICK_BASE = 0xE000E010;

var ticks: volatile u32 = 0; // 中断里写、主循环读，volatile 保证可见

fn systick_init(reload: u32) void {
    reg(SYSTICK_BASE, 0x00).* = 0;          // CTRL = 0，先关
    reg(SYSTICK_BASE, 0x04).* = reload - 1; // LOAD
    reg(SYSTICK_BASE, 0x08).* = 0;          // VAL = 0
    reg(SYSTICK_BASE, 0x00).* =
        (1 << 2) |  // CLKSOURCE：处理器时钟
        (1 << 1) |  // TICKINT：使能中断
        (1 << 0);   // ENABLE
}

fn systick_handler() callconv(.c) void {
    ticks += 1;
}

// 向量表第 15 项（IRQ 0）挂 SysTick
export var vectors linksection(".isr_vector") = blk: {
    var v: [32]usize = undefined;
    v[0] = @intFromPtr(&_stack_top);
    v[1] = @intFromPtr(&reset_handler);
    v[14] = @intFromPtr(&systick_handler); // 15 - 1
    // ... 其余默认 exception_loop
    break :blk v;
};

// RP2040 第二核心入口：核 1 启动时跳到该地址
export fn second_core_entry() callconv(.c) void {
    // 跑在核 1 上的代码
}

# 构建（Debug，带符号）
zig build -Doptimize=Debug

# 烧录并暂停在入口
probe-rs run --chip STM32F411CEUx zig-out/bin/stm32f411.elf

# 只烧录不运行（Release）
zig build -Doptimize=ReleaseSmall
probe-rs download --chip STM32F411CEUx zig-out/bin/stm32f411.bin \
  --base-address 0x08000000

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg \
  -c "program zig-out/bin/stm32f411.elf verify reset exit"