General Functions

General functions for I2C driver. More...

Functions
INIT_CODE i2c_status_en	i2c_init (i2c_instance_en id)
INIT_CODE i2c_status_en	i2c_deinit (i2c_instance_en id)
i2c_status_en	i2c_controller_set_config (i2c_instance_en id, i2c_controller_config_t *cfg)
i2c_status_en	i2c_controller_get_config (i2c_instance_en id, i2c_controller_config_t *cfg)
i2c_status_en	i2c_controller_set_target_address (i2c_instance_en id, uint32_t address)
i2c_status_en	i2c_controller_get_target_address (i2c_instance_en id, uint32_t *tar_addr)
i2c_status_en	i2c_enable (i2c_instance_en id)
i2c_status_en	i2c_disable (i2c_instance_en id)
i2c_status_en	i2c_register_callback (i2c_instance_en id, i2c_event_cb_t cb, void *user_data)
i2c_status_en	i2c_controller_write_blocking (i2c_instance_en id, i2c_blocking_config_t *xfer)
i2c_status_en	i2c_controller_read_blocking (i2c_instance_en id, i2c_blocking_config_t *xfer)
i2c_status_en	i2c_controller_write_non_blocking (i2c_instance_en id, i2c_nonblocking_config_t *xfer)
i2c_status_en	i2c_controller_read_non_blocking (i2c_instance_en id, i2c_nonblocking_config_t *xfer)
i2c_status_en	i2c_controller_abort (i2c_instance_en id)
i2c_status_en	i2c_controller_get_transfer_count (i2c_instance_en id, uint32_t *count)
i2c_transfer_status_en	i2c_controller_get_transfer_status (i2c_instance_en id)
i2c_status_en	i2c_target_set_config (i2c_instance_en id, i2c_target_config_t *cfg)
i2c_status_en	i2c_target_get_config (i2c_instance_en id, i2c_target_config_t *cfg)
i2c_status_en	i2c_target_get_transfer_count (i2c_instance_en id, uint32_t *count)
i2c_status_en	i2c_target_abort (i2c_instance_en id)
i2c_transfer_status_en	i2c_target_get_transfer_status (i2c_instance_en id)
i2c_status_en	i2c_target_prep_controller_write (i2c_instance_en id, uint8_t *buf, uint32_t size)
i2c_status_en	i2c_target_prep_controller_read (i2c_instance_en id, uint8_t *buf, uint32_t size)
i2c_status_en	i2c_s_get_standard_speed_high_low_count (i2c_instance_en id, uint32_t *ss_low_count, uint32_t *ss_high_count)
i2c_status_en	i2c_s_get_fast_speed_high_low_count (i2c_instance_en id, uint32_t *fs_low_count, uint32_t *fs_high_count)
i2c_status_en	i2c_s_get_sda_hold_config (i2c_instance_en id, uint32_t *sda_hold_time_rx, uint32_t *sda_hold_time_tx)
i2c_status_en	i2c_s_set_standard_speed_high_low_count (i2c_instance_en id, uint32_t ss_low_count, uint32_t ss_high_count)
i2c_status_en	i2c_s_set_fast_speed_high_low_count (i2c_instance_en id, uint32_t fs_low_count, uint32_t fs_high_count)
i2c_status_en	i2c_s_set_sda_hold_config (i2c_instance_en id, uint32_t sda_hold_time_rx, uint32_t sda_hold_time_tx)

Detailed Description

General functions for I2C driver.

Function Documentation

i2c_init()

INIT_CODE i2c_status_en i2c_init

(

i2c_instance_en

id

)

Initialize the I²C peripheral for the given instance. Must be called before any other I²C driver functions. Reset block to default state and enables clock to I²C peripheral registers interface.

Parameters

id	I²C Instance ID.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_deinit()

INIT_CODE i2c_status_en i2c_deinit

(

i2c_instance_en

id

)

Reset context structure and hardware registers to default state, disable interrupts, disable the I²C peripheral, and disable clock to I²C peripheral registers interface.

Parameters

id	I²C Instance ID.

Returns

i2c_status_en. Status code indicating success or the reason for failure.

i2c_controller_set_config()

i2c_status_en i2c_controller_set_config	(	i2c_instance_en	id,
		i2c_controller_config_t *	cfg )

Configure the I²C peripheral for controller mode, formerly known as "master" mode. This includes configuring the following parameters:

• Addressing mode (7-bit or 10-bit)
• Bus speed (standard, fast, or high-speed)
• Enable SDA recovery (if SDA is stuck low hardware will attempt to recover)
• Set stuck low timers for SCL and SDA lines (if not required, set to 0)

Parameters

id	I²C instance identifier.
cfg	Pointer to configuration struct.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_controller_get_config()

i2c_status_en i2c_controller_get_config	(	i2c_instance_en	id,
		i2c_controller_config_t *	cfg )

Retrieve the current configuration of the I²C peripheral configured in controller mode.

Parameters

id	I²C instance identifier.
cfg	Pointer to structure to receive current configuration.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_controller_set_target_address()

i2c_status_en i2c_controller_set_target_address	(	i2c_instance_en	id,
		uint32_t	address )

In Controller mode set the 7 or 10-bit address of the Target device. Must be called while the block is disabled.

Parameters

id	I²C Instance ID.
address	7- or 10-bit target address.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_controller_get_target_address()

i2c_status_en i2c_controller_get_target_address	(	i2c_instance_en	id,
		uint32_t *	tar_addr )

Get the 7- or 10-bit Target address currently configured in Controller mode. Must be called while the block is disabled.

Parameters

id	I²C Instance ID.
tar_addr	Pointer to a variable that receives the current Target address.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_enable()

i2c_status_en i2c_enable

(

i2c_instance_en

id

)

Enable the I²C peripheral. After enabling, configuration cannot be changed, nor can the target address be changed until the block is disabled again.

Parameters

id	I²C Instance ID.

i2c_disable()

i2c_status_en i2c_disable

(

i2c_instance_en

id

)

Disable the I²C peripheral. Masks and clears all interrupts.

Parameters

id	I²C Instance ID.

i2c_register_callback()

i2c_status_en i2c_register_callback	(	i2c_instance_en	id,
		i2c_event_cb_t	cb,
		void *	user_data )

Register a callback. A majority of I²C block logic is handled in the driver ISR. This callback will be called on various events such as:

• Non-blocking transfer complete (read or write)
• General call detected (target mode)
• Write started (target mode)
• Read request (target mode)
• Transmitter Abort
• SCL Stuck Low Timeout

Note

That the callback can be called at anytime after the I²C block is enabled, Especially in target mode if the controller sends a read request, start writing data, or general call.

Parameters

id	I²C Instance ID.
cb	User callback function.

i2c_controller_write_blocking()

i2c_status_en i2c_controller_write_blocking	(	i2c_instance_en	id,
		i2c_blocking_config_t *	xfer )

Perform a blocking write as controller to the target with the address set in Setting Target Address. This function blocks until:

• All data is loaded into the TX FIFO (configurable via xfer.block_all)
• All data is sent and acknowledged by the target (configurable via xfer.block_all)
• Timeout occurs
• An error occurs (e.g., NACK from target, bus error, etc.)

If this transfer should not end with a STOP condition, set xfer.send_stop to false. This will force the next transfer to use a RESTART condition instead of a Start.

Parameters

id	I²C Instance ID.
xfer	Blocking transfer configuration.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_controller_read_blocking()

i2c_status_en i2c_controller_read_blocking	(	i2c_instance_en	id,
		i2c_blocking_config_t *	xfer )

Perform a blocking read as controller to the target with the address set in Setting Target Address.

This function blocks until:

• All data has been recieved and written into passed buffer
• Timeout occurs
• An error occurs

If this transfer should not end with a STOP condition, set xfer.send_stop to false. This will force the next transfer to use a RESTART condition instead of a Start.

Parameters

id	I²C Instance ID.
xfer	Blocking transfer configuration.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_controller_write_non_blocking()

i2c_status_en i2c_controller_write_non_blocking	(	i2c_instance_en	id,
		i2c_nonblocking_config_t *	xfer )

Start a non-blocking write as controller to the target with the address set in Setting Target Address. This function loads the TX FIFO with data and configures the the I²C interrupts to handle the rest of the transfer in the driver ISR.

The callback set in i2c_register_callback will be called when:

• All data is loaded into the TX FIFO (configurable via xfer.block_all)
• All data is sent and acknowledged by the target (configurable via xfer.block_all)
• An error occurs (e.g., NACK from target, bus error, etc.)

Parameters

id	I²C Instance ID.
xfer	Non-blocking transfer configuration.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_controller_read_non_blocking()

i2c_status_en i2c_controller_read_non_blocking	(	i2c_instance_en	id,
		i2c_nonblocking_config_t *	xfer )

Start a non-blocking read as controller to the target with the address set in Setting Target Address. This function configures the I²C interrupts to handle the transfer in the driver ISR.

The callback set in i2c_register_callback will be called when:

• All data has been received and written into the passed buffer
• An error occurs

Parameters

id	I²C Instance ID.
xfer	Non-blocking transfer configuration.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_controller_abort()

i2c_status_en i2c_controller_abort

(

i2c_instance_en

id

)

Abort an ongoing controller transfer. Issues STOP and clears FIFOs.

Parameters

id	I²C Instance ID.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_controller_get_transfer_count()

i2c_status_en i2c_controller_get_transfer_count	(	i2c_instance_en	id,
		uint32_t *	count )

Returns the number of bytes transferred since last call to a non-blocking read or write function.

Parameters

id	I²C Instance ID.
count	Pointer to a variable where the function will store the number of bytes transferred since the last non-blocking operation

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_controller_get_transfer_status()

i2c_transfer_status_en i2c_controller_get_transfer_status

(

i2c_instance_en

id

)

Returns the status of the ongoing non-blocking read or write transfer.

Parameters

id	I²C Instance ID.

Returns

i2c_transfer_status_en - Status:

• TRANSFER_STATUS_IDLE
• TRANSFER_STATUS_IN_PROGRESS
• TRANSFER_STATUS_COMPLETE
• TRANSFER_STATUS_ABORTED
• TRANSFER_STATUS_ERROR

i2c_target_set_config()

i2c_status_en i2c_target_set_config	(	i2c_instance_en	id,
		i2c_target_config_t *	cfg )

Configure the I²C peripheral for target mode, formerly known as "slave" mode. This includes configuring the following parameters:

• Addressing mode (7-bit or 10-bit)
• Controller Address (formerly known as "slave address"), the addres of this device.
• Bus speed (standard, fast, or high-speed)
• Enable general call response (if target should respond to general calls)
• Set stuck low timers for SCL and SDA lines (if not required, set to 0)

Parameters

id	I²C instance identifier.
cfg	Pointer to configuration struct.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_target_get_config()

i2c_status_en i2c_target_get_config	(	i2c_instance_en	id,
		i2c_target_config_t *	cfg )

Retrieve the current configuration of the I²C peripheral configured in target mode.

Parameters

id	I²C Instance ID.
cfg	Pointer to structure to receive current configuration.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_target_get_transfer_count()

i2c_status_en i2c_target_get_transfer_count	(	i2c_instance_en	id,
		uint32_t *	count )

Returns the number of bytes transferred since last call to a non-blocking read or write funciton.

Parameters

id	I²C Instance ID.
count	Pointer to a variable where the function will store the number of bytes transferred since the last non-blocking operation.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_target_abort()

i2c_status_en i2c_target_abort

(

i2c_instance_en

id

)

Abort an ongoing target transfer. Issues STOP and clears FIFOs.

Parameters

id	I²C Instance ID.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_target_get_transfer_status()

i2c_transfer_status_en i2c_target_get_transfer_status

(

i2c_instance_en

id

)

Get the status of an ongoing non-blocking I2C transfer.

Parameters

id	I2C instance identifier (e.g., I2CS)

Returns

Transfer status of type i2c_transfer_status_en. Possible return values:

• I2C_TRANSFER_STATUS_IN_PROGRESS : Transfer is still ongoing
• I2C_TRANSFER_STATUS_COMPLETE : Transfer completed successfully
• I2C_TRANSFER_STATUS_ABORTED : Transfer was aborted
• I2C_TRANSFER_STATUS_ERROR : Transfer encountered an error

i2c_target_prep_controller_write()

i2c_status_en i2c_target_prep_controller_write	(	i2c_instance_en	id,
		uint8_t *	buf,
		uint32_t	size )

Prepare target to receive a write from controller. If there is already data in the RX FIFO, it will first load that data into the provided buffer. The rest of the data will be received in the driver ISR.

Parameters

id	I²C Instance ID.
buf	Buffer for incoming data.
size	Number of bytes expected.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_target_prep_controller_read()

i2c_status_en i2c_target_prep_controller_read	(	i2c_instance_en	id,
		uint8_t *	buf,
		uint32_t	size )

Prepare target to send data to the controller, by writing data to the TX FIFO, and configuring interrupts to load more data if required. This could be called after a read request from the controller.

Parameters

id	I²C Instance ID.
buf	Data to send.
size	Number of bytes to send.

Returns

i2c_status_en Status code indicating success or the reason for failure.

i2c_s_get_standard_speed_high_low_count()

i2c_status_en i2c_s_get_standard_speed_high_low_count	(	i2c_instance_en	id,
		uint32_t *	ss_low_count,
		uint32_t *	ss_high_count )

Retrieves the Standard-mode SCL low and high counts from the I²C registers.

Parameters

id	I²C Instance ID.
ss_low_count	Pointer to a variable that will receive the Standard-mode SCL low count value.
ss_high_count	Pointer to a variable that will receive the Standard-mode SCL high count value.

Returns

i2c_status_en - Status:

• I2C_OK : Counts retrieved successfully.
• I2C_ERROR_PARAMETER : Invalid I²C instance or NULL pointer(s).

i2c_s_get_fast_speed_high_low_count()

i2c_status_en i2c_s_get_fast_speed_high_low_count	(	i2c_instance_en	id,
		uint32_t *	fs_low_count,
		uint32_t *	fs_high_count )

Retrieves the Fast-mode SCL low and high counts from the I²C registers.

Parameters

id	I²C Instance ID.
fs_low_count	Pointer to a variable that will receive the Fast-mode SCL low count value.
fs_high_count	Pointer to a variable that will receive the Fast-mode SCL high count value.

Returns

i2c_status_en - Status:

• I2C_OK : Counts retrieved successfully.
• I2C_ERROR_PARAMETER : Invalid I²C instance or NULL pointer(s).

i2c_s_get_sda_hold_config()

i2c_status_en i2c_s_get_sda_hold_config	(	i2c_instance_en	id,
		uint32_t *	sda_hold_time_rx,
		uint32_t *	sda_hold_time_tx )

Retrieves the SDA RX and TX hold times from the I²C registers.

Parameters

id	I²C Instance ID.
sda_hold_time_rx	Pointer to a variable that will receive the SDA RX hold time value.
sda_hold_time_tx	Pointer to a variable that will receive the SDA TX hold time value.

Returns

i2c_status_en - Status:

• I2C_OK : Hold times retrieved successfully.
• I2C_ERROR_PARAMETER : Invalid I²C instance or NULL pointer(s).

i2c_s_set_standard_speed_high_low_count()

i2c_status_en i2c_s_set_standard_speed_high_low_count	(	i2c_instance_en	id,
		uint32_t	ss_low_count,
		uint32_t	ss_high_count )

Sets the I²C Standard-mode SCL low and high counts to the specified values.

Parameters

id	I²C Instance ID.
ss_low_count	Standard-mode SCL low count value to program.
ss_high_count	Standard-mode SCL high count value to program.

Returns

i2c_status_en - Status:

• I2C_OK : Configuration applied successfully.
• I2C_ERROR_PARAMETER : Invalid I²C instance.

i2c_s_set_fast_speed_high_low_count()

i2c_status_en i2c_s_set_fast_speed_high_low_count	(	i2c_instance_en	id,
		uint32_t	fs_low_count,
		uint32_t	fs_high_count )

Sets the I²C Fast-mode SCL low and high counts to the specified values.

Parameters

id	I²C Instance ID.
fs_low_count	Fast-mode SCL low count value to program.
fs_high_count	Fast-mode SCL high count value to program.

Returns

i2c_status_en - Status:

• I2C_OK : Configuration applied successfully.
• I2C_ERROR_PARAMETER : Invalid I²C instance.

i2c_s_set_sda_hold_config()

i2c_status_en i2c_s_set_sda_hold_config	(	i2c_instance_en	id,
		uint32_t	sda_hold_time_rx,
		uint32_t	sda_hold_time_tx )

Sets the I²C SDA RX and TX hold times to the specified values.

Parameters

id	I²C Instance ID.
sda_hold_time_rx	SDA RX hold time value to program.
sda_hold_time_tx	SDA TX hold time value to program.

Returns

i2c_status_en - Status:

• I2C_OK : Configuration applied successfully.
• I2C_ERROR_PARAMETER : Invalid I²C instance.