Matt Knight
2 years ago
committed by
GitHub
parent
0936dfb05c
commit
a2dd362ce7
@ -1,135 +1,133 @@
|
|||||||
|
:imagesdir: design
|
||||||
|
:toc: macro
|
||||||
[](https://discord.gg/ShUWykk38X)
|
|
||||||
|
image::logo-text-auto.svg[]
|
||||||
## NOTE: in development
|
|
||||||
|
image::https://img.shields.io/discord/824493524413710336.svg?logo=discord[link=https://discord.gg/ShUWykk38X]
|
||||||
APIs will likely break in the future
|
|
||||||
|
[NOTE]
|
||||||
# Table of Contents
|
This is in development, breaks in the API are bound to happen
|
||||||
|
|
||||||
- [Contributing](#contributing)
|
toc::[]
|
||||||
- [Introduction](#introduction)
|
|
||||||
- [How to](#how-to)
|
== Contributing
|
||||||
- [Embedded project with "supported" chip/board](#embedded-project-with-supported-chipboard)
|
|
||||||
- [Embedded project with "unsupported" chip](#embedded-project-with-unsupported-chip)
|
Please see the https://github.com/orgs/ZigEmbeddedGroup/projects/1/views/1[project page], its used as a place to brainstorm and organize work in ZEG.
|
||||||
- [Interrupts](#interrupts)
|
There will be issues marked as `good first issue`, or drafts for larger ideas that need scoping/breaking ground on.
|
||||||
|
|
||||||
<!-- Created by https://github.com/ekalinin/github-markdown-toc -->
|
== Introduction
|
||||||
|
|
||||||
## Contributing
|
This repo contains the infrastructure for getting started in an embedded Zig project, as well as some code to interact with some chips/boards.
|
||||||
|
Specifically it offers:
|
||||||
Please see the [project page](https://github.com/orgs/ZigEmbeddedGroup/projects/1/views/1), its used as a place to brainstorm and organize work in ZEG.
|
|
||||||
There will be issues marked as `good first issue`, or drafts for larger ideas that need scoping/breaking ground on.
|
* a single easy-to-use builder function that:
|
||||||
|
** generates your linker script
|
||||||
## Introduction
|
** sets up packages and start code
|
||||||
|
* generalized interfaces for common devices, such as UART.
|
||||||
This repo contains the infrastructure for getting started in an embedded Zig project, as well as some code to interact with some chips/boards. Specifically it offers:
|
* device drivers for interacting with external hardware
|
||||||
|
* an uncomplicated method to define xref:interrupts[interrupts]
|
||||||
- a single easy-to-use builder function that:
|
|
||||||
- generates your linker script
|
== How to
|
||||||
- sets up packages and start code
|
|
||||||
- generalized interfaces for common devices, such as UART.
|
Here's a number of things you might be interested in doing, and how to achieve them with microzig and other ZEG tools.
|
||||||
- device drivers for interacting with external hardware
|
|
||||||
- an uncomplicated method to define [interrupts](#interrupts)
|
=== Embedded project with "supported" chip/board
|
||||||
|
|
||||||
## How to
|
Start with an empty Zig project by running `zig init-exe`, and add microzig as a git submodule (or your choice of package manager).
|
||||||
|
Then in your `build.zig`:
|
||||||
Here's a number of things you might be interested in doing, and how to achieve them with microzig and other ZEG tools.
|
|
||||||
|
[source,zig]
|
||||||
### Embedded project with "supported" chip/board
|
----
|
||||||
|
const std = @import("std");
|
||||||
Start with an empty Zig project by running `zig init-exe`, and add microzig as a git submodule (or your choice of package manager).
|
const microzig = @import("path/to/microzig/src/main.zig");
|
||||||
Then in your `build.zig`:
|
|
||||||
|
pub fn build(b: *std.build.Builder) !void {
|
||||||
```zig
|
const backing = .{
|
||||||
const std = @import("std");
|
.board = microzig.boards.arduino_nano,
|
||||||
const microzig = @import("path/to/microzig/src/main.zig");
|
|
||||||
|
// if you don't have one of the boards, but do have one of the
|
||||||
pub fn build(b: *std.build.Builder) !void {
|
// "supported" chips:
|
||||||
const backing = .{
|
// .chip = microzig.chips.atmega328p,
|
||||||
.board = microzig.boards.arduino_nano,
|
};
|
||||||
|
|
||||||
// if you don't have one of the boards, but do have one of the
|
const exe = try microzig.addEmbeddedExecutable(
|
||||||
// "supported" chips:
|
b,
|
||||||
// .chip = microzig.chips.atmega328p,
|
"my-executable",
|
||||||
};
|
"src/main.zig",
|
||||||
|
backing,
|
||||||
const exe = try microzig.addEmbeddedExecutable(
|
.{
|
||||||
b,
|
// optional slice of packages that can be imported into your app:
|
||||||
"my-executable",
|
// .packages = &my_packages,
|
||||||
"src/main.zig",
|
},
|
||||||
backing,
|
);
|
||||||
.{
|
exe.setBuildMode(.ReleaseSmall);
|
||||||
// optional slice of packages that can be imported into your app:
|
exe.install();
|
||||||
// .packages = &my_packages,
|
}
|
||||||
},
|
----
|
||||||
);
|
|
||||||
exe.setBuildMode(.ReleaseSmall);
|
`zig build` and now you have an executable for an Arduino Nano.
|
||||||
exe.install();
|
In your application you can import `microzig` in order to interact with the hardware:
|
||||||
}
|
|
||||||
```
|
[source,zig]
|
||||||
|
----
|
||||||
`zig build` and now you have an executable for an Arduino Nano.
|
const microzig = @import("microzig");
|
||||||
In your application you can import `microzig` in order to interact with the hardware:
|
|
||||||
|
// `microzig.chip.registers`: access to register definitions
|
||||||
```zig
|
|
||||||
const microzig = @import("microzig");
|
pub fn main() !void {
|
||||||
|
// your program here
|
||||||
// `microzig.chip.registers`: access to register definitions
|
}
|
||||||
|
----
|
||||||
pub fn main() !void {
|
|
||||||
// your program here
|
=== Embedded project with "unsupported" chip
|
||||||
}
|
|
||||||
```
|
If you have a board/chip that isn't defined in microzig, you can set it up yourself!
|
||||||
|
You need to have:
|
||||||
### Embedded project with "unsupported" chip
|
|
||||||
|
* SVD or ATDF file defining registers
|
||||||
If you have a board/chip that isn't defined in microzig, you can set it up yourself!
|
* flash and ram address and sizes
|
||||||
You need to have:
|
|
||||||
|
First use https://github.com/ZigEmbeddedGroup/regz[regz] to generate the register definitions for your chip and save them to a file.
|
||||||
- SVD or ATDF file defining registers
|
Then your `build.zig` is going to be the same, but you'll define the chip yourself:
|
||||||
- flash and ram address and sizes
|
|
||||||
|
[source,zig]
|
||||||
First use [regz](https://github.com/ZigEmbeddedGroup/regz) to generate the register definitions for your chip and save them to a file.
|
----
|
||||||
Then your `build.zig` is going to be the same, but you'll define the chip yourself:
|
const nrf52832 = Chip{
|
||||||
|
.name = "nRF52832",
|
||||||
```zig
|
.path = "path/to/generated/file.zig",
|
||||||
const nrf52832 = Chip{
|
.cpu = cpus.cortex_m4,
|
||||||
.name = "nRF52832",
|
.memory_regions = &.{
|
||||||
.path = "path/to/generated/file.zig",
|
MemoryRegion{ .offset = 0x00000000, .length = 0x80000, .kind = .flash },
|
||||||
.cpu = cpus.cortex_m4,
|
MemoryRegion{ .offset = 0x20000000, .length = 0x10000, .kind = .ram },
|
||||||
.memory_regions = &.{
|
},
|
||||||
MemoryRegion{ .offset = 0x00000000, .length = 0x80000, .kind = .flash },
|
};
|
||||||
MemoryRegion{ .offset = 0x20000000, .length = 0x10000, .kind = .ram },
|
|
||||||
},
|
const backing = .{
|
||||||
};
|
.chip = nrf52832,
|
||||||
|
};
|
||||||
const backing = .{
|
----
|
||||||
.chip = nrf52832,
|
|
||||||
};
|
[NOTE]
|
||||||
```
|
`regz` is also still in development, and while it tends to generate code well, it's possible that there will be errors in the generated code!
|
||||||
|
Please create an issue if you run into anything fishy.
|
||||||
NOTE: `regz` is also still in development, and while it tends to generate code well, it's possible that there will be errors in the generated code!
|
|
||||||
Please create an issue if you run into anything fishy.
|
=== Interrupts
|
||||||
|
|
||||||
### Interrupts
|
The current supported architectures for interrupt vector generation are ARM and AVR.
|
||||||
|
To define the Interrupt Service Routine (ISR) for a given interrupt, you create a function with the same name in an `interrupts` namespace:
|
||||||
The current supported architectures for interrupt vector generation are ARM and AVR.
|
|
||||||
To define the Interrupt Service Routine (ISR) for a given interrupt, you create a function with the same name in an `interrupts` namespace:
|
[source,zig]
|
||||||
|
----
|
||||||
```zig
|
pub const interrupts = struct {
|
||||||
|
pub fn PCINT0() void {
|
||||||
pub const interrupts = struct {
|
// interrupt handling code
|
||||||
pub fn PCINT0() void {
|
}
|
||||||
// interrupt handling code
|
};
|
||||||
}
|
|
||||||
};
|
pub fn main() !void {
|
||||||
|
// my application
|
||||||
pub fn main() !void {
|
}
|
||||||
// my application
|
----
|
||||||
}
|
|
||||||
```
|
We're using compile-time checks along with the generated code to determine the list of interrupts.
|
||||||
|
If a function is defined whose name is not in this list, you'll get a compiler error with the list of interrupts/valid names.
|
||||||
We're using compile-time checks along with the generated code to determine the list of interrupts.
|
|
||||||
If a function is defined whose name is not in this list, you'll get a compiler error with the list of interrupts/valid names.
|
|
||||||
Loading…
Reference in New Issue