ADM-XRC SDK 2.8.1 User Guide (Linux)
© Copyright 2001-2009 Alpha Data


ADMXRC2_SetupDMA

Prototype

ADMXRC2_STATUS
ADMXRC2_SetupDMA(
    ADMXRC2_HANDLE   Card,
    const void*      Buffer,
    unsigned long    Size,
    uint32_t         Flags,
    ADMXRC2_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
ADMXRC2_SUCCESS The application buffer was successfully locked down and a DMA descriptor returned
ADMXRC2_INVALID_HANDLE The Card handle was not valid
ADMXRC2_INVALID_PARAMETER Flags was not valid
ADMXRC2_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 ADMXRC2_DoDMA and ADMXRC2_DoDMAImmediate.

The Buffer parameter must point to the application buffer to be mapped. On a Linux platform, due to the way a 2.4.x kernel locks down memory, the ADMXRC2_Malloc API function must be used to allocate and free memory that is to be used as a DMA target (ie. passed to ADMXRC2_SetupDMA in this parameter).

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 ADMXRC2_DMADESC. If ADMXRC2_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 ADMXRC2_SetupDMA commits a descriptor, until freed by a matching call to ADMXRC2_UnsetupDMA.

 


 Top of page