Defined behavior

More...

Modules
	I2C hal tests
	The I2C HAL tests ensure driver conformance to defined behaviour.

Functions
void	i2c_get_capabilities (i2c_capabilities_t *capabilities)
	Fills structure indicating supported features and frequencies on the current platform. More...

void	i2c_init (i2c_t *obj, PinName sda, PinName scl, bool is_slave)
	Initialize the I2C peripheral. More...

void	i2c_free (i2c_t *obj)
	Release the I2C object. More...

uint32_t	i2c_frequency (i2c_t *obj, uint32_t frequency)
	Configure the frequency in Hz at which the I2C peripheral should operate. More...

void	i2c_set_clock_stretching (i2c_t *obj, bool enabled)
	Enable or disable clock stretching for the I2C peripheral. More...

void	i2c_timeout (i2c_t *obj, uint32_t timeout)
	Configure the timeout duration in microseconds for blocking transmission. More...

void	i2c_start (i2c_t *obj)
	Send START command. More...

void	i2c_stop (i2c_t *obj)
	Send STOP command. More...

int32_t	i2c_write (i2c_t obj, uint16_t address, const uint8_t data, uint32_t length, bool stop)
	Blocking sending data. More...

int32_t	i2c_read (i2c_t obj, uint16_t address, uint8_t data, uint32_t length, bool stop)
	Blocking reading data. More...

const PinMap *	i2c_master_sda_pinmap (void)
	Get the pins that support I2C SDA. More...

const PinMap *	i2c_master_scl_pinmap (void)
	Get the pins that support I2C SCL. More...

const PinMap *	i2c_slave_sda_pinmap (void)
	Get the pins that support I2C SDA. More...

const PinMap *	i2c_slave_scl_pinmap (void)
	Get the pins that support I2C SCL. More...

Detailed Description

Defined behavior

i2c_init initializes i2c_t control structure
i2c_init configures the pins used by I2C
i2c_free returns the pins owned by the I2C object to their reset state
i2c_frequency configure the I2C frequency
i2c_start sends START command
i2c_read reads length bytes from the I2C slave specified by address to the data buffer
i2c_read reads generates a stop condition on the bus at the end of the transfer if stop parameter is non-zero
i2c_read reads returns the number of symbols received from the bus
i2c_write writes length bytes to the I2C slave specified by address from the data buffer
i2c_write generates a stop condition on the bus at the end of the transfer if stop parameter is non-zero
i2c_write returns zero on success, error code otherwise
::i2c_reset resets the I2C peripheral
::i2c_byte_read reads and return one byte from the specfied I2C slave
::i2c_byte_read uses last parameter to inform the slave that all bytes have been read
::i2c_byte_write writes one byte to the specified I2C slave
::i2c_byte_write returns 0 if NAK was received, 1 if ACK was received, 2 for timeout
::i2c_slave_mode enables/disables I2S slave mode
::i2c_slave_receive returns: 1 - read addresses, 2 - write to all slaves, 3 write addressed, 0 - the slave has not been addressed
::i2c_slave_read reads length bytes from the I2C master to the data buffer
::i2c_slave_read returns non-zero if a value is available, 0 otherwise
::i2c_slave_write writes length bytes to the I2C master from the data buffer
::i2c_slave_write returns non-zero if a value is available, 0 otherwise
i2c_slave_address configures I2C slave address
::i2c_transfer_asynch starts I2C asynchronous transfer
::i2c_transfer_asynch writes tx_length bytes to the I2C slave specified by address from the tx buffer
::i2c_transfer_asynch reads rx_length bytes from the I2C slave specified by address to the rx buffer
::i2c_transfer_asynch generates a stop condition on the bus at the end of the transfer if stop parameter is non-zero
The callback given to ::i2c_transfer_asynch is invoked when the transfer completes
::i2c_transfer_asynch specifies the logical OR of events to be registered
The ::i2c_transfer_asynch function may use the DMAUsage hint to select the appropriate async algorithm
::i2c_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise returns 0.
::i2c_active returns non-zero if the I2C module is active or 0 if it is not
::i2c_abort_asynch aborts an on-going async transfer

Undefined behavior

Calling i2c_init multiple times on the same i2c_t
Calling any function other than i2c_init on a non-initialized i2c_t
Initialising the I2C peripheral with invalid SDA and SCL pins.
Passing pins that cannot be on the same peripheral
Passing an invalid pointer as obj to any function
Use of a null pointer as an argument to any function.
Initialising the peripheral in slave mode if slave mode is not supported
Operating the peripheral in slave mode without first specifying and address using i2c_slave_address
Setting an address using i2c_slave_address after initialising the peripheral in master mode
Setting an address to an I2C reserved value
Specifying an invalid address when calling any read or write functions
Setting the length of the transfer or receive buffers to larger than the buffers are
Passing an invalid pointer as handler
Calling i2c_abort_async when no transfer is currently in progress

Function Documentation

void i2c_free ( i2c_t * obj )

Release the I2C object.

Parameters

obj	The I2C object to deinitialize

uint32_t i2c_frequency	(	i2c_t *	obj,
		uint32_t	frequency
	)

Configure the frequency in Hz at which the I2C peripheral should operate.

Parameters

obj	The I2C object
frequency	Frequency in Hz

Returns: The actual frequency that the peripheral generates to allow a user to adjust its strategy in case the target cannot be reached.

void i2c_get_capabilities ( i2c_capabilities_t * capabilities )

Fills structure indicating supported features and frequencies on the current platform.

Parameters

[out] capabilities Capabilities structure filled with supported configurations.

void i2c_init	(	i2c_t *	obj,
		PinName	sda,
		PinName	scl,
		bool	is_slave
	)

Initialize the I2C peripheral.

It sets the default parameters for the I2C peripheral and configures its pins.

Parameters

obj	The I2C object
sda	The sda pin
scl	The scl pin
is_slave	Choose whether the peripheral is initialized as master or slave.

const PinMap* i2c_master_scl_pinmap ( void )

Get the pins that support I2C SCL.

Return a PinMap array of pins that support I2C SCL in master mode. The array is terminated with {NC, NC, 0}.

Returns: PinMap array

const PinMap* i2c_master_sda_pinmap ( void )

Get the pins that support I2C SDA.

Return a PinMap array of pins that support I2C SDA in master mode. The array is terminated with {NC, NC, 0}.

Returns: PinMap array

int32_t i2c_read	(	i2c_t *	obj,
		uint16_t	address,
		uint8_t *	data,
		uint32_t	length,
		bool	stop
	)

Blocking reading data.

This function receives data when the peripheral is configured as Master from the selected slave and when configured as Slave from the Master.

This function is blocking; it returns when the transfer is complete or a timeout event is triggered. The number of bytes received is returned by the function after the operation is completed. Receive operation cannot be canceled or aborted.

When in master mode, the operation consists of:

Addressing the slave as a Master receiver.
Receiving data from the addressed slave.
Generating a STOP condition if the specified stop field is true.

Parameters

obj	The I2C object
address	7/10-bit address (last bit is 1)
data	The buffer for receiving
length	Number of bytes to read
stop	If true, stop is generated after the transfer is done

Note: If the current platform supports multimaster operation, the peripheral performs arbitration automatically when detecting collisions and completes the transfer or returns I2C_ERROR_ARBITRATION_LOST when it loses arbitration.

Additional time for arbitration or clock stretching should by count by setting appropriate timeout value.

When no transmision timeout is set by the user, the default timeout value is used. It counts one additional byte for addressing stage: default_timeout = (length + 1) * byte_timeout.

Returns: zero or nonzero - Number of written bytes negative - I2C_ERROR_XXX status

void i2c_set_clock_stretching	(	i2c_t *	obj,
		bool	enabled
	)

Enable or disable clock stretching for the I2C peripheral.

Parameters

obj	The I2C object
enabled	If 'true', enable clock stretching on the given I2C peripheral; otherwise, disable it.

const PinMap* i2c_slave_scl_pinmap ( void )

Get the pins that support I2C SCL.

Return a PinMap array of pins that support I2C SCL in slave mode. The array is terminated with {NC, NC, 0}.

Returns: PinMap array

const PinMap* i2c_slave_sda_pinmap ( void )

Get the pins that support I2C SDA.

Return a PinMap array of pins that support I2C SDA in slave mode. The array is terminated with {NC, NC, 0}.

Returns: PinMap array

void i2c_start ( i2c_t * obj )

Send START command.

Parameters

obj	The I2C object.

void i2c_stop ( i2c_t * obj )

Send STOP command.

Parameters

obj	The I2C object

void i2c_timeout	(	i2c_t *	obj,
		uint32_t	timeout
	)

Configure the timeout duration in microseconds for blocking transmission.

Parameters

obj	The I2C object
timeout	Transmission timeout in microseconds.

Note: If no timeout is set, the default timeout is used. Default timeout value is based on I2C frequency. Byte timeout is computed as triple amount of time it would take to send 10 bit over I2C and is expressed by the formula: byte_timeout = 3 * (1/frequency * 10 * 1000000)

int32_t i2c_write	(	i2c_t *	obj,
		uint16_t	address,
		const uint8_t *	data,
		uint32_t	length,
		bool	stop
	)

Blocking sending data.

This function transmits data when the peripheral is configured as Master to the selected slave and when configured as Slave transmits data to the Master.

This function is blocking; it returns when the transfer is complete or a timeout event is triggered. The number of bytes transmitted is returned by the function after the operation is completed. Transmit operation cannot be canceled or aborted.

The data buffer must stay allocated during the duration of the transfer, and the contents must not be modified. The value of the specified address is ignored when configured in slave mode. In master mode, it contains the address of the target peripheral. This is a 7-bit value unless 10-bit addressing is configured, and the target supports it.

When in master mode, the operation consists of:

Addressing the slave as a Master transmitter.
Transmitting data to the addressed slave.
Generating a STOP condition if the specified stop field is true.

Parameters

obj	The I2C object
address	7/10-bit address (last bit is 0)
data	The buffer for sending
length	Number of bytes to write
stop	If true, stop is generated after the transfer is done

Note: If the current platform supports multimaster operation, the peripheral performs arbitration automatically when detecting collisions and completes the transfer or returns I2C_ERROR_ARBITRATION_LOST when it loses arbitration.

Additional time for arbitration or clock stretching should by count by setting appropriate timeout value.

When no transmision timeout is set by the user, the default timeout value is used. It counts one additional byte for addressing stage: default_timeout = (length + 1) * byte_timeout.

Returns: zero or nonzero - Number of written bytes negative - I2C_ERROR_XXX status

Defined behavior

Modules

Functions

Detailed Description

Defined behavior

Undefined behavior

Function Documentation

Important Information for this Arm website