Integrates driver framework

.gitignore

@@ -1,11 +1,11 @@
-zig-out/
-zig-cache/
-.zig-cache/
-microzig-deploy/
+__pycache__/
+.direnv/
 .DS_Store
 .gdbinit
 .lldbinit
-.direnv/
-__pycache__/
 .venv
+.zig-cache/
 boxzer-out
+microzig-deploy/
+zig-cache/
+zig-out/

driver/base/DatagramDevice.zig

@@ -0,0 +1,180 @@
+//!
+//! An abstract datagram orientied device with runtime dispatch.
+//!
+//! Datagram devices behave similar to an SPI or Ethernet device where
+//! packets with an ahead-of-time known length can be transferred in a
+//! single transaction.
+//!
+
+const std = @import("std");
+
+const DatagramDevice = @This();
+
+const BaseError = error{ IoError, Timeout };
+
+pub const ConnectError = BaseError || error{DeviceBusy};
+
+/// Establishes a connection to the device (like activating a chip-select lane or similar).
+/// NOTE: Call `.disconnect()` when the usage of the device is done to release it.
+pub fn connect(dd: DatagramDevice) ConnectError!void {
+    if (dd.vtable.connectFn) |connectFn| {
+        return connectFn(dd.object);
+    }
+}
+
+/// Releases a device from the connection.
+pub fn disconnect(dd: DatagramDevice) void {
+    if (dd.vtable.disconnectFn) |disconnectFn| {
+        return disconnectFn(dd.object);
+    }
+}
+
+pub const WriteError = BaseError || error{ Unsupported, NotConnected };
+
+/// Writes a single `datagram` to the device.
+pub fn write(dd: DatagramDevice, datagram: []const u8) WriteError!void {
+    if (dd.vtable.writeFn) |writeFn| {
+        return writeFn(dd.object, datagram);
+    } else {
+        return error.Unsupported;
+    }
+}
+
+pub const ReadError = BaseError || error{ Unsupported, NotConnected };
+
+/// Reads a single `datagram` from the device.
+pub fn read(dd: DatagramDevice, datagram: []u8) ReadError!void {
+    if (dd.vtable.readFn) |readFn| {
+        return readFn(dd.object, datagram);
+    } else {
+        return error.Unsupported;
+    }
+}
+
+object: ?*anyopaque,
+vtable: *const VTable,
+
+pub const VTable = struct {
+    connectFn: ?*const fn (?*anyopaque) ConnectError!void,
+    disconnectFn: ?*const fn (?*anyopaque) void,
+    writeFn: ?*const fn (?*anyopaque, datagram: []const u8) WriteError!void,
+    readFn: ?*const fn (?*anyopaque, datagram: []u8) ReadError!void,
+};
+
+/// A device implementation that can be used to write unit tests.
+pub const TestDevice = struct {
+    arena: std.heap.ArenaAllocator,
+    packets: std.ArrayList([]u8),
+
+    input_sequence: ?[]const []const u8,
+    input_sequence_pos: usize,
+
+    write_enabled: bool,
+
+    connected: bool,
+
+    pub fn init_receiver_only() TestDevice {
+        return init(null, true);
+    }
+
+    pub fn init_sender_only(input: []const []const u8) TestDevice {
+        return init(input, false);
+    }
+
+    pub fn init(input: ?[]const []const u8, write_enabled: bool) TestDevice {
+        return TestDevice{
+            .arena = std.heap.ArenaAllocator.init(std.testing.allocator),
+            .packets = std.ArrayList([]u8).init(std.testing.allocator),
+
+            .input_sequence = input,
+            .input_sequence_pos = 0,
+
+            .write_enabled = write_enabled,
+
+            .connected = false,
+        };
+    }
+
+    pub fn deinit(td: *TestDevice) void {
+        td.arena.deinit();
+        td.packets.deinit();
+        td.* = undefined;
+    }
+
+    pub fn expect_sent(td: TestDevice, expected_datagrams: []const []const u8) !void {
+        const actual_datagrams = td.packets.items;
+
+        try std.testing.expectEqual(expected_datagrams.len, actual_datagrams.len);
+        for (expected_datagrams, actual_datagrams) |expected, actual| {
+            try std.testing.expectEqualSlices(u8, expected, actual);
+        }
+    }
+
+    pub fn datagram_device(td: *TestDevice) DatagramDevice {
+        return DatagramDevice{
+            .object = td,
+            .vtable = &vtable,
+        };
+    }
+
+    fn connectFn(ctx: ?*anyopaque) ConnectError!void {
+        const td: *TestDevice = @ptrCast(@alignCast(ctx.?));
+        if (td.connected)
+            return error.DeviceBusy;
+        td.connected = true;
+    }
+
+    fn disconnectFn(ctx: ?*anyopaque) void {
+        const td: *TestDevice = @ptrCast(@alignCast(ctx.?));
+        if (!td.connected) {
+            std.log.err("disconnect when test device was not connected!", .{});
+        }
+        td.connected = false;
+    }
+
+    fn writeFn(ctx: ?*anyopaque, datagram: []const u8) WriteError!void {
+        const td: *TestDevice = @ptrCast(@alignCast(ctx.?));
+
+        if (!td.connected) {
+            return error.NotConnected;
+        }
+
+        if (!td.write_enabled) {
+            return error.Unsupported;
+        }
+
+        const dg = td.arena.allocator().dupe(u8, datagram) catch return error.IoError;
+        errdefer td.arena.allocator().free(dg);
+
+        td.packets.append(dg) catch return error.IoError;
+    }
+
+    fn readFn(ctx: ?*anyopaque, datagram: []u8) ReadError!void {
+        const td: *TestDevice = @ptrCast(@alignCast(ctx.?));
+
+        if (!td.connected) {
+            return error.NotConnected;
+        }
+
+        const inputs = td.input_sequence orelse return error.Unsupported;
+
+        if (td.input_sequence_pos >= inputs.len) {
+            return error.IoError;
+        }
+
+        const packet = inputs[td.input_sequence_pos];
+        td.input_sequence_pos += 1;
+
+        if (packet.len != datagram.len)
+            return error.IoError;
+
+        @memcpy(datagram, packet);
+    }
+
+    const vtable = VTable{
+        .connectFn = connectFn,
+        .disconnectFn = disconnectFn,
+        .writeFn = writeFn,
+        .readFn = readFn,
+    };
+};

driver/base/DigitalIO.zig

@@ -0,0 +1,109 @@
+//!
+//! An abstract digital input/output pin.
+//!
+//! Digital I/Os can be used to drive single-wire data
+//!
+
+const std = @import("std");
+
+const DigitalIO = @This();
+const BaseError = error{ IoError, Timeout };
+
+object: ?*anyopaque,
+vtable: *const VTable,
+
+pub const SetDirError = error{Unsupported};
+pub const SetBiasError = error{Unsupported};
+pub const WriteError = error{Unsupported};
+pub const ReadError = error{Unsupported};
+
+pub const State = enum(u1) {
+    low = 0,
+    high = 1,
+
+    pub inline fn invert(state: State) State {
+        return @as(State, @enumFromInt(~@intFromEnum(state)));
+    }
+
+    pub inline fn value(state: State) u1 {
+        return @intFromEnum(state);
+    }
+};
+pub const Direction = enum { input, output };
+
+/// Sets the direction of the pin.
+pub fn set_direction(dio: DigitalIO, dir: Direction) SetDirError!void {
+    return dio.vtable.set_direction_fn(dio.object, dir);
+}
+
+/// Sets if the pin has a bias towards either `low` or `high` or no bias at all.
+/// Bias is usually implemented with pull-ups and pull-downs.
+pub fn set_bias(dio: DigitalIO, bias: ?State) SetBiasError!void {
+    return dio.vtable.set_bias_fn(dio.object, bias);
+}
+
+/// Changes the state of the pin.
+pub fn write(dio: DigitalIO, state: State) WriteError!void {
+    return dio.vtable.write_fn(dio.object, state);
+}
+
+/// Reads the state state of the pin.
+pub fn read(dio: DigitalIO) ReadError!State {
+    return dio.vtable.read_fn(dio.object);
+}
+
+pub const VTable = struct {
+    set_direction_fn: *const fn (?*anyopaque, dir: Direction) SetDirError!void,
+    set_bias_fn: *const fn (?*anyopaque, bias: ?State) SetBiasError!void,
+    write_fn: *const fn (?*anyopaque, state: State) WriteError!void,
+    read_fn: *const fn (?*anyopaque) State,
+};
+
+pub const TestDevice = struct {
+    state: State,
+    dir: Direction,
+
+    pub fn init(initial_dir: Direction, initial_state: State) TestDevice {
+        return TestDevice{
+            .dir = initial_dir,
+            .state = initial_state,
+        };
+    }
+
+    pub fn digital_io(dev: *TestDevice) DigitalIO {
+        return DigitalIO{
+            .object = dev,
+            .vtable = &vtable,
+        };
+    }
+
+    fn set_direction_fn(ctx: ?*anyopaque, dir: Direction) SetDirError!void {
+        const dev: *TestDevice = @ptrCast(@alignCast(ctx.?));
+        dev.dir = dir;
+    }
+
+    fn set_bias_fn(ctx: ?*anyopaque, bias: ?State) SetBiasError!void {
+        const dev: *TestDevice = @ptrCast(@alignCast(ctx.?));
+        _ = dev;
+        _ = bias;
+    }
+
+    fn write_fn(ctx: ?*anyopaque, state: State) WriteError!void {
+        const dev: *TestDevice = @ptrCast(@alignCast(ctx.?));
+        if (dev.dir != .output)
+            return error.Unsupported;
+        dev.state = state;
+    }
+
+    fn read_fn(ctx: ?*anyopaque) State {
+        const dev: *TestDevice = @ptrCast(@alignCast(ctx.?));
+        return dev.state;
+    }
+
+    const vtable = VTable{
+        .set_direction_fn = set_direction_fn,
+        .set_bias_fn = set_bias_fn,
+        .write_fn = write_fn,
+        .read_fn = read_fn,
+    };
+};

driver/base/StreamDevice.zig

@@ -0,0 +1,77 @@
+//!
+//! An abstract stream orientied device with runtime dispatch.
+//!
+//! Stream devices behave similar to an UART and can send/receive data
+//! in variying lengths without clear boundaries between transmissions.
+//!
+
+const std = @import("std");
+
+const StreamDevice = @This();
+
+object: ?*anyopaque,
+vtable: *const VTable,
+
+const BaseError = error{ IoError, Timeout };
+
+pub const ConnectError = BaseError || error{DeviceBusy};
+pub const WriteError = BaseError || error{ Unsupported, NotConnected };
+pub const ReadError = BaseError || error{ Unsupported, NotConnected };
+
+/// Establishes a connection to the device (like activating a chip-select lane or similar).
+/// NOTE: Call `.disconnect()` when the usage of the device is done to release it.
+pub fn connect(sd: StreamDevice) ConnectError!void {
+    if (sd.vtable.connectFn) |connectFn| {
+        return connectFn(sd.object);
+    }
+}
+
+/// Releases a device from the connection.
+pub fn disconnect(sd: StreamDevice) void {
+    if (sd.vtable.disconnectFn) |disconnectFn| {
+        return disconnectFn(sd.object);
+    }
+}
+
+/// Writes some `bytes` to the device and returns the number of bytes written.
+pub fn write(sd: StreamDevice, bytes: []const u8) WriteError!usize {
+    if (sd.vtable.writeFn) |writeFn| {
+        return writeFn(sd.object, bytes);
+    } else {
+        return error.Unsupported;
+    }
+}
+
+/// Reads some `bytes` to the device and returns the number of bytes read.
+pub fn read(sd: StreamDevice, bytes: []u8) ReadError!usize {
+    if (sd.vtable.readFn) |readFn| {
+        return readFn(sd.object, bytes);
+    } else {
+        return error.Unsupported;
+    }
+}
+
+pub const Reader = std.io.Reader(StreamDevice, ReadError, reader_read);
+pub fn reader(sd: StreamDevice) Reader {
+    return .{ .context = sd };
+}
+
+fn reader_read(sd: StreamDevice, buf: []u8) ReadError!usize {
+    return sd.read(buf);
+}
+
+pub const Writer = std.io.Reader(StreamDevice, WriteError, writer_write);
+pub fn writer(sd: StreamDevice) Writer {
+    return .{ .context = sd };
+}
+
+fn writer_write(sd: StreamDevice, buf: []const u8) WriteError!usize {
+    return sd.write(buf);
+}
+
+pub const VTable = struct {
+    connect_fn: ?*const fn (?*anyopaque) ConnectError!void,
+    disconnect_fn: ?*const fn (?*anyopaque) void,
+    write_fn: ?*const fn (?*anyopaque, datagram: []const u8) WriteError!usize,
+    read_fn: ?*const fn (?*anyopaque, datagram: []u8) ReadError!usize,
+};