QDMA Functions

#include <DDMA.h>

QDMA_STATUS QDMA_Claim(SC6xQDMA *I, unsigned int Te, QDMA_COMPLETE How);

This reserves the single QDMA channel on a processor for the thread’s exclusive use; if the QDMA channel has already been claimed, the call suspend the calling thread until the owning thread releases the QDMA channel.

The parameters are as follows:

I	The QDMA interface previously got by a call to QDMA_Interface.
Te	The termination event to be used. This must be in the range 0 ≤ Te ≤ 15 and also indicates which EDMA channel is to be claimed. You should chose an event that is not used elsewhere for a different purpose. This example uses event 15 which is never used by Diamond.
How	The action taken once a transfer has started. There are three options: QDMA_INTERRUPT, QDMA_POLL, and QDMA_NOWAIT. Most users find the interrupt option most convenient.
	QDMA_INTERRUPT	Suspend the calling thread and wait for the QDMA to indicate completion of the transfer with an interrupt. The thread is rescheduled when the interrupt is detected. Other threads can continue to execute while the thread is waiting. All interrupt handling is managed for you. In particular, the CIPR and CIER system registers must not be altered by user code.
	QDMA_POLL	Poll (loop, repeatedly testing status) for completion of the transfer. This should be used only for transfers that terminate quickly, as the thread consumes CPU cycles while it waits.
	QDMA_NOWAIT	Pass control back to the calling thread immediately after starting the transfer, which continues to progress. It is your responsibility to determine when the transfer has completed.

The function can return four values:

	QDMA_OK	The claim was successful.
	QDMA_RANGE	The termination event is not in the range 0 ≤ N ≤ 15.
	QDMA_HOW	The termination action is unknown.
	QDMA_EDMAINUSE	The corresponding EDMA channel is in use.

QDMA_Complete

#include <QDMA.h>

int QDMA_Complete(SC6xQDMA *I);

stand-alone

This function returns a non-zero value when a QDMA transfer is active. It returns zero when no transfer has been started or the previous transfer has completed.

QDMA_Interface

#include <QDMA.h>

SC6xQDMA *QDMA_Interface(void);

stand-alone

This function returns an interface pointer that is required by other QDMA functions. You need do this only once in any task; calling it repeatedly is not wrong but waste time.

It returns NULL if the QDMA module cannot be found.

QDMA_Perform

#include <QDMA.h>

QDMA_STATUS QDMA_Perform(SC6xQDMA *I, QDMA_REGS *R);

stand-alone

The values in the QDMA_REGS structure, R, are assigned to the corresponding QDMA parameter registers.

The R->Opt value is assigned last using a pseudo register to start the transfer. The value you have given to R->Opt will be modified automatically before assignment as follows:

1.	The TCC (Transfer complete code) field will be set to the value of the termination event specified when the channel was claimed.
2.	The TCCM field will be set to 0.
3.	The TCINT (Transfer complete interrupt) bit will be set to allow CIPR to be used to indicate completion of the transfer.

This modification of Opt is not done if you write to the register explicitly. Should you decide to do so, it is your responsibility to ensure that the value written has the correct values in the TCC, TCCM, and TCINT fields.

Depending on the way the QDMA channel had been claimed, this call will either wait for the transfer to complete (QDMA_INTERRUPT or QDMA_POLL) or return immediately (QDMA_NOWAIT).

The function can return two values:

	QDMA_OK	The call was successful.
	QDMA_UNCLAIMED	The QDMA channel had not been claimed.

If you use QDMA_NOWAIT you can explicitly test for completion using QDMA_Complete, which returns a non-zero value if the previous QDMA transfer has completed. It returns 0 otherwise.

For example,

while (QDMA_Complete(QdmaI)==0) {}

Dragons003 This is not recommended. Such polling should only ever be used for short transfers that are expected to finish very quickly.

QDMA_Release

#include <QDMA.h>

QDMA_STATUS QDMA_Release(SC6xQDMA *Interface);

stand-alone

This function releases all resources held by the QDMA channel (including the associated EDMA channel). It makes QDMA available for use by other threads. The interface remains valid for further use.

The function can return two values:

	QDMA_OK	The release was successful.
	QDMA_UNCLAIMED	The QDMA channel had not been claimed.

If only one thread on a processor needs to use QDMA, it may claim the channel once and never release it. If you wish to change the termination action (from QDMA_POLL to QDMA_INTERRUPT, for example) you must release the channel and then claim it again.

QDMA_Restart

#include <QDMA.h>

QDMA_Restart(SC6xQDMA *I, unsigned int *Param, unsigned int Value);

stand-alone

Having completed one transfer using QDMA_Perform, you can perform subsequent transfers by directly assigning new values to the registers in QDMA_REGS and then assigning the final, or only, changed value to a pseudo register using QDMA_Restart.

QDMA_REGS *Q = QDMA_REGISTERS;

Q->Src = &input_buffer;

QDMA_Restart(QdmaI, Q->Dst, &output_buffer);

Dragons003 You should not touch the QDMA pseudo registers explicitly; these are managed for you by Diamond.