ADM-XRC SDK 2.8.1 User Guide (Linux)
© Copyright 2001-2009 Alpha Data
Prototype
ADMXRC_STATUS ADMXRC_SetupDMA( ADMXRC_HANDLE Card, void* Buffer, unsigned long Size, DWORD Flags, ADMXRC_DMADESC* DMADesc);
Arguments
Argument | Type | Purpose |
Card | In | Handle of card |
Buffer | In | The application buffer to lock down |
Size | In | The size of the application buffer |
Flags | In | Miscellaneous flags |
DMADesc | Out | The DMA descriptor returned |
Return value
Value | Meaning |
ADMXRC_SUCCESS | The application buffer was successfully locked down and a DMA descriptor returned |
ADMXRC_INVALID_HANDLE | The Card handle was not valid |
ADMXRC_INVALID_PARAMETER | Flags was not valid |
ADMXRC_NO_DMADESC | All DMA descriptors were in use |
Description
This function locks down and maps an application buffer, returning a descriptor which can subsequently be used to identify the buffer to the DMA API functions such as ADMXRC_DoDMA and ADMXRC_DoDMAImmediate.
The Buffer parameter must point to the application buffer to be mapped.
The Size parameter specifies the size, in bytes, of the application buffer to be mapped.
The Flags parameter must currently be 0.
The DMADesc parameter must point to a variable of type ADMXRC_DMADESC. If ADMXRC_SetupDMA succeeds, this variable will contain a DMA descriptor on return.
The application buffer is locked down (made non-swappable) so that the system cannot swap any page of physical memory spanned by the buffer out to disk. Locking down a very large region of memory under low memory conditions should be avoided.
There are a limited number of DMA descriptors, and each successful call to ADMXRC_SetupDMA commits a descriptor, until freed by a matching call to ADMXRC_UnsetupDMA.