The I2C hal provides a low level interface to the I2C interface of a target. More...

Detailed Description

The I2C hal provides a low level interface to the I2C interface of a target.

Defined behavior

• The function i2c_init initializes the peripheral pins specified in the input parameters, initializes the peripheral in master mode if is_slave is false, initializes the peripheral in slave mode if is_slave is true and supports_slave_mode is true - Verified by test fpga_i2c_test_init_free.
• The function i2c_free resets the pins used to initialize the peripheral to their default state and disables the peripheral clock - Verified by test fpga_i2c_test_init_free.
• The function i2c_get_capabilities fills the contents of the i2c_capabilities_t parameter - Verified by test fpga_i2c_test_get_capabilities.
• The function i2c_frequency sets the frequency to use for the transfer, returns the actual frequency used and must leave all other configuration unchanged - Verified by test fpga_i2c_test_frequency.
• The function i2c_timeout sets the transmision timeout to use for the following blocking transfers. If the timeout is not set, the default timeout is used. The default timeout value is based on I2C frequency. It's computed as triple the amount of time it would take to send data over I2C - Verified by test fpga_i2c_test_blocking_transmission_timeout.
• The function i2c_write writes length number of symbols to the bus, returns the number of symbols sent to the bus, returns an error code if the transfer fails, generates a stop condition on the bus at the end of the transfer if stop parameter is true, and handles transfer collisions and loss of arbitration if the platform supports multimaster in hardware. The transfer times out and returns I2C_ERROR_TIMEOUT if the transfer takes longer than the configured timeout duration - Verified by test fpga_i2c_test_blocking_write_read.
• The function i2c_read reads length symbols from the bus, returns the number of symbols received from the bus, returns an error code if the transfer fails, generates a stop condition on the bus at the end of the transfer if stop parameter is true and handles transfer collisions and loss of arbitration if the platform supports multimaster in hardware. The transfer times out and returns I2C_ERROR_TIMEOUT if the transfer takes longer than the configured timeout duration - Verified by test fpga_i2c_test_blocking_write_read.
• The function i2c_start generates I2C START condition on the bus in master mode and does nothing if called when the peripheral is configured in slave mode.
• The function i2c_stop generates I2C STOP condition on the bus in master mode and does nothing if called when the peripheral is configured in slave mode
• Verified by test fpga_i2c_test_blocking_write_read fpga_i2c_test_async_write_read.
• The function i2c_slave_status indicates which mode the peripheral has been addressed in and returns not addressed when called in master mode.
• The function i2c_slave_address sets the address of the peripheral to the address parameter and does nothing if called in master mode.
• The function i2c_transfer_async returns immediately with a bool indicating whether the transfer was successfully scheduled. The callback given to i2c_transfer_async is invoked when the transfer finishes or an error occurs and must save the handler and context pointers inside the obj pointer. The context pointer is passed to the callback on transfer completion. The callback must be invoked on completion unless the transfer is aborted and may handle transfer collisions and loss of arbitration if the platform supports multimaster in hardware and enabled in API. i2c_async_event_t must be filled with the number of symbols sent to the bus during transfer - Verified by test fpga_i2c_test_async_write_read.
• The function i2c_abort_async aborts any ongoing async transfers - Verified by test fpga_i2c_test_async_abort.

Undefined behaviors

• Use of a null pointer as an argument to any function.
• Calling any I2C function before calling i2c_init or after calling i2c_free.
• Initializing the I2C peripheral with invalid SDA and SCL pins.
• Initializing the peripheral in slave mode if slave mode is not supported, indicated by i2c_get_capabilities.
• Operating the peripheral in slave mode without first specifying an address using i2c_slave_address.
• Setting an address using i2c_slave_address after initializing the peripheral in master mode.
• Setting an address to an I2C reserved value.
• Setting an address larger than the 7-bit supported maximum if 10-bit addressing is not supported.
• Setting an address larger than the 10-bit supported maximum.
• Setting a frequency outside the supported range given by i2c_get_capabilities.
• Using the device in a multimaster configuration when supports_multimaster_mode is false.
• 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 to i2c_transfer_async.
• Calling i2c_abort_async when no transfer is in progress.

Typedef Documentation

Enumeration Type Documentation