I2C

I2C controller driver interface. More...

Modules
	I2C bus definitions
	Bus and device definitions shared by boards, the common I2C code and the bus HALs.
	I2C HAL
	Interface between the common I2C code and the per-SoC bus controller drivers.
	nRF5 I2C
	I2C HAL implementation for the nRF5 TWIM peripheral.
	SF32LB I2C
	I2C HAL implementation for the SF32LB I2C controller.

Functions
void	i2c_use (I2CSlavePort *slave)
	Start using the bus a device is connected to.
void	i2c_release (I2CSlavePort *slave)
	Stop using the bus a device is connected to.
void	i2c_reset (I2CSlavePort *slave)
	Reset the bus a device is connected to.
bool	i2c_bitbang_recovery (I2CSlavePort *slave)
	Recover a stuck bus by clocking SCL until SDA is released.
bool	i2c_read_register (I2CSlavePort *slave, uint8_t register_address, uint8_t *result)
	Read a register.
bool	i2c_read_register_block (I2CSlavePort *slave, uint8_t register_address_start, uint32_t read_size, uint8_t *result_buffer)
	Read consecutive registers.
bool	i2c_read_register_block_dma (I2CSlavePort *slave, uint8_t register_address_start, uint32_t read_size, uint8_t *result_buffer)
	Read a block of registers into a buffer the controller may fill through DMA.
bool	i2c_read_block (I2CSlavePort *slave, uint32_t read_size, uint8_t *result_buffer)
	Read data without sending a register address.
bool	i2c_write_register (I2CSlavePort *slave, uint8_t register_address, uint8_t value)
	Write a register.
bool	i2c_write_register_block (I2CSlavePort *slave, uint8_t register_address_start, uint32_t write_size, const uint8_t *buffer)
	Write consecutive registers.
bool	i2c_write_block (I2CSlavePort *slave, uint32_t write_size, const uint8_t *buffer)
	Write data without sending a register address.
bool	i2c_write_read_block (I2CSlavePort *slave, uint32_t write_size, const uint8_t *write_buffer, uint32_t read_size, uint8_t *read_buffer)
	Write data, then read data, with no other transfer on the bus in between.

Detailed Description

I2C controller driver interface.

Devices are addressed through the board's I2CSlavePort, which names the bus and the device address. A bus is powered while it has users: bracket transfers with i2c_use() and i2c_release(). Transfers block the calling task, are serialized per bus and must not be issued from ISRs.

uint8_t id;
uint8_t fifo[6];
 
i2c_use(I2C_ACCEL);
bool ok = i2c_read_register(I2C_ACCEL, REG_WHO_AM_I, &id) &&
          i2c_write_register(I2C_ACCEL, REG_CTRL1, CTRL1_ODR_50HZ) &&
          i2c_read_register_block(I2C_ACCEL, REG_OUT_X_L, sizeof(fifo), fifo);
i2c_release(I2C_ACCEL);

Function Documentation

i2c_bitbang_recovery()

bool i2c_bitbang_recovery

(

I2CSlavePort *

slave

)

Recover a stuck bus by clocking SCL until SDA is released.

Not supported by the current bus drivers, which always fail.

Parameters

slave

Device, which identifies the bus.

Returns

True if SDA recovered.

i2c_read_block()

bool i2c_read_block	(	I2CSlavePort *	slave,
		uint32_t	read_size,
		uint8_t *	result_buffer
	)

Read data without sending a register address.

Parameters

	slave	Device to read from.
	read_size	Number of bytes to read.
[out]	result_buffer	Destination buffer of at least read_size bytes.

Returns

True on success.

i2c_read_register()

bool i2c_read_register	(	I2CSlavePort *	slave,
		uint8_t	register_address,
		uint8_t *	result
	)

Read a register.

Parameters

	slave	Device to read from.
	register_address	Register address.
[out]	result	Register value.

Returns

True on success.

i2c_read_register_block()

bool i2c_read_register_block	(	I2CSlavePort *	slave,
		uint8_t	register_address_start,
		uint32_t	read_size,
		uint8_t *	result_buffer
	)

Read consecutive registers.

Sends the start register address, then reads after a repeated start.

Parameters

	slave	Device to read from.
	register_address_start	First register address.
	read_size	Number of bytes to read.
[out]	result_buffer	Destination buffer of at least read_size bytes.

Returns

True on success.

i2c_read_register_block_dma()

bool i2c_read_register_block_dma	(	I2CSlavePort *	slave,
		uint8_t	register_address_start,
		uint32_t	read_size,
		uint8_t *	result_buffer
	)

Read a block of registers into a buffer the controller may fill through DMA.

Like i2c_read_register_block(), but the bus may use DMA and let the CPU sleep through the transfer. The buffer must be aligned to DCACHE_LINE_SIZE_MAX and own the whole cache lines it covers, DCACHE_ROUND_UP(read_size) bytes: declare it with PBL_ALIGNED( DCACHE_LINE_SIZE_MAX) and that size.

Parameters

	slave	Device to read from.
	register_address_start	First register address.
	read_size	Number of bytes to read.
[out]	result_buffer	Destination buffer, see above.

Returns

True on success.

i2c_release()

void i2c_release

(

I2CSlavePort *

slave

)

Stop using the bus a device is connected to.

The bus is disabled when its last user releases it.

Parameters

slave

Device, which identifies the bus.

i2c_reset()

void i2c_reset

(

I2CSlavePort *

slave

)

Reset the bus a device is connected to.

Disables and re-enables the bus controller. The caller must be using the bus (i2c_use()).

Parameters

slave

Device, which identifies the bus.

i2c_use()

void i2c_use

(

I2CSlavePort *

slave

)

Start using the bus a device is connected to.

Reference counted per bus; the bus is enabled on the first user. Must be called before any transfer to the device.

Parameters

slave

Device, which identifies the bus.

i2c_write_block()

bool i2c_write_block	(	I2CSlavePort *	slave,
		uint32_t	write_size,
		const uint8_t *	buffer
	)

Write data without sending a register address.

Parameters

slave	Device to write to.
write_size	Number of bytes to write.
buffer	Data to write.

Returns

True on success.

i2c_write_read_block()

bool i2c_write_read_block	(	I2CSlavePort *	slave,
		uint32_t	write_size,
		const uint8_t *	write_buffer,
		uint32_t	read_size,
		uint8_t *	read_buffer
	)

Write data, then read data, with no other transfer on the bus in between.

Two transfers made while holding the bus lock, for devices that need a command before a read. The read is skipped if the write fails.

Parameters

	slave	Device to talk to.
	write_size	Number of bytes to write.
	write_buffer	Data to write.
	read_size	Number of bytes to read.
[out]	read_buffer	Destination buffer of at least read_size bytes.

Returns

True if both transfers succeeded.

i2c_write_register()

bool i2c_write_register	(	I2CSlavePort *	slave,
		uint8_t	register_address,
		uint8_t	value
	)

Write a register.

Parameters

slave	Device to write to.
register_address	Register address.
value	Value to write.

Returns

True on success.

i2c_write_register_block()

bool i2c_write_register_block	(	I2CSlavePort *	slave,
		uint8_t	register_address_start,
		uint32_t	write_size,
		const uint8_t *	buffer
	)

Write consecutive registers.

Parameters

slave	Device to write to.
register_address_start	First register address.
write_size	Number of bytes to write.
buffer	Data to write.

Returns

True on success.