Repository navigation
Add ARCHITECTURE.md - #1005
Add ARCHITECTURE.md#1005Grazfather wants to merge 4 commits into
Conversation
4ab4aa2 to
e83c5d6
Compare
bc28c03 to
f87d07b
Compare
f87d07b to
b819891
Compare
|
|
||
| MicroZig is a Zig framework for programming microcontrollers. It provides a unified build system, hardware abstraction | ||
| layers, and device drivers across 14+ microcontroller families (ARM Cortex-M, RISC-V, AVR, MSP430). The core idea: write | ||
| portable embedded code in Zig, with platform details handled by ports and a code-generating build system. |
There was a problem hiding this comment.
This is a bit too "write once run everywhere" and implies heavy abstraction. We don't push this on everyone. The core idea is more to add convenience to the low level aspects of targeting an MCU, but not getting in between the user and hardware.
There was a problem hiding this comment.
We should also specify that MicroZig is not a variant of the Zig language for microcontrollers. Many people ask me that when I tell them what I do and they guess what it is.
There was a problem hiding this comment.
nixed the whole last sentence.
| The foundational library that every firmware links against. Key files in `core/src/`: | ||
|
|
||
| - _microzig.zig_: Root API. Exposes `cpu`, `chip`, `hal`, `board`, `drivers` namespaces. Implements the default panic | ||
| handler, `export_startup()` for entry point generation, and `std_options()` for logging integration. |
There was a problem hiding this comment.
std_options isn't for logging integration, it just changes some defaults so we don't hit compile errors
| - _microzig.zig_: Root API. Exposes `cpu`, `chip`, `hal`, `board`, `drivers` namespaces. Implements the default panic | ||
| handler, `export_startup()` for entry point generation, and `std_options()` for logging integration. | ||
| - _mmio.zig_: `Mmio` generic type that wraps a packed struct into a volatile MMIO register interface with `read()`, | ||
| `write()`, `modify()`, `toggle()` methods. Validates register sizes at comptime. |
There was a problem hiding this comment.
"Validates register sizes at comptime" is unneeded.
| `write()`, `modify()`, `toggle()` methods. Validates register sizes at comptime. | ||
| - _interrupt.zig_: `enable()`, `disable()`, critical sections, `Mutex` (HAL-provided or fallback | ||
| `CriticalSectionMutex`), `Handler` union type. | ||
| - _allocator.zig_: Multi-tier free-list allocator. |
There was a problem hiding this comment.
The implementation details of the allocator are less important than the fact that it manages a fixed chunk of memory.
| vector tables. | ||
| - _riscv32.zig_: RISC-V 32-bit support. | ||
| - _avr_common.zig_, _avr25.zig_, _avr5.zig_: AVR architecture. | ||
| - _msp430.zig_, _msp430x.zig_: TI MSP430. |
There was a problem hiding this comment.
Is the point of this document to list other files? The comments here barely do more than restate the file name
There was a problem hiding this comment.
Yes. I can nix them if you want. I find it useful so you know what file to look for for each arch.
|
|
||
| ## Build System | ||
|
|
||
| The build system centers on `MicroBuild`, defined in the root `build.zig`. |
There was a problem hiding this comment.
The above section is completely redundant, remove it because this is far better.
| - **Ports are self-contained**. | ||
| - **Core is port-agnostic.** It receives chip/HAL/board configuration through comptime module imports injected by the | ||
| build system. | ||
| - **Register definitions are generated, not hand-written.** The source of truth is the vendor SVD/ATDF file plus |
There was a problem hiding this comment.
Fails to specify that patches are where the user fixes mistakes in vendors register schemas.
| to branch on chip features, CPU type, or board identity. HALs use it to select peripheral implementations, setup clocks, | ||
| etc. | ||
|
|
||
| **Startup sequence**: Each CPU architecture in _core/src/cpus/_ provides a `_start` entry point. The typical sequence |
There was a problem hiding this comment.
This is good but I think it's already been mentioned.
| **Startup sequence**: Each CPU architecture in _core/src/cpus/_ provides a `_start` entry point. The typical sequence | ||
| is: set stack pointer → zero BSS → copy `.data` from flash to RAM → call `microzig_main`. | ||
|
|
||
| **Naming conventions**: The codebase uses _snake_case_ (C-style), not the typical Zig camelCase. Run `zig fmt` for |
There was a problem hiding this comment.
Misses the type naming format we use.
| **Naming conventions**: The codebase uses _snake_case_ (C-style), not the typical Zig camelCase. Run `zig fmt` for | ||
| formatting. | ||
|
|
||
| **MMIO access**: All register access should go through `Mmio`. The packed struct defines the register layout, the `Mmio` |
There was a problem hiding this comment.
Most of this is redundant, and shouldn't be at the end of the file as an afterthought.
There was a problem hiding this comment.
added a blurb to the first mention above and removed this.
b819891 to
fa25885
Compare
fa25885 to
f95f22e
Compare
No description provided.