Software Drivers
Main Page | Data Structures | File List | Data Fields | Globals

xaxidma_bd.h File Reference


Detailed Description

Buffer descriptor (BD) management API.

Buffer Descriptors

A BD defines a DMA transaction (see "Transaction" section in xaxidma.h). All accesses to a BD go through this set of API.

The XAxiDma_Bd structure defines a BD. The first XAXIDMA_BD_HW_NUM_BYTES are shared between hardware and software.

Actual Transfer Length

The actual transfer length for receive could be smaller than the requested transfer length. The hardware sets the actual transfer length in the completed BD. The API to retrieve the actual transfer length is XAxiDma_GetActualLength().

User IP words

There are 5 user IP words in each BD.

If hardware does not have the StsCntrl stream built in, then these words are not usable. Retrieving these words get a NULL pointer and setting these words results an error.

Performance

BDs are typically in a non-cached memory space. Reducing the number of I/O operations to BDs can improve overall performance of the DMA channel.

 MODIFICATION HISTORY:

 Ver   Who  Date     Changes
 ----- ---- -------- ------------------------------------------------------
 1.00a jz   05/18/10 First release
 2.00a jz   08/10/10 Second release, added in xaxidma_g.c, xaxidma_sinit.c,
                     updated tcl file, added xaxidma_porting_guide.h
 3.00a jz   11/22/10 Support IP core parameters change
 


Defines

#define XAxiDma_BdRead(BaseAddress, Offset)
#define XAxiDma_BdWrite(BaseAddress, Offset, Data)
#define XAxiDma_BdClear(BdPtr)
#define XAxiDma_BdGetCtrl(BdPtr)
#define XAxiDma_BdGetSts(BdPtr)
#define XAxiDma_BdGetLength(BdPtr)
#define XAxiDma_BdSetId(BdPtr, Id)
#define XAxiDma_BdGetId(BdPtr)
#define XAxiDma_BdGetBufAddr(BdPtr)
#define XAxiDma_BdHwCompleted(BdPtr)
#define XAxiDma_BdGetActualLength(BdPtr)

Typedefs

typedef u32 XAxiDma_Bd [XAXIDMA_BD_NUM_WORDS]

Functions

int XAxiDma_BdSetLength (XAxiDma_Bd *BdPtr, u32 LenBytes)
int XAxiDma_BdSetBufAddr (XAxiDma_Bd *BdPtr, u32 Addr)
int XAxiDma_BdSetAppWord (XAxiDma_Bd *BdPtr, int Offset, u32 Word)
u32 XAxiDma_BdGetAppWord (XAxiDma_Bd *BdPtr, int Offset, int *Valid)
void XAxiDma_BdSetCtrl (XAxiDma_Bd *BdPtr, u32 Data)
void XAxiDma_DumpBd (XAxiDma_Bd *BdPtr)


Define Documentation

#define XAxiDma_BdClear BdPtr   ) 
 

Zero out BD specific fields. BD fields that are for the BD ring or for the system hardware build information are not touched.

Parameters:
BdPtr is the BD to operate on
Returns:
Nothing
Note:
C-style signature: void XAxiDma_BdClear(XAxiDma_Bd* BdPtr)

#define XAxiDma_BdGetActualLength BdPtr   ) 
 

Get the actual transfer length of a BD. The BD has completed in hw.

This function may not work if the BD is in cached memory.

Parameters:
BdPtr is the BD to check on
Note:
C-style signature: int XAxiDma_BdGetActualLength(XAxiDma_Bd* BdPtr)

#define XAxiDma_BdGetBufAddr BdPtr   ) 
 

Get the BD's buffer address

Parameters:
BdPtr is the BD to operate on
Note:
C-style signature: u32 XAxiDma_BdGetBufAddr(XAxiDma_Bd* BdPtr)

#define XAxiDma_BdGetCtrl BdPtr   ) 
 

Get the control bits for the BD

Parameters:
BdPtr is the BD to operate on
Returns:
The bit mask for the control of the BD
Note:
C-style signature: u32 XAxiDma_BdGetCtrl(XAxiDma_Bd* BdPtr)

#define XAxiDma_BdGetId BdPtr   ) 
 

Retrieve the ID field of the given BD previously set with XAxiDma_BdSetId.

Parameters:
BdPtr is the BD to operate on
Note:
C-style signature: u32 XAxiDma_BdGetId(XAxiDma_Bd* BdPtr)

#define XAxiDma_BdGetLength BdPtr   ) 
 

Retrieve the length field value from the given BD. The returned value is the same as what was written with XAxiDma_BdSetLength(). Note that in the this value does not reflect the real length of received data. See the comments of XAxiDma_BdSetLength() for more details. To obtain the actual transfer length, use XAxiDma_BdGetActualLength().

Parameters:
BdPtr is the BD to operate on.
Returns:
The length value set in the BD.
Note:
C-style signature: u32 XAxiDma_BdGetLength(XAxiDma_Bd* BdPtr)

#define XAxiDma_BdGetSts BdPtr   ) 
 

Retrieve the status of a BD

Parameters:
BdPtr is the BD to operate on
Returns:
Word at offset XAXIDMA_BD_DMASR_OFFSET. Use XAXIDMA_BD_STS_*** values defined in xaxidma_hw.h to interpret the returned value
Note:
C-style signature: u32 XAxiDma_BdGetSts(XAxiDma_Bd* BdPtr)

#define XAxiDma_BdHwCompleted BdPtr   ) 
 

Check whether a BD has completed in hardware. This BD has been submitted to hardware. The application can use this function to poll for the completion of the BD.

This function may not work if the BD is in cached memory.

Parameters:
BdPtr is the BD to check on
Returns:
0 if not complete, XAXIDMA_BD_STS_COMPLETE_MASK if completed, may contain XAXIDMA_BD_STS_*_ERR_MASK bits.
Note:
C-style signature: int XAxiDma_BdHwCompleted(XAxiDma_Bd* BdPtr)

#define XAxiDma_BdRead BaseAddress,
Offset   ) 
 

Read the given Buffer Descriptor word.

Parameters:
BaseAddress is the base address of the BD to read
Offset is the word offset to be read
Returns:
The 32-bit value of the field
Note:
C-style signature: u32 XAxiDma_BdRead(u32 BaseAddress, u32 Offset)

#define XAxiDma_BdSetId BdPtr,
Id   ) 
 

Set the ID field of the given BD. The ID is an arbitrary piece of data the application can associate with a specific BD.

Parameters:
BdPtr is the BD to operate on
Id is a 32 bit quantity to set in the BD
Note:
C-style signature: void XAxiDma_BdSetId(XAxiDma_Bd* BdPtr, void Id)

#define XAxiDma_BdWrite BaseAddress,
Offset,
Data   ) 
 

Write the given Buffer Descriptor word.

Parameters:
BaseAddress is the base address of the BD to write
Offset is the word offset to be written
Data is the 32-bit value to write to the field
Returns:
None.
Note:
C-style signature: void XAxiDma_BdWrite(u32 BaseAddress, u32 RegOffset, u32 Data)


Typedef Documentation

typedef u32 XAxiDma_Bd[XAXIDMA_BD_NUM_WORDS]
 

The XAxiDma_Bd is the type for a buffer descriptor (BD).


Function Documentation

u32 XAxiDma_BdGetAppWord XAxiDma_Bd BdPtr,
int  Offset,
int *  Valid
 

Get the APP word at the specified APP word offset for a BD.

Parameters:
BdPtr is the BD to operate on.
Offset is the offset inside the APP word, it is valid from 0 to 4
Valid is to tell the caller whether parameters are valid
Returns:
The APP word. Passed in parameter Valid holds 0 for failure, and 1 for success.

int XAxiDma_BdSetAppWord XAxiDma_Bd BdPtr,
int  Offset,
u32  Word
 

Set the APP word at the specified APP word offset for a BD.

Parameters:
BdPtr is the BD to operate on.
Offset is the offset inside the APP word, it is valid from 0 to 4
Word is the value to set
Returns:
  • XST_SUCCESS for success
  • XST_INVALID_PARAM under following error conditions: 1) StsCntrlStrm is not built in hardware 2) Offset is not in valid range
Note:
If the hardware build has C_SG_USE_STSAPP_LENGTH set to 1, then the last APP word, XAXIDMA_LAST_APPWORD, must have non-zero value when AND with 0x7FFFFF. Not doing so will cause the hardware to stall.

int XAxiDma_BdSetBufAddr XAxiDma_Bd BdPtr,
u32  Addr
 

Set the BD's buffer address.

Parameters:
BdPtr is the BD to operate on
Addr is the address to set
Returns:
  • XST_SUCCESS if buffer address set successfully
  • XST_INVALID_PARAM if hardware has no DRE and address is not aligned

void XAxiDma_BdSetCtrl XAxiDma_Bd BdPtr,
u32  Data
 

Set the control bits for a BD.

Parameters:
BdPtr is the BD to operate on.
Data is the bit value to set
Returns:
None

int XAxiDma_BdSetLength XAxiDma_Bd BdPtr,
u32  LenBytes
 

Set the length field for the given BD.

Length has to be non-zero and less than XAXIDMA_MAX_TRANSFER_LEN.

For TX channels, the value passed in should be the number of bytes to transmit from the TX buffer associated with the given BD.

For RX channels, the value passed in should be the size of the RX buffer associated with the given BD in bytes. This is to notify the RX channel the capability of the RX buffer to avoid buffer overflow.

The actual receive length can be equal or smaller than the specified length. The actual transfer length will be updated by the hardware in the XAXIDMA_BD_STS_OFFSET word in the BD.

Parameters:
BdPtr is the BD to operate on.
LenBytes is the requested transfer length
Returns:
  • XST_SUCCESS for success
  • XST_INVALID_PARAM for invalid BD length

void XAxiDma_DumpBd XAxiDma_Bd BdPtr  ) 
 

Dump the fields of a BD.

Parameters:
BdPtr is the BD to operate on.
Returns:
None