Generic I2S Driver. More...

Detailed Description

Generic I2S Driver.

This module implements a generic I2S driver.

Precondition: In order to use the I2S driver the HAL_USE_I2S option must be enabled in halconf.h.

Driver State Machine

Collaboration diagram for I2S Driver:

I2S modes
#define	I2S_MODE_SLAVE 0
#define	I2S_MODE_MASTER 1

Macro Functions
#define	i2sIsBufferComplete(i2sp)
	Buffer state.
#define	i2sStartExchangeI(i2sp)
	Starts a I2S data exchange.
#define	i2sStopExchangeI(i2sp)
	Stops the ongoing data exchange.
#define	_i2s_isr_half_code(i2sp)
	Common ISR code, half buffer event.
#define	_i2s_isr_full_code(i2sp)
	Common ISR code.

PLATFORM configuration options
#define	PLATFORM_I2S_USE_I2S1 FALSE
	I2SD1 driver enable switch.

Data Structures
struct	hal_i2s_driver
	Structure representing an I2S driver. More...
struct	hal_i2s_config
	Driver configuration structure. More...

Macros
#define	i2s_lld_driver_fields
	Low level fields of the I2S driver structure.
#define	i2s_lld_config_fields
	Low level fields of the I2S configuration structure.

Typedefs
typedef struct hal_i2s_driver	I2SDriver
	Type of a structure representing an I2S driver.
typedef struct hal_i2s_config	I2SConfig
	Type of a structure representing an I2S driver configuration.
typedef void(*	i2scallback_t) (I2SDriver *i2sp)
	I2S notification callback type.

Enumerations
enum	i2sstate_t { I2S_UNINIT = 0 , I2S_STOP = 1 , I2S_READY = 2 , I2S_ACTIVE = 3 , I2S_COMPLETE = 4 }
	Driver state machine possible states. More...

Functions
void	i2sInit (void)
	I2S Driver initialization.
void	i2sObjectInit (I2SDriver *i2sp)
	Initializes the standard part of a `I2SDriver` structure.
msg_t	i2sStart (I2SDriver i2sp, const I2SConfig config)
	Configures and activates the I2S peripheral.
void	i2sStop (I2SDriver *i2sp)
	Deactivates the I2S peripheral.
void	i2sStartExchange (I2SDriver *i2sp)
	Starts a I2S data exchange.
void	i2sStopExchange (I2SDriver *i2sp)
	Stops the ongoing data exchange.
void	i2s_lld_init (void)
	Low level I2S driver initialization.
void	i2s_lld_start (I2SDriver *i2sp)
	Configures and activates the I2S peripheral.
void	i2s_lld_stop (I2SDriver *i2sp)
	Deactivates the I2S peripheral.
void	i2s_lld_start_exchange (I2SDriver *i2sp)
	Starts a I2S data exchange.
void	i2s_lld_stop_exchange (I2SDriver *i2sp)
	Stops the ongoing data exchange.

Variables
I2SDriver	I2SD1
	I2S2 driver identifier.

Macro Definition Documentation

◆ I2S_MODE_SLAVE

#define I2S_MODE_SLAVE 0

Definition at line 38 of file hal_i2s.h.

◆ I2S_MODE_MASTER

#define I2S_MODE_MASTER 1

Definition at line 39 of file hal_i2s.h.

◆ i2sIsBufferComplete

#define i2sIsBufferComplete ( i2sp )

Value:

((bool)((i2sp)->state == I2S_COMPLETE))

I2S_COMPLETE

@ I2S_COMPLETE

Definition hal_i2s.h:62

Buffer state.

Note: This function is meant to be called from the SPI callback only.

Parameters

[in] i2sp pointer to the I2SDriver object

Returns: The buffer state.

Return values

false	if the driver filled/sent the first half of the buffer.
true	if the driver filled/sent the second half of the buffer.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 149 of file hal_i2s.h.

◆ i2sStartExchangeI

#define i2sStartExchangeI ( i2sp )

Value:

  {                                           \
  i2s_lld_start_exchange(i2sp);                                             \
  (i2sp)->state = I2S_ACTIVE;                                               \
}

Starts a I2S data exchange.

Parameters

[in] i2sp pointer to the I2SDriver object

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 158 of file hal_i2s.h.

Referenced by i2sStartExchange().

◆ i2sStopExchangeI

#define i2sStopExchangeI ( i2sp )

Value:

  {                                            \
  i2s_lld_stop_exchange(i2sp);                                              \
  (i2sp)->state = I2S_READY;                                                \
}

Stops the ongoing data exchange.

The ongoing data exchange, if any, is stopped, if the driver was not active the function does nothing.

Parameters

[in] i2sp pointer to the I2SDriver object

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 172 of file hal_i2s.h.

Referenced by i2sStopExchange().

◆ _i2s_isr_half_code

#define _i2s_isr_half_code ( i2sp )

Value:

  {                                          \
  if ((i2sp)->config->end_cb != NULL) {                                     \
    (i2sp)->config->end_cb(i2sp);                                           \
  }                                                                         \
}

Common ISR code, half buffer event.

This code handles the portable part of the ISR code:

Callback invocation.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] i2sp pointer to the I2CDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 189 of file hal_i2s.h.

◆ _i2s_isr_full_code

#define _i2s_isr_full_code ( i2sp )

Value:

  {                                          \
  if ((i2sp)->config->end_cb) {                                             \
    (i2sp)->state = I2S_COMPLETE;                                           \
    (i2sp)->config->end_cb(i2sp);                                           \
    if ((i2sp)->state == I2S_COMPLETE) {                                    \
      (i2sp)->state = I2S_ACTIVE;                                           \
    }                                                                       \
  }                                                                         \
}

Common ISR code.

This code handles the portable part of the ISR code:

Callback invocation.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] i2sp pointer to the I2CDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 208 of file hal_i2s.h.

◆ PLATFORM_I2S_USE_I2S1

#define PLATFORM_I2S_USE_I2S1 FALSE

I2SD1 driver enable switch.

If set to TRUE the support for I2S1 is included.

Note: The default is FALSE.

Definition at line 48 of file hal_i2s_lld.h.

◆ i2s_lld_driver_fields

#define i2s_lld_driver_fields

Value:

/* Dummy field, it is not needed.*/ \

uint32_t dummy;

Low level fields of the I2S driver structure.

Definition at line 67 of file hal_i2s_lld.h.

◆ i2s_lld_config_fields

#define i2s_lld_config_fields

Value:

/* Dummy configuration, it is not needed.*/ \

uint32_t dummy;

Low level fields of the I2S configuration structure.

Definition at line 74 of file hal_i2s_lld.h.

Typedef Documentation

◆ I2SDriver

typedef struct hal_i2s_driver I2SDriver

Type of a structure representing an I2S driver.

Definition at line 68 of file hal_i2s.h.

◆ I2SConfig

typedef struct hal_i2s_config I2SConfig

Type of a structure representing an I2S driver configuration.

Definition at line 73 of file hal_i2s.h.

◆ i2scallback_t

typedef void(* i2scallback_t) (I2SDriver *i2sp)

I2S notification callback type.

Parameters

[in] i2sp pointer to the I2SDriver object

Definition at line 80 of file hal_i2s.h.

Enumeration Type Documentation

◆ i2sstate_t

enum i2sstate_t

Driver state machine possible states.

Enumerator
I2S_UNINIT	Not initialized.
I2S_STOP	Stopped.
I2S_READY	Ready.
I2S_ACTIVE	Active.
I2S_COMPLETE	Transmission complete.

Definition at line 57 of file hal_i2s.h.

Function Documentation

◆ i2sInit()

void i2sInit ( void )

I2S Driver initialization.

Note: This function is implicitly invoked by halInit(), there is no need to explicitly initialize the driver.

Function Class:: Object or module nitializer function.

Definition at line 56 of file hal_i2s.c.

References i2s_lld_init().

Referenced by halInit().

Here is the call graph for this function:

◆ i2sObjectInit()

void i2sObjectInit ( I2SDriver * i2sp )

Initializes the standard part of a I2SDriver structure.

Parameters

[out] i2sp pointer to the I2SDriver object

Function Class:: Object or module nitializer function.

Definition at line 68 of file hal_i2s.c.

References hal_i2s_driver::config, I2S_STOP, and hal_i2s_driver::state.

Referenced by i2s_lld_init().

◆ i2sStart()

msg_t i2sStart	(	I2SDriver *	i2sp,
		const I2SConfig *	config )

Configures and activates the I2S peripheral.

Parameters

[in]	i2sp	pointer to the `I2SDriver` object
[in]	config	pointer to the `I2SConfig` object

Returns: The operation status.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 83 of file hal_i2s.c.

References hal_i2s_driver::config, HAL_RET_SUCCESS, i2s_lld_start(), I2S_READY, I2S_STOP, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and hal_i2s_driver::state.

Here is the call graph for this function:

◆ i2sStop()

void i2sStop ( I2SDriver * i2sp )

Deactivates the I2S peripheral.

Parameters

[in] i2sp pointer to the I2SDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 120 of file hal_i2s.c.

References hal_i2s_driver::config, i2s_lld_stop(), I2S_READY, I2S_STOP, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and hal_i2s_driver::state.

Here is the call graph for this function:

◆ i2sStartExchange()

void i2sStartExchange ( I2SDriver * i2sp )

Starts a I2S data exchange.

Parameters

[in] i2sp pointer to the I2SDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 143 of file hal_i2s.c.

References I2S_READY, i2sStartExchangeI, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and hal_i2s_driver::state.

Here is the call graph for this function:

◆ i2sStopExchange()

void i2sStopExchange ( I2SDriver * i2sp )

Stops the ongoing data exchange.

The ongoing data exchange, if any, is stopped, if the driver was not active the function does nothing.

Parameters

[in] i2sp pointer to the I2SDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 162 of file hal_i2s.c.

References I2S_ACTIVE, I2S_COMPLETE, I2S_READY, i2sStopExchangeI, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and hal_i2s_driver::state.

Here is the call graph for this function:

◆ i2s_lld_init()

void i2s_lld_init ( void )

Low level I2S driver initialization.

Function Class:: Not an API, this function is for internal use only.

Definition at line 63 of file hal_i2s_lld.c.

References I2SD1, and i2sObjectInit().

Referenced by i2sInit().

Here is the call graph for this function:

◆ i2s_lld_start()

void i2s_lld_start ( I2SDriver * i2sp )

Configures and activates the I2S peripheral.

Parameters

[in] i2sp pointer to the I2SDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 77 of file hal_i2s_lld.c.

References I2S_STOP, I2SD1, and hal_i2s_driver::state.

Referenced by i2sStart().

◆ i2s_lld_stop()

void i2s_lld_stop ( I2SDriver * i2sp )

Deactivates the I2S peripheral.

Parameters

[in] i2sp pointer to the I2SDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 97 of file hal_i2s_lld.c.

References I2S_READY, I2SD1, and hal_i2s_driver::state.

Referenced by i2sStop().

◆ i2s_lld_start_exchange()

void i2s_lld_start_exchange ( I2SDriver * i2sp )

Starts a I2S data exchange.

Parameters

[in] i2sp pointer to the I2SDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 116 of file hal_i2s_lld.c.

◆ i2s_lld_stop_exchange()

void i2s_lld_stop_exchange ( I2SDriver * i2sp )

Stops the ongoing data exchange.

The ongoing data exchange, if any, is stopped, if the driver was not active the function does nothing.

Parameters

[in] i2sp pointer to the I2SDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 130 of file hal_i2s_lld.c.

Variable Documentation

◆ I2SD1

I2SDriver I2SD1

I2S2 driver identifier.

Definition at line 39 of file hal_i2s_lld.c.

Referenced by i2s_lld_init(), i2s_lld_start(), and i2s_lld_stop().

Detailed Description

Driver State Machine

I2S modes

Macro Functions

PLATFORM configuration options

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

◆ I2S_MODE_SLAVE

◆ I2S_MODE_MASTER

◆ i2sIsBufferComplete

◆ i2sStartExchangeI

◆ i2sStopExchangeI

◆ _i2s_isr_half_code

◆ _i2s_isr_full_code

◆ PLATFORM_I2S_USE_I2S1

◆ i2s_lld_driver_fields

◆ i2s_lld_config_fields

Typedef Documentation

◆ I2SDriver

◆ I2SConfig

◆ i2scallback_t

Enumeration Type Documentation

◆ i2sstate_t

Function Documentation

◆ i2sInit()

◆ i2sObjectInit()

◆ i2sStart()

◆ i2sStop()

◆ i2sStartExchange()

◆ i2sStopExchange()

◆ i2s_lld_init()

◆ i2s_lld_start()

◆ i2s_lld_stop()

◆ i2s_lld_start_exchange()

◆ i2s_lld_stop_exchange()

Variable Documentation

◆ I2SD1