I2C bus definitions

Bus and device definitions shared by boards, the common I2C code and the bus HALs. More...

Data Structures
struct	I2CTransfer
	Transfer in progress on a bus. More...
struct	I2CBusState
	Bus runtime state, owned by the common I2C code. More...
struct	I2CBus
	I2C bus, defined by the board. More...
struct	I2CSlavePort
	Device on an I2C bus, defined by the board. More...

Enumerations
enum	I2CTransferEvent { I2CTransferEvent_Timeout , I2CTransferEvent_TransferComplete , I2CTransferEvent_NackReceived , I2CTransferEvent_Error }
	Transfer outcome reported by a HAL. More...
enum	I2CTransferDirection { I2CTransferDirection_Read , I2CTransferDirection_Write }
	Transfer direction. More...
enum	I2CTransferType { I2CTransferType_SendRegisterAddress , I2CTransferType_NoRegisterAddress }
	Transfer type. More...
enum	I2CTransferState {   I2CTransferState_WriteAddressTx , I2CTransferState_WriteRegAddress , I2CTransferState_RepeatStart , I2CTransferState_WriteAddressRx ,   I2CTransferState_WaitForData , I2CTransferState_ReadData , I2CTransferState_WriteData , I2CTransferState_EndWrite ,   I2CTransferState_Complete }
	Transfer state, for HALs that drive the transfer byte by byte. More...

Functions
void	i2c_init (I2CBus *bus)
	Initialize a bus.
void	i2c_handle_transfer_event (I2CBus *device, I2CTransferEvent event)
	Report the outcome of the current transfer.

Detailed Description

Bus and device definitions shared by boards, the common I2C code and the bus HALs.

The common code runs one transfer at a time per bus: it fills I2CBusState::transfer, starts it through the I2C HAL and waits for the HAL to report the outcome with i2c_handle_transfer_event().

---

Data Structure Documentation

I2CTransfer

struct I2CTransfer

Transfer in progress on a bus.

Data Fields
uint8_t *	data	Data to write or buffer to read into.
uint16_t	device_address	Device address, as in I2CSlavePort::address.
I2CTransferDirection	direction	Transfer direction.
bool	dma	data follows the i2c_read_register_block_dma() rules, so the HAL may use DMA.
uint32_t	idx	Index of the next data byte, for HALs that use it.
uint8_t	register_address	Register address, for I2CTransferType_SendRegisterAddress.
uint32_t	size	Number of data bytes.
I2CTransferState	state	Transfer state, for HALs that use it.
I2CTransferType	type	Transfer type.

I2CBusState

struct I2CBusState

Bus runtime state, owned by the common I2C code.

Data Fields
struct pbl_mutex	bus_mutex	Serializes bus access.
struct pbl_sem	event_semaphore	Signaled when the current transfer ends.
I2CTransfer	transfer	Current transfer.
I2CTransferEvent	transfer_event	Outcome of the current transfer, set by i2c_handle_transfer_event().
int	transfer_nack_count	NACKs received during the current transfer.
RtcTicks	transfer_start_ticks	Start time of the current transfer.
int	user_count	Number of i2c_use() users.

I2CBus

struct I2CBus

I2C bus, defined by the board.

Data Fields
const struct I2CBusHal *const	hal	HAL-specific configuration.
const char *	name	Bus name, for logging.
I2CBusState *const	state	Runtime state.

I2CSlavePort

struct I2CSlavePort

Device on an I2C bus, defined by the board.

Data Fields
uint16_t	address	Device address: 8-bit (7-bit address shifted left by one) on nRF5, 7-bit on SF32LB.
const I2CBus *	bus	Bus the device is connected to.

Enumeration Type Documentation

I2CTransferDirection

enum I2CTransferDirection

Transfer direction.

Enumerator
I2CTransferDirection_Read	Read from the device.
I2CTransferDirection_Write	Write to the device.

I2CTransferEvent

enum I2CTransferEvent

Transfer outcome reported by a HAL.

Enumerator
I2CTransferEvent_Timeout	Transfer timed out.
I2CTransferEvent_TransferComplete	Transfer completed.
I2CTransferEvent_NackReceived	Device did not acknowledge; the transfer is retried.
I2CTransferEvent_Error	Transfer failed.

I2CTransferState

enum I2CTransferState

Transfer state, for HALs that drive the transfer byte by byte.

Enumerator
I2CTransferState_WriteAddressTx	Send the device address for writing.
I2CTransferState_WriteRegAddress	Send the register address.
I2CTransferState_RepeatStart	Send a repeated start.
I2CTransferState_WriteAddressRx	Send the device address for reading.
I2CTransferState_WaitForData	Wait for data.
I2CTransferState_ReadData	Read data.
I2CTransferState_WriteData	Write data.
I2CTransferState_EndWrite	Finish the write.
I2CTransferState_Complete	Transfer complete.

I2CTransferType

enum I2CTransferType

Transfer type.

Enumerator
I2CTransferType_SendRegisterAddress	Send a register address first, followed by a repeated start for reads.
I2CTransferType_NoRegisterAddress	Do not send a register address; used for block reads and writes.

Function Documentation

i2c_handle_transfer_event()

void i2c_handle_transfer_event	(	I2CBus *	device,
		I2CTransferEvent	event
	)

Report the outcome of the current transfer.

Called by the HAL, typically from its interrupt handler.

Parameters

device	Bus the transfer ran on.
event	Transfer outcome.

i2c_init()

void i2c_init

(

I2CBus *

bus

)

Initialize a bus.

Called once at boot for every bus, before any i2c_use().

Parameters

bus	Bus to initialize.