Interface for the I2C module. More...

#include "hal_types.h"

Include dependency graph for i2c.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	hal_i2c_txn_t
	The main data structure for interacting with the I2C module. More...

Macros
#define	TX_MESSAGE_MAX_LENGTH 1024
	May be set to change the size of the TX data array inside the I2C transaction data struct. Unit is bytes.

#define	RX_MESSAGE_MAX_LENGTH 1024
	May be set to change the size of the RX data array inside the I2C transaction data struct. Unit is bytes.

Enumerations
enum	hal_i2c_txn_state_t { _HAL_I2C_TXN_STATE_MIN = 0 , HAL_I2C_TXN_STATE_CREATED = _HAL_I2C_TXN_STATE_MIN , HAL_I2C_TXN_STATE_QUEUED , HAL_I2C_TXN_STATE_PROCESSING , HAL_I2C_TXN_STATE_COMPLETED , _HAL_I2C_TXN_STATE_MAX }
	The possible states of an I2C transaction (txn). More...

enum	hal_i2c_op_t { _HAL_I2C_OP_MIN = 0 , HAL_I2C_OP_WRITE = _HAL_I2C_OP_MIN , HAL_I2C_OP_READ , HAL_I2C_OP_WRITE_READ , _HAL_I2C_OP_MAX }
	The common I2C operations read, write, and write-read. More...

enum	hal_i2c_txn_result_t { _HAL_I2C_TXN_RESULT_MIN = 0 , HAL_I2C_TXN_RESULT_NONE = _HAL_I2C_TXN_RESULT_MIN , HAL_I2C_TXN_RESULT_SUCCESS , HAL_I2C_TXN_RESULT_FAIL , _HAL_I2C_TX_RESULT_MAX }
	Result status of a completed transaction. More...

Functions
hal_status_t	hal_i2c_init ()
	Initialize the I2C Module. Must be called prior to using the I2C Module. More...

hal_status_t	hal_i2c_submit_transaction (hal_i2c_txn_t *txn)
	Submit a transaction to be processed by the driver. More...

hal_status_t	hal_i2c_transaction_servicer ()
	Called periodically to manage the loading and unloading of transactions. More...

Detailed Description

Interface for the I2C module.

The I2C module is designed around the idea of a transaction. A transaction is a data structure that contains all information needed to operate on a peripheral on the I2C bus (eg read register X on target, or write X to target) as well as all results from the operation. The transaction is the smallest "unit" of work that the I2C driver operates on. See hal_i2c_txn_t for more information.

To use the driver to communicate with a peripheral device on the I2C bus, first create the transaction data struct that defines the operation and expected results. Then submit the transaction to the api via reference. Maintain the memory of the transaction while it is processing (the I2C module only maintains a pointer to the transaction), and poll the processing_state to determine when the transaction is HAL_I2C_TXN_STATE_COMPLETED. Once completed, results can be retrieved from inside the transaction struct.

Attention: hal_i2c_transaction_servicer() must be called periodically to service the transactions that are submitted to the I2C driver. Otherwise, they remain in the queue untouched.

Enumeration Type Documentation

◆ hal_i2c_op_t

enum hal_i2c_op_t

The common I2C operations read, write, and write-read.

The most common use is most likely HAL_I2C_OP_WRITE_READ. The mode allows reading a given register on the target device by first writing the address of the register to target follow by a read.

Enumerator
_HAL_I2C_OP_MIN	Lower bound of enum. Inclusive.
HAL_I2C_OP_WRITE	Send bytes to the target device.
HAL_I2C_OP_READ	Read bytes from the target device.
HAL_I2C_OP_WRITE_READ	Most common pattern for reading a specific register from the target device.
_HAL_I2C_OP_MAX	Upper bound of enum. Exclusive.

◆ hal_i2c_txn_result_t

enum hal_i2c_txn_result_t

Result status of a completed transaction.

After a transaction is completed, the transaction result can be checked to inquire if the transaction was completed successfully or not.

Note: The user never modifies this except to initialize to HAL_I2C_TXN_RESULT_NONE.

Enumerator
_HAL_I2C_TXN_RESULT_MIN	Lower bound of enum. Inclusive.
HAL_I2C_TXN_RESULT_NONE	Default. Transaction result has not been set.
HAL_I2C_TXN_RESULT_SUCCESS	The transaction was successfully processed.
HAL_I2C_TXN_RESULT_FAIL	The transaction was unable to be processed.
_HAL_I2C_TX_RESULT_MAX	Upper bound of enum. Exclusive.

◆ hal_i2c_txn_state_t

enum hal_i2c_txn_state_t

The possible states of an I2C transaction (txn).

An I2C transaction can be in only one of these states at any given time. It may only progress linearly through each state, unless it fails. In the case of failure, the transaction state is considered COMPLETED.

Note: The user never modifies the state manually except to set HAL_I2C_TXN_STATE_CREATED during transaction initialization.

Enumerator
_HAL_I2C_TXN_STATE_MIN	Lower bound of enum. Inclusive.
HAL_I2C_TXN_STATE_CREATED	The transaction has just been created and the state is not set.
HAL_I2C_TXN_STATE_QUEUED	The transaction has been submitted to the processing queue.
HAL_I2C_TXN_STATE_PROCESSING	The transaction is now processing. It is currently commanding the I2C bus.
HAL_I2C_TXN_STATE_COMPLETED	The transaction is done being processed. Success/Failure is determined by checking hal_i2c_txn_result_t.
_HAL_I2C_TXN_STATE_MAX	Upper bound of enum. Exclusive.

Function Documentation

◆ hal_i2c_init()

hal_status_t hal_i2c_init ( )

Initialize the I2C Module. Must be called prior to using the I2C Module.

Returns: HAL_STATUS_OK on success.

◆ hal_i2c_submit_transaction()

hal_status_t hal_i2c_submit_transaction ( hal_i2c_txn_t * txn )

Submit a transaction to be processed by the driver.

Parameters

txn	A reference to a transaction with the appropriate fields already filled out. See hal_i2c_txn_t for details about filling out the transaction correctly, as well as information about checking progress.

Returns: HAL_STATUS_OK if transaction was submitted successfully.

Note: Successful return from this function only represents that the transaction was successfully queued.; Clients must maintain the memory of their transactions. Only a reference to the transaction is queued.

◆ hal_i2c_transaction_servicer()

hal_status_t hal_i2c_transaction_servicer ( )

Called periodically to manage the loading and unloading of transactions.

Returns: HAL_STATUS_OK on success.

Classes

Macros

Enumerations

Functions