Overhaul i2c_device interfaces, implement, update some drivers (#645)

Author: Grazfather

drivers/base/I2C_Device.zig

@@ -44,7 +44,7 @@ pub const Address = enum(u7) {
     /// Reserved addresses are ones that match `0b0000XXX` or `0b1111XXX`.
     ///
     /// See more here: https://www.i2c-bus.org/addressing/
-    pub fn is_reserved(addr: Address) Address.Error!void {
+    pub fn check_reserved(addr: Address) Address.Error!void {
         const value: u7 = @intFromEnum(addr);
 
         switch (value) {
@@ -77,58 +77,52 @@ ptr: *anyopaque,
 /// Virtual table for the datagram device functions.
 vtable: *const VTable,
 
-pub fn set_address(dev: I2C_Device, addr: Address, allow_reserved: Allow_Reserved) InterfaceError!void {
-    const set_address_fn = dev.vtable.set_address_fn orelse return InterfaceError.Unsupported;
-    return set_address_fn(dev.ptr, addr, allow_reserved);
-}
-
 /// Writes a single `datagram` to the device.
-pub fn write(dev: I2C_Device, datagram: []const u8) InterfaceError!void {
-    return try dev.writev(&.{datagram});
+pub fn write(dev: I2C_Device, address: Address, datagram: []const u8) InterfaceError!void {
+    return try dev.writev(address, &.{datagram});
 }
 
 /// Writes multiple `datagrams` to the device.
-pub fn writev(dev: I2C_Device, datagrams: []const []const u8) InterfaceError!void {
+pub fn writev(dev: I2C_Device, address: Address, datagrams: []const []const u8) InterfaceError!void {
     const writev_fn = dev.vtable.writev_fn orelse return InterfaceError.Unsupported;
-    return writev_fn(dev.ptr, datagrams);
+    return writev_fn(dev.ptr, address, datagrams);
 }
 
 /// Writes then reads a single `datagram` to the device.
-pub fn write_then_read(dev: I2C_Device, src: []const u8, dst: []u8) InterfaceError!void {
-    return try dev.writev_then_readv(&.{src}, &.{dst});
+pub fn write_then_read(dev: I2C_Device, address: Address, src: []const u8, dst: []u8) InterfaceError!void {
+    return try dev.writev_then_readv(address, &.{src}, &.{dst});
 }
 
 /// Writes a slice of datagrams to the device, then reads back into another slice of datagrams
 pub fn writev_then_readv(
     dev: I2C_Device,
+    address: Address,
     write_chunks: []const []const u8,
     read_chunks: []const []u8,
 ) InterfaceError!void {
     const writev_then_readv_fn = dev.vtable.writev_then_readv_fn orelse return InterfaceError.Unsupported;
-    return writev_then_readv_fn(dev.ptr, write_chunks, read_chunks);
+    return writev_then_readv_fn(dev.ptr, address, write_chunks, read_chunks);
 }
 
 /// Reads a single `datagram` from the device.
 /// Function returns the number of bytes written in `datagram`.
-pub fn read(dev: I2C_Device, datagram: []u8) InterfaceError!usize {
-    return try dev.readv(&.{datagram});
+pub fn read(dev: I2C_Device, address: Address, datagram: []u8) InterfaceError!usize {
+    return try dev.readv(address, &.{datagram});
 }
 
 /// Reads multiple `datagrams` from the device.
 /// Function returns the number of bytes written in `datagrams`.
-pub fn readv(dev: I2C_Device, datagrams: []const []u8) InterfaceError!usize {
+pub fn readv(dev: I2C_Device, address: Address, datagrams: []const []u8) InterfaceError!usize {
     const readv_fn = dev.vtable.readv_fn orelse return InterfaceError.Unsupported;
-    return readv_fn(dev.ptr, datagrams);
+    return readv_fn(dev.ptr, address, datagrams);
 }
 
-pub const Allow_Reserved = enum { allow_general, allow_reserved, dont_allow_reserved };
-
 pub const VTable = struct {
-    set_address_fn: ?*const fn (*anyopaque, Address, Allow_Reserved) InterfaceError!void,
-    writev_fn: ?*const fn (*anyopaque, datagrams: []const []const u8) InterfaceError!void,
-    readv_fn: ?*const fn (*anyopaque, datagrams: []const []u8) InterfaceError!usize,
+    writev_fn: ?*const fn (*anyopaque, Address, datagrams: []const []const u8) InterfaceError!void,
+    readv_fn: ?*const fn (*anyopaque, Address, datagrams: []const []u8) InterfaceError!usize,
     writev_then_readv_fn: ?*const fn (
         *anyopaque,
+        Address,
         write_chunks: []const []const u8,
         read_chunks: []const []u8,
     ) InterfaceError!void = null,
@@ -191,18 +185,9 @@ pub const Test_Device = struct {
         };
     }
 
-    fn set_address(ctx: *anyopaque, addr: Address, allow_reserved: Allow_Reserved) InterfaceError!void {
-        const td: *Test_Device = @ptrCast(@alignCast(ctx));
-        if (allow_reserved == .dont_allow_reserved)
-            addr.is_reserved() catch return Error.IllegalAddress
-        else if (allow_reserved == .allow_general)
-            addr.is_reserved() catch |err| if (err != Address.Error.GeneralCall)
-                return Error.IllegalAddress;
-        td.addr = addr;
-    }
-
-    fn writev(ctx: *anyopaque, datagrams: []const []const u8) InterfaceError!void {
+    fn writev(ctx: *anyopaque, address: Address, datagrams: []const []const u8) InterfaceError!void {
         const td: *Test_Device = @ptrCast(@alignCast(ctx));
+        _ = address;
 
         if (!td.write_enabled) {
             return error.Unsupported;
@@ -231,8 +216,9 @@ pub const Test_Device = struct {
         td.packets.append(dg) catch return error.UnknownAbort;
     }
 
-    fn readv(ctx: *anyopaque, datagrams: []const []u8) InterfaceError!usize {
+    fn readv(ctx: *anyopaque, address: Address, datagrams: []const []u8) InterfaceError!usize {
         const td: *Test_Device = @ptrCast(@alignCast(ctx));
+        _ = address;
 
         const inputs = td.input_sequence orelse return error.Unsupported;
 
@@ -271,20 +257,19 @@ pub const Test_Device = struct {
         return written;
     }
 
-    fn writev_then_readv(ctx: *anyopaque, write_chunks: []const []const u8, read_chunks: []const []u8) InterfaceError!void {
-        try Test_Device.writev(ctx, write_chunks);
-        _ = try Test_Device.readv(ctx, read_chunks);
+    fn writev_then_readv(ctx: *anyopaque, address: Address, write_chunks: []const []const u8, read_chunks: []const []u8) InterfaceError!void {
+        try Test_Device.writev(ctx, address, write_chunks);
+        _ = try Test_Device.readv(ctx, address, read_chunks);
     }
 
     const vtable = I2C_Device.VTable{
-        .set_address_fn = Test_Device.set_address,
         .writev_fn = Test_Device.writev,
         .readv_fn = Test_Device.readv,
         .writev_then_readv_fn = Test_Device.writev_then_readv,
     };
 };
 
-test "Address.is_reserved returns correct error types" {
+test "Address.check_reserved returns correct error types" {
     const TestCase = struct {
         address: u7,
         expected_error: ?Address.Error,
@@ -310,15 +295,15 @@ test "Address.is_reserved returns correct error types" {
     for (test_cases) |test_case| {
         const addr: Address = @enumFromInt(test_case.address);
         if (test_case.expected_error) |expected_error| {
-            std.testing.expectError(expected_error, addr.is_reserved()) catch |err| {
+            std.testing.expectError(expected_error, addr.check_reserved()) catch |err| {
                 std.debug.print(
                     "Failed test case: {s} (address 0x{X:0>2})\n",
                     .{ test_case.description, test_case.address },
                 );
                 return err;
             };
         } else {
-            addr.is_reserved() catch |err| {
+            addr.check_reserved() catch |err| {
                 std.debug.print(
                     "Expected valid address but got error for: {s} (address 0x{X:0>2})\n",
                     .{ test_case.description, test_case.address },
@@ -339,34 +324,35 @@ test Test_Device {
 
     var buffer: [16]u8 = undefined;
 
-    const dd = td.i2c_device();
+    const id = td.i2c_device();
+    const addr: Address = @enumFromInt(0);
 
     {
         // The first input datagram will be received here:
-        const recv_len = try dd.read(&buffer);
+        const recv_len = try id.read(addr, &buffer);
         try std.testing.expectEqualStrings("first datagram", buffer[0..recv_len]);
     }
 
     {
         // The second one here:
-        const recv_len = try dd.read(&buffer);
+        const recv_len = try id.read(addr, &buffer);
         try std.testing.expectEqualStrings("second datagram", buffer[0..recv_len]);
     }
 
     {
         // The third datagram will overrun our buffer, so we're receiving an error
         // which tells us that the whole buffer is filled, but there's data that
         // was discarded:
-        try std.testing.expectError(error.BufferOverrun, dd.read(&buffer));
+        try std.testing.expectError(error.BufferOverrun, id.read(addr, &buffer));
         try std.testing.expectEqualStrings("the very third d", &buffer);
     }
 
     // As there's no fourth datagram available, the test device will yield
     // an `IoError` for when no datagrams are available anymore:
-    try std.testing.expectError(error.NoData, dd.read(&buffer));
+    try std.testing.expectError(error.NoData, id.read(addr, &buffer));
 
-    try dd.write("Hello, World!");
-    try dd.writev(&.{ "See", " you ", "soon!" });
+    try id.write(addr, "Hello, World!");
+    try id.writev(addr, &.{ "See", " you ", "soon!" });
 
     // Check if we had exactly these datagrams:
     try td.expect_sent(&.{

drivers/io_expander/pcf8574.zig

@@ -7,19 +7,22 @@ const SetBiasError = Digital_IO.SetBiasError;
 const SetDirError = Digital_IO.SetDirError;
 const WriteError = Digital_IO.WriteError;
 
+const I2CAddress = mdf.base.I2C_Device.Address;
+
 pub const PCF8574_Config = struct {
-    Datagram_Device: type = mdf.base.Datagram_Device,
+    I2C_Device: type = mdf.base.I2C_Device,
 };
 
 pub fn PCF8574(comptime config: PCF8574_Config) type {
     return struct {
         const Self = @This();
-        interface: config.Datagram_Device,
+        interface: config.I2C_Device,
+        address: mdf.base.I2C_Device.Address,
         pins: u8 = 0,
         pin_arr: [8]u8 = undefined,
 
         inline fn update(self: *const Self) !void {
-            try self.interface.write(&[1]u8{self.pins});
+            try self.interface.write(self.address, &[1]u8{self.pins});
         }
 
         pub fn put(self: *Self, pin: u3, st: State) !void {
@@ -42,12 +45,12 @@ pub fn PCF8574(comptime config: PCF8574_Config) type {
         pub fn read(self: *Self, pin: u3) !State {
             const mask: u8 = @as(u8, 1) << pin;
             var pkg: [1]u8 = .{mask | self.pins};
-            const read_value = try self.interface.read(&pkg); //keep pullup enable until next call
+            const read_value = try self.interface.read(self.address, &pkg); //keep pullup enable until next call
             return if (read_value & mask != 0) State.high else State.low;
         }
 
-        pub fn init(datagram: config.Datagram_Device) Self {
-            var obj = Self{ .interface = datagram };
+        pub fn init(datagram: config.I2C_Device, address: I2CAddress) Self {
+            var obj = Self{ .interface = datagram, .address = address };
             for (0..obj.pin_arr.len) |index| {
                 obj.pin_arr[index] = @intCast(index);
             }

drivers/sensor/ICM-20948.zig

@@ -7,7 +7,8 @@
 //! Example usage:
 //! ```zig
 //! var sensor = try ICM_20948.init(
-//!     i2c_device.datagram_device(),
+//!     i2c_device.i2c_device(),
+//!     @enumFromInt(0x69),
 //!     clock.clock_device(),
 //!     .{
 //!         .accel_range = .gs4,
@@ -62,7 +63,8 @@ pub const ICM_20948 = struct {
     const MAG_READ_DELAY_US = 10_000;
     const MAG_RESET_DELAY_US = 100_000;
 
-    dev: mdf.base.Datagram_Device,
+    dev: mdf.base.I2C_Device,
+    address: mdf.base.I2C_Device.Address,
     clock: mdf.base.Clock_Device,
     config: Config,
     current_bank: ?u2 = null,
@@ -320,8 +322,13 @@ pub const ICM_20948 = struct {
         i2c_slv0_en: u1 = 0,
     };
 
-    pub fn init(dev: mdf.base.Datagram_Device, clock: mdf.base.Clock_Device, config: Config) Error!Self {
-        return Self{ .dev = dev, .clock = clock, .config = config };
+    pub fn init(
+        dev: mdf.base.I2C_Device,
+        address: mdf.base.I2C_Device.Address,
+        clock: mdf.base.Clock_Device,
+        config: Config,
+    ) Error!Self {
+        return Self{ .dev = dev, .address = address, .clock = clock, .config = config };
     }
 
     pub fn setup(self: *Self) Error!void {
@@ -399,7 +406,7 @@ pub const ICM_20948 = struct {
 
         try self.set_bank(reg.bank());
 
-        self.dev.writev_then_readv(&.{&.{reg.value()}}, &.{buf}) catch |err| {
+        self.dev.writev_then_readv(self.address, &.{&.{reg.value()}}, &.{buf}) catch |err| {
             log.err("Failed to read register 0x{X:02}: {}", .{ reg.value(), err });
             return Error.ReadError;
         };
@@ -416,7 +423,7 @@ pub const ICM_20948 = struct {
     pub inline fn write_byte(self: *Self, reg: Self.Register, val: u8) Error!void {
         try self.set_bank(reg.bank());
 
-        self.dev.write(&.{ reg.value(), val }) catch |err| {
+        self.dev.write(self.address, &.{ reg.value(), val }) catch |err| {
             log.err("Failed to write register 0x{X:02} = 0x{X:02}: {}", .{ reg.value(), val, err });
             return Error.WriteError;
         };
@@ -452,7 +459,7 @@ pub const ICM_20948 = struct {
         if (bank == self.current_bank) return;
 
         // Bits 5:4 - directly write to bank0 register without recursion
-        self.dev.write(&.{ 0x7F, @as(u8, bank) << 4 }) catch |err| {
+        self.dev.write(self.address, &.{ 0x7F, @as(u8, bank) << 4 }) catch |err| {
             log.err("Failed to switch to bank {}: {}", .{ bank, err });
             return Error.BankSwitchFailed;
         };
@@ -889,17 +896,16 @@ pub const ICM_20948 = struct {
 };
 
 // Testing
-const TestDatagramDevice = mdf.base.Datagram_Device.Test_Device;
+const TestI2CDevice = mdf.base.I2C_Device.Test_Device;
 const TestTime = mdf.base.Clock_Device.Test_Device;
 
 test "set_bank" {
     var ttd = TestTime.init();
-    var d = TestDatagramDevice.init(null, true);
+    var d = TestI2CDevice.init(null, true);
     defer d.deinit();
-    const dd = d.datagram_device();
-    try dd.connect();
+    const id = d.i2c_device();
 
-    var dev = try ICM_20948.init(dd, ttd.clock_device(), .{});
+    var dev = try ICM_20948.init(id, @enumFromInt(0), ttd.clock_device(), .{});
 
     // Nothing is sent in init
     try d.expect_sent(&.{});
@@ -923,12 +929,11 @@ test "set_bank" {
 
 test "reset" {
     var ttd = TestTime.init();
-    var d = TestDatagramDevice.init(null, true);
+    var d = TestI2CDevice.init(null, true);
     defer d.deinit();
-    const dd = d.datagram_device();
-    try dd.connect();
+    const id = d.i2c_device();
 
-    var dev = try ICM_20948.init(dd, ttd.clock_device(), .{});
+    var dev = try ICM_20948.init(id, @enumFromInt(0), ttd.clock_device(), .{});
 
     // Nothing is sent in init
     try d.expect_sent(&.{});
@@ -942,12 +947,11 @@ test "reset" {
 
 test "read_byte" {
     var ttd = TestTime.init();
-    var d = TestDatagramDevice.init(null, true);
+    var d = TestI2CDevice.init(null, true);
     defer d.deinit();
-    const dd = d.datagram_device();
-    try dd.connect();
+    const id = d.i2c_device();
 
-    var dev = try ICM_20948.init(dd, ttd.clock_device(), .{});
+    var dev = try ICM_20948.init(id, @enumFromInt(0), ttd.clock_device(), .{});
 
     // Read byte will set the bank
     // -- Put in the values it expects to read
@@ -960,12 +964,11 @@ test "read_byte" {
 
 test "error handling in setup" {
     var ttd = TestTime.init();
-    var d = TestDatagramDevice.init(null, true);
+    var d = TestI2CDevice.init(null, true);
     defer d.deinit();
-    const dd = d.datagram_device();
-    try dd.connect();
+    const id = d.i2c_device();
 
-    var dev = try ICM_20948.init(dd, ttd.clock_device(), .{});
+    var dev = try ICM_20948.init(id, @enumFromInt(0), ttd.clock_device(), .{});
 
     // Test wrong WHO_AM_I response, first byte is read during reset()
     d.input_sequence = &.{ &.{0x00}, &.{0xFF} }; // Wrong ID after reset
@@ -975,12 +978,11 @@ test "error handling in setup" {
 
 test "device responsiveness check" {
     var ttd = TestTime.init();
-    var d = TestDatagramDevice.init(null, true);
+    var d = TestI2CDevice.init(null, true);
     defer d.deinit();
-    const dd = d.datagram_device();
-    try dd.connect();
+    const id = d.i2c_device();
 
-    var dev = try ICM_20948.init(dd, ttd.clock_device(), .{});
+    var dev = try ICM_20948.init(id, @enumFromInt(0), ttd.clock_device(), .{});
 
     // Test with correct WHO_AM_I
     d.input_sequence = &.{&.{ICM_20948.WHOAMI}};