std/embedded/peripheral/designware_i2c

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/embedded/peripheral/designware_i2c"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Timing

Struct · Source

The controller settings for one SCL frequency, from timing.

pub struct Timing {
    // The controller's input clock, in hertz.
    pub clock_hz: u32
    // The SCL high and low count registers. SCL is high for
    // `high + spike + 7` input clock cycles and low for `low + 1`.
    pub high: u32
    pub low: u32
    // Longest glitch the input filters suppress, in input clock cycles.
    pub spike: u32
    // How long SDA is held after SCL falls, in input clock cycles.
    pub hold: u32
    // The resulting SCL frequency, in hertz, counting the controller's
    // extra cycles but not the bus's rise times, which stretch it further.
    pub frequency_hz: u32
}

timing

Function · Source

Controller settings for an SCL frequency of frequency_hz (1 Hz to hal.I2C_FAST_PLUS_HZ) from an input clock of clock_hz. SCL is low for 60% of each period, which meets the I2C specification’s minimum low times at 100 kHz, 400 kHz, and 1 MHz. Returns InvalidInput for a frequency the controller cannot produce from this clock: below about 1.2 kHz at 125 MHz, or 1 MHz from a clock below about 36 MHz.

pub fn timing(clock_hz: u32, frequency_hz: u32) -> Timing!hal.Error

Controller

Struct · Source

An I2C bus master on one DW_apb_i2c controller with registers R, a value with the register block protocol of std/embedded/hal. Implements the std/embedded/hal I2C bus protocol.

pub struct Controller<R> {
    // Private implementation fields omitted.
}

Controller.new

Function · Source

Configure a controller fresh out of reset as the bus’s only master, using timing from the same clock that feeds it. It is enabled by the first transaction.

pub fn new(registers: R, timing: Timing) -> Controller<R>

Controller.frequency_hz

Function · Source

The SCL frequency, in hertz, as computed by timing: the request, rounded to whole input clock cycles.

pub fn frequency_hz(&self) -> u32

Controller.set_frequency

Function · Source

Change the SCL frequency between transactions, for example to talk to a slower device. InvalidInput leaves the frequency unchanged.

pub fn set_frequency(&mut self, frequency_hz: u32) -> void!hal.Error

Controller.write

Function · Source

Send bytes to the device at address, then a STOP condition. NoAcknowledge if the address or a byte is not acknowledged, Bus if another master won arbitration, Timeout if the bus is stuck, and InvalidInput for an empty transfer or an address above 0x7F.

pub fn write(&mut self, address: u8, bytes: &[u8]) -> void!hal.Error

Controller.read

Function · Source

Fill buffer from the device at address, then a STOP condition. Errors as for write.

pub fn read(&mut self, address: u8, buffer: &mut[u8]) -> void!hal.Error

Controller.write_read

Function · Source

Send bytes, then fill buffer after a repeated START, all in one transaction, so no other master can get in between; the usual way to read a numbered register. Errors as for write, and InvalidInput only when both are empty.

pub fn write_read(&mut self, address: u8, bytes: &[u8], buffer: &mut[u8]) -> void!hal.Error

Controller.release

Function · Source

Disable the controller and give back its registers.

pub fn release(self) -> R

Bus

Struct · Source

A DW_apb_i2c on the chip, as chip packages hand it to applications. It implements the std/embedded/hal I2C bus protocol like Controller but keeps the register block: RegisterBlock trusts its owner with every offset, which only the driver may be.

pub struct Bus {
    // Private implementation fields omitted.
}

Bus.at

Function · Source

SAFETY: as for hal.RegisterBlock.at, with base a DW_apb_i2c whose reset and pins the caller has set up and that only this bus uses.

pub unsafe fn at(base: usize, timing: Timing) -> Bus

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Bus.write

Function · Source

pub fn write(&mut self, address: u8, bytes: &[u8]) -> void!hal.Error

Bus.read

Function · Source

pub fn read(&mut self, address: u8, buffer: &mut[u8]) -> void!hal.Error

Bus.write_read

Function · Source

pub fn write_read(&mut self, address: u8, bytes: &[u8], buffer: &mut[u8]) -> void!hal.Error

Bus.frequency_hz

Function · Source

The SCL frequency, in hertz.

pub fn frequency_hz(&self) -> u32

Bus.set_frequency

Function · Source

Change the SCL frequency between transactions.

pub fn set_frequency(&mut self, frequency_hz: u32) -> void!hal.Error

Bus.release

Function · Source

Disable the controller and return its base address, for the chip package to take the bus back.

pub fn release(self) -> usize