ADM-XRC SDK 2.8.1 User Guide (Linux)
© Copyright 2001-2009 Alpha Data
Prototype
ADMXRC2_STATUS ADMXRC2_MapDirectMaster( ADMXRC2_HANDLE Card, ADMXRC2_DMADESC Buffer, unsigned long Offset, unsigned long Length, ADMXRC2_BUFFERMAP* Map);
Arguments
Argument | Type | Purpose |
Card | In | Handle of card that the bitstream targets |
Buffer | In | Specifies application buffer to map |
Offset | In | Where to begin mapping within the application buffer |
Length | In | Size of region of application buffer to map |
Map | In/Out | Structure to receive map information |
Return value
Value | Meaning |
ADMXRC2_SUCCESS | The bitstream file was successfully loaded |
ADMXRC2_INVALID_HANDLE | The Card parameter did not refer to an open card |
ADMXRC2_INVALID_DMADESC | The DMA descriptor representing the application buffer was not valid |
ADMXRC2_INVALID_PARAMETER | The Offset or Length parameters were outside the bounds of the application buffer |
Description
This function builds an array of PCI addresses of the pages of memory that comprise a buffer in the application's address space.
The Card parameter should be the handle of the card that was used to create the DMA descriptor DmaDesc. DMA descriptors are obtained via the ADMXRC2_SetupDMA API call.
The Offset and Length parameters identify a region within the buffer that DmaDesc refers to.
The Map parameter must point to an ADMXRC2_BUFFERMAP structure.
If the call to ADMXRC2_MapDirectMaster is successful, the array of page addresses may used by the FPGA in order to allow the FPGA to perform direct master access to the user buffer represented by DmaDesc. It is up to the application programmer to provide a mechanism by which the returned PCI page addresses are transferred to the FPGA. A simple mechanism is a bank of registers within the FPGA; the host simply writes the PCI page addresses to these registers using direct slave transfers.
Prior to calling ADMXRC2_MapDirectMaster, the MaxPages and PagesPci members must be initialized by the application. PagesPci should point to an application-allocated buffer that will receive the PCI addresses of the pages comprising the specified region of the application buffer. This region is specified by the Offset and Length parameters. MaxPages should be initialized to the number of unsigned long elements in the array that PagesPci points to.
If ADMXRC2_MapDirectMaster succeeds, the PageLength, PagesSpanned, BytesSpanned and InitOffset members of the ADMXRC2_BUFFERMAP that Map points to will be filled in with valid values.
It is possible that the number of pages in the array Map->PagesPci will not be sufficient to map the entire region specified by Length and Offset. There are two cases: