Generic I2C Driver. More...

Collaboration diagram for I2C Driver:

Detailed Description

Generic I2C Driver.

This module implements a generic I2C (Inter-Integrated Circuit) driver.

Precondition: In order to use the I2C driver the HAL_USE_I2C option must be enabled in halconf.h.

Driver State Machine

The driver implements a state machine internally, not all the driver functionalities can be used in any moment, any transition not explicitly shown in the following diagram has to be considered an error and shall be captured by an assertion (if enabled).

The driver is not thread safe for performance reasons, if you need to access the I2C bus from multiple threads then use the i2cAcquireBus() and i2cReleaseBus() APIs in order to gain exclusive access.

Macros
#define	I2C_USE_MUTUAL_EXCLUSION TRUE
	Enables the mutual exclusion APIs on the I2C bus. More...

#define	_i2c_wakeup_isr(i2cp)
	Wakes up the waiting thread notifying no errors. More...

#define	_i2c_wakeup_error_isr(i2cp)
	Wakes up the waiting thread notifying errors. More...

#define	i2cMasterTransmit(i2cp, addr, txbuf, txbytes, rxbuf, rxbytes)
	Wrap i2cMasterTransmitTimeout function with TIME_INFINITE timeout. More...

#define	i2cMasterReceive(i2cp, addr, rxbuf, rxbytes) (i2cMasterReceiveTimeout(i2cp, addr, rxbuf, rxbytes, TIME_INFINITE))
	Wrap i2cMasterReceiveTimeout function with TIME_INFINITE timeout. More...

#define	i2c_lld_get_errors(i2cp) ((i2cp)->errors)
	Get errors from I2C driver. More...

I2C bus error conditions
#define	I2C_NO_ERROR 0x00
	No error. More...

#define	I2C_BUS_ERROR 0x01
	Bus Error. More...

#define	I2C_ARBITRATION_LOST 0x02
	Arbitration Lost. More...

#define	I2C_ACK_FAILURE 0x04
	Acknowledge Failure. More...

#define	I2C_OVERRUN 0x08
	Overrun/Underrun. More...

#define	I2C_PEC_ERROR 0x10
	PEC Error in reception. More...

#define	I2C_TIMEOUT 0x20
	Hardware timeout. More...

#define	I2C_SMB_ALERT 0x40
	SMBus Alert. More...

PLATFORM configuration options
#define	PLATFORM_I2C_USE_I2C1 FALSE
	I2C1 driver enable switch. More...

Typedefs
typedef uint16_t	i2caddr_t
	Type representing an I2C address. More...

typedef uint32_t	i2cflags_t
	Type of I2C Driver condition flags. More...

typedef struct I2CDriver	I2CDriver
	Type of a structure representing an I2C driver. More...

Data Structures
struct	I2CConfig
	Type of I2C driver configuration structure. More...

struct	I2CDriver
	Structure representing an I2C driver. More...

Functions
void	i2cInit (void)
	I2C Driver initialization. More...

void	i2cObjectInit (I2CDriver *i2cp)
	Initializes the standard part of a `I2CDriver` structure. More...

void	i2cStart (I2CDriver i2cp, const I2CConfig config)
	Configures and activates the I2C peripheral. More...

void	i2cStop (I2CDriver *i2cp)
	Deactivates the I2C peripheral. More...

i2cflags_t	i2cGetErrors (I2CDriver *i2cp)
	Returns the errors mask associated to the previous operation. More...

msg_t	i2cMasterTransmitTimeout (I2CDriver i2cp, i2caddr_t addr, const uint8_t txbuf, size_t txbytes, uint8_t *rxbuf, size_t rxbytes, sysinterval_t timeout)
	Sends data via the I2C bus. More...

msg_t	i2cMasterReceiveTimeout (I2CDriver i2cp, i2caddr_t addr, uint8_t rxbuf, size_t rxbytes, sysinterval_t timeout)
	Receives data from the I2C bus. More...

void	i2cAcquireBus (I2CDriver *i2cp)
	Gains exclusive access to the I2C bus. More...

void	i2cReleaseBus (I2CDriver *i2cp)
	Releases exclusive access to the I2C bus. More...

void	i2c_lld_init (void)
	Low level I2C driver initialization. More...

void	i2c_lld_start (I2CDriver *i2cp)
	Configures and activates the I2C peripheral. More...

void	i2c_lld_stop (I2CDriver *i2cp)
	Deactivates the I2C peripheral. More...

msg_t	i2c_lld_master_receive_timeout (I2CDriver i2cp, i2caddr_t addr, uint8_t rxbuf, size_t rxbytes, sysinterval_t timeout)
	Receives data via the I2C bus as master. More...

msg_t	i2c_lld_master_transmit_timeout (I2CDriver i2cp, i2caddr_t addr, const uint8_t txbuf, size_t txbytes, uint8_t *rxbuf, size_t rxbytes, sysinterval_t timeout)
	Transmits data via the I2C bus as master. More...

Enumerations

Variables
I2CDriver	I2CD1
	I2C1 driver identifier. More...

Macro Definition Documentation

#define I2C_NO_ERROR 0x00

No error.

Definition at line 43 of file hal_i2c.h.

Referenced by i2cMasterReceiveTimeout(), and i2cMasterTransmitTimeout().

#define I2C_BUS_ERROR 0x01

Bus Error.

Definition at line 44 of file hal_i2c.h.

#define I2C_ARBITRATION_LOST 0x02

Arbitration Lost.

Definition at line 45 of file hal_i2c.h.

#define I2C_ACK_FAILURE 0x04

Acknowledge Failure.

Definition at line 46 of file hal_i2c.h.

#define I2C_OVERRUN 0x08

Overrun/Underrun.

Definition at line 47 of file hal_i2c.h.

#define I2C_PEC_ERROR 0x10

PEC Error in reception.

Definition at line 48 of file hal_i2c.h.

#define I2C_TIMEOUT 0x20

Hardware timeout.

Definition at line 51 of file hal_i2c.h.

#define I2C_SMB_ALERT 0x40

SMBus Alert.

Definition at line 52 of file hal_i2c.h.

#define I2C_USE_MUTUAL_EXCLUSION TRUE

Enables the mutual exclusion APIs on the I2C bus.

Definition at line 63 of file hal_i2c.h.

#define _i2c_wakeup_isr ( i2cp )

Value:

do {                                          \
  osalSysLockFromISR();                                                     \
  osalThreadResumeI(&(i2cp)->thread, MSG_OK);                               \
  osalSysUnlockFromISR();                                                   \
} while(0)

Wakes up the waiting thread notifying no errors.

Parameters

[in] i2cp pointer to the I2CDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 99 of file hal_i2c.h.

#define _i2c_wakeup_error_isr ( i2cp )

Value:

do {                                    \
  osalSysLockFromISR();                                                     \
  osalThreadResumeI(&(i2cp)->thread, MSG_RESET);                            \
  osalSysUnlockFromISR();                                                   \
} while(0)

Wakes up the waiting thread notifying errors.

Parameters

[in] i2cp pointer to the I2CDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 112 of file hal_i2c.h.

#define i2cMasterTransmit	(	i2cp,
		addr,
		txbuf,
		txbytes,
		rxbuf,
		rxbytes
	)

Value:

(i2cMasterTransmitTimeout(i2cp, addr, txbuf, txbytes, rxbuf, rxbytes, \

TIME_INFINITE))

i2cMasterTransmitTimeout

msg_t i2cMasterTransmitTimeout(I2CDriver *i2cp, i2caddr_t addr, const uint8_t *txbuf, size_t txbytes, uint8_t *rxbuf, size_t rxbytes, sysinterval_t timeout)

Sends data via the I2C bus.

Definition: hal_i2c.c:170

Wrap i2cMasterTransmitTimeout function with TIME_INFINITE timeout.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 122 of file hal_i2c.h.

#define i2cMasterReceive	(	i2cp,
		addr,
		rxbuf,
		rxbytes
	)	(i2cMasterReceiveTimeout(i2cp, addr, rxbuf, rxbytes, TIME_INFINITE))

Wrap i2cMasterReceiveTimeout function with TIME_INFINITE timeout.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 130 of file hal_i2c.h.

#define PLATFORM_I2C_USE_I2C1 FALSE

I2C1 driver enable switch.

If set to TRUE the support for I2C1 is included.

Note: The default is FALSE.

Definition at line 48 of file hal_i2c_lld.h.

#define i2c_lld_get_errors ( i2cp ) ((i2cp)->errors)

Get errors from I2C driver.

Parameters

[in] i2cp pointer to the I2CDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 121 of file hal_i2c_lld.h.

Referenced by i2cGetErrors().

Typedef Documentation

typedef uint16_t i2caddr_t

Type representing an I2C address.

Definition at line 63 of file hal_i2c_lld.h.

typedef uint32_t i2cflags_t

Type of I2C Driver condition flags.

Definition at line 68 of file hal_i2c_lld.h.

typedef struct I2CDriver I2CDriver

Type of a structure representing an I2C driver.

Definition at line 83 of file hal_i2c_lld.h.

Enumeration Type Documentation

enum i2cstate_t

Driver state machine possible states.

Enumerator
I2C_UNINIT	Not initialized.
I2C_STOP	Stopped.
I2C_READY	Ready.
I2C_ACTIVE_TX	Transmitting.
I2C_ACTIVE_RX	Receiving.

Definition at line 77 of file hal_i2c.h.

Function Documentation

void i2cInit ( void )

I2C Driver initialization.

Note: This function is implicitly invoked by halInit(), there is no need to explicitly initialize the driver.

Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 59 of file hal_i2c.c.

References i2c_lld_init().

Referenced by halInit().

Here is the call graph for this function:

void i2cObjectInit ( I2CDriver * i2cp )

Initializes the standard part of a I2CDriver structure.

Parameters

[out] i2cp pointer to the I2CDriver object

Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 71 of file hal_i2c.c.

References I2CDriver::config, I2C_STOP, osalMutexObjectInit(), and I2CDriver::state.

Referenced by i2c_lld_init().

Here is the call graph for this function:

void i2cStart	(	I2CDriver *	i2cp,
		const I2CConfig *	config
	)

Configures and activates the I2C peripheral.

Parameters

[in]	i2cp	pointer to the `I2CDriver` object
[in]	config	pointer to the `I2CConfig` object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 93 of file hal_i2c.c.

References I2CDriver::config, i2c_lld_start(), I2C_READY, I2C_STOP, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and I2CDriver::state.

Here is the call graph for this function:

void i2cStop ( I2CDriver * i2cp )

Deactivates the I2C peripheral.

Parameters

[in] i2cp pointer to the I2CDriver object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 113 of file hal_i2c.c.

References I2CDriver::config, i2c_lld_stop(), I2C_READY, I2C_STOP, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and I2CDriver::state.

Here is the call graph for this function:

i2cflags_t i2cGetErrors ( I2CDriver * i2cp )

Returns the errors mask associated to the previous operation.

Parameters

[in] i2cp pointer to the I2CDriver object

Returns: The errors mask.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 137 of file hal_i2c.c.

References i2c_lld_get_errors, and osalDbgCheck.

msg_t i2cMasterTransmitTimeout	(	I2CDriver *	i2cp,
		i2caddr_t	addr,
		const uint8_t *	txbuf,
		size_t	txbytes,
		uint8_t *	rxbuf,
		size_t	rxbytes,
		sysinterval_t	timeout
	)

Sends data via the I2C bus.

Function designed to realize "read-through-write" transfer paradigm. If you want transmit data without any further read, than set rxbytes field to 0.

Parameters

[in]	i2cp	pointer to the `I2CDriver` object
[in]	addr	slave device address (7 bits) without R/W bit
[in]	txbuf	pointer to transmit buffer
[in]	txbytes	number of bytes to be transmitted
[out]	rxbuf	pointer to receive buffer
[in]	rxbytes	number of bytes to be received, set it to 0 if you want transmit only
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_INFINITE no timeout.

Returns: The operation status.

Return values

MSG_OK	if the function succeeded.
MSG_RESET	if one or more I2C errors occurred, the errors can be retrieved using `i2cGetErrors()`.
MSG_TIMEOUT	if a timeout occurred before operation end.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 170 of file hal_i2c.c.

References I2CDriver::errors, I2C_ACTIVE_TX, i2c_lld_master_transmit_timeout(), I2C_NO_ERROR, I2C_READY, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and I2CDriver::state.

Here is the call graph for this function:

msg_t i2cMasterReceiveTimeout	(	I2CDriver *	i2cp,
		i2caddr_t	addr,
		uint8_t *	rxbuf,
		size_t	rxbytes,
		sysinterval_t	timeout
	)

Receives data from the I2C bus.

Parameters

[in]	i2cp	pointer to the `I2CDriver` object
[in]	addr	slave device address (7 bits) without R/W bit
[out]	rxbuf	pointer to receive buffer
[in]	rxbytes	number of bytes to be received
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_INFINITE no timeout.

Returns: The operation status.

Return values

MSG_OK	if the function succeeded.
MSG_RESET	if one or more I2C errors occurred, the errors can be retrieved using `i2cGetErrors()`.
MSG_TIMEOUT	if a timeout occurred before operation end.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 221 of file hal_i2c.c.

References I2CDriver::errors, I2C_ACTIVE_RX, i2c_lld_master_receive_timeout(), I2C_NO_ERROR, I2C_READY, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and I2CDriver::state.

Here is the call graph for this function:

void i2cAcquireBus ( I2CDriver * i2cp )

Gains exclusive access to the I2C bus.

This function tries to gain ownership to the I2C bus, if the bus is already being used then the invoking thread is queued.

Precondition: In order to use this function the option I2C_USE_MUTUAL_EXCLUSION must be enabled.

Parameters

[in] i2cp pointer to the I2CDriver object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 261 of file hal_i2c.c.

References osalDbgCheck, and osalMutexLock().

Here is the call graph for this function:

void i2cReleaseBus ( I2CDriver * i2cp )

Releases exclusive access to the I2C bus.

Precondition: In order to use this function the option I2C_USE_MUTUAL_EXCLUSION must be enabled.

Parameters

[in] i2cp pointer to the I2CDriver object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 277 of file hal_i2c.c.

References osalDbgCheck, and osalMutexUnlock().

Here is the call graph for this function:

void i2c_lld_init ( void )

Low level I2C driver initialization.

Function Class:Not an API, this function is for internal use only.

Definition at line 65 of file hal_i2c_lld.c.

References i2cObjectInit().

Referenced by i2cInit().

Here is the call graph for this function:

void i2c_lld_start ( I2CDriver * i2cp )

Configures and activates the I2C peripheral.

Parameters

[in] i2cp pointer to the I2CDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 79 of file hal_i2c_lld.c.

References I2C_STOP, and I2CDriver::state.

Referenced by i2cStart().

void i2c_lld_stop ( I2CDriver * i2cp )

Deactivates the I2C peripheral.

Parameters

[in] i2cp pointer to the I2CDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 99 of file hal_i2c_lld.c.

References I2C_STOP, and I2CDriver::state.

Referenced by i2cStop().

msg_t i2c_lld_master_receive_timeout	(	I2CDriver *	i2cp,
		i2caddr_t	addr,
		uint8_t *	rxbuf,
		size_t	rxbytes,
		sysinterval_t	timeout
	)

Receives data via the I2C bus as master.

Parameters

[in]	i2cp	pointer to the `I2CDriver` object
[in]	addr	slave device address
[out]	rxbuf	pointer to the receive buffer
[in]	rxbytes	number of bytes to be received
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_INFINITE no timeout.

Returns: The operation status.

Return values

MSG_OK	if the function succeeded.
MSG_RESET	if one or more I2C errors occurred, the errors can be retrieved using `i2cGetErrors()`.
MSG_TIMEOUT	if a timeout occurred before operation end. After a timeout the driver must be stopped and restarted because the bus is in an uncertain state.

Function Class:Not an API, this function is for internal use only.

Definition at line 133 of file hal_i2c_lld.c.

Referenced by i2cMasterReceiveTimeout().

msg_t i2c_lld_master_transmit_timeout	(	I2CDriver *	i2cp,
		i2caddr_t	addr,
		const uint8_t *	txbuf,
		size_t	txbytes,
		uint8_t *	rxbuf,
		size_t	rxbytes,
		sysinterval_t	timeout
	)

Transmits data via the I2C bus as master.

Parameters

[in]	i2cp	pointer to the `I2CDriver` object
[in]	addr	slave device address
[in]	txbuf	pointer to the transmit buffer
[in]	txbytes	number of bytes to be transmitted
[out]	rxbuf	pointer to the receive buffer
[in]	rxbytes	number of bytes to be received
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_INFINITE no timeout.

Returns: The operation status.

Return values

MSG_OK	if the function succeeded.
MSG_RESET	if one or more I2C errors occurred, the errors can be retrieved using `i2cGetErrors()`.
MSG_TIMEOUT	if a timeout occurred before operation end. After a timeout the driver must be stopped and restarted because the bus is in an uncertain state.

Function Class:Not an API, this function is for internal use only.

Definition at line 169 of file hal_i2c_lld.c.

Referenced by i2cMasterTransmitTimeout().

Variable Documentation

I2CDriver I2CD1

I2C1 driver identifier.

Definition at line 41 of file hal_i2c_lld.c.

Detailed Description

Driver State Machine

Macros

I2C bus error conditions

PLATFORM configuration options

Typedefs

Data Structures

Functions

Enumerations

Variables

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation