Move flash example out of rp2040_only and refactor

Author: tact1m4n3

examples/raspberrypi/rp2xxx/build.zig

@@ -17,7 +17,6 @@ pub fn build(b: *std.Build) void {
     const specific_examples: []const Example = &.{
         // RaspberryPi Boards:
         .{ .target = raspberrypi.pico, .name = "pico_board_blinky", .file = "src/board_blinky.zig" },
-        .{ .target = raspberrypi.pico, .name = "pico_flash-program", .file = "src/rp2040_only/flash_program.zig" },
         .{ .target = raspberrypi.pico, .name = "pico_random", .file = "src/rp2040_only/random.zig" },
         .{ .target = raspberrypi.pico, .name = "pico_rtc", .file = "src/rp2040_only/rtc.zig" },
         .{ .target = raspberrypi.pico, .name = "pico_multicore", .file = "src/blinky_core1.zig" },
@@ -35,7 +34,6 @@ pub fn build(b: *std.Build) void {
         .{ .target = raspberrypi.pico2_arm, .name = "pico2_arm_freertos-multitask-demo", .file = "src/freertos/multitask_demo.zig" },
 
         .{ .target = raspberrypi.pico_flashless, .name = "pico_flashless_blinky", .file = "src/blinky.zig" },
-        .{ .target = raspberrypi.pico_flashless, .name = "pico_flashless_flash-program", .file = "src/rp2040_only/flash_program.zig" },
 
         .{ .target = raspberrypi.pico2_arm_flashless, .name = "pico2_arm_flashless_blinky", .file = "src/blinky.zig" },
         .{ .target = raspberrypi.pico2_riscv_flashless, .name = "pico2_riscv_flashless_blinky", .file = "src/blinky.zig" },
@@ -108,6 +106,7 @@ pub fn build(b: *std.Build) void {
         .{ .name = "net-tcp_client", .file = "src/net/tcp_client.zig" },
         .{ .name = "net-tcp_server", .file = "src/net/tcp_server.zig" },
         .{ .name = "board-id", .file = "src/board_id.zig" },
+        .{ .name = "flash-program", .file = "src/flash_program.zig" },
     };
 
     var available_examples: std.array_list.Managed(Example) = .init(b.allocator);

…rp2xxx/src/rp2040_only/flash_program.zig …raspberrypi/rp2xxx/src/flash_program.zigexamples/raspberrypi/rp2xxx/src/rp2040_only/flash_program.zig renamed to examples/raspberrypi/rp2xxx/src/flash_program.zig examples/raspberrypi/rp2xxx/src/rp2040_only/flash_program.zig renamed to examples/raspberrypi/rp2xxx/src/flash_program.zig

@@ -202,8 +202,6 @@ pub fn init(dep: *std.Build.Dependency) Self {
                         .name = "RaspberryPi Pico (ram image)",
                         .url = "https://www.raspberrypi.com/products/raspberry-pi-pico/",
                         .root_source_file = b.path("src/boards/raspberry_pi_pico.zig"),
-                        // needed by the flash hal
-                        .imports = rp2040_bootrom_imports,
                     },
                 }),
                 .pico2_arm = chip_rp2350_arm.derive(.{

port/raspberrypi/rp2xxx/build.zig

@@ -4,15 +4,13 @@ const microzig = @import("microzig");
 const hal = microzig.hal;
 const pins = hal.pins;
 
-pub const bootrom = @import("shared/rp2040_bootrom.zig");
-
-comptime {
-    _ = bootrom;
-}
-
 pub const pin_config = pins.GlobalConfiguration{
     .GPIO25 = .{
         .name = "led",
         .function = .SIO,
     },
 };
+
+comptime {
+    _ = @import("shared/rp2040_bootrom.zig");
+}

port/raspberrypi/rp2xxx/src/boards/raspberry_pi_pico.zig

@@ -4,40 +4,41 @@ const chip = microzig.hal.compatibility.chip;
 
 comptime {
     if (chip == .RP2040 and !microzig.config.ram_image) {
-        _ = bootloader_data;
+        _ = BootromData.bootloader_data;
     }
 }
 
-/// Raw stage2 bootrom
-pub const stage2_rom: []align(2) const u8 = @embedFile("bootloader");
+const BootromData = struct {
+    fn prepare_boot_sector(comptime stage2_rom: []const u8) [256]u8 {
+        @setEvalBranchQuota(10_000);
 
-pub export const bootloader_data: [256]u8 linksection(".boot2") = blk: {
-    @setEvalBranchQuota(10_000);
+        var bootrom: [256]u8 = @splat(0xFF);
+        @memcpy(bootrom[0..stage2_rom.len], stage2_rom);
 
-    var bootrom: [256]u8 = @splat(0xFF);
-    @memcpy(bootrom[0..stage2_rom.len], stage2_rom);
+        // 2.8.1.3.1. Checksum
+        // The last four bytes of the image loaded from flash (which we hope is a valid flash second stage) are a CRC32 checksum
+        // of the first 252 bytes. The parameters of the checksum are:
+        // • Polynomial: 0x04c11db7
+        // • Input reflection: no
+        // • Output reflection: no
+        // • Initial value: 0xffffffff
+        // • Final XOR: 0x00000000
+        // • Checksum value appears as little-endian integer at end of image
+        // The Bootrom makes 128 attempts of approximately 4ms each for a total of approximately 0.5 seconds before giving up
+        // and dropping into USB code to load and checksum the second stage with varying SPI parameters. If it sees a checksum
+        // pass it will immediately jump into the 252-byte payload which contains the flash second stage.
+        const Hash = std.hash.crc.Crc(u32, .{
+            .polynomial = 0x04c11db7,
+            .initial = 0xffffffff,
+            .reflect_input = false,
+            .reflect_output = false,
+            .xor_output = 0x00000000,
+        });
 
-    // 2.8.1.3.1. Checksum
-    // The last four bytes of the image loaded from flash (which we hope is a valid flash second stage) are a CRC32 checksum
-    // of the first 252 bytes. The parameters of the checksum are:
-    // • Polynomial: 0x04c11db7
-    // • Input reflection: no
-    // • Output reflection: no
-    // • Initial value: 0xffffffff
-    // • Final XOR: 0x00000000
-    // • Checksum value appears as little-endian integer at end of image
-    // The Bootrom makes 128 attempts of approximately 4ms each for a total of approximately 0.5 seconds before giving up
-    // and dropping into USB code to load and checksum the second stage with varying SPI parameters. If it sees a checksum
-    // pass it will immediately jump into the 252-byte payload which contains the flash second stage.
-    const Hash = std.hash.crc.Crc(u32, .{
-        .polynomial = 0x04c11db7,
-        .initial = 0xffffffff,
-        .reflect_input = false,
-        .reflect_output = false,
-        .xor_output = 0x00000000,
-    });
+        std.mem.writeInt(u32, bootrom[252..256], Hash.hash(bootrom[0..252]), .little);
 
-    std.mem.writeInt(u32, bootrom[252..256], Hash.hash(bootrom[0..252]), .little);
+        return bootrom;
+    }
 
-    break :blk bootrom;
+    export const bootloader_data: [256]u8 linksection(".boot2") = prepare_boot_sector(@embedFile("bootloader"));
 };

port/raspberrypi/rp2xxx/src/boards/shared/rp2040_bootrom.zig

@@ -15,38 +15,23 @@ pub const PAGE_SIZE = 256;
 pub const SECTOR_SIZE = 4096;
 pub const BLOCK_SIZE = 65536;
 
-/// Bus reads to a 16MB memory window start at this address
+/// Bus reads to a 16MB memory window start at this address.
 pub const XIP_BASE = 0x10000000;
 
-/// After the bootrom enters the user application, it contains also a copy of
-/// the flash XIP setup function.
+/// After the bootrom enters the user application, a copy of the flash XIP
+/// setup function is found here on RP2350.
 pub const BOOTRAM_BASE = 0x400e0000;
 
-/// Flash code related to the second stage boot loader
-pub const boot2 = if (!microzig.config.ram_image) struct {
-    /// Size of the second stage bootloader in words
+/// Infrastructure for reentering XIP mode after exiting for programming.
+pub const boot2 = if (!microzig.config.ram_image and compatibility.arch == .arm) struct {
     const BOOT2_SIZE_WORDS = 64;
 
-    /// Buffer for the second stage bootloader
-    ///
-    /// The only job of the second stage bootloader is to configure the SSI and
-    /// the external flash for the best possible execute-in-place (XIP)
-    /// performance. Until the SSI is correctly configured for the attached
-    /// flash device, it's not possible to access flash via the XIP address
-    /// window, i.e., we have to copy the bootloader into sram before calling
-    /// `rom.flash_exit_xip`. This is required if we want to erase and/or write
-    /// to flash.
-    ///
-    /// At the end we can then just make a subroutine call to copyout, to
-    /// configure the SSI and flash. The second stage bootloader will return to
-    /// the calling function if a return address is provided in `lr`.
     var copyout: [BOOT2_SIZE_WORDS]u32 = undefined;
     var copyout_valid: bool = false;
 
-    /// Copy the 2nd stage bootloader into memory
-    ///
-    /// This is required by `_range_erase` and `_range_program` so we can later
-    /// setup XIP via the second stage bootloader.
+    /// Copies the XIP setup function into RAM:
+    /// - On RP2040 this *is* the second stage bootloader
+    /// - On RP2350 it is found at BOOTRAM_BASE.
     pub export fn flash_init() linksection(".ram_text") void {
         if (copyout_valid) return;
         const bootloader = @as([*]u32, @ptrFromInt(switch (compatibility.chip) {
@@ -61,25 +46,23 @@ pub const boot2 = if (!microzig.config.ram_image) struct {
         copyout_valid = true;
     }
 
-    /// Configure the SSI and the external flash for XIP by calling the second
-    /// stage bootloader that was copied out to `copyout`.
+    /// Configure the SSI and the external flash for XIP using the XIP setup
+    /// function that was copied out to `copyout`.
     pub export fn flash_enable_xip() linksection(".ram_text") void {
-        const f: *const fn () callconv(.c) void = @ptrCast(&copyout);
-        f();
+
+        // Calling boot2 as a function works because it accepts a return vector in
+        // LR (and doesn't trash r4-r7). Bootrom passes NULL in LR, instructing
+        // boot2 to enter flash vector table's reset handler.
+        @as(*const fn () callconv(.c) void, @ptrFromInt(@intFromPtr(&copyout) + 1))();
     }
 } else struct {
     // no op
     pub inline fn flash_init() linksection(".ram_text") void {}
 
-    /// Configure the SSI and the external flash for XIP by calling the second
-    /// stage bootloader embedded into RAM.
+    // Fallback. This is a very slow XIP configuration, but is very widely
+    // supported.
     pub inline fn flash_enable_xip() linksection(".ram_text") void {
-        if (compatibility.chip == .RP2040 and @hasDecl(microzig.board, "bootrom")) {
-            const f: *const fn () callconv(.c) void = @ptrCast(microzig.board.bootrom.stage2_rom.ptr);
-            f();
-        } else {
-            rom.flash_enter_cmd_xip();
-        }
+        rom.flash_enter_cmd_xip();
     }
 };