From c8bd2a2712ba1d795431c1030494fb0e4196417c Mon Sep 17 00:00:00 2001
From: tanche <18555580+lcp5y3@users.noreply.github.com>
Date: Thu, 16 Jan 2025 03:43:20 +0100
Subject: [PATCH] add an example of how to use MicroZig without HAL (#344)

* add an example of how to use MicroZig without HAL

* move no hal example to a dedicated folder

---------

Co-authored-by: lcp5y3 <>
Co-authored-by: tanche <oruz@mailz.org>
---
 examples/no_hal/stm32_l031/LICENSE        | 19 ++++++++++
 examples/no_hal/stm32_l031/build.zig      | 46 +++++++++++++++++++++++
 examples/no_hal/stm32_l031/build.zig.zon  | 14 +++++++
 examples/no_hal/stm32_l031/readme.md      |  6 +++
 examples/no_hal/stm32_l031/src/blinky.zig | 20 ++++++++++
 5 files changed, 105 insertions(+)
 create mode 100644 examples/no_hal/stm32_l031/LICENSE
 create mode 100644 examples/no_hal/stm32_l031/build.zig
 create mode 100644 examples/no_hal/stm32_l031/build.zig.zon
 create mode 100644 examples/no_hal/stm32_l031/readme.md
 create mode 100644 examples/no_hal/stm32_l031/src/blinky.zig

diff --git a/examples/no_hal/stm32_l031/LICENSE b/examples/no_hal/stm32_l031/LICENSE
new file mode 100644
index 000000000..33640972a
--- /dev/null
+++ b/examples/no_hal/stm32_l031/LICENSE
@@ -0,0 +1,19 @@
+Copyright (c) Zig Embedded Group contributors
+
+This software is provided 'as-is', without any express or implied warranty. In
+no event will the authors be held liable for any damages arising from the use
+of this software.
+
+Permission is granted to anyone to use this software for any purpose, including
+commercial applications, and to alter it and redistribute it freely, subject to
+the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not claim
+   that you wrote the original software. If you use this software in a product,
+   an acknowledgment in the product documentation would be appreciated but is
+   not required.
+
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+
+3. This notice may not be removed or altered from any source distribution.
diff --git a/examples/no_hal/stm32_l031/build.zig b/examples/no_hal/stm32_l031/build.zig
new file mode 100644
index 000000000..06c81c79f
--- /dev/null
+++ b/examples/no_hal/stm32_l031/build.zig
@@ -0,0 +1,46 @@
+const std = @import("std");
+const microzig = @import("microzig");
+
+const MicroBuild = microzig.MicroBuild(.{
+    .stm32 = true,
+});
+
+pub fn build(b: *std.Build) void {
+    const optimize = b.standardOptimizeOption(.{});
+
+    const mz_dep = b.dependency("microzig", .{});
+    const mb = MicroBuild.init(b, mz_dep) orelse return;
+
+    const available_examples = [_]Example{
+        .{ .target = mb.ports.stm32.chips.STM32L031K6, .name = "STM32L031K6", .file = "src/blinky.zig" },
+    };
+
+    for (available_examples) |example| {
+        // `add_firmware` basically works like addExecutable, but takes a
+        // `microzig.Target` for target instead of a `std.zig.CrossTarget`.
+        //
+        // The target will convey all necessary information on the chip,
+        // cpu and potentially the board as well.
+        const fw = mb.add_firmware(.{
+            .name = example.name,
+            .target = example.target,
+            .optimize = optimize,
+            .root_source_file = b.path(example.file),
+        });
+
+        // `install_firmware()` is the MicroZig pendant to `Build.installArtifact()`
+        // and allows installing the firmware as a typical firmware file.
+        //
+        // This will also install into `$prefix/firmware` instead of `$prefix/bin`.
+        mb.install_firmware(fw, .{});
+
+        // For debugging, we also always install the firmware as an ELF file
+        mb.install_firmware(fw, .{ .format = .elf });
+    }
+}
+
+const Example = struct {
+    target: *const microzig.Target,
+    name: []const u8,
+    file: []const u8,
+};
diff --git a/examples/no_hal/stm32_l031/build.zig.zon b/examples/no_hal/stm32_l031/build.zig.zon
new file mode 100644
index 000000000..6be821502
--- /dev/null
+++ b/examples/no_hal/stm32_l031/build.zig.zon
@@ -0,0 +1,14 @@
+.{
+    .name = "examples/stmicro/stm32",
+    .version = "0.0.0",
+    .dependencies = .{
+        .microzig = .{ .path = "../../.." },
+    },
+
+    .paths = .{
+        "LICENSE",
+        "build.zig",
+        "build.zig.zon",
+        "src",
+    },
+}
diff --git a/examples/no_hal/stm32_l031/readme.md b/examples/no_hal/stm32_l031/readme.md
new file mode 100644
index 000000000..a784cb936
--- /dev/null
+++ b/examples/no_hal/stm32_l031/readme.md
@@ -0,0 +1,6 @@
+# MicroZig Without HAL
+
+This example show you how to use MicroZig without HAL.
+In this example, we use direct register access to toggle
+an outuput GPIO.
+
diff --git a/examples/no_hal/stm32_l031/src/blinky.zig b/examples/no_hal/stm32_l031/src/blinky.zig
new file mode 100644
index 000000000..6438e5927
--- /dev/null
+++ b/examples/no_hal/stm32_l031/src/blinky.zig
@@ -0,0 +1,20 @@
+const std = @import("std");
+const microzig = @import("microzig");
+const chip = microzig.chip;
+const RCC = chip.peripherals.RCC;
+const GPIOB = chip.peripherals.GPIOB;
+const GPIO_TYPE = chip.types.peripherals.gpio_v2;
+
+pub fn main() !void {
+    RCC.GPIOENR.modify(.{ .GPIOBEN = 1 });
+    GPIOB.MODER.modify(.{ .@"MODER[3]" = GPIO_TYPE.MODER.Output });
+
+    while (true) {
+        var i: u32 = 0;
+        while (i < 100_000) {
+            asm volatile ("nop");
+            i += 1;
+        }
+        GPIOB.ODR.raw = (GPIOB.ODR.raw ^ 0x8);
+    }
+}