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_i2s.h File Reference

I2S (Serial Audio Interface) 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_i2s_config_t
 I2S configuration structure. More...
 
struct  cfn_hal_i2s_phy_t
 I2S hardware physical mapping. More...
 
struct  cfn_hal_i2s_api_s
 I2S Virtual Method Table (VMT). More...
 

Typedefs

typedef struct cfn_hal_i2s_s cfn_hal_i2s_t
 
typedef struct cfn_hal_i2s_api_s cfn_hal_i2s_api_t
 
typedef void(* cfn_hal_i2s_callback_t) (cfn_hal_i2s_t *driver, uint32_t event_mask, uint32_t error_mask, void *user_arg)
 I2S callback signature.
 

Enumerations

enum  cfn_hal_i2s_event_t { CFN_HAL_I2S_EVENT_NONE = 0 , CFN_HAL_I2S_EVENT_TX_COMPLETE = CFN_HAL_BIT(0) , CFN_HAL_I2S_EVENT_RX_READY = CFN_HAL_BIT(1) }
 I2S nominal event flags. More...
 
enum  cfn_hal_i2s_error_t { CFN_HAL_I2S_ERROR_NONE = 0 , CFN_HAL_I2S_ERROR_OVERRUN = CFN_HAL_BIT(0) , CFN_HAL_I2S_ERROR_SYNC = CFN_HAL_BIT(1) , CFN_HAL_I2S_ERROR_GENERAL = CFN_HAL_BIT(2) }
 I2S exception error flags. More...
 
enum  cfn_hal_i2s_config_mode_t {
  CFN_HAL_I2S_CONFIG_MODE_MASTER_TX , CFN_HAL_I2S_CONFIG_MODE_MASTER_RX , CFN_HAL_I2S_CONFIG_MODE_SLAVE_TX , CFN_HAL_I2S_CONFIG_MODE_SLAVE_RX ,
  CFN_HAL_I2S_CONFIG_MODE_MAX
}
 I2S operational mode. More...
 
enum  cfn_hal_i2s_config_standard_t {
  CFN_HAL_I2S_CONFIG_STANDARD_PHILIPS , CFN_HAL_I2S_CONFIG_STANDARD_MSB , CFN_HAL_I2S_CONFIG_STANDARD_LSB , CFN_HAL_I2S_CONFIG_STANDARD_PCM_SHORT ,
  CFN_HAL_I2S_CONFIG_STANDARD_PCM_LONG , CFN_HAL_I2S_CONFIG_STANDARD_MAX
}
 I2S communication standard. More...
 
enum  cfn_hal_i2s_config_dataformat_t {
  CFN_HAL_I2S_CONFIG_DATAFORMAT_16B , CFN_HAL_I2S_CONFIG_DATAFORMAT_16B_EXTENDED , CFN_HAL_I2S_CONFIG_DATAFORMAT_24B , CFN_HAL_I2S_CONFIG_DATAFORMAT_32B ,
  CFN_HAL_I2S_CONFIG_DATAFORMAT_MAX
}
 I2S data format. More...
 

Functions

 CFN_HAL_VMT_CHECK (struct cfn_hal_i2s_api_s)
 
 CFN_HAL_CREATE_DRIVER_TYPE (i2s, cfn_hal_i2s_config_t, cfn_hal_i2s_api_t, cfn_hal_i2s_phy_t, cfn_hal_i2s_callback_t)
 
CFN_HAL_INLINE void cfn_hal_i2s_populate (cfn_hal_i2s_t *driver, uint32_t peripheral_id, struct cfn_hal_clock_s *clock, void *dependency, const cfn_hal_i2s_api_t *api, const cfn_hal_i2s_phy_t *phy, const cfn_hal_i2s_config_t *config, cfn_hal_i2s_callback_t callback, void *user_arg)
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_config_validate (const cfn_hal_i2s_t *driver, const cfn_hal_i2s_config_t *config)
 Validates the I2S configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_init (cfn_hal_i2s_t *driver)
 Initializes the I2S driver.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_deinit (cfn_hal_i2s_t *driver)
 Deinitializes the I2S driver.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_config_set (cfn_hal_i2s_t *driver, const cfn_hal_i2s_config_t *config)
 Sets the I2S configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_config_get (cfn_hal_i2s_t *driver, cfn_hal_i2s_config_t *config)
 Gets the current I2S configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_callback_register (cfn_hal_i2s_t *driver, const cfn_hal_i2s_callback_t callback, void *user_arg)
 Registers a callback for I2S events and errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_power_state_set (cfn_hal_i2s_t *driver, cfn_hal_power_state_t state)
 Sets the I2S power state.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_event_enable (cfn_hal_i2s_t *driver, uint32_t event_mask)
 Enables one or more I2S nominal events.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_event_disable (cfn_hal_i2s_t *driver, uint32_t event_mask)
 Disables one or more I2S nominal events.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_event_get (cfn_hal_i2s_t *driver, uint32_t *event_mask)
 Retrieves the current I2S nominal event status.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_error_enable (cfn_hal_i2s_t *driver, uint32_t error_mask)
 Enables one or more I2S exception errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_error_disable (cfn_hal_i2s_t *driver, uint32_t error_mask)
 Disables one or more I2S exception errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_error_get (cfn_hal_i2s_t *driver, uint32_t *error_mask)
 Retrieves the current I2S exception error status.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_transmit_dma (cfn_hal_i2s_t *driver, const uint16_t *data, size_t size)
 Starts non-blocking audio transmission via DMA.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_receive_dma (cfn_hal_i2s_t *driver, uint16_t *data, size_t size)
 Starts non-blocking audio reception via DMA.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_pause (cfn_hal_i2s_t *driver)
 Pauses the ongoing I2S audio stream.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_resume (cfn_hal_i2s_t *driver)
 Resumes a previously paused I2S audio stream.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_stop (cfn_hal_i2s_t *driver)
 Stops the I2S audio operation and DMA transfers.
 
cfn_hal_error_code_t cfn_hal_i2s_construct (cfn_hal_i2s_t *driver, const cfn_hal_i2s_config_t *config, const cfn_hal_i2s_phy_t *phy, struct cfn_hal_clock_s *clock, void *dependency, cfn_hal_i2s_callback_t callback, void *user_arg)
 
cfn_hal_error_code_t cfn_hal_i2s_destruct (cfn_hal_i2s_t *driver)
 

Detailed Description

I2S (Serial Audio Interface) 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_i2s_api_t

◆ cfn_hal_i2s_callback_t

typedef void(* cfn_hal_i2s_callback_t) (cfn_hal_i2s_t *driver, uint32_t event_mask, uint32_t error_mask, void *user_arg)

I2S callback signature.

Parameters
driverPointer to the I2S driver instance.
event_maskMask of triggered nominal events.
error_maskMask of triggered exception errors.
user_argUser-defined argument passed during registration.

◆ cfn_hal_i2s_t

typedef struct cfn_hal_i2s_s cfn_hal_i2s_t

Enumeration Type Documentation

◆ cfn_hal_i2s_config_dataformat_t

I2S data format.

Enumerator
CFN_HAL_I2S_CONFIG_DATAFORMAT_16B 
CFN_HAL_I2S_CONFIG_DATAFORMAT_16B_EXTENDED 
CFN_HAL_I2S_CONFIG_DATAFORMAT_24B 
CFN_HAL_I2S_CONFIG_DATAFORMAT_32B 
CFN_HAL_I2S_CONFIG_DATAFORMAT_MAX 

◆ cfn_hal_i2s_config_mode_t

I2S operational mode.

Enumerator
CFN_HAL_I2S_CONFIG_MODE_MASTER_TX 
CFN_HAL_I2S_CONFIG_MODE_MASTER_RX 
CFN_HAL_I2S_CONFIG_MODE_SLAVE_TX 
CFN_HAL_I2S_CONFIG_MODE_SLAVE_RX 
CFN_HAL_I2S_CONFIG_MODE_MAX 

◆ cfn_hal_i2s_config_standard_t

I2S communication standard.

Enumerator
CFN_HAL_I2S_CONFIG_STANDARD_PHILIPS 
CFN_HAL_I2S_CONFIG_STANDARD_MSB 
CFN_HAL_I2S_CONFIG_STANDARD_LSB 
CFN_HAL_I2S_CONFIG_STANDARD_PCM_SHORT 
CFN_HAL_I2S_CONFIG_STANDARD_PCM_LONG 
CFN_HAL_I2S_CONFIG_STANDARD_MAX 

◆ cfn_hal_i2s_error_t

I2S exception error flags.

Enumerator
CFN_HAL_I2S_ERROR_NONE 
CFN_HAL_I2S_ERROR_OVERRUN 

Rx overrun or Tx underrun

CFN_HAL_I2S_ERROR_SYNC 

Frame synchronization error

CFN_HAL_I2S_ERROR_GENERAL 

General hardware error

◆ cfn_hal_i2s_event_t

I2S nominal event flags.

Enumerator
CFN_HAL_I2S_EVENT_NONE 
CFN_HAL_I2S_EVENT_TX_COMPLETE 

Audio data transmission complete

CFN_HAL_I2S_EVENT_RX_READY 

Audio data reception ready

Function Documentation

◆ CFN_HAL_CREATE_DRIVER_TYPE()

CFN_HAL_CREATE_DRIVER_TYPE ( i2s  ,
cfn_hal_i2s_config_t  ,
cfn_hal_i2s_api_t  ,
cfn_hal_i2s_phy_t  ,
cfn_hal_i2s_callback_t   
)

◆ cfn_hal_i2s_callback_register()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_callback_register ( cfn_hal_i2s_t driver,
const cfn_hal_i2s_callback_t  callback,
void *  user_arg 
)

Registers a callback for I2S events and errors.

Parameters
driverPointer to the I2S 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_i2s_config_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_config_get ( cfn_hal_i2s_t driver,
cfn_hal_i2s_config_t config 
)

Gets the current I2S configuration.

Parameters
driverPointer to the I2S 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_i2s_config_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_config_set ( cfn_hal_i2s_t driver,
const cfn_hal_i2s_config_t config 
)

Sets the I2S configuration.

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

◆ cfn_hal_i2s_config_validate()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_config_validate ( const cfn_hal_i2s_t driver,
const cfn_hal_i2s_config_t config 
)

Validates the I2S configuration.

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

◆ cfn_hal_i2s_construct()

cfn_hal_error_code_t cfn_hal_i2s_construct ( cfn_hal_i2s_t driver,
const cfn_hal_i2s_config_t config,
const cfn_hal_i2s_phy_t phy,
struct cfn_hal_clock_s *  clock,
void *  dependency,
cfn_hal_i2s_callback_t  callback,
void *  user_arg 
)

◆ cfn_hal_i2s_deinit()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_deinit ( cfn_hal_i2s_t driver)

Deinitializes the I2S driver.

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

◆ cfn_hal_i2s_destruct()

cfn_hal_error_code_t cfn_hal_i2s_destruct ( cfn_hal_i2s_t driver)

◆ cfn_hal_i2s_error_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_error_disable ( cfn_hal_i2s_t driver,
uint32_t  error_mask 
)

Disables one or more I2S exception errors.

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

◆ cfn_hal_i2s_error_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_error_enable ( cfn_hal_i2s_t driver,
uint32_t  error_mask 
)

Enables one or more I2S exception errors.

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

◆ cfn_hal_i2s_error_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_error_get ( cfn_hal_i2s_t driver,
uint32_t *  error_mask 
)

Retrieves the current I2S exception error status.

Parameters
driverPointer to the I2S 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_i2s_event_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_event_disable ( cfn_hal_i2s_t driver,
uint32_t  event_mask 
)

Disables one or more I2S nominal events.

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

◆ cfn_hal_i2s_event_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_event_enable ( cfn_hal_i2s_t driver,
uint32_t  event_mask 
)

Enables one or more I2S nominal events.

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

◆ cfn_hal_i2s_event_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_event_get ( cfn_hal_i2s_t driver,
uint32_t *  event_mask 
)

Retrieves the current I2S nominal event status.

Parameters
driverPointer to the I2S 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_i2s_init()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_init ( cfn_hal_i2s_t driver)

Initializes the I2S driver.

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

◆ cfn_hal_i2s_pause()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_pause ( cfn_hal_i2s_t driver)

Pauses the ongoing I2S audio stream.

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

◆ cfn_hal_i2s_populate()

CFN_HAL_INLINE void cfn_hal_i2s_populate ( cfn_hal_i2s_t driver,
uint32_t  peripheral_id,
struct cfn_hal_clock_s *  clock,
void *  dependency,
const cfn_hal_i2s_api_t api,
const cfn_hal_i2s_phy_t phy,
const cfn_hal_i2s_config_t config,
cfn_hal_i2s_callback_t  callback,
void *  user_arg 
)

◆ cfn_hal_i2s_power_state_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_power_state_set ( cfn_hal_i2s_t driver,
cfn_hal_power_state_t  state 
)

Sets the I2S power state.

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

◆ cfn_hal_i2s_receive_dma()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_receive_dma ( cfn_hal_i2s_t driver,
uint16_t *  data,
size_t  size 
)

Starts non-blocking audio reception via DMA.

Parameters
driverPointer to the I2S driver instance.
dataPointer to the buffer where received samples will be stored.
sizeNumber of samples to receive.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_i2s_resume()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_resume ( cfn_hal_i2s_t driver)

Resumes a previously paused I2S audio stream.

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

◆ cfn_hal_i2s_stop()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_stop ( cfn_hal_i2s_t driver)

Stops the I2S audio operation and DMA transfers.

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

◆ cfn_hal_i2s_transmit_dma()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_i2s_transmit_dma ( cfn_hal_i2s_t driver,
const uint16_t *  data,
size_t  size 
)

Starts non-blocking audio transmission via DMA.

Parameters
driverPointer to the I2S driver instance.
dataPointer to the buffer containing audio samples.
sizeNumber of samples to transmit.
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_i2s_api_s  )