//elements to help me manage the memory

    XsDmaDeviceTypeT sourceDeviceType;
    XsDmaDeviceTypeT targetDeviceType;
    UINT32 signature;    // this is an embedded signature for a descriptor 
    
    // additional elements required for client usage
    UINT32 currentPhysicalAddr; // the physical address of this descriptor
    XsDmaDescriptorElementsTPT prevDescrP;
    UINT32 spare1;
    UINT32 spare2;
    
}XsDmaDescriptorElementsT;



/*
*******************************************************************************
Defines for the device name used in XsDmatoDevice_T structure
*******************************************************************************
*/

typedef enum XsDmaDeviceNamesE
{
    XSDMA_DN_MEMORY,
    XSDMA_DN_I2S,
    XSDMA_DN_BTUART,
    XSDMA_DN_FFUART,
    XSDMA_DN_AC97_MIC,
    XSDMA_DN_AC97_MODEM,
    XSDMA_DN_AC97_AUDIO,
    XSDMA_DN_SSP,
    XSDMA_DN_ICP,
    XSDMA_DN_STUART,
    XSDMA_DN_MMC,
    XSDMA_DN_USB_EP1,        // EP for Endpoint
    XSDMA_DN_USB_EP2,
    XSDMA_DN_USB_EP3,
    XSDMA_DN_USB_EP4,
    XSDMA_DN_USB_EP6,
    XSDMA_DN_USB_EP7,
    XSDMA_DN_USB_EP8,
    XSDMA_DN_USB_EP9,
    XSDMA_DN_USB_EP11,
    XSDMA_DN_USB_EP12,
    XSDMA_DN_USB_EP13,
    XSDMA_DN_USB_EP14
} XsDmaDeviceNamesT;

/*
*******************************************************************************
    Constants for use in identifying deviceName as source or target
*******************************************************************************
*/

typedef enum XsDmaDeviceDirectionE
{
    XSDMA_DEV_DIRN_SOURCE,
    XSDMA_DEV_DIRN_TARGET
    
} XsDmaDeviceDirectionT;

/*
*******************************************************************************
define the usage verbs for DMA channel management
*******************************************************************************
*/

typedef enum ChannelOperationsE
{ 
    CHANNEL_OP_GET, 
    CHANNEL_OP_SET, 
    CHANNEL_OP_RESET 
} ChannelOperationsT;

/*
*******************************************************************************
define priority types for channel acquisition
*******************************************************************************
*/

typedef enum XsDmaChannelPriorityE
{
    XSDMA_CH_PR_HIGH,
    XSDMA_CH_PR_MEDIUM,
    XSDMA_CH_PR_LOW
} XsDmaChannelPriorityT;

/*
*******************************************************************************
define burst size for the DMA transfer
*******************************************************************************
*/

typedef enum XsDmaBurstSizeE
{
    XSDMA_BURST_SIZE_8  = 8,
    XSDMA_BURST_SIZE_16 = 16,
    XSDMA_BURST_SIZE_32 = 32
} XsDmaBurstSizeT;

/*
*******************************************************************************
status values for channel acquisition. 
*******************************************************************************
*/

typedef enum XsDmaChannelStatusE
{
    XSDMA_CS_GOT_EXPECTED,        // if a channel with the requested priority was returned
    XSDMA_CS_LOWER_THAN_EXPECTED,  // if a channel with a lower priority was returned
    XSDMA_CS_HIGHER_THAN_EXPECTED,  // if a channel with a higher priority was returned
    XSDMA_CS_NONE_AVAILABLE        // No channel available
} XsDmaChannelStatusT;

/*
*******************************************************************************
alignment masks
*******************************************************************************
*/

//#define BYTE16      0xFFFFFFF0U
//#define BIT16       0xFFFFFFFEU
//#define BIT32       0xFFFFFFFCU
//#define BIT64       0xFFFFFFF8U

/*
*******************************************************************************
Interrupt reasons - used for enable or disable
*******************************************************************************
*/

    // Interrupt if a bus error event occurs on the target channel.
    //  Bus errors will apparently always cause interrupts; there is no
    //  documented way to turn them on or off.  If a channel client does
    //  not  have an ISR, there will be no record of this error because
    //  the DMA ISR will clear it even if there is no client channel ISR.
// Uses DCSR_BUSERRINTR

    // Set DCSR[EndIntr] interrupt for the channel when DCMD[LENGTH] is 
    //  decreased to zero.  Bit 21 in the CMD word of the descriptor.
    // Note that this is different than channel stopped.
// Uses DCSR_ENDINTR

    // Descriptor successful load: Bit 22 in the CMD word of the descriptor.
    //  Valid only for No-Descriptor Fetch Mode.  (Not currently supported by
    //  DMA driver API)
// Uses DCSR_STARTINTR


    // Interrupt if channel is stopped or uninitialized.  DCSR bit 29.
    //  Will cause an initial interrupt if enabled before channel is running.
// Uses DCSR_STOPINTR


/*
*******************************************************************************
interrupt handler callback function type
*******************************************************************************
*/

typedef void (*XsDmaHandlerFnPT) (void *, UINT32);                                         


/*
*******************************************************************************
function prototypes
*******************************************************************************
*/

void   XsDmaSWInit (void);
UINT32 XsDmaHWSetup (void);
UINT32 XsDmaRegisterHandler (UINT, XsDmaHandlerFnPT , void *);
UINT32 XsDmaUnregisterHandler (UINT);
INT XsDmaGetFreeChannel (XsDmaChannelPriorityT , 
                          XsDmaDeviceNamesT , 
                          BOOL ,
                          XsDmaChannelStatusT *); 
UINT32 XsDmaFreeChannel(INT);
UINT32 XsDmaLoadFirstDescriptorAddr (INT, 
                                 XsDmaDescriptorElementsTPT);
UINT32 XsDmaStart (INT channel);
UINT32 XsDmaStop (UINT32);
UINT32 XsDmaWaitUntilStopped (UINT32);
UINT32 XsDmaDestroyChain (XsDmaDescriptorElementsTPT);
UINT32 XsDmaIntReasonEnable(UINT, UINT32);
UINT32 XsDmaIntReasonDisable(UINT, UINT32);


//-----------------------------------
typedef UINT32 (*XsDmaOperateOnDescriptorFnPT)(XsDmaDescriptorElementsTPT);

INT XsDmaGetRemainingLength (INT channel);
UINT32 XsDmaReadChannelStatus (INT channel);
UINT32 XsDmaRangeCheckChannel (INT);
void XsDmaCloseChain  (XsDmaDescriptorElementsTPT);
void XsDmaOpenChain   (XsDmaDescriptorElementsTPT);
UINT32 XsDmaMakeBackLink(XsDmaDescriptorElementsTPT);
UINT32 XsDmaOperateOnChain (XsDmaDescriptorElementsTPT,
                           XsDmaOperateOnDescriptorFnPT);
UINT32 XsDmaMakeBackLinksInChain (XsDmaDescriptorElementsTPT);
XsDmaDescriptorElementsTPT XsDmaCreateDescriptorChain (INT , INT, UINT);
XsDmaDescriptorElementsTPT XsDmaCreateBareDescChain(INT , INT, UINT);
XsDmaDescriptorElementsTPT XsDmaCreateDescriptorFromChan (INT, UINT);
UINT32 XsDmaConfigureDevice (XsDmaChannelPriorityT desiredPriority,
                            XsDmaDeviceNamesT deviceName, 
                            BOOL isTarget,
                            XsDmaDescriptorElementsTPT * firstDescVtP,
                            INT numDescriptors,
                            UINT xferByteCount,
                            XsDmaHandlerFnPT callbackFnP,
                            PVOID param,
                            UINT32 intReasons,
                            PINT returnChannelNumP);
UINT32 XsDmaConfigureMemToMem (XsDmaChannelPriorityT desiredPriority,
                            XsDmaDeviceNamesT deviceName, 
                            XsDmaDescriptorElementsTPT * firstDescVtP,
                            INT numDescriptors,
                            UINT xferByteCount,
                            XsDmaHandlerFnPT callbackFnP,
                            PVOID param,
                            UINT32 intReasons,
                            PINT returnChannelNumP); 
UINT32 XsDmaSetStartIntrReason   (XsDmaDescriptorElementsTPT);
UINT32 XsDmaClearStartIntrReason (XsDmaDescriptorElementsTPT);
UINT32 XsDmaSetEndIntrReason     (XsDmaDescriptorElementsTPT);
UINT32 XsDmaClearEndIntrReason   (XsDmaDescriptorElementsTPT);
UINT32 XsDmaDescrSetStopBit      (XsDmaDescriptorElementsTPT);
UINT32 XsDmaDescrClrStopBit      (XsDmaDescriptorElementsTPT);
VOID XsDmaSetBurstSize (XsDmaDeviceNamesT deviceName, XsDmaBurstSizeT burstSize);


//------------ Debug utilities ----------------

void XsDmaDumpDescriptor (XsDmaDescriptorElementsTPT, INT);

/********************************************************************************/

#endif // C_DMA_CONTROLLER_API