tools: Add printer tool (#622)

* commit files

* fix formatting

* add ci

* add testing

* devlog and final touches

* add tests folder in build.zig.zon

* try to fix testing

* fix testing and add elfs

* refactoring and fix testing

* refactor

* cleanup and fix formatting

Author: tact1m4n3

.github/workflows/ci.yml

@@ -77,6 +77,27 @@ jobs:
         run: zig build test
         working-directory: tools/esp-image
 
+  test-printer:
+    name: Test Printer
+    continue-on-error: true
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Zig
+        uses: mlugg/setup-zig@v2
+        with:
+          version: ${{ env.ZIG_VERSION }}
+      - name: Build Printer
+        run: zig build
+        working-directory: tools/printer
+      - name: Test Printer
+        run: zig build test
+        working-directory: tools/printer
+
   stm32-gen-check:
     name: Check that stm32 generated code is up to date
     continue-on-error: true

build.zig

@@ -346,9 +346,15 @@ pub fn MicroBuild(port_select: PortSelect) type {
             ///     exe.link_function_sections = true;
             strip_unused_symbols: bool = true,
 
-            /// Unwind tables option for the firmware executable
+            /// Unwind tables option for the firmware executable.
             unwind_tables: ?std.builtin.UnwindTables = null,
 
+            /// Error tracing option for the firmware executable.
+            error_tracing: ?bool = null,
+
+            /// Dwarf format option for the firmware executable.
+            dwarf_format: ?std.dwarf.Format = null,
+
             /// Additional patches the user may apply to the generated register
             /// code. This does not override the chip's existing patches.
             patches: []const regz.patch.Patch = &.{},
@@ -535,6 +541,8 @@ pub fn MicroBuild(port_select: PortSelect) type {
                         .single_threaded = options.single_threaded orelse target.single_threaded,
                         .strip = options.strip,
                         .unwind_tables = options.unwind_tables,
+                        .error_tracing = options.error_tracing,
+                        .dwarf_format = options.dwarf_format,
                     }),
                     .linkage = .static,
                 }),

tools/printer/README.md

@@ -0,0 +1,12 @@
+# Printer
+
+Printer is a tool to process logging output from your code and print it in a
+readable and pretty format. As of now it only annotates addresses from stack
+traces with source code locations, but it can be extended later to also print
+defmt (when this kind of logger will be added to microzig).
+
+## Use it like a library!
+
+You can easily write a small zig script that flashes the device and then prints
+pretty logs to console on `zig build run`. Checkout
+[](examples/rp2xxx_runner.zig)

tools/printer/build.zig

@@ -0,0 +1,113 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const serial_dep = b.dependency("serial", .{
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const printer_mod = b.addModule("printer", .{
+        .root_source_file = b.path("src/root.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const printer_exe = b.addExecutable(.{
+        .name = "printer",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/main.zig"),
+            .imports = &.{
+                .{ .name = "printer", .module = printer_mod },
+            },
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    b.installArtifact(printer_exe);
+
+    const example_exe = b.addExecutable(.{
+        .name = "rp2xxx_runner",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("examples/rp2xxx_runner.zig"),
+            .imports = &.{
+                .{ .name = "printer", .module = printer_mod },
+                .{ .name = "serial", .module = serial_dep.module("serial") },
+            },
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    b.installArtifact(example_exe);
+
+    const test_common_mod = b.createModule(.{
+        .root_source_file = b.path("tests/common.zig"),
+        .imports = &.{
+            .{ .name = "printer", .module = printer_mod },
+        },
+    });
+
+    const generate_test_data_exe = b.addExecutable(.{
+        .name = "generate_results",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("tests/generate_test_data.zig"),
+            .imports = &.{
+                .{ .name = "common", .module = test_common_mod },
+                .{ .name = "printer", .module = printer_mod },
+            },
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+
+    const test_exe = b.addExecutable(.{
+        .name = "test",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("tests/test.zig"),
+            .imports = &.{
+                .{ .name = "common", .module = test_common_mod },
+                .{ .name = "printer", .module = printer_mod },
+            },
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+
+    const generate_test_data_run = b.addRunArtifact(generate_test_data_exe);
+    if (b.option(bool, "rebuild-test-elf", "rebuild the test program elf") == true) {
+        const mz_dep = b.lazyDependency("microzig", .{}) orelse return;
+
+        const mb = @import("microzig").MicroBuild(.{
+            .rp2xxx = true,
+        }).init(b, mz_dep) orelse return;
+
+        generate_test_data_run.addFileArg(blk: {
+            break :blk mb.add_firmware(.{
+                .name = "test_program.dwarf32",
+                .root_source_file = b.path("tests/test_program.zig"),
+                .optimize = .Debug,
+                .target = mb.ports.rp2xxx.boards.raspberrypi.pico2_arm,
+                .dwarf_format = .@"32",
+            }).get_emitted_elf();
+        });
+
+        generate_test_data_run.addFileArg(blk: {
+            break :blk mb.add_firmware(.{
+                .name = "test_program.dwarf64",
+                .root_source_file = b.path("tests/test_program.zig"),
+                .optimize = .Debug,
+                .target = mb.ports.rp2xxx.boards.raspberrypi.pico2_arm,
+                .dwarf_format = .@"64",
+            }).get_emitted_elf();
+        });
+    }
+
+    const generate_test_results_step = b.step("generate-test-data", "regenerate test data");
+    generate_test_results_step.dependOn(&generate_test_data_run.step);
+
+    const run_tests_run = b.addRunArtifact(test_exe);
+    const run_tests_step = b.step("test", "test printer");
+    run_tests_step.dependOn(&run_tests_run.step);
+}

tools/printer/build.zig.zon

@@ -0,0 +1,22 @@
+.{
+    .name = .tools_printer,
+    .version = "0.0.0",
+    .fingerprint = 0x72009d00e5692d30,
+    .minimum_zig_version = "0.14.1",
+    .dependencies = .{
+        .serial = .{
+            .url = "git+https://github.com/ZigEmbeddedGroup/serial#ad338133eda8d86332718bbdc58c641a66307c84",
+            .hash = "serial-0.0.1-PoeRzI20AABcp4FffI6HXKOL6LcGPKmeqfN4Bna4-YYm",
+        },
+        // use to compile the test program
+        .microzig = .{ .path = "../..", .lazy = true },
+    },
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "README.md",
+        "src",
+        "examples",
+        "tests",
+    },
+}

tools/printer/examples/rp2xxx_runner.zig

@@ -0,0 +1,64 @@
+const std = @import("std");
+const printer = @import("printer");
+const serial = @import("serial");
+
+pub fn main() !void {
+    var debug_allocator: std.heap.DebugAllocator(.{}) = .init;
+    defer _ = debug_allocator.deinit();
+    const allocator = debug_allocator.allocator();
+
+    const args = try std.process.argsAlloc(allocator);
+    defer std.process.argsFree(allocator, args);
+
+    if (args.len != 4) return error.UsageError;
+
+    const elf_path = args[1];
+    const serial_device_path = args[2];
+    const baud_rate = try std.fmt.parseInt(u32, args[3], 10);
+
+    const elf_file = try std.fs.cwd().openFile(elf_path, .{});
+    defer elf_file.close();
+
+    var elf = try printer.Elf.init(allocator, elf_file);
+    defer elf.deinit(allocator);
+
+    var debug_info = try printer.DebugInfo.init(allocator, elf);
+    defer debug_info.deinit(allocator);
+
+    var annotator: printer.Annotator = .init;
+
+    const serial_device = try std.fs.cwd().openFile(serial_device_path, .{});
+    defer serial_device.close();
+    try serial.configureSerialPort(serial_device, .{
+        .baud_rate = baud_rate,
+    });
+    try serial.flushSerialPort(serial_device, .both);
+
+    {
+        var flash_cmd: std.process.Child = .init(&.{
+            "picotool",
+            "load",
+            "-u",
+            "-v",
+            "-x",
+            "-t",
+            "elf",
+            elf_path,
+        }, allocator);
+        const term = try flash_cmd.spawnAndWait();
+        switch (term) {
+            .Exited => |code| if (code != 0) return error.FlashCommandFailed,
+            else => {},
+        }
+    }
+
+    const stdout = std.io.getStdOut();
+    const out_stream = stdout.writer();
+    const out_tty_config = std.io.tty.detectConfig(stdout);
+
+    var buf: [4096]u8 = undefined;
+    while (true) {
+        const n = try serial_device.read(&buf);
+        try annotator.process(buf[0..n], elf, &debug_info, out_stream, out_tty_config);
+    }
+}