Overview

Data Structures
struct	hal_audio_dma_mux_config_t
	HAL Audio DMA mux user configuration. More...

struct	hal_audio_dma_channel_mux_config_t
	HAL Audio DMA channel mux user configuration. More...

struct	hal_audio_dma_extra_config_t
	HAL Audio DMA extra user configuration. More...

struct	hal_audio_dma_config_t
	HAL Audio DMA user configuration. More...

struct	hal_audio_ip_config_t
	HAL Audio IP specific feature configuration. More...

struct	hal_audio_config_t
	HAL Audio configuration structure. More...

struct	hal_audio_transfer_t
	HAL Audio transfer structure. More...

Macros
#define	HAL_AUDIO_HANDLE_SIZE (HAL_AUDIO_HANDLE_SIZE_TEMP)
	Definition of audio adapter handle size. More...

#define	HAL_AUDIO_HANDLE_DEFINE(name) uint32_t name[(HAL_AUDIO_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t)]
	Defines the Audio handle. More...

Typedefs
typedef void *	hal_audio_handle_t
	HAL Audio transfer handle. More...

typedef void(*	hal_audio_transfer_callback_t )(hal_audio_handle_t handle, hal_audio_status_t completionStatus, void *callbackParam)
	HAL Audio completion callback function pointer type. More...

Enumerations
enum	hal_audio_status_t { kStatus_HAL_AudioSuccess = kStatus_Success, kStatus_HAL_AudioError = MAKE_STATUS(kStatusGroup_HAL_I2S, 1), kStatus_HAL_AudioBusy = MAKE_STATUS(kStatusGroup_HAL_I2S, 2), kStatus_HAL_AudioIdle = MAKE_STATUS(kStatusGroup_HAL_I2S, 3), kStatus_HAL_AudioQueueFull = MAKE_STATUS(kStatusGroup_HAL_I2S, 4) }
	HAL Audio status. More...

enum	hal_audio_channel_t { kHAL_AudioMono = 0x7FU, kHAL_AudioMonoRight = 0x0U, kHAL_AudioMonoLeft, kHAL_AudioStereo, kHAL_AudioStereo3Channel, kHAL_AudioStereo4Channel, kHAL_AudioStereo5Channel, kHAL_AudioStereo6Channel, kHAL_AudioStereo7Channel, kHAL_AudioStereo8Channel, kHAL_AudioStereo9Channel, kHAL_AudioStereo10Channel, kHAL_AudioStereo11Channel, kHAL_AudioStereo12Channel, kHAL_AudioStereo13Channel, kHAL_AudioStereo14Channel, kHAL_AudioStereo15Channel, kHAL_AudioStereo16Channel }
	HAL Audio channel number. More...

enum	hal_audio_sample_rate_t { kHAL_AudioSampleRate8KHz = 8000U, kHAL_AudioSampleRate11025Hz = 11025U, kHAL_AudioSampleRate12KHz = 12000U, kHAL_AudioSampleRate16KHz = 16000U, kHAL_AudioSampleRate22050Hz = 22050U, kHAL_AudioSampleRate24KHz = 24000U, kHAL_AudioSampleRate32KHz = 32000U, kHAL_AudioSampleRate44100Hz = 44100U, kHAL_AudioSampleRate48KHz = 48000U, kHAL_AudioSampleRate96KHz = 96000U, kHAL_AudioSampleRate192KHz = 192000U, kHAL_AudioSampleRate384KHz = 384000U }
	HAL Audio sample rate. More...

enum	hal_audio_bit_width_t { kHAL_AudioWordWidth8bits = 8U, kHAL_AudioWordWidth16bits = 16U, kHAL_AudioWordWidth24bits = 24U, kHAL_AudioWordWidth32bits = 32U }
	HAL Audio bit width. More...

enum	hal_audio_bclk_polarity_t { kHAL_AudioSampleOnFallingEdge = 0x00U, kHAL_AudioSampleOnRisingEdge }
	HAL Audio bit clock polarity. More...

enum	hal_audio_frame_sync_width_t { kHAL_AudioFrameSyncWidthOneBitClk = 0x00U, kHAL_AudioFrameSyncWidthPerWordWidth, kHAL_AudioFrameSyncWidthHalfFrame }
	HAL Audio frame sync width. More...

enum	hal_audio_frame_sync_polarity_t { kHAL_AudioBeginAtRisingEdge = 0x00U, kHAL_AudioBeginAtFallingEdge }
	HAL Audio frame sync polarity. More...

enum	hal_audio_master_slave_t { kHAL_AudioMaster = 0x0U, kHAL_AudioSlave, kHAL_AudioBclkMasterFrameSyncSlave, kHAL_AudioBclkSlaveFrameSyncMaster }
	HAL Audio master or slave mode. More...

enum	hal_audio_sai_sync_mode_t { kHAL_AudioSaiModeAsync = 0x0U, kHAL_AudioSaiModeSync }
	Synchronous or asynchronous mode, only for SAI configuration. More...

enum	hal_audio_data_format_t { kHAL_AudioDataFormatI2sClassic = 0x0U, kHAL_AudioDataFormatLeftJustified, kHAL_AudioDataFormatRightJustified, kHAL_AudioDataFormatDspModeA, kHAL_AudioDataFormatDspModeB }
	HAL Audio data format. More...

enum	hal_audio_dma_channel_priority_t { , kHAL_AudioDmaChannelPriorityDefault = 0xFFU }
	HAL Audio DMA channel priority. More...

Initialization and de-initialization
hal_audio_status_t	HAL_AudioTxInit (hal_audio_handle_t handle, const hal_audio_config_t *config)
	Initializes the HAL Audio peripheral. More...

hal_audio_status_t	HAL_AudioRxInit (hal_audio_handle_t handle, const hal_audio_config_t *config)
	Initializes the HAL Audio peripheral. More...

hal_audio_status_t	HAL_AudioTxDeinit (hal_audio_handle_t handle)
	De-initializes the HAL Audio peripheral. More...

hal_audio_status_t	HAL_AudioRxDeinit (hal_audio_handle_t handle)
	De-initializes the HAL Audio peripheral. More...

Transactional
hal_audio_status_t	HAL_AudioTxInstallCallback (hal_audio_handle_t handle, hal_audio_transfer_callback_t callback, void *callbackParam)
	Installs a callback and callback parameter. More...

hal_audio_status_t	HAL_AudioRxInstallCallback (hal_audio_handle_t handle, hal_audio_transfer_callback_t callback, void *callbackParam)
	Installs a callback and callback parameter. More...

hal_audio_status_t	HAL_AudioTransferSendNonBlocking (hal_audio_handle_t handle, hal_audio_transfer_t *xfer)
	Performs a DMA non-blocking send on the data bus. More...

hal_audio_status_t	HAL_AudioTransferReceiveNonBlocking (hal_audio_handle_t handle, hal_audio_transfer_t *xfer)
	Performs a DMA non-blocking receive on the HAL Audio bus. More...

hal_audio_status_t	HAL_AudioTransferAbortSend (hal_audio_handle_t handle)
	Aborts a DMA non-blocking transfer early. More...

hal_audio_status_t	HAL_AudioTransferAbortReceive (hal_audio_handle_t handle)
	Aborts a DMA non-blocking transfer early. More...

hal_audio_status_t	HAL_AudioTransferGetSendCount (hal_audio_handle_t handle, size_t *count)
	Gets the tx transfer status during a DMA non-blocking transfer. More...

hal_audio_status_t	HAL_AudioTransferGetReceiveCount (hal_audio_handle_t handle, size_t *count)
	Gets the rx transfer status during a DMA non-blocking transfer. More...

Data Structure Documentation

struct hal_audio_dma_mux_config_t

struct hal_audio_dma_channel_mux_config_t

struct hal_audio_dma_extra_config_t

struct hal_audio_dma_config_t

Data Fields
uint8_t	instance
	DMA instance.

uint8_t	channel
	DMA channel.

hal_audio_dma_channel_priority_t	priority
	DMA channel priority.

bool	enablePreemption
	If true, a channel can be suspended by other channel with higher priority. More...

bool	enablePreemptAbility
	If true, a channel can suspend other channel with low priority Not all SOCs support this feature. More...

void *	dmaMuxConfig
	The pointer points to an entity defined by hal_audio_dma_mux_config_t. More...

void *	dmaChannelMuxConfig
	The pointer points to an entity defined by hal_audio_dma_channel_mux_config_t. More...

void *	dmaChannelConfig
	The pointer points to an entity defined by channel configuration structure that is defined in dma driver, such as edma_channel_config_t. More...

void *	dmaExtraConfig
	The pointer points to an entity defined by hal_audio_dma_extra_config_t. More...

Field Documentation

bool hal_audio_dma_config_t::enablePreemption

Not all SOCs support this feature. For example, EDMA, DMA4 supports this feature. For detailed information please refer to the SOC corresponding RM. If not supported, the value should be set to false.

bool hal_audio_dma_config_t::enablePreemptAbility

For example, EDMA, DMA4 supports this feature. For detailed information please refer to the SOC corresponding RM. If not supported, the value should be set to false.

void* hal_audio_dma_config_t::dmaMuxConfig

Not all SOCs support this feature. In general, when the macro FSL_FEATURE_SOC_DMAMUX_COUNT is defined as non-zero, the SOC supports this feature. For detailed information please refer to the SOC corresponding RM. If not supported, the pointer should be set to NULL.

void* hal_audio_dma_config_t::dmaChannelMuxConfig

Not all SOCs support this feature. In general, when the macro FSL_FEATURE_EDMA_HAS_CHANNEL_MUX is defined as non-zero, the SOC supports this feature. For detailed information please refer to the SOC corresponding RM. If not supported, the pointer should be set to NULL.

void* hal_audio_dma_config_t::dmaChannelConfig

Not all SOCs support this feature. In general, when the macro FSL_FEATURE_EDMA_HAS_CHANNEL_CONFIG is defined as non-zero, the SOC supports this feature. For detailed information please refer to the SOC corresponding RM. If not supported, the pointer should be set to NULL.

void* hal_audio_dma_config_t::dmaExtraConfig

Some DMA IPs have extra configurations, such as EDMA, DMA4. The structure is used for these extra configurations. Not all SOCs support this feature. For detailed information please refer to the SOC corresponding RM. If not supported, the pointer should be set to NULL.

struct hal_audio_ip_config_t

Field Documentation

uint32_t hal_audio_ip_config_t::lineMask

lineMask = 0x1U, represents RX0/TX0 data line is enabled. lineMask = 0xFU, represents RX0-3/TX0-3 data line are enabled.

struct hal_audio_config_t

Data Fields
hal_audio_dma_config_t *	dmaConfig
	DMA configuration.

void *	ipConfig
	IP specific feature configuration. More...

uint32_t	srcClock_Hz
	Source clock.

uint32_t	sampleRate_Hz
	Sample rate.

uint16_t	frameLength
	Only flexcomm_i2s uses this field. More...

uint16_t	fifoWatermark
	FIFO watermark value. More...

hal_audio_master_slave_t	msaterSlave
	master or slave, configure where the bclk and frame sync come from. More...

hal_audio_bclk_polarity_t	bclkPolarity
	bclk polarity, data sample on rising edge or falling edge. More...

hal_audio_frame_sync_width_t	frameSyncWidth
	Only DSP mode uses this field. More...

hal_audio_frame_sync_polarity_t	frameSyncPolarity
	frame sync polarity, frame sync begin at rising or falling edge. More...

hal_audio_channel_t	lineChannels
	Configure the number of channel on the data line. More...

hal_audio_data_format_t	dataFormat
	data format on bus

uint8_t	bitWidth
	Bit Width.

uint8_t	instance
	Instance (0 - I2S0/SAI0, 1 - I2S1/SAI1, ...), for detailed information please refer to the SOC corresponding RM. More...

Field Documentation

void* hal_audio_config_t::ipConfig

The pointer points to an entity defined by hal_audio_ip_config_t. If there is no specific feature configuration, it should be set to NULL.

uint16_t hal_audio_config_t::frameLength

In most cases, frameLength is equal to bitWidth times lineChannels. In some cases, frameLength needs to be set to other value. For example, when the number of bit clock on the bus between two neighboring WS value is greater than bitWidth times lineChannels, frameLength needs to be set to the value that is equal to the number of bit clock between two neighboring WS signal. SAI does not use this field because frameLength can be determined internally by bitWidth and lineChannels.

uint16_t hal_audio_config_t::fifoWatermark

Generally, the value is set to half the number of FIFO(F). Note that the receive(R) or transmit length(T) is related to fifoWatermark(W) and bitWidth(B). The relationship between them is: R = N * W * B, T = N * (F - W) * B (N is integer). On some SOCs, the W and (F - W) is constant 1 and setting the W does not take effect. In that case the fifoWatermark does not need to be set. If the value set by application is greater than the number of FIFO, a maximum value will be used. For example, if the number of FIFO is 32 on a SOC but the watermark is set to 64 by application, the real value that is written to register will be 31.

hal_audio_master_slave_t hal_audio_config_t::msaterSlave

hal_audio_bclk_polarity_t hal_audio_config_t::bclkPolarity

hal_audio_frame_sync_width_t hal_audio_config_t::frameSyncWidth

For other data format, this field does not need to be set and the frameSyncWidth is determined internally that depends on different mode. For example, for I2S classic mode, frameSyncWidth is equal to bitWidth.

hal_audio_frame_sync_polarity_t hal_audio_config_t::frameSyncPolarity

This field is not used now and reserved for future use. The frameSyncPolarity is set internally that depends on different mode. For example, for I2S classic mode, frameSyncWidth is equal to kHAL_AudioBeginAtFallingEdge.

hal_audio_channel_t hal_audio_config_t::lineChannels

uint8_t hal_audio_config_t::instance

Invalid instance value will cause initialization failure.

struct hal_audio_transfer_t

Data Fields
uint8_t *	data
	A transfer buffer. More...

size_t	dataSize
	A transfer size. More...

Field Documentation

uint8_t* hal_audio_transfer_t::data

size_t hal_audio_transfer_t::dataSize

Macro Definition Documentation

#define HAL_AUDIO_HANDLE_SIZE (HAL_AUDIO_HANDLE_SIZE_TEMP)

#define HAL_AUDIO_HANDLE_DEFINE ( name ) uint32_t name[(HAL_AUDIO_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t)]

This macro is used to define a 4 byte aligned Audio handle. Then use "(hal_audio_handle_t)name" to get the Audio handle.

The macro should be global and could be optional. You could also define Audio handle by yourself.

This is an example,

* HAL_AUDIO_HANDLE_DEFINE(audioTxHandle);

*

Parameters

name	The name string of the Audio transfer handle.

Typedef Documentation

typedef void* hal_audio_handle_t

typedef void(* hal_audio_transfer_callback_t)(hal_audio_handle_t handle, hal_audio_status_t completionStatus, void *callbackParam)

This callback is used only for the non-blocking Audio transfer API. Specify the callback you wish to use in the call to HAL_AudioTxInstallCallback() or HAL_AudioRxInstallCallback().

Parameters

handle	audio transfer handle pointer, this should be a static variable.
completionStatus	Either kStatus_HAL_AudioIdle or an error code describing how the transfer completed.
callbackParam	Arbitrary pointer-sized value passed from the application.

Enumeration Type Documentation

enum hal_audio_status_t

Enumerator
kStatus_HAL_AudioSuccess	Successfully.
kStatus_HAL_AudioError	Error occurs on HAL Audio.
kStatus_HAL_AudioBusy	HAL Audio is busy with current transfer.
kStatus_HAL_AudioIdle	HAL Audio transmitter is idle.
kStatus_HAL_AudioQueueFull	Transfer queue is full.

enum hal_audio_channel_t

Enumerator
kHAL_AudioMono	Only one channel on bus.
kHAL_AudioMonoRight	Only Right channel have sound.
kHAL_AudioMonoLeft	Only left channel have sound.
kHAL_AudioStereo	Stereo sound.
kHAL_AudioStereo3Channel	Stereo 3 channel sound.
kHAL_AudioStereo4Channel	Stereo 4 channel sound.
kHAL_AudioStereo5Channel	Stereo 5 channel sound.
kHAL_AudioStereo6Channel	Stereo 6 channel sound.
kHAL_AudioStereo7Channel	Stereo 7 channel sound.
kHAL_AudioStereo8Channel	Stereo 8 channel sound.
kHAL_AudioStereo9Channel	Stereo 9 channel sound.
kHAL_AudioStereo10Channel	Stereo 10 channel sound.
kHAL_AudioStereo11Channel	Stereo 11 channel sound.
kHAL_AudioStereo12Channel	Stereo 12 channel sound.
kHAL_AudioStereo13Channel	Stereo 13 channel sound.
kHAL_AudioStereo14Channel	Stereo 14 channel sound.
kHAL_AudioStereo15Channel	Stereo 15 channel sound.
kHAL_AudioStereo16Channel	Stereo 16 channel sound.

enum hal_audio_sample_rate_t

Enumerator
kHAL_AudioSampleRate8KHz	Sample rate 8000 Hz.
kHAL_AudioSampleRate11025Hz	Sample rate 11025 Hz.
kHAL_AudioSampleRate12KHz	Sample rate 12000 Hz.
kHAL_AudioSampleRate16KHz	Sample rate 16000 Hz.
kHAL_AudioSampleRate22050Hz	Sample rate 22050 Hz.
kHAL_AudioSampleRate24KHz	Sample rate 24000 Hz.
kHAL_AudioSampleRate32KHz	Sample rate 32000 Hz.
kHAL_AudioSampleRate44100Hz	Sample rate 44100 Hz.
kHAL_AudioSampleRate48KHz	Sample rate 48000 Hz.
kHAL_AudioSampleRate96KHz	Sample rate 96000 Hz.
kHAL_AudioSampleRate192KHz	Sample rate 192000 Hz.
kHAL_AudioSampleRate384KHz	Sample rate 384000 Hz.

enum hal_audio_bit_width_t

Enumerator
kHAL_AudioWordWidth8bits	Audio data width 8 bits.
kHAL_AudioWordWidth16bits	Audio data width 16 bits.
kHAL_AudioWordWidth24bits	Audio data width 24 bits.
kHAL_AudioWordWidth32bits	Audio data width 32 bits.

enum hal_audio_bclk_polarity_t

Enumerator
kHAL_AudioSampleOnFallingEdge	Data samples at the falling edge.
kHAL_AudioSampleOnRisingEdge	Data samples at the rising edge.

enum hal_audio_frame_sync_width_t

Enumerator
kHAL_AudioFrameSyncWidthOneBitClk	1 bit clock frame sync len for DSP mode
kHAL_AudioFrameSyncWidthPerWordWidth	Frame sync length decided by word width.
kHAL_AudioFrameSyncWidthHalfFrame	Frame sync length is half of frame length.

enum hal_audio_frame_sync_polarity_t

Enumerator
kHAL_AudioBeginAtRisingEdge	Frame sync begins at the rising edge.
kHAL_AudioBeginAtFallingEdge	Frame sync begins at the falling edge.

enum hal_audio_master_slave_t

Enumerator
kHAL_AudioMaster	Master mode include bclk and frame sync.
kHAL_AudioSlave	Slave mode include bclk and frame sync.
kHAL_AudioBclkMasterFrameSyncSlave	BCLK in master mode, frame sync in slave mode.
kHAL_AudioBclkSlaveFrameSyncMaster	BCLK in slave mode, frame sync in master mode.

enum hal_audio_sai_sync_mode_t

Enumerator
kHAL_AudioSaiModeAsync	Asynchronous mode.
kHAL_AudioSaiModeSync	Synchronous mode (with receiver or transmit)

enum hal_audio_data_format_t

Enumerator
kHAL_AudioDataFormatI2sClassic	I2S classic mode.
kHAL_AudioDataFormatLeftJustified	Left-Justified mode.
kHAL_AudioDataFormatRightJustified	Right-Justified mode.
kHAL_AudioDataFormatDspModeA	DSP mode A, channel is available on 2nd rising edge of BCLK following a rising edge of frame sync.
kHAL_AudioDataFormatDspModeB	DSP mode B, channel is available on 1st rising edge of BCLK following a rising edge of frame sync.

enum hal_audio_dma_channel_priority_t

Enumerator
kHAL_AudioDmaChannelPriorityDefault	Use default value, not to configure priority.

Function Documentation

hal_audio_status_t HAL_AudioTxInit	(	hal_audio_handle_t	handle,
		const hal_audio_config_t *	config
	)

Note: This API should be called at the beginning of the application. Otherwise, any operation to the HAL Audio module can cause a hard fault because the clock is not enabled. This function configures the audio with user-defined settings. The user can configure the configuration structure. The parameter handle is a pointer to point to a memory space of size HAL_AUDIO_HANDLE_SIZE allocated by the caller.; DMA will be initialized and enabled by default in this function and calling HAL_AudioTransferSendNonBlocking or HAL_AudioTransferReceiveNonBlocking will use DMA to transfer data. Thus application should avoid initializing DMA repeatedly and dmaConfig should be configured.

Example below shows how to use this API to configure the audio peripheral. For SAI,

*   HAL_AUDIO_HANDLE_DEFINE(audioTxHandle);
*   hal_audio_config_t audioConfig;
*   hal_audio_dma_config_t dmaConfig;
*   hal_audio_ip_config_t ipConfig;
*   hal_audio_dma_mux_config_t dmaMuxConfig;
*   dmaMuxConfig.dmaMuxConfig.dmaMuxInstance   = 0;
*   dmaMuxConfig.dmaMuxConfig.dmaRequestSource = (uint32_t)kDmaRequestMuxSai1Tx;
*   dmaConfig.instance                         = 0;
*   dmaConfig.channel                          = 0;
*   dmaConfig.priority                         = kHAL_AudioDmaChannelPriorityDefault;
*   dmaConfig.enablePreemption                 = false;
*   dmaConfig.enablePreemptAbility             = false;
*   dmaConfig.dmaMuxConfig                     = &dmaMuxConfig;
*   dmaConfig.dmaChannelMuxConfig              = NULL;
*   ipConfig.sai.lineMask                      = 1U << 0U;
*   ipConfig.sai.syncMode                      = kHAL_AudioSaiModeAsync;
*   audioConfig.dmaConfig                      = &dmaConfig;
*   audioConfig.ipConfig                       = &ipConfig;
*   audioConfig.srcClock_Hz                    = 24576000;
*   audioConfig.sampleRate_Hz                  = (uint32_t)kHAL_AudioSampleRate48KHz;
*   audioConfig.fifoWatermark                  = 16;
*   audioConfig.msaterSlave                    = kHAL_AudioMaster;
*   audioConfig.bclkPolarity                   = kHAL_AudioSampleOnRisingEdge;
*   audioConfig.frameSyncWidth                 = kHAL_AudioFrameSyncWidthHalfFrame;
*   audioConfig.frameSyncPolarity              = kHAL_AudioBeginAtFallingEdge;
*   audioConfig.lineChannels                   = kHAL_AudioStereo;
*   audioConfig.dataFormat                     = kHAL_AudioDataFormatI2sClassic;
*   audioConfig.bitWidth                       = (uint8_t)kHAL_AudioWordWidth16bits;
*   audioConfig.instance                       = 0U;
*   HAL_AudioTxInit((hal_audio_handle_t)audioTxHandle, &audioConfig);
* 

For I2S,

*   HAL_AUDIO_HANDLE_DEFINE(audioTxHandle);
*   hal_audio_config_t     audioConfig;
*   hal_audio_dma_config_t dmaConfig;
*   dmaConfig.instance             = 0;
*   dmaConfig.channel              = 0;
*   dmaConfig.priority             = kHAL_AudioDmaChannelPriorityDefault;
*   dmaConfig.enablePreemption     = false;
*   dmaConfig.enablePreemptAbility = false;
*   dmaConfig.dmaMuxConfig         = NULL;
*   dmaConfig.dmaChannelMuxConfig  = NULL;
*   audioConfig.dmaConfig          = &dmaConfig;
*   audioConfig.ipConfig           = NULL;
*   audioConfig.srcClock_Hz        = 24576000;
*   audioConfig.sampleRate_Hz      = (uint32_t)kHAL_AudioSampleRate48KHz;
*   audioConfig.fifoWatermark      = 0;
*   audioConfig.msaterSlave        = kHAL_AudioMaster;
*   audioConfig.bclkPolarity       = kHAL_AudioSampleOnRisingEdge;
*   audioConfig.frameSyncWidth     = kHAL_AudioFrameSyncWidthHalfFrame;
*   audioConfig.frameSyncPolarity  = kHAL_AudioBeginAtFallingEdge;
*   audioConfig.lineChannels       = kHAL_AudioStereo;
*   audioConfig.dataFormat         = kHAL_AudioDataFormatI2sClassic;
*   audioConfig.bitWidth           = (uint8_t)kHAL_AudioWordWidth16bits;
*   audioConfig.instance           = 0U;
*   HAL_AudioTxInit((hal_audio_handle_t)audioTxHandle, &audioConfig);
* 

Parameters

handle	Pointer to point to a memory space of size HAL_AUDIO_HANDLE_SIZE allocated by the caller. The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. You can define the handle in the following two ways: HAL_AUDIO_HANDLE_DEFINE(handle); or uint32_t handle[((HAL_AUDIO_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))];
config	A pointer to the audio configuration structure

Return values

kStatus_HAL_AudioSuccess audio initialization succeed

hal_audio_status_t HAL_AudioRxInit	(	hal_audio_handle_t	handle,
		const hal_audio_config_t *	config
	)

Note: This API should be called at the beginning of the application. Otherwise, any operation to the HAL Audio module can cause a hard fault because the clock is not enabled. This function configures the audio with user-defined settings. The user can configure the configuration structure. The parameter handle is a pointer to point to a memory space of size HAL_AUDIO_HANDLE_SIZE allocated by the caller.; DMA will be initialized and enabled by default in this function and calling HAL_AudioTransferSendNonBlocking or HAL_AudioTransferReceiveNonBlocking will use DMA to transfer data. Thus application should avoid initializing DMA repeatedly and dmaConfig should be configured.

Example below shows how to use this API to configure the audio peripheral. For SAI,

*   HAL_AUDIO_HANDLE_DEFINE(audioRxHandle);
*   hal_audio_config_t audioConfig;
*   hal_audio_dma_config_t dmaConfig;
*   hal_audio_ip_config_t ipConfig;
*   hal_audio_dma_mux_config_t dmaMuxConfig;
*   dmaMuxConfig.dmaMuxConfig.dmaMuxInstance   = 0;
*   dmaMuxConfig.dmaMuxConfig.dmaRequestSource = (uint32_t)kDmaRequestMuxSai1Rx;
*   dmaConfig.instance                         = 0;
*   dmaConfig.channel                          = 0;
*   dmaConfig.priority                         = kHAL_AudioDmaChannelPriorityDefault;
*   dmaConfig.enablePreemption                 = false;
*   dmaConfig.enablePreemptAbility             = false;
*   dmaConfig.dmaMuxConfig                     = &dmaMuxConfig;
*   dmaConfig.dmaChannelMuxConfig              = NULL;
*   ipConfig.sai.lineMask                      = 1U << 0U;
*   ipConfig.sai.syncMode                      = kHAL_AudioSaiModeAsync;
*   audioConfig.dmaConfig                      = &dmaConfig;
*   audioConfig.ipConfig                       = &ipConfig;
*   audioConfig.srcClock_Hz                    = 24576000;
*   audioConfig.sampleRate_Hz                  = (uint32_t)kHAL_AudioSampleRate48KHz;
*   audioConfig.fifoWatermark                  = 16;
*   audioConfig.msaterSlave                    = kHAL_AudioMaster;
*   audioConfig.bclkPolarity                   = kHAL_AudioSampleOnRisingEdge;
*   audioConfig.frameSyncWidth                 = kHAL_AudioFrameSyncWidthHalfFrame;
*   audioConfig.frameSyncPolarity              = kHAL_AudioBeginAtFallingEdge;
*   audioConfig.lineChannels                   = kHAL_AudioStereo;
*   audioConfig.dataFormat                     = kHAL_AudioDataFormatI2sClassic;
*   audioConfig.bitWidth                       = (uint8_t)kHAL_AudioWordWidth16bits;
*   audioConfig.instance                       = 0U;
*   HAL_AudioRxInit((hal_audio_handle_t)audioRxHandle, &audioConfig);
* 

For I2S,

*   HAL_AUDIO_HANDLE_DEFINE(audioRxHandle);
*   hal_audio_config_t     audioConfig;
*   hal_audio_dma_config_t dmaConfig;
*   dmaConfig.instance             = 0;
*   dmaConfig.channel              = 0;
*   dmaConfig.priority             = kHAL_AudioDmaChannelPriorityDefault;
*   dmaConfig.enablePreemption     = false;
*   dmaConfig.enablePreemptAbility = false;
*   dmaConfig.dmaMuxConfig         = NULL;
*   dmaConfig.dmaChannelMuxConfig  = NULL;
*   audioConfig.dmaConfig          = &dmaConfig;
*   audioConfig.ipConfig           = NULL;
*   audioConfig.srcClock_Hz        = 24576000;
*   audioConfig.sampleRate_Hz      = (uint32_t)kHAL_AudioSampleRate48KHz;
*   audioConfig.fifoWatermark      = 0;
*   audioConfig.msaterSlave        = kHAL_AudioMaster;
*   audioConfig.bclkPolarity       = kHAL_AudioSampleOnRisingEdge;
*   audioConfig.frameSyncWidth     = kHAL_AudioFrameSyncWidthHalfFrame;
*   audioConfig.frameSyncPolarity  = kHAL_AudioBeginAtFallingEdge;
*   audioConfig.lineChannels       = kHAL_AudioStereo;
*   audioConfig.dataFormat         = kHAL_AudioDataFormatI2sClassic;
*   audioConfig.bitWidth           = (uint8_t)kHAL_AudioWordWidth16bits;
*   audioConfig.instance           = 0U;
*   HAL_AudioRxInit((hal_audio_handle_t)audioRxHandle, &audioConfig);
* 

Parameters

handle	Pointer to point to a memory space of size HAL_AUDIO_HANDLE_SIZE allocated by the caller. The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. You can define the handle in the following two ways: HAL_AUDIO_HANDLE_DEFINE(handle); or uint32_t handle[((HAL_AUDIO_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))];
config	A pointer to the audio configuration structure

Return values

kStatus_HAL_AudioSuccess audio initialization succeed

hal_audio_status_t HAL_AudioTxDeinit ( hal_audio_handle_t handle )

Call this API to gate the HAL Audio clock. The HAL Audio module can't work unless the HAL_AudioTxInit is called.

Parameters

handle audio handle pointer, this should be a static variable.

Return values

kStatus_HAL_AudioSuccess audio de-initialization succeed

hal_audio_status_t HAL_AudioRxDeinit ( hal_audio_handle_t handle )

Call this API to gate the HAL Audio clock. The HAL Audio module can't work unless the HAL_AudioRxInit is called.

Parameters

handle audio handle pointer, this should be a static variable.

Return values

kStatus_HAL_AudioSuccess audio de-initialization succeed

hal_audio_status_t HAL_AudioTxInstallCallback	(	hal_audio_handle_t	handle,
		hal_audio_transfer_callback_t	callback,
		void *	callbackParam
	)

This function is used to install the callback and callback parameter for audio module. When any status of the audio changed, the driver will notify the upper layer by the installed callback function. And the status is also passed as status parameter when the callback is called.

Parameters

handle	audio handle pointer, this should be a static variable.
callback	pointer to user callback function.
callbackParam	user parameter passed to the callback function.

Return values

kStatus_HAL_AudioSuccess audio tx transfer handle created

hal_audio_status_t HAL_AudioRxInstallCallback	(	hal_audio_handle_t	handle,
		hal_audio_transfer_callback_t	callback,
		void *	callbackParam
	)

This function is used to install the callback and callback parameter for audio module. When any status of the audio changed, the driver will notify the upper layer by the installed callback function. And the status is also passed as status parameter when the callback is called.

Parameters

handle	audio handle pointer, this should be a static variable.
callback	pointer to user callback function.
callbackParam	user parameter passed to the callback function.

Return values

kStatus_HAL_AudioSuccess audio rx transfer handle created

hal_audio_status_t HAL_AudioTransferSendNonBlocking	(	hal_audio_handle_t	handle,
		hal_audio_transfer_t *	xfer
	)

Note: Calling the API returns immediately after transfer initiates. The user can call HAL_AudioTransferGetSendCount to poll the transfer status to check whether the transfer is finished. If the return status is kStatus_HAL_AudioIdle, the transfer is finished.

Parameters

handle	audio handle pointer, this should be a static variable.
xfer	pointer to hal_audio_transfer_t structure.

Note: The transmit length(T) is related to fifoWatermark(W), bitWidth(B) and the number of FIFO(F). The relationship between them is: T = N * (F - W) * B (N is integer).

Return values

kStatus_HAL_AudioSuccess	Successfully start the data transmission.
kStatus_HAL_AudioBusy	Previous transmission still not finished.
kStatus_HAL_AudioError	An error occurred.

hal_audio_status_t HAL_AudioTransferReceiveNonBlocking	(	hal_audio_handle_t	handle,
		hal_audio_transfer_t *	xfer
	)

Note: Calling the API returns immediately after transfer initiates. The user can call HAL_AudioTransferGetReceiveCount to poll the transfer status to check whether the transfer is finished. If the return status is kStatus_HAL_AudioIdle, the transfer is finished.

Parameters

handle	audio handle pointer, this should be a static variable.
xfer	pointer to hal_audio_transfer_t structure.

Note: The receive length(R) is related to fifoWatermark(W), bitWidth(B) and the number of FIFO(F). The relationship between them is: R = N * W * B (N is integer).

Return values

kStatus_HAL_AudioSuccess	Successfully start the data transmission.
kStatus_HAL_AudioBusy	Previous transmission still not finished.
kStatus_HAL_AudioError	An error occurred.

hal_audio_status_t HAL_AudioTransferAbortSend ( hal_audio_handle_t handle )

Note: This API can be called at any time when a DMA non-blocking transfer initiates to abort the transfer early.

Parameters

handle audio handle pointer, this should be a static variable.

Return values

kStatus_HAL_AudioSuccess Successfully abort the transfer.

hal_audio_status_t HAL_AudioTransferAbortReceive ( hal_audio_handle_t handle )

Note: This API can be called at any time when a DMA non-blocking transfer initiates to abort the transfer early.

Parameters

handle audio handle pointer, this should be a static variable.

Return values

kStatus_HAL_AudioSuccess Successfully abort the transfer.

hal_audio_status_t HAL_AudioTransferGetSendCount	(	hal_audio_handle_t	handle,
		size_t *	count
	)

Parameters

handle	audio handle pointer, this should be a static variable.
count	Number of bytes sent so far by the non-blocking transaction.

Return values

kStatus_HAL_AudioSuccess	Successfully return the count.
kStatus_HAL_AudioIdle	Previous transmission has been finished.
kStatus_HAL_AudioError	An error occurred.

hal_audio_status_t HAL_AudioTransferGetReceiveCount	(	hal_audio_handle_t	handle,
		size_t *	count
	)

Parameters

handle	audio handle pointer, this should be a static variable.
count	Number of bytes received so far by the non-blocking transaction.

Return values

kStatus_HAL_AudioSuccess	Successfully return the count.
kStatus_HAL_AudioIdle	Previous transmission has been finished.
kStatus_HAL_AudioError	An error occurred.

Overview

Data Structures

Macros

Typedefs

Enumerations

Initialization and de-initialization

Transactional

Data Structure Documentation

Data Fields

Field Documentation

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation