Linker script generation update (#588)

Author: tact1m4n3

build-internals/build.zig

@@ -59,10 +59,10 @@ pub const Target = struct {
     /// if present.
     board: ?Board = null,
 
-    /// (optional) Provide a custom linker script for the hardware or define a custom generation.
-    linker_script: ?LazyPath = null,
+    /// Provide a custom linker script for the hardware or define a custom generation.
+    linker_script: LinkerScript = .{},
 
-    /// (Optional) Explicitly set the entry point
+    /// (optional) Explicitly set the entry point.
     entry: ?Build.Step.Compile.Entry = null,
 
     /// (optional) Post processing step that will patch up and modify the elf file if necessary.
@@ -79,7 +79,7 @@ pub const Target = struct {
         ram_image: ?bool = null,
         hal: ?HardwareAbstractionLayer = null,
         board: ?Board = null,
-        linker_script: ?LazyPath = null,
+        linker_script: ?LinkerScript = null,
         entry: ?Build.Step.Compile.Entry = null,
         patch_elf: ?*const fn (*Build.Dependency, LazyPath) LazyPath = null,
     };
@@ -206,11 +206,10 @@ pub const BinaryFormat = union(enum) {
     pub fn get_extension(format: BinaryFormat) []const u8 {
         return switch (format) {
             .elf => ".elf",
-            .bin => ".bin",
+            .bin, .esp => ".bin",
             .hex => ".hex",
             .dfu => ".dfu",
             .uf2 => ".uf2",
-            .esp => ".bin",
 
             .custom => |c| c.extension,
         };
@@ -225,41 +224,74 @@ pub const BinaryFormat = union(enum) {
     };
 };
 
+pub const LinkerScript = struct {
+    /// Will anything be auto-generated for this linker script?
+    generate: GenerateOptions = .{ .memory_regions_and_sections = .{} },
+    /// Linker script path. Will be appended after what is auto-generated if it's not null.
+    file: ?LazyPath = null,
+
+    pub const GenerateOptions = union(enum) {
+        /// Only generates a comment with target info.
+        none,
+        /// Only generates memory regions.
+        memory_regions,
+        /// Generates memory regions and default sections based on the provided options.
+        memory_regions_and_sections: struct {
+            /// Where should rodata go?
+            rodata_location: enum {
+                /// Place rodata in the first region tagged as flash.
+                flash,
+                /// Place rodata in the first region tagged as ram.
+                ram,
+            } = .flash,
+        },
+    };
+};
+
 /// A descriptor for memory regions in a microcontroller.
 pub const MemoryRegion = struct {
-    /// The type of the memory region for generating a proper linker script.
-    kind: Kind,
+    name: ?[]const u8 = null,
+    tag: Tag = .none,
     offset: u64,
     length: u64,
+    access: Access,
+
+    pub fn validate_tag(region: MemoryRegion) void {
+        switch (region.tag) {
+            .flash => if (!region.access.read or !region.access.execute)
+                @panic("memory regions tagged as `flash` must be executable"),
+            .ram => if (!region.access.read or !region.access.write)
+                @panic("memory regions tagged as `ram` must be both readable and writable"),
+            else => {},
+        }
+    }
 
-    pub const Kind = union(enum) {
+    pub const Tag = enum {
         /// This is a (normally) immutable memory region where the code is stored.
         flash,
 
         /// This is a mutable memory region for data storage.
         ram,
 
-        /// This is a memory region that maps MMIO devices.
-        io,
-
-        /// This is a memory region that exists, but is reserved and must not be used.
-        reserved,
-
-        /// This is a memory region used for internal linking tasks required by the board support package.
-        private: PrivateRegion,
+        /// No tag.
+        none,
     };
 
-    pub const PrivateRegion = struct {
-        /// The name of the memory region. Will not have an automatic numeric counter and must be unique.
-        name: []const u8,
-
-        /// Is the memory region executable?
-        executable: bool,
+    pub const Access = struct {
+        pub const r: Access = .{ .read = true };
+        pub const w: Access = .{ .write = true };
+        pub const x: Access = .{ .execute = true };
+        pub const rw: Access = .{ .read = true, .write = true };
+        pub const rx: Access = .{ .read = true, .execute = true };
+        pub const rwx: Access = .{ .read = true, .write = true, .execute = true };
 
         /// Is the memory region readable?
-        readable: bool,
+        read: bool = false,
 
         /// Is the memory region writable?
-        writeable: bool,
+        write: bool = false,
+
+        /// Is the memory region executable?
+        execute: bool = false,
     };
 };

build.zig

@@ -9,6 +9,7 @@ pub const Chip = internals.Chip;
 pub const HardwareAbstractionLayer = internals.HardwareAbstractionLayer;
 pub const Board = internals.Board;
 pub const BinaryFormat = internals.BinaryFormat;
+pub const LinkerScript = internals.LinkerScript;
 pub const MemoryRegion = internals.MemoryRegion;
 
 const regz = @import("tools/regz");
@@ -330,7 +331,7 @@ pub fn MicroBuild(port_select: PortSelect) type {
             board: ?Board = null,
 
             /// If set, overrides the `linker_script` property of the target.
-            linker_script: ?LazyPath = null,
+            linker_script: ?LinkerScript = null,
 
             /// If set, overrides the default `entry` property of the arget.
             entry: ?Build.Step.Compile.Entry = null,
@@ -370,11 +371,16 @@ pub fn MicroBuild(port_select: PortSelect) type {
 
             const target = options.target;
 
+            // validate that tagged memory regions meet the requirements
+            for (target.chip.memory_regions) |region| {
+                region.validate_tag();
+            }
+
             // TODO: let the user override which ram section to use the stack on,
             // for now just using the first ram section in the memory region list
             const first_ram = blk: {
                 for (target.chip.memory_regions) |region| {
-                    if (region.kind == .ram)
+                    if (region.tag == .ram)
                         break :blk region;
                 } else @panic("no ram memory region found for setting the end-of-stack address");
             };
@@ -547,17 +553,22 @@ pub fn MicroBuild(port_select: PortSelect) type {
             fw.artifact.root_module.addImport("microzig", core_mod);
             fw.artifact.root_module.addImport("app", app_mod);
 
-            // If not specified then generate the linker script
-            const linker_script = options.linker_script orelse target.linker_script orelse blk: {
+            const linker_script_options = options.linker_script orelse target.linker_script;
+            const linker_script = blk: {
                 const GenerateLinkerScriptArgs = @import("tools/generate_linker_script.zig").Args;
 
+                if (linker_script_options.file == null and linker_script_options.generate != .memory_regions_and_sections) {
+                    @panic("linker script: no file provided and no sections are auto-generated");
+                }
+
                 const generate_linker_script_exe = mb.dep.artifact("generate_linker_script");
 
                 const generate_linker_script_args: GenerateLinkerScriptArgs = .{
-                    .cpu_name = zig_resolved_target.result.cpu.model.name,
+                    .cpu_name = cpu.name,
                     .cpu_arch = zig_resolved_target.result.cpu.arch,
                     .chip_name = target.chip.name,
                     .memory_regions = target.chip.memory_regions,
+                    .generate = linker_script_options.generate,
                 };
 
                 const args_str = std.json.stringifyAlloc(
@@ -568,7 +579,11 @@ pub fn MicroBuild(port_select: PortSelect) type {
 
                 const generate_linker_script_run = b.addRunArtifact(generate_linker_script_exe);
                 generate_linker_script_run.addArg(args_str);
-                break :blk generate_linker_script_run.addOutputFileArg("linker.ld");
+                const output = generate_linker_script_run.addOutputFileArg("linker.ld");
+                if (linker_script_options.file) |file| {
+                    generate_linker_script_run.addFileArg(file);
+                }
+                break :blk output;
             };
             fw.artifact.setLinkerScript(linker_script);
 

docs/design.md

@@ -75,8 +75,8 @@ pub const stm32f103: microzig.Target = .{
             .zig = b.path("/path/to/file.zig"),
         },
         .memory_regions = &.{
-            .{ .offset = 0x08000000, .length = 64 * 1024, .kind = .flash },
-            .{ .offset = 0x20000000, .length = 20 * 1024, .kind = .ram },
+            .{ .tag = .flash, .offset = 0x08000000, .length = 64 * 1024, .access = .rx },
+            .{ .tag = .ram, .offset = 0x20000000, .length = 20 * 1024, .access = .rwx },
         },
     },
     .hal = .{
@@ -105,9 +105,171 @@ TODO
 
 TODO
 
-## Linkerscript Generation
+## Linker Script Generation
 
-TODO
+Every firmware needs a linker script that places stuff where it belongs in
+memory. When porting microzig to a new target you must face the challenge of
+dealing with a linker script. But fear not as microzig has your back (in most
+cases). Let's checkout the `linker_script` field in `Target`.
+
+```zig
+linker_script: LinkerScript = .{},
+```
+
+```zig
+pub const LinkerScript = struct {
+    /// Will anything be auto-generated for this linker script?
+    generate: GenerateOptions = .{ .memory_regions_and_sections = .{} },
+    /// Linker script path. Will be appended after what is auto-generated if it's not null.
+    file: ?LazyPath = null,
+
+    pub const GenerateOptions = union(enum) {
+        /// Only generates a comment with target info.
+        none,
+        /// Only generates memory regions.
+        memory_regions,
+        /// Generates memory regions and default sections based on the provided options.
+        memory_regions_and_sections: struct {
+            /// Where should rodata go?
+            rodata_location: enum {
+                /// Place rodata in the first region tagged as flash.
+                flash,
+                /// Place rodata in the first region tagged as ram.
+                ram,
+            } = .flash,
+        },
+    };
+};
+```
+
+For an example let's look at the target definition of rp2040. In this case we
+need a linker script that should also place the bootrom at the beginning of
+flash. Fortunately, we can still mostly auto-generate one and just patch it up
+a bit.
+
+```zig
+// port/raspberrypi/rp2xxx/build.zig
+
+const chip_rp2040: microzig.Target = .{
+    // ...
+    .chip = .{
+        // ...
+        .memory_regions = &.{
+            .{ .tag = .flash, .offset = 0x10000000, .length = 2048 * 1024, .access = .rx },
+            .{ .tag = .ram, .offset = 0x20000000, .length = 256 * 1024, .access = .rwx },
+        },
+    },
+    .linker_script = .{
+        // The `generate` field defaults to `.memory_regions_and_sections`.
+
+        // This will be appended at the end of the auto-generated linker
+        // script.
+        .file = b.path("ld/rp2040/sections.ld"),
+    },
+};
+```
+
+```ld
+/* port/raspberrypi/rp2xxx/ld/rp2040/sections.ld */
+
+SECTIONS
+{
+  .boot2 : {
+    __boot2_start__ = .;
+    KEEP (*(.boot2))
+    __boot2_end__ = .;
+  } > flash0
+
+  ASSERT(__boot2_end__ - __boot2_start__ == 256,
+    "ERROR: Pico second stage bootloader must be 256 bytes in size")
+}
+INSERT BEFORE .flash_start;
+```
+
+This is the generated linker script:
+
+```ld
+/*
+ * Target CPU:  cortex_m0plus
+ * Target Chip: RP2040
+ */
+
+/*
+ * This section was auto-generated by microzig.
+ */
+MEMORY
+{
+  flash0 (rx!w) : ORIGIN = 0x10000000, LENGTH = 0x00200000
+  ram0 (rwx) : ORIGIN = 0x20000000, LENGTH = 0x00040000
+}
+SECTIONS
+{
+  .flash_start :
+  {
+    KEEP(*(microzig_flash_start))
+  } > flash0
+
+  .text :
+  {
+    *(.text*)
+    *(.srodata*)
+    *(.rodata*)
+  } > flash0
+
+  .ARM.extab : {
+    *(.ARM.extab* .gnu.linkonce.armextab.*)
+  } > flash0
+
+  .ARM.exidx : {
+    *(.ARM.exidx* .gnu.linkonce.armexidx.*)
+  } > flash0
+
+  .data :
+  {
+    microzig_data_start = .;
+    *(.sdata*)
+    *(.data*)
+    KEEP(*(.ram_text))
+    microzig_data_end = .;
+  } > ram0 AT> flash0
+
+  .bss (NOLOAD) :
+  {
+    microzig_bss_start = .;
+    *(.sbss*)
+    *(.bss*)
+    microzig_bss_end = .;
+  } > ram0
+
+  .flash_end :
+  {
+    microzig_flash_end = .;
+  } > flash0
+
+  microzig_data_load_start = LOADADDR(.data);
+}
+/*
+ * End of auto-generated section.
+ */
+SECTIONS
+{
+  .boot2 : {
+    __boot2_start__ = .;
+    KEEP (*(.boot2))
+    __boot2_end__ = .;
+  } > flash0
+
+  ASSERT(__boot2_end__ - __boot2_start__ == 256,
+    "ERROR: Pico second stage bootloader must be 256 bytes in size")
+}
+INSERT BEFORE .flash_start;
+```
+
+### FYI
+- If the ram memory region used by the linker script generator is executable, a
+`.ram_text` section will be included for code that should be placed in ram.
+This applies to the rp2040 target where the section tagged as ram is
+executable.
 
 ## JSON register schema
 

examples/espressif/esp/src/systimer.zig

@@ -16,8 +16,7 @@ pub const microzig_options: microzig.Options = .{
 
 const alarm = systimer.alarm(0);
 
-// the `.trap` link section is placed in iram in image boot mode or irom in direct boot mode.
-fn timer_interrupt(_: *microzig.cpu.TrapFrame) linksection(".trap") callconv(.c) void {
+fn timer_interrupt(_: *microzig.cpu.TrapFrame) linksection(".ram_text") callconv(.c) void {
     std.log.info("timer interrupt!", .{});
 
     alarm.clear_interrupt();