Module hal 

The C ABI for the bus layer: one I2C bus that a program and every driver on it share.

A bus is the kernel’s adapter on a Linux board, a set of simulated parts, or a script of the transfers a driver is expected to make, and the same calls work on each: a write, a read, and a write then a read in one transaction, which is how a register is read. A driver built on a bus, such as the BME280 in crate::sensors_driver, holds a share of it, so the caller keeps its own handle, reads back what a simulated part holds after a driver wrote to it, and frees its handle whenever it likes; the bus closes when the last holder lets go.

A part and a script are built here and copied onto a bus, so the handles that built them stay the caller’s to free. Every failed transfer returns PamojaStatus::Io with the reason in the last error message: nothing answered at the address, the script expected something else, or the kernel’s own words for what went wrong.

A simulated part is one of three kinds, and one handle holds any of them: PAMOJA_I2C_PART_BYTES, registers a byte wide, as Bosch’s parts have; PAMOJA_I2C_PART_WORDS, registers sixteen bits wide, as Texas Instruments’ parts have; and PAMOJA_I2C_PART_COMMANDS, commands that leave replies, as Sensirion’s parts take. A call made on the wrong kind of part is refused with PamojaStatus::InvalidArgument, or reads as zero where the call returns a value.

Structs

PamojaI2cBus

One I2C bus, shared with every driver built on it. Opaque; release it with pamoja_i2c_bus_free.

PamojaI2cPart

A part that is not there, answering from its registers or its commands. Opaque; release it with pamoja_i2c_part_free.

PamojaI2cScript

The transfers a driver is expected to make, in order, and the replies. Opaque; release it with pamoja_i2c_script_free.

Constants

PAMOJA_I2C_BUS_ADAPTER

A bus kind: the kernel’s adapter, with real parts on real wires.

PAMOJA_I2C_BUS_SCRIPTED

A bus kind: a script of the transfers a driver is expected to make.

PAMOJA_I2C_BUS_SIMULATED

A bus kind: simulated parts answering from their registers.

PAMOJA_I2C_FAULT_ARBITRATION_LOSS

A scripted failure: another controller won the bus.

PAMOJA_I2C_FAULT_BUS

A scripted failure: a bus error, such as a misplaced start or stop condition.

PAMOJA_I2C_FAULT_NO_ACKNOWLEDGE

A scripted failure: a missing acknowledge, with no telling whether of the address or data.

PAMOJA_I2C_FAULT_NO_ACKNOWLEDGE_ADDRESS

A scripted failure: nothing acknowledged the address.

PAMOJA_I2C_FAULT_NO_ACKNOWLEDGE_DATA

A scripted failure: the part did not acknowledge a data byte.

PAMOJA_I2C_FAULT_OTHER

A scripted failure of no more particular kind.

PAMOJA_I2C_FAULT_OVERRUN

A scripted failure: data arrived faster than it was taken.

PAMOJA_I2C_PART_BYTES

A part kind: 256 registers a byte wide.

PAMOJA_I2C_PART_COMMANDS

A part kind: commands, each leaving the reply it was given for a read to take.

PAMOJA_I2C_PART_WORDS

A part kind: 256 registers sixteen bits wide, each traveling most significant byte first.

Functions

pamoja_i2c_bus_attach^⚠

Puts a copy of a part of any kind on a simulated bus, in place of any part already at its address.

pamoja_i2c_bus_free^⚠

Releases the caller’s share of a bus. The bus closes when no driver holds it either. A null pointer is ignored.

pamoja_i2c_bus_kind^⚠

Returns what answers on a bus.

pamoja_i2c_bus_open^⚠

Opens the kernel’s I2C adapter, such as /dev/i2c-1 on a Raspberry Pi.

pamoja_i2c_bus_part^⚠

Copies what a simulated part holds now, with whatever drivers have written to it.

pamoja_i2c_bus_read^⚠

Reads bytes from a part, in one transaction.

pamoja_i2c_bus_remaining^⚠

Reports how many steps a scripted bus has left.

pamoja_i2c_bus_scripted^⚠

Creates a bus that plays a script and refuses any transfer that is not its next step.

pamoja_i2c_bus_simulated

Creates a simulated bus with no parts on it yet; pamoja_i2c_bus_attach puts them on.

pamoja_i2c_bus_transfers^⚠

Returns how many transfers have been made on a bus, by the caller and every driver on it, including any that failed.

pamoja_i2c_bus_waited_micros^⚠

Returns how long the drivers on a bus have asked to wait.

pamoja_i2c_bus_write^⚠

Writes bytes to a part, in one transaction.

pamoja_i2c_bus_write_read^⚠

Writes bytes to a part and reads its reply in one transaction, with a repeated start between them, which is how a register is read.

pamoja_i2c_command_part_new

Creates a part answering at one address that takes commands and has been given no replies yet. A write sends a command and any arguments after it; a read takes the reply that command left, once, padded with 0xFF; a read with no reply waiting is not acknowledged.

pamoja_i2c_part_address^⚠

Returns the address a part answers to.

pamoja_i2c_part_answer^⚠

Gives a part that takes commands the reply one command leaves, in place of any reply given before.

pamoja_i2c_part_free^⚠

Releases a part. A null pointer is ignored.

pamoja_i2c_part_kind^⚠

Returns which kind of part a handle holds.

pamoja_i2c_part_load^⚠

Puts bytes in a part whose registers are a byte wide, from a register on. Past the last register they wrap to the first.

pamoja_i2c_part_new

Creates a part answering at one address from 256 registers a byte wide, every one reading zero.

pamoja_i2c_part_read^⚠

Reads consecutive registers of a part whose registers are a byte wide, from one register on.

pamoja_i2c_part_read_only^⚠

Marks bits of one register of a part whose registers are sixteen bits wide as the part’s to set: a driver’s write leaves them as the part holds them, as a conversion-ready flag is.

pamoja_i2c_part_received^⚠

Copies one write a part that takes commands received: a command and any arguments after it.

pamoja_i2c_part_received_count^⚠

Returns how many writes a part that takes commands has received.

pamoja_i2c_part_register^⚠

Reads what one register of a part whose registers are a byte wide holds.

pamoja_i2c_part_set_word^⚠

Puts a value in one register of a part whose registers are sixteen bits wide, read-only bits included, the way the part itself would.

pamoja_i2c_part_transfers^⚠

Returns how many transfers a part has served.

pamoja_i2c_part_word^⚠

Reads what one register of a part whose registers are sixteen bits wide holds.

pamoja_i2c_script_fault^⚠

Adds a step: the next transfer to the address fails, the way a missing or busy part does.

pamoja_i2c_script_free^⚠

Releases a script. A null pointer is ignored.

pamoja_i2c_script_len^⚠

Returns how many steps a script holds.

pamoja_i2c_script_new

Creates an empty script.

pamoja_i2c_script_read^⚠

Adds a step: the driver reads from the address and receives the reply, whose length is the length it must ask for.

pamoja_i2c_script_write^⚠

Adds a step: the driver writes exactly these bytes to the address.

pamoja_i2c_script_write_read^⚠

Adds a step: the driver writes these bytes and then reads the reply in one transaction, the shape of a register read.

pamoja_i2c_word_part_new

Creates a part answering at one address from 256 registers sixteen bits wide, every one reading zero. A pointer byte names a register, a write of a word stores it and leaves the pointer where it was, and a read takes words from the pointer on.