RTOS-integrated I2C Framework. More...

Data Structures
struct	sf_i2c_instance_ctrl_t

Functions
ssp_err_t	SF_I2C_Open (sf_i2c_ctrl_t const p_api_ctrl, sf_i2c_cfg_t const const p_cfg)
	Initialize a I2C bus and open low level I2C driver. More...

ssp_err_t	SF_I2C_Read (sf_i2c_ctrl_t const p_api_ctrl, uint8_t const p_dest, uint32_t const bytes, bool const restart, uint32_t const timeout)
	Start the transfer process and receive data from I2C device. More...

ssp_err_t	SF_I2C_Write (sf_i2c_ctrl_t const p_api_ctrl, uint8_t const p_src, uint32_t const bytes, bool const restart, uint32_t const timeout)
	Start the transfer process and send data on I2C bus. More...

ssp_err_t	SF_I2C_Reset (sf_i2c_ctrl_t *const p_api_ctrl, uint32_t const timeout)
	Abort any in-progress transfer. More...

ssp_err_t	SF_I2C_Close (sf_i2c_ctrl_t *const p_api_ctrl)
	Close the I2C device designated by the control handle and close the RTOS services used by the bus if last device is connected to the bus calls this API, else decrement the device count. More...

ssp_err_t	SF_I2C_Lock (sf_i2c_ctrl_t *const p_api_ctrl)
	Lock the bus for a device. Once bus is locked by a device it can not be used by other devices. More...

ssp_err_t	SF_I2C_Unlock (sf_i2c_ctrl_t *const p_api_ctrl)
	Unlock the locked bus and make the bus usable for other devices. More...

ssp_err_t	SF_I2C_VersionGet (ssp_version_t *const p_version)
	Get the version information of the framework. More...

ssp_err_t	SF_I2C_LockWait (sf_i2c_ctrl_t *const p_api_ctrl, uint32_t const timeout)
	Lock the I2C Bus resource. Once bus is locked by a device it can not be used by other devices. More...

Detailed Description

RTOS-integrated I2C Framework.

SSP I2C framework driver API

.

Summary

This is a ThreadX-aware I2C driver API. The API implements the I2C Framework interface and can access several hardware peripherals at the HAL layer. The connection to the HAL layer is established by passing in a driver structure in SF_I2C_Open.

Interface Used

See also: I2C Framework

Function Documentation

◆ SF_I2C_Close()

ssp_err_t SF_I2C_Close ( sf_i2c_ctrl_t *const p_api_ctrl )

Close the I2C device designated by the control handle and close the RTOS services used by the bus if last device is connected to the bus calls this API, else decrement the device count.

Return values

SSP_SUCCESS	Device is successfully closed.
SSP_ERR_NOT_OPEN	Device was not even opened.
SSP_ERR_ASSERTION	Following parameters is NULL: p_api_ctrl.

Returns

See Common Error Codes and lower level driver function for other possible return codes. This driver function is:

i2c_api_master_t::close

Note: This function is reentrant for any device.

Check whether device is opened or not.

Acquire the device count mutex before accessing the shared resource in close.

Check the count of opened devices on the bus. If there are no devices opened or all other devices on the bus are closed then close the low level I2C driver and release the RTOS services used by the bus.

Get the low level control in use.

Close low level driver.

Delete RTOS services used by the bus.

Decrement device count.

Delete the device count mutex

Decrement device count.

Release the device count mutex

Set device to closed state and restarted flag to false.

◆ SF_I2C_Lock()

ssp_err_t SF_I2C_Lock ( sf_i2c_ctrl_t *const p_api_ctrl )

Lock the bus for a device. Once bus is locked by a device it can not be used by other devices.

Return values

SSP_SUCCESS	I2C channel is successfully locked.
SSP_ERR_NOT_OPEN	Device not opened.
SSP_ERR_IN_USE	In-use error.
SSP_ERR_ASSERTION	Following parameters is NULL: p_api_ctrl.

Note: This function is reentrant for any device.

Check whether device is opened or not.

Get mutex since this will access hardware registers.

Reconfigure the device address, if necessary

◆ SF_I2C_LockWait()

ssp_err_t SF_I2C_LockWait	(	sf_i2c_ctrl_t *const	p_api_ctrl,
		uint32_t const	timeout
	)

Lock the I2C Bus resource. Once bus is locked by a device it can not be used by other devices.

Return values

SSP_SUCCESS	I2C channel is successfully locked within the specified timeout.
SSP_ERR_ASSERTION	Pointer to I2C control block is NULL.
SSP_ERR_NOT_OPEN	Device not opened.
SSP_ERR_TIMEOUT	Mutex not available in timeout.

Note: This function is reentrant for any device.

Check whether device is opened or not.

Get the mutex for this device.

Reconfigure the device address, if necessary

◆ SF_I2C_Open()

ssp_err_t SF_I2C_Open	(	sf_i2c_ctrl_t *const	p_api_ctrl,
		sf_i2c_cfg_t const *const	p_cfg
	)

Initialize a I2C bus and open low level I2C driver.

Return values

SSP_SUCCESS	I2C device is successfully opened.
SSP_ERR_ASSERTION	One of the following parameters is NULL: p_api_ctrl, p_cfg, Pointer to Open, Close, Read, Write, or reset API interfaces,p_cfg->p_bus.
SSP_ERR_INTERNAL	Internal error occurred.
SSP_ERR_ALREADY_OPEN	Same I2C framework device is already open.

Returns

See Common Error Codes and lower level driver function for other possible return codes. This driver function is

i2c_api_master_t::open

Note: This function is reentrant for any channel.; Control handle must be cleared by caller before calling this function.

Check whether device is already opened or not.

Copy bus pointer to control

Set framework level callback function.

Save context for use in ISRs.

Enter a critical section before checking the device count mutex status.

Check if device count mutex is already created. If not then create the mutex.

Create device_count_mutex. This is used to protect shared variable device_count in bus control structure.

If mutex create fails, return error.

Exit critical section

Acquire the device count mutex before accessing the shared resource. Try again if the mutex was deleted in close.

Increment device count.

Release the device count mutex

Save device configuration for reconfiguration.

Set device state as Opened.

Initialize restarted flag to false.

◆ SF_I2C_Read()

ssp_err_t SF_I2C_Read	(	sf_i2c_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_dest,
		uint32_t const	bytes,
		bool const	restart,
		uint32_t const	timeout
	)

Start the transfer process and receive data from I2C device.

Return values

SSP_SUCCESS	Data received successfully.
SSP_ERR_NOT_OPEN	Device instance not opened.
SSP_ERR_ASSERTION	One of the following parameters is NULL: p_api_ctrl, p_dest, bytes, timeout.

Returns

See Common Error Codes and lower level driver function for other possible return codes. This driver function is:

i2c_api_master_t::read

Check whether device is opened or not.

Start transfer process - check reconfiguration, get Mutex.

Get the low level control in use.

Perform read.

Wait for callback to set event flag.

Finish transfer.

◆ SF_I2C_Reset()

ssp_err_t SF_I2C_Reset	(	sf_i2c_ctrl_t *const	p_api_ctrl,
		uint32_t const	timeout
	)

Abort any in-progress transfer.

Return values

SSP_SUCCESS	Channel was reseted without issue.
SSP_ERR_NOT_OPEN	Device was not even opened.
SSP_ERR_IN_USE	In-use error.
SSP_ERR_INTERNAL	Internal error occurred.
SSP_ERR_ASSERTION	Following parameters is NULL: p_api_ctrl.

Returns

See Common Error Codes and lower level driver function for other possible return codes. This driver function is:

i2c_api_master_t::reset

Check whether device is opened or not.

Get the low level control in use.

Get mutex since this will access hardware registers.

◆ SF_I2C_Unlock()

ssp_err_t SF_I2C_Unlock ( sf_i2c_ctrl_t *const p_api_ctrl )

Unlock the locked bus and make the bus usable for other devices.

Return values

SSP_SUCCESS	I2C bus is successfully unlocked.
SSP_ERR_NOT_OPEN	Device not opened.
SSP_ERR_IN_USE	In-use error.
SSP_ERR_ASSERTION	Following parameters is NULL: p_api_ctrl.

Note: This function is reentrant for any device.

Check whether device is opened or not.

Release the mutex so that others can use the bus.

◆ SF_I2C_VersionGet()

ssp_err_t SF_I2C_VersionGet ( ssp_version_t *const p_version )

Get the version information of the framework.

Return values

SSP_SUCCESS	Got version number successfully.
SSP_ERR_ASSERTION	Following parameters is NULL: p_version.

Checks error. Further parameter checking can be done at the driver layer.

◆ SF_I2C_Write()

ssp_err_t SF_I2C_Write	(	sf_i2c_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_src,
		uint32_t const	bytes,
		bool const	restart,
		uint32_t const	timeout
	)

Start the transfer process and send data on I2C bus.

Return values

SSP_SUCCESS	Data written successfully.
SSP_ERR_NOT_OPEN	Device instance not opened.
SSP_ERR_ASSERTION	One of the following parameters is NULL: p_api_ctrl, p_src, bytes.

Returns

See Common Error Codes and lower level driver function for other possible return codes. This driver function is:

i2c_api_master_t::write

Check whether device is opened or not.

Start transfer process - check reconfiguration, get Mutex.

Get the low level control in use.

Perform write.

Wait for callback to set event flag.

Finish transfer.

Data Structures

Functions

Detailed Description

Summary

Interface Used

Function Documentation

◆ SF_I2C_Close()

◆ SF_I2C_Lock()

◆ SF_I2C_LockWait()

◆ SF_I2C_Open()

◆ SF_I2C_Read()

◆ SF_I2C_Reset()

◆ SF_I2C_Unlock()

◆ SF_I2C_VersionGet()

◆ SF_I2C_Write()