/**
* Fully or partially undo an XEmacPs_BdRingAlloc() operation. Use this
* function if all the BDs allocated by XEmacPs_BdRingAlloc() could not be
* transferred to hardware with XEmacPs_BdRingToHw().
*
* This function helps out in situations when an unrelated error occurs after
* BDs have been allocated but before they have been given to hardware.
* An example of this type of error would be an OS running out of resources.
*
* This function is not the same as XEmacPs_BdRingFree(). The Free function
* returns BDs to the free list after they have been processed by hardware,
* while UnAlloc returns them before being processed by hardware.
*
* There are two scenarios where this function can be used. Full UnAlloc or
* Partial UnAlloc. A Full UnAlloc means all the BDs Alloc'd will be returned:
*
* <pre>
* Status = XEmacPs_BdRingAlloc(MyRingPtr, 10, &BdPtr);
* ...
* if (Error)
* {
* Status = XEmacPs_BdRingUnAlloc(MyRingPtr, 10, &BdPtr);
* }
* </pre>
*
* A partial UnAlloc means some of the BDs Alloc'd will be returned:
*
* <pre>
* Status = XEmacPs_BdRingAlloc(MyRingPtr, 10, &BdPtr);
* BdsLeft = 10;
* CurBdPtr = BdPtr;
*
* while (BdsLeft)
* {
* if (Error)
* {
* Status = XEmacPs_BdRingUnAlloc(MyRingPtr, BdsLeft, CurBdPtr);
* }
*
* CurBdPtr = XEmacPs_BdRingNext(MyRingPtr, CurBdPtr);
* BdsLeft--;
* }
* </pre>
*
* A partial UnAlloc must include the last BD in the list that was Alloc'd.
*
* @param RingPtr is a pointer to the instance to be worked on.
* @param NumBd is the number of BDs to allocate
* @param BdSetPtr is an output parameter, it points to the first BD available
* for modification.
*
* @return
* - XST_SUCCESS if the BDs were unallocated.
* - XST_FAILURE if NumBd parameter was greater that the number of BDs in
* the preprocessing state.
*
* @note This function should not be preempted by another XEmacPs_Bd function
* call that modifies the BD space. It is the caller's responsibility to
* provide a mutual exclusion mechanism.
*
*****************************************************************************/
int XEmacPs_BdRingUnAlloc(XEmacPs_BdRing * RingPtr, unsigned NumBd,
XEmacPs_Bd * BdSetPtr)
{
/* Enough BDs in the free state for the request? */
if (RingPtr->PreCnt < NumBd) {
return (XST_FAILURE);
}
/* Set the return argument and move FreeHead backward */
XEMACPS_RING_SEEKBACK(RingPtr, RingPtr->FreeHead, NumBd);
RingPtr->FreeCnt += NumBd;
RingPtr->PreCnt -= NumBd;
return (XST_SUCCESS);
}
/**
* Fully or partially undo an XEmacPs_BdRingAlloc() operation. Use this
* function if all the BDs allocated by XEmacPs_BdRingAlloc() could not be
* transferred to hardware with XEmacPs_BdRingToHw().
*
* This function helps out in situations when an unrelated error occurs after
* BDs have been allocated but before they have been given to hardware.
* An example of this type of error would be an OS running out of resources.
*
* This function is not the same as XEmacPs_BdRingFree(). The Free function
* returns BDs to the free list after they have been processed by hardware,
* while UnAlloc returns them before being processed by hardware.
*
* There are two scenarios where this function can be used. Full UnAlloc or
* Partial UnAlloc. A Full UnAlloc means all the BDs Alloc'd will be returned:
*
* <pre>
* Status = XEmacPs_BdRingAlloc(MyRingPtr, 10, &BdPtr),
* ...
* if (Error)
* {
* Status = XEmacPs_BdRingUnAlloc(MyRingPtr, 10, &BdPtr),
* }
* </pre>
*
* A partial UnAlloc means some of the BDs Alloc'd will be returned:
*
* <pre>
* Status = XEmacPs_BdRingAlloc(MyRingPtr, 10, &BdPtr),
* BdsLeft = 10,
* CurBdPtr = BdPtr,
*
* while (BdsLeft)
* {
* if (Error)
* {
* Status = XEmacPs_BdRingUnAlloc(MyRingPtr, BdsLeft, CurBdPtr),
* }
*
* CurBdPtr = XEmacPs_BdRingNext(MyRingPtr, CurBdPtr),
* BdsLeft--,
* }
* </pre>
*
* A partial UnAlloc must include the last BD in the list that was Alloc'd.
*
* @param RingPtr is a pointer to the instance to be worked on.
* @param NumBd is the number of BDs to allocate
* @param BdSetPtr is an output parameter, it points to the first BD available
* for modification.
*
* @return
* - XST_SUCCESS if the BDs were unallocated.
* - XST_FAILURE if NumBd parameter was greater that the number of BDs in
* the preprocessing state.
*
* @note This function should not be preempted by another XEmacPs_Bd function
* call that modifies the BD space. It is the caller's responsibility to
* provide a mutual exclusion mechanism.
*
*****************************************************************************/
LONG XEmacPs_BdRingUnAlloc(XEmacPs_BdRing * RingPtr, u32 NumBd,
XEmacPs_Bd * BdSetPtr)
{
LONG Status;
(void *)BdSetPtr;
Xil_AssertNonvoid(RingPtr != NULL);
Xil_AssertNonvoid(BdSetPtr != NULL);
/* Enough BDs in the free state for the request? */
if (RingPtr->PreCnt < NumBd) {
Status = (LONG)(XST_FAILURE);
} else {
/* Set the return argument and move FreeHead backward */
XEMACPS_RING_SEEKBACK(RingPtr, (RingPtr->FreeHead), NumBd);
RingPtr->FreeCnt += NumBd;
RingPtr->PreCnt -= NumBd;
Status = (LONG)(XST_SUCCESS);
}
return Status;
}
