caffeine-hal 0.6.6
A Header-Defined Interface c library, it provides the hal layer for the Caffeine framework
Loading...
Searching...
No Matches
Data Structures | Typedefs | Enumerations | Functions
cfn_hal_i2c.h File Reference

Inter-Integrated Circuit (I2C) HAL API. More...

#include "cfn_hal.h"
#include "cfn_hal_base.h"
#include "cfn_hal_gpio.h"
#include "cfn_hal_types.h"

Go to the source code of this file.

Data Structures

struct  cfn_hal_i2c_phy_t
 I2C hardware physical mapping. More...
 
struct  cfn_hal_i2c_config_s
 I2C configuration structure. More...
 
struct  cfn_hal_i2c_transaction_t
 Standard I2C transaction structure. More...
 
struct  cfn_hal_i2c_mem_transaction_t
 I2C memory access transaction structure. More...
 
struct  cfn_hal_i2c_device_t
 I2C Device addressing association. More...
 
struct  cfn_hal_i2c_api_s
 I2C Virtual Method Table (VMT). More...
 

Typedefs

typedef struct cfn_hal_i2c_config_s cfn_hal_i2c_config_t
 I2C configuration structure.
 
typedef struct cfn_hal_i2c_s cfn_hal_i2c_t
 
typedef struct cfn_hal_i2c_api_s cfn_hal_i2c_api_t
 
typedef void(* cfn_hal_i2c_callback_t) (cfn_hal_i2c_t *driver, uint32_t event_mask, uint32_t error_mask, uint8_t *payload, size_t nbr_of_bytes, void *user_arg)
 I2C callback signature.
 

Enumerations

enum  cfn_hal_i2c_event_t {
  CFN_HAL_I2C_EVENT_NONE = 0 , CFN_HAL_I2C_EVENT_TX_COMPLETE = CFN_HAL_BIT(0) , CFN_HAL_I2C_EVENT_RX_READY = CFN_HAL_BIT(1) , CFN_HAL_I2C_EVENT_START_SENT = CFN_HAL_BIT(2) ,
  CFN_HAL_I2C_EVENT_ADDR_SENT = CFN_HAL_BIT(3) , CFN_HAL_I2C_EVENT_HEADER_SENT = CFN_HAL_BIT(4) , CFN_HAL_I2C_EVENT_DATA_SENT = CFN_HAL_BIT(5) , CFN_HAL_I2C_EVENT_STOP_DET = CFN_HAL_BIT(6)
}
 I2C nominal event flags. More...
 
enum  cfn_hal_i2c_error_t {
  CFN_HAL_I2C_ERROR_NONE = 0 , CFN_HAL_I2C_ERROR_ARBITRATION = CFN_HAL_BIT(0) , CFN_HAL_I2C_ERROR_ACK = CFN_HAL_BIT(1) , CFN_HAL_I2C_ERROR_OVERRUN = CFN_HAL_BIT(2) ,
  CFN_HAL_I2C_ERROR_PEC = CFN_HAL_BIT(3) , CFN_HAL_I2C_ERROR_TIMEOUT = CFN_HAL_BIT(4) , CFN_HAL_I2C_ERROR_SMB = CFN_HAL_BIT(5) , CFN_HAL_I2C_ERROR_GENERAL = CFN_HAL_BIT(6)
}
 I2C exception error flags. More...
 
enum  cfn_hal_i2c_config_speed_t {
  CFN_HAL_I2C_CONFIG_SPEED_100KHZ , CFN_HAL_I2C_CONFIG_SPEED_400KHZ , CFN_HAL_I2C_CONFIG_SPEED_1000KHZ , CFN_HAL_I2C_CONFIG_SPEED_3330KHZ ,
  CFN_HAL_I2C_CONFIG_SPEED_3400KHZ , CFN_HAL_I2C_CONFIG_SPEED_5000KHZ , CFN_HAL_I2C_CONFIG_SPEED_CUSTOM , CFN_HAL_I2C_CONFIG_SPEED_MAX
}
 I2C bus speeds. More...
 

Functions

 CFN_HAL_VMT_CHECK (struct cfn_hal_i2c_api_s)
 
 CFN_HAL_CREATE_DRIVER_TYPE (i2c, cfn_hal_i2c_config_t, cfn_hal_i2c_api_t, cfn_hal_i2c_phy_t, cfn_hal_i2c_callback_t)
 
CFN_HAL_INLINE void cfn_hal_i2c_populate (cfn_hal_i2c_t *driver, uint32_t peripheral_id, struct cfn_hal_clock_s *clock, void *dependency, const cfn_hal_i2c_api_t *api, const cfn_hal_i2c_phy_t *phy, const cfn_hal_i2c_config_t *config, cfn_hal_i2c_callback_t callback, void *user_arg)
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_config_validate (const cfn_hal_i2c_t *driver, const cfn_hal_i2c_config_t *config)
 Validates the I2C configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_init (cfn_hal_i2c_t *driver)
 Initializes the I2C driver.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_deinit (cfn_hal_i2c_t *driver)
 Deinitializes the I2C driver.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_config_set (cfn_hal_i2c_t *driver, const cfn_hal_i2c_config_t *config)
 Sets the I2C configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_config_get (cfn_hal_i2c_t *driver, cfn_hal_i2c_config_t *config)
 Gets the current I2C configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_callback_register (cfn_hal_i2c_t *driver, const cfn_hal_i2c_callback_t callback, void *user_arg)
 Registers a callback for I2C events and errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_power_state_set (cfn_hal_i2c_t *driver, cfn_hal_power_state_t state)
 Sets the I2C power state.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_event_enable (cfn_hal_i2c_t *driver, uint32_t event_mask)
 Enables one or more I2C nominal events.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_event_disable (cfn_hal_i2c_t *driver, uint32_t event_mask)
 Disables one or more I2C nominal events.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_event_get (cfn_hal_i2c_t *driver, uint32_t *event_mask)
 Retrieves the current I2C nominal event status.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_error_enable (cfn_hal_i2c_t *driver, uint32_t error_mask)
 Enables one or more I2C exception errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_error_disable (cfn_hal_i2c_t *driver, uint32_t error_mask)
 Disables one or more I2C exception errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_error_get (cfn_hal_i2c_t *driver, uint32_t *error_mask)
 Retrieves the current I2C exception error status.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_xfr_irq (cfn_hal_i2c_t *driver, const cfn_hal_i2c_transaction_t *xfr)
 Starts an I2C transaction using interrupts (non-blocking).
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_xfr_irq_abort (cfn_hal_i2c_t *driver)
 Aborts an ongoing non-blocking I2C transaction.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_xfr_polling (cfn_hal_i2c_t *driver, const cfn_hal_i2c_transaction_t *xfr, uint32_t timeout)
 Executes an I2C transaction using polling (blocking).
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_mem_read (cfn_hal_i2c_t *driver, const cfn_hal_i2c_mem_transaction_t *mem_xfr, uint32_t timeout)
 Reads data from a specific memory address on an I2C device (blocking).
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_mem_write (cfn_hal_i2c_t *driver, const cfn_hal_i2c_mem_transaction_t *mem_xfr, uint32_t timeout)
 Writes data to a specific memory address on an I2C device (blocking).
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_xfr_dma (cfn_hal_i2c_t *driver, const cfn_hal_i2c_transaction_t *xfr)
 Starts an I2C transaction using DMA (non-blocking).
 
cfn_hal_error_code_t cfn_hal_i2c_construct (cfn_hal_i2c_t *driver, const cfn_hal_i2c_config_t *config, const cfn_hal_i2c_phy_t *phy, struct cfn_hal_clock_s *clock, void *dependency, cfn_hal_i2c_callback_t callback, void *user_arg)
 
cfn_hal_error_code_t cfn_hal_i2c_destruct (cfn_hal_i2c_t *driver)
 

Detailed Description

Inter-Integrated Circuit (I2C) HAL API.

Copyright (c) 2026 Hisham Moussa Daou https://www.whileone.me

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Typedef Documentation

◆ cfn_hal_i2c_api_t

◆ cfn_hal_i2c_callback_t

typedef void(* cfn_hal_i2c_callback_t) (cfn_hal_i2c_t *driver, uint32_t event_mask, uint32_t error_mask, uint8_t *payload, size_t nbr_of_bytes, void *user_arg)

I2C callback signature.

Parameters
driverPointer to the I2C driver instance.
event_maskMask of triggered nominal events.
error_maskMask of triggered exception errors.
payloadPointer to the transaction buffer (if applicable).
nbr_of_bytesNumber of bytes transferred.
user_argUser-defined argument passed during registration.

◆ cfn_hal_i2c_config_t

I2C configuration structure.

◆ cfn_hal_i2c_t

typedef struct cfn_hal_i2c_s cfn_hal_i2c_t

Enumeration Type Documentation

◆ cfn_hal_i2c_config_speed_t

I2C bus speeds.

Enumerator
CFN_HAL_I2C_CONFIG_SPEED_100KHZ 

Standard Mode

CFN_HAL_I2C_CONFIG_SPEED_400KHZ 

Fast Mode

CFN_HAL_I2C_CONFIG_SPEED_1000KHZ 

Fast Mode Plus

CFN_HAL_I2C_CONFIG_SPEED_3330KHZ 

High Speed (3.33 MHz)

CFN_HAL_I2C_CONFIG_SPEED_3400KHZ 

High Speed (3.40 MHz)

CFN_HAL_I2C_CONFIG_SPEED_5000KHZ 

Ultra Fast Mode

CFN_HAL_I2C_CONFIG_SPEED_CUSTOM 

Vendor-specific speed

CFN_HAL_I2C_CONFIG_SPEED_MAX 

◆ cfn_hal_i2c_error_t

I2C exception error flags.

Enumerator
CFN_HAL_I2C_ERROR_NONE 
CFN_HAL_I2C_ERROR_ARBITRATION 

Arbitration lost

CFN_HAL_I2C_ERROR_ACK 

Acknowledge failure

CFN_HAL_I2C_ERROR_OVERRUN 

Data overrun/underrun

CFN_HAL_I2C_ERROR_PEC 

Packet Error Checking mismatch

CFN_HAL_I2C_ERROR_TIMEOUT 

Bus timeout

CFN_HAL_I2C_ERROR_SMB 

SMBus alert/error

CFN_HAL_I2C_ERROR_GENERAL 

General hardware error

◆ cfn_hal_i2c_event_t

I2C nominal event flags.

Enumerator
CFN_HAL_I2C_EVENT_NONE 
CFN_HAL_I2C_EVENT_TX_COMPLETE 

Transmission complete

CFN_HAL_I2C_EVENT_RX_READY 

Data received and ready

CFN_HAL_I2C_EVENT_START_SENT 

Start condition generated

CFN_HAL_I2C_EVENT_ADDR_SENT 

Address phase complete

CFN_HAL_I2C_EVENT_HEADER_SENT 

10-bit header sent

CFN_HAL_I2C_EVENT_DATA_SENT 

Single byte transfer complete

CFN_HAL_I2C_EVENT_STOP_DET 

Stop condition detected

Function Documentation

◆ CFN_HAL_CREATE_DRIVER_TYPE()

CFN_HAL_CREATE_DRIVER_TYPE ( i2c  ,
cfn_hal_i2c_config_t  ,
cfn_hal_i2c_api_t  ,
cfn_hal_i2c_phy_t  ,
cfn_hal_i2c_callback_t   
)

◆ cfn_hal_i2c_callback_register()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_callback_register ( cfn_hal_i2c_t driver,
const cfn_hal_i2c_callback_t  callback,
void *  user_arg 
)

Registers a callback for I2C events and errors.

Parameters
driverPointer to the I2C driver instance.
callbackThe callback function to register.
user_argUser-defined argument passed to the callback.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_config_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_config_get ( cfn_hal_i2c_t driver,
cfn_hal_i2c_config_t config 
)

Gets the current I2C configuration.

Parameters
driverPointer to the I2C driver instance.
config[out] Pointer to store the configuration.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_config_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_config_set ( cfn_hal_i2c_t driver,
const cfn_hal_i2c_config_t config 
)

Sets the I2C configuration.

Parameters
driverPointer to the I2C driver instance.
configPointer to the configuration structure.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_config_validate()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_config_validate ( const cfn_hal_i2c_t driver,
const cfn_hal_i2c_config_t config 
)

Validates the I2C configuration.

Parameters
driverPointer to the I2C driver instance.
configPointer to the configuration structure.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_construct()

cfn_hal_error_code_t cfn_hal_i2c_construct ( cfn_hal_i2c_t driver,
const cfn_hal_i2c_config_t config,
const cfn_hal_i2c_phy_t phy,
struct cfn_hal_clock_s *  clock,
void *  dependency,
cfn_hal_i2c_callback_t  callback,
void *  user_arg 
)

◆ cfn_hal_i2c_deinit()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_deinit ( cfn_hal_i2c_t driver)

Deinitializes the I2C driver.

Parameters
driverPointer to the I2C driver instance.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_destruct()

cfn_hal_error_code_t cfn_hal_i2c_destruct ( cfn_hal_i2c_t driver)

◆ cfn_hal_i2c_error_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_error_disable ( cfn_hal_i2c_t driver,
uint32_t  error_mask 
)

Disables one or more I2C exception errors.

Parameters
driverPointer to the I2C driver instance.
error_maskMask of errors to disable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_error_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_error_enable ( cfn_hal_i2c_t driver,
uint32_t  error_mask 
)

Enables one or more I2C exception errors.

Parameters
driverPointer to the I2C driver instance.
error_maskMask of errors to enable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_error_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_error_get ( cfn_hal_i2c_t driver,
uint32_t *  error_mask 
)

Retrieves the current I2C exception error status.

Parameters
driverPointer to the I2C driver instance.
error_mask[out] Pointer to store the error mask.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_event_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_event_disable ( cfn_hal_i2c_t driver,
uint32_t  event_mask 
)

Disables one or more I2C nominal events.

Parameters
driverPointer to the I2C driver instance.
event_maskMask of events to disable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_event_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_event_enable ( cfn_hal_i2c_t driver,
uint32_t  event_mask 
)

Enables one or more I2C nominal events.

Parameters
driverPointer to the I2C driver instance.
event_maskMask of events to enable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_event_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_event_get ( cfn_hal_i2c_t driver,
uint32_t *  event_mask 
)

Retrieves the current I2C nominal event status.

Parameters
driverPointer to the I2C driver instance.
event_mask[out] Pointer to store the event mask.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_init()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_init ( cfn_hal_i2c_t driver)

Initializes the I2C driver.

Parameters
driverPointer to the I2C driver instance.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_mem_read()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_mem_read ( cfn_hal_i2c_t driver,
const cfn_hal_i2c_mem_transaction_t mem_xfr,
uint32_t  timeout 
)

Reads data from a specific memory address on an I2C device (blocking).

Parameters
driverPointer to the I2C driver instance.
mem_xfrPointer to the memory transaction structure.
timeoutTimeout duration in milliseconds.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_mem_write()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_mem_write ( cfn_hal_i2c_t driver,
const cfn_hal_i2c_mem_transaction_t mem_xfr,
uint32_t  timeout 
)

Writes data to a specific memory address on an I2C device (blocking).

Parameters
driverPointer to the I2C driver instance.
mem_xfrPointer to the memory transaction structure.
timeoutTimeout duration in milliseconds.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_populate()

CFN_HAL_INLINE void cfn_hal_i2c_populate ( cfn_hal_i2c_t driver,
uint32_t  peripheral_id,
struct cfn_hal_clock_s *  clock,
void *  dependency,
const cfn_hal_i2c_api_t api,
const cfn_hal_i2c_phy_t phy,
const cfn_hal_i2c_config_t config,
cfn_hal_i2c_callback_t  callback,
void *  user_arg 
)

◆ cfn_hal_i2c_power_state_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_power_state_set ( cfn_hal_i2c_t driver,
cfn_hal_power_state_t  state 
)

Sets the I2C power state.

Parameters
driverPointer to the I2C driver instance.
stateTarget power state.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_xfr_dma()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_xfr_dma ( cfn_hal_i2c_t driver,
const cfn_hal_i2c_transaction_t xfr 
)

Starts an I2C transaction using DMA (non-blocking).

Parameters
driverPointer to the I2C driver instance.
xfrPointer to the transaction structure.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_xfr_irq()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_xfr_irq ( cfn_hal_i2c_t driver,
const cfn_hal_i2c_transaction_t xfr 
)

Starts an I2C transaction using interrupts (non-blocking).

Parameters
driverPointer to the I2C driver instance.
xfrPointer to the transaction structure.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_xfr_irq_abort()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_xfr_irq_abort ( cfn_hal_i2c_t driver)

Aborts an ongoing non-blocking I2C transaction.

Parameters
driverPointer to the I2C driver instance.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2c_xfr_polling()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2c_xfr_polling ( cfn_hal_i2c_t driver,
const cfn_hal_i2c_transaction_t xfr,
uint32_t  timeout 
)

Executes an I2C transaction using polling (blocking).

Parameters
driverPointer to the I2C driver instance.
xfrPointer to the transaction structure.
timeoutTimeout duration in milliseconds.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ CFN_HAL_VMT_CHECK()

CFN_HAL_VMT_CHECK ( struct cfn_hal_i2c_api_s  )