I2S DMA Driver

Overview

Data Structures
struct	_i2s_dma_handle
	i2s dma handle More...

Typedefs
typedef struct _i2s_dma_handle	i2s_dma_handle_t
	Members not to be accessed / modified outside of the driver. More...
typedef void(*	i2s_dma_transfer_callback_t )(I2S_Type *base, i2s_dma_handle_t *handle, status_t completionStatus, void *userData)
	Callback function invoked from DMA API on completion. More...

Driver version
#define	FSL_I2S_DMA_DRIVER_VERSION   (MAKE_VERSION(2, 3, 3))
	I2S DMA driver version 2.3.3. More...

DMA API
void	I2S_TxTransferCreateHandleDMA (I2S_Type *base, i2s_dma_handle_t *handle, dma_handle_t *dmaHandle, i2s_dma_transfer_callback_t callback, void *userData)
	Initializes handle for transfer of audio data. More...
status_t	I2S_TxTransferSendDMA (I2S_Type *base, i2s_dma_handle_t *handle, i2s_transfer_t transfer)
	Begins or queue sending of the given data. More...
void	I2S_TransferAbortDMA (I2S_Type *base, i2s_dma_handle_t *handle)
	Aborts transfer of data. More...
void	I2S_RxTransferCreateHandleDMA (I2S_Type *base, i2s_dma_handle_t *handle, dma_handle_t *dmaHandle, i2s_dma_transfer_callback_t callback, void *userData)
	Initializes handle for reception of audio data. More...
status_t	I2S_RxTransferReceiveDMA (I2S_Type *base, i2s_dma_handle_t *handle, i2s_transfer_t transfer)
	Begins or queue reception of data into given buffer. More...
void	I2S_DMACallback (dma_handle_t *handle, void *userData, bool transferDone, uint32_t tcds)
	Invoked from DMA interrupt handler. More...
void	I2S_TransferInstallLoopDMADescriptorMemory (i2s_dma_handle_t *handle, void *dmaDescriptorAddr, size_t dmaDescriptorNum)
	Install DMA descriptor memory for loop transfer only. More...
status_t	I2S_TransferSendLoopDMA (I2S_Type *base, i2s_dma_handle_t *handle, i2s_transfer_t *xfer, uint32_t loopTransferCount)
	Send link transfer data using DMA. More...
status_t	I2S_TransferReceiveLoopDMA (I2S_Type *base, i2s_dma_handle_t *handle, i2s_transfer_t *xfer, uint32_t loopTransferCount)
	Receive link transfer data using DMA. More...

---

Data Structure Documentation

struct _i2s_dma_handle

Data Fields
uint32_t	state
	Internal state of I2S DMA transfer.
uint8_t	bytesPerFrame
	bytes per frame
i2s_dma_transfer_callback_t	completionCallback
	Callback function pointer.
void *	userData
	Application data passed to callback.
dma_handle_t *	dmaHandle
	DMA handle.
volatile i2s_transfer_t	i2sQueue [I2S_NUM_BUFFERS]
	Transfer queue storing transfer buffers.
volatile uint8_t	queueUser
	Queue index where user's next transfer will be stored.
volatile uint8_t	queueDriver
	Queue index of buffer actually used by the driver.
dma_descriptor_t *	i2sLoopDMADescriptor
	descriptor pool pointer
size_t	i2sLoopDMADescriptorNum
	number of descriptor in descriptors pool

Macro Definition Documentation

#define FSL_I2S_DMA_DRIVER_VERSION   (MAKE_VERSION(2, 3, 3))

Typedef Documentation

typedef struct _i2s_dma_handle i2s_dma_handle_t

typedef void(* i2s_dma_transfer_callback_t)(I2S_Type *base, i2s_dma_handle_t *handle, status_t completionStatus, void *userData)

Parameters

base	I2S base pointer.
handle	pointer to I2S transaction.
completionStatus	status of the transaction.
userData	optional pointer to user arguments data.

Function Documentation

void I2S_TxTransferCreateHandleDMA	(	I2S_Type *	base,
		i2s_dma_handle_t *	handle,
		dma_handle_t *	dmaHandle,
		i2s_dma_transfer_callback_t	callback,
		void *	userData
	)

Parameters

base	I2S base pointer.
handle	pointer to handle structure.
dmaHandle	pointer to dma handle structure.
callback	function to be called back when transfer is done or fails.
userData	pointer to data passed to callback.

status_t I2S_TxTransferSendDMA	(	I2S_Type *	base,
		i2s_dma_handle_t *	handle,
		i2s_transfer_t	transfer
	)

Parameters

base	I2S base pointer.
handle	pointer to handle structure.
transfer	data buffer.

Return values

kStatus_Success
kStatus_I2S_Busy	if all queue slots are occupied with unsent buffers.

void I2S_TransferAbortDMA	(	I2S_Type *	base,
		i2s_dma_handle_t *	handle
	)

Parameters

base	I2S base pointer.
handle	pointer to handle structure.

void I2S_RxTransferCreateHandleDMA	(	I2S_Type *	base,
		i2s_dma_handle_t *	handle,
		dma_handle_t *	dmaHandle,
		i2s_dma_transfer_callback_t	callback,
		void *	userData
	)

Parameters

base	I2S base pointer.
handle	pointer to handle structure.
dmaHandle	pointer to dma handle structure.
callback	function to be called back when transfer is done or fails.
userData	pointer to data passed to callback.

status_t I2S_RxTransferReceiveDMA	(	I2S_Type *	base,
		i2s_dma_handle_t *	handle,
		i2s_transfer_t	transfer
	)

Parameters

base	I2S base pointer.
handle	pointer to handle structure.
transfer	data buffer.

Return values

kStatus_Success
kStatus_I2S_Busy	if all queue slots are occupied with buffers which are not full.

void I2S_DMACallback	(	dma_handle_t *	handle,
		void *	userData,
		bool	transferDone,
		uint32_t	tcds
	)

Parameters

handle	pointer to DMA handle structure.
userData	argument for user callback.
transferDone	if transfer was done.
tcds

void I2S_TransferInstallLoopDMADescriptorMemory	(	i2s_dma_handle_t *	handle,
		void *	dmaDescriptorAddr,
		size_t	dmaDescriptorNum
	)

This function used to register DMA descriptor memory for the i2s loop dma transfer.

It must be callbed before I2S_TransferSendLoopDMA/I2S_TransferReceiveLoopDMA and after I2S_RxTransferCreateHandleDMA/I2S_TxTransferCreateHandleDMA.

User should be take care about the address of DMA descriptor pool which required align with 16BYTE at least.

Parameters

handle	Pointer to i2s DMA transfer handle.
dmaDescriptorAddr	DMA descriptor start address.
dmaDescriptorNum	DMA descriptor number.

status_t I2S_TransferSendLoopDMA	(	I2S_Type *	base,
		i2s_dma_handle_t *	handle,
		i2s_transfer_t *	xfer,
		uint32_t	loopTransferCount
	)

This function receives data using DMA. This is a non-blocking function, which returns right away. When all data is received, the receive callback function is called.

This function support loop transfer, such as A->B->...->A, the loop transfer chain will be converted into a chain of descriptor and submit to dma. Application must be aware of that the more counts of the loop transfer, then more DMA descriptor memory required, user can use function I2S_InstallDMADescriptorMemory to register the dma descriptor memory.

As the DMA support maximum 1024 transfer count, so application must be aware of that this transfer function support maximum 1024 samples in each transfer, otherwise assert error or error status will be returned. Once the loop transfer start, application can use function I2S_TransferAbortDMA to stop the loop transfer.

Parameters

base	I2S peripheral base address.
handle	Pointer to usart_dma_handle_t structure.
xfer	I2S DMA transfer structure. See i2s_transfer_t.
loopTransferCount	loop count

Return values

kStatus_Success

status_t I2S_TransferReceiveLoopDMA	(	I2S_Type *	base,
		i2s_dma_handle_t *	handle,
		i2s_transfer_t *	xfer,
		uint32_t	loopTransferCount
	)

This function receives data using DMA. This is a non-blocking function, which returns right away. When all data is received, the receive callback function is called.

This function support loop transfer, such as A->B->...->A, the loop transfer chain will be converted into a chain of descriptor and submit to dma. Application must be aware of that the more counts of the loop transfer, then more DMA descriptor memory required, user can use function I2S_InstallDMADescriptorMemory to register the dma descriptor memory.

As the DMA support maximum 1024 transfer count, so application must be aware of that this transfer function support maximum 1024 samples in each transfer, otherwise assert error or error status will be returned. Once the loop transfer start, application can use function I2S_TransferAbortDMA to stop the loop transfer.

Parameters

base	I2S peripheral base address.
handle	Pointer to usart_dma_handle_t structure.
xfer	I2S DMA transfer structure. See i2s_transfer_t.
loopTransferCount	loop count

Return values

kStatus_Success