SAI EDMA Driver

Overview

Data Structures
struct	sai_edma_handle_t
	SAI DMA transfer handle, users should not touch the content of the handle. More...

Typedefs
typedef void(*	sai_edma_callback_t )(I2S_Type *base, sai_edma_handle_t *handle, status_t status, void *userData)
	SAI eDMA transfer callback function for finish and error.

Enumerations
enum	sai_edma_interleave_t {   kSAI_EDMAInterleavePerChannelSample,   kSAI_EDMAInterleavePerChannelBlock }
	sai interleave type More...

Driver version
#define	FSL_SAI_EDMA_DRIVER_VERSION   (MAKE_VERSION(2, 7, 1))
	Version 2.7.1.

eDMA Transactional
void	SAI_TransferTxCreateHandleEDMA (I2S_Type *base, sai_edma_handle_t *handle, sai_edma_callback_t callback, void *userData, edma_handle_t *txDmaHandle)
	Initializes the SAI eDMA handle. More...
void	SAI_TransferRxCreateHandleEDMA (I2S_Type *base, sai_edma_handle_t *handle, sai_edma_callback_t callback, void *userData, edma_handle_t *rxDmaHandle)
	Initializes the SAI Rx eDMA handle. More...
void	SAI_TransferSetInterleaveType (sai_edma_handle_t *handle, sai_edma_interleave_t interleaveType)
	Initializes the SAI interleave type. More...
void	SAI_TransferTxSetConfigEDMA (I2S_Type *base, sai_edma_handle_t *handle, sai_transceiver_t *saiConfig)
	Configures the SAI Tx. More...
void	SAI_TransferRxSetConfigEDMA (I2S_Type *base, sai_edma_handle_t *handle, sai_transceiver_t *saiConfig)
	Configures the SAI Rx. More...
status_t	SAI_TransferSendEDMA (I2S_Type *base, sai_edma_handle_t *handle, sai_transfer_t *xfer)
	Performs a non-blocking SAI transfer using DMA. More...
status_t	SAI_TransferReceiveEDMA (I2S_Type *base, sai_edma_handle_t *handle, sai_transfer_t *xfer)
	Performs a non-blocking SAI receive using eDMA. More...
status_t	SAI_TransferSendLoopEDMA (I2S_Type *base, sai_edma_handle_t *handle, sai_transfer_t *xfer, uint32_t loopTransferCount)
	Performs a non-blocking SAI loop transfer using eDMA. More...
status_t	SAI_TransferReceiveLoopEDMA (I2S_Type *base, sai_edma_handle_t *handle, sai_transfer_t *xfer, uint32_t loopTransferCount)
	Performs a non-blocking SAI loop transfer using eDMA. More...
void	SAI_TransferTerminateSendEDMA (I2S_Type *base, sai_edma_handle_t *handle)
	Terminate all SAI send. More...
void	SAI_TransferTerminateReceiveEDMA (I2S_Type *base, sai_edma_handle_t *handle)
	Terminate all SAI receive. More...
void	SAI_TransferAbortSendEDMA (I2S_Type *base, sai_edma_handle_t *handle)
	Aborts a SAI transfer using eDMA. More...
void	SAI_TransferAbortReceiveEDMA (I2S_Type *base, sai_edma_handle_t *handle)
	Aborts a SAI receive using eDMA. More...
status_t	SAI_TransferGetSendCountEDMA (I2S_Type *base, sai_edma_handle_t *handle, size_t *count)
	Gets byte count sent by SAI. More...
status_t	SAI_TransferGetReceiveCountEDMA (I2S_Type *base, sai_edma_handle_t *handle, size_t *count)
	Gets byte count received by SAI. More...
uint32_t	SAI_TransferGetValidTransferSlotsEDMA (I2S_Type *base, sai_edma_handle_t *handle)
	Gets valid transfer slot. More...

---

Data Structure Documentation

struct sai_edma_handle

Data Fields
edma_handle_t *	dmaHandle
	DMA handler for SAI send.
uint8_t	nbytes
	eDMA minor byte transfer count initially configured. More...
uint8_t	bytesPerFrame
	Bytes in a frame.
uint8_t	channelMask
	Enabled channel mask value, reference _sai_channel_mask.
uint8_t	channelNums
	total enabled channel nums
uint8_t	channel
	Which data channel.
uint8_t	count
	The transfer data count in a DMA request.
uint32_t	state
	Internal state for SAI eDMA transfer.
sai_edma_callback_t	callback
	Callback for users while transfer finish or error occurs.
void *	userData
	User callback parameter.
uint8_t	tcd [(SAI_XFER_QUEUE_SIZE+1U)*sizeof(edma_tcd_t)]
	TCD pool for eDMA transfer. More...
sai_transfer_t	saiQueue [SAI_XFER_QUEUE_SIZE]
	Transfer queue storing queued transfer. More...
size_t	transferSize [SAI_XFER_QUEUE_SIZE]
	Data bytes need to transfer.
sai_edma_interleave_t	interleaveType
	Transfer interleave type.
volatile uint8_t	queueUser
	Index for user to queue transfer. More...
volatile uint8_t	queueDriver
	Index for driver to get the transfer data and size.

Field Documentation

uint8_t sai_edma_handle_t::nbytes

uint8_t sai_edma_handle_t::tcd[(SAI_XFER_QUEUE_SIZE+1U)*sizeof(edma_tcd_t)]

sai_transfer_t sai_edma_handle_t::saiQueue[SAI_XFER_QUEUE_SIZE]

volatile uint8_t sai_edma_handle_t::queueUser

Enumeration Type Documentation

enum sai_edma_interleave_t

Enumerator
kSAI_EDMAInterleavePerChannelSample	SAI data interleave per channel sample |LEFT CHANNEL | RIGHT CHANNEL | LEFT CHANNEL | RIGHT CHANNEL | LEFT CHANNEL | RIGHT CHANNEL | .... |
kSAI_EDMAInterleavePerChannelBlock	SAI data interleave per channel block |LEFT CHANNEL | LEFT CHANNEL | LEFT CHANNEL | ... | RIGHT CHANNEL | RIGHT CHANNEL | RIGHT CHANNEL | ...|

Function Documentation

void SAI_TransferTxCreateHandleEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle,
		sai_edma_callback_t	callback,
		void *	userData,
		edma_handle_t *	txDmaHandle
	)

This function initializes the SAI master DMA handle, which can be used for other SAI master transactional APIs. Usually, for a specified SAI instance, call this API once to get the initialized handle.

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.
callback	Pointer to user callback function.
userData	User parameter passed to the callback function.
txDmaHandle	eDMA handle pointer, this handle shall be static allocated by users.

void SAI_TransferRxCreateHandleEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle,
		sai_edma_callback_t	callback,
		void *	userData,
		edma_handle_t *	rxDmaHandle
	)

This function initializes the SAI slave DMA handle, which can be used for other SAI master transactional APIs. Usually, for a specified SAI instance, call this API once to get the initialized handle.

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.
callback	Pointer to user callback function.
userData	User parameter passed to the callback function.
rxDmaHandle	eDMA handle pointer, this handle shall be static allocated by users.

void SAI_TransferSetInterleaveType	(	sai_edma_handle_t *	handle,
		sai_edma_interleave_t	interleaveType
	)

This function initializes the SAI DMA handle member interleaveType, it shall be called only when application would like to use type kSAI_EDMAInterleavePerChannelBlock, since the default interleaveType is kSAI_EDMAInterleavePerChannelSample always

Parameters

handle	SAI eDMA handle pointer.
interleaveType	Multi channel interleave type.

void SAI_TransferTxSetConfigEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle,
		sai_transceiver_t *	saiConfig
	)

Note

SAI eDMA supports data transfer in a multiple SAI channels if the FIFO Combine feature is supported. To activate the multi-channel transfer enable SAI channels by filling the channelMask of sai_transceiver_t with the corresponding values of _sai_channel_mask enum, enable the FIFO Combine mode by assigning kSAI_FifoCombineModeEnabledOnWrite to the fifoCombine member of sai_fifo_combine_t which is a member of sai_transceiver_t. This is an example of multi-channel data transfer configuration step.

*   sai_transceiver_t config;
*   SAI_GetClassicI2SConfig(&config, kSAI_WordWidth16bits, kSAI_Stereo, kSAI_Channel0Mask|kSAI_Channel1Mask);
*   config.fifo.fifoCombine = kSAI_FifoCombineModeEnabledOnWrite;
*   SAI_TransferTxSetConfigEDMA(I2S0, &edmaHandle, &config);
*  

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.
saiConfig	sai configurations.

void SAI_TransferRxSetConfigEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle,
		sai_transceiver_t *	saiConfig
	)

Note

SAI eDMA supports data transfer in a multiple SAI channels if the FIFO Combine feature is supported. To activate the multi-channel transfer enable SAI channels by filling the channelMask of sai_transceiver_t with the corresponding values of _sai_channel_mask enum, enable the FIFO Combine mode by assigning kSAI_FifoCombineModeEnabledOnRead to the fifoCombine member of sai_fifo_combine_t which is a member of sai_transceiver_t. This is an example of multi-channel data transfer configuration step.

*   sai_transceiver_t config;
*   SAI_GetClassicI2SConfig(&config, kSAI_WordWidth16bits, kSAI_Stereo, kSAI_Channel0Mask|kSAI_Channel1Mask);
*   config.fifo.fifoCombine = kSAI_FifoCombineModeEnabledOnRead;
*   SAI_TransferRxSetConfigEDMA(I2S0, &edmaHandle, &config);
*  

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.
saiConfig	sai configurations.

status_t SAI_TransferSendEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle,
		sai_transfer_t *	xfer
	)

Note

This interface returns immediately after the transfer initiates. Call SAI_GetTransferStatus to poll the transfer status and check whether the SAI transfer is finished.

This function support multi channel transfer,

1. for the sai IP support fifo combine mode, application should enable the fifo combine mode, no limitation on channel numbers
2. for the sai IP not support fifo combine mode, sai edma provide another solution which using EDMA modulo feature, but support 2 or 4 channels only.

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.
xfer	Pointer to the DMA transfer structure.

Return values

kStatus_Success	Start a SAI eDMA send successfully.
kStatus_InvalidArgument	The input argument is invalid.
kStatus_TxBusy	SAI is busy sending data.

status_t SAI_TransferReceiveEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle,
		sai_transfer_t *	xfer
	)

Note

This interface returns immediately after the transfer initiates. Call the SAI_GetReceiveRemainingBytes to poll the transfer status and check whether the SAI transfer is finished.

This function support multi channel transfer,

1. for the sai IP support fifo combine mode, application should enable the fifo combine mode, no limitation on channel numbers
2. for the sai IP not support fifo combine mode, sai edma provide another solution which using EDMA modulo feature, but support 2 or 4 channels only.

Parameters

base	SAI base pointer
handle	SAI eDMA handle pointer.
xfer	Pointer to DMA transfer structure.

Return values

kStatus_Success	Start a SAI eDMA receive successfully.
kStatus_InvalidArgument	The input argument is invalid.
kStatus_RxBusy	SAI is busy receiving data.

status_t SAI_TransferSendLoopEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle,
		sai_transfer_t *	xfer,
		uint32_t	loopTransferCount
	)

Note

This function support loop transfer only,such as A->B->...->A, application must be aware of that the more counts of the loop transfer, then more tcd memory required, as the function use the tcd pool in sai_edma_handle_t, so application could redefine the SAI_XFER_QUEUE_SIZE to determine the proper TCD pool size. This function support one sai channel only.

Once the loop transfer start, application can use function SAI_TransferAbortSendEDMA to stop the loop transfer.

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.
xfer	Pointer to the DMA transfer structure, should be a array with elements counts >=1(loopTransferCount).
loopTransferCount	the counts of xfer array.

Return values

kStatus_Success	Start a SAI eDMA send successfully.
kStatus_InvalidArgument	The input argument is invalid.

status_t SAI_TransferReceiveLoopEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle,
		sai_transfer_t *	xfer,
		uint32_t	loopTransferCount
	)

Note

This function support loop transfer only,such as A->B->...->A, application must be aware of that the more counts of the loop transfer, then more tcd memory required, as the function use the tcd pool in sai_edma_handle_t, so application could redefine the SAI_XFER_QUEUE_SIZE to determine the proper TCD pool size. This function support one sai channel only.

Once the loop transfer start, application can use function SAI_TransferAbortReceiveEDMA to stop the loop transfer.

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.
xfer	Pointer to the DMA transfer structure, should be a array with elements counts >=1(loopTransferCount).
loopTransferCount	the counts of xfer array.

Return values

kStatus_Success	Start a SAI eDMA receive successfully.
kStatus_InvalidArgument	The input argument is invalid.

void SAI_TransferTerminateSendEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle
	)

This function will clear all transfer slots buffered in the sai queue. If users only want to abort the current transfer slot, please call SAI_TransferAbortSendEDMA.

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.

void SAI_TransferTerminateReceiveEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle
	)

This function will clear all transfer slots buffered in the sai queue. If users only want to abort the current transfer slot, please call SAI_TransferAbortReceiveEDMA.

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.

void SAI_TransferAbortSendEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle
	)

This function only aborts the current transfer slots, the other transfer slots' information still kept in the handler. If users want to terminate all transfer slots, just call SAI_TransferTerminateSendEDMA.

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.

void SAI_TransferAbortReceiveEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle
	)

This function only aborts the current transfer slots, the other transfer slots' information still kept in the handler. If users want to terminate all transfer slots, just call SAI_TransferTerminateReceiveEDMA.

Parameters

base	SAI base pointer
handle	SAI eDMA handle pointer.

status_t SAI_TransferGetSendCountEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle,
		size_t *	count
	)

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.
count	Bytes count sent by SAI.

Return values

kStatus_Success	Succeed get the transfer count.
kStatus_NoTransferInProgress	There is no non-blocking transaction in progress.

status_t SAI_TransferGetReceiveCountEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle,
		size_t *	count
	)

Parameters

base	SAI base pointer
handle	SAI eDMA handle pointer.
count	Bytes count received by SAI.

Return values

kStatus_Success	Succeed get the transfer count.
kStatus_NoTransferInProgress	There is no non-blocking transaction in progress.

uint32_t SAI_TransferGetValidTransferSlotsEDMA	(	I2S_Type *	base,
		sai_edma_handle_t *	handle
	)

This function can be used to query the valid transfer request slot that the application can submit. It should be called in the critical section, that means the application could call it in the corresponding callback function or disable IRQ before calling it in the application, otherwise, the returned value may not correct.

Parameters

base	SAI base pointer
handle	SAI eDMA handle pointer.

Return values

valid

slot count that application submit.