IxQMgrQSizeInWords qSizeInWords,	       IxQMgrQEntrySizeInWords qEntrySizeInWords) * * @brief Configure an AQM queue. * * This function is called by a client to setup a queue. The size and entrySize * qId and qName(NULL pointer) are checked for valid values. This function must * be called for each queue, before any queue accesses are made and after * ixQMgrInit() has been called. qName is assumed to be a '\0' terminated array * of 16 charachters or less. * * @param *qName char [in] - is the name provided by the client and is associated *                          with a QId by the QMgr. * @param qId @ref IxQMgrQId [in]  - the qId of this queue * @param qSizeInWords @ref IxQMgrQSize [in] - the size of the queue can be one of 16,32 *                                       64, 128 words. * @param qEntrySizeInWords @ref IxQMgrQEntrySizeInWords [in] - the size of a queue entry *                                                        can be one of 1,2,4 words. * * @return @li IX_SUCCESS, a specified queue has been successfully configured. * @return @li IX_FAIL, IxQMgr has not been initialised. * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s). * @return @li IX_QMGR_INVALID_QSIZE, invalid queue size * @return @li IX_QMGR_INVALID_Q_ID, invalid queue id * @return @li IX_QMGR_INVALID_Q_ENTRY_SIZE, invalid queue entry size * @return @li IX_QMGR_Q_ALREADY_CONFIGURED, queue already configured * */PUBLIC IX_STATUSixQMgrQConfig (char *qName,	       IxQMgrQId qId,	       IxQMgrQSizeInWords qSizeInWords,	       IxQMgrQEntrySizeInWords qEntrySizeInWords);/** * @ingroup IxQMgrAPI *  * @fn ixQMgrQSizeInEntriesGet (IxQMgrQId qId,			 unsigned *qSizeInEntries) * * @brief Return the size of a queue in entries. * * This function returns the the size of the queue in entriese. * * @param qId @ref IxQMgrQId [in] - the queue identifier * @param *qSizeInEntries @ref IxQMgrQSize [out] - queue size in entries * * @return @li IX_SUCCESS, successfully retrieved the number of full entrie * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s). * */PUBLIC IX_STATUSixQMgrQSizeInEntriesGet (IxQMgrQId qId,			 unsigned *qSizeInEntries);/** * * @ingroup IxQMgrAPI *  * @fn ixQMgrWatermarkSet (IxQMgrQId qId,		    IxQMgrWMLevel ne,		    IxQMgrWMLevel nf) * * @brief Set the Nearly Empty and Nearly Full Watermarks fo a queue. * * This function is called by a client to set the watermarks NE and NF for the * queue specified by qId. * The queue must be empty at the time this function is called, it is the clients * responsibility to ensure that the queue is empty. * This function will read the status of the queue before the watermarks are set * and again after the watermarks are set. If the status register has changed, * due to a queue access by an NPE for example, a warning is returned. * Queues 32-63 only support the NE flag, therefore the value of nf will be ignored * for these queues. * * @param qId @ref IxQMgrQId [in] -  the QId of the queue. * @param ne @ref IxQMgrWMLevel [in]  - the NE(Nearly Empty) watermark for this *                                 queue. Valid values are 0,1,2,4,8,16,32 and *                                 64 entries. * @param nf @ref IxQMgrWMLevel [in] - the NF(Nearly Full) watermark for this queue. *                                 Valid values are 0,1,2,4,8,16,32 and 64 *                                 entries. * * @return @li IX_SUCCESS, watermarks have been set for the queu * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId * @return @li IX_QMGR_INVALID_Q_WM, invalid watermark * @return @li IX_QMGR_WARNING, the status register may not be constistent * */PUBLIC IX_STATUSixQMgrWatermarkSet (IxQMgrQId qId,		    IxQMgrWMLevel ne,		    IxQMgrWMLevel nf);/** * @ingroup IxQMgrAPI *  * @fn ixQMgrAvailableSramAddressGet (UINT32 *address,			       unsigned *sizeOfFreeSram) * * @brief Return the address of available AQM SRAM. * * This function returns the starting address in AQM SRAM not used by the * current queue configuration and should only be called after all queues * have been configured. * Calling this function before all queues have been configured will will return * the currently available SRAM. A call to configure another queue will use some * of the available SRAM. * The amount of SRAM available is specified in sizeOfFreeSram. The address is the * address of the bottom of available SRAM. Available SRAM extends from address * from address to address + sizeOfFreeSram. * * @param **address UINT32 [out] - the address of the available SRAM, NULL if *                                none available. * @param *sizeOfFreeSram unsigned [out]- the size in words of available SRAM * * @return @li IX_SUCCESS, there is available SRAM and is pointed to by address * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s) * @return @li IX_QMGR_NO_AVAILABLE_SRAM, all AQM SRAM is consumed by the queue *             configuration. * */PUBLIC IX_STATUSixQMgrAvailableSramAddressGet (UINT32 *address,			       unsigned *sizeOfFreeSram);/* ------------------------------------------------------------   Queue access related functions   ---------------------------------------------------------- *//** * * @ingroup IxQMgrAPI *  * @fn ixQMgrQReadWithChecks (IxQMgrQId qId,                       UINT32 *entry) * * @brief Read an entry from a queue. * * This function reads an entire entry from a queue returning it in entry. The * queue configuration word is read to determine what entry size this queue is * configured for and then the number of words specified by the entry size is * read.  entry must be a pointer to a previously allocated array of sufficient * size to hold an entry. * * @note - IX_QMGR_Q_UNDERFLOW is only returned for queues 0-31 as queues 32-63 * do not have an underflow status maintained. * * @param  qId @ref IxQMgrQId [in]   - the queue identifier. * @param  *entry UINT32 [out]  - pointer to the entry word(s). * * @return @li IX_SUCCESS, entry was successfully read. * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s). * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue * */PUBLIC IX_STATUSixQMgrQReadWithChecks (IxQMgrQId qId,                       UINT32 *entry);/**  * @brief Internal structure to facilitate inlining functions in IxQMgr.h */typedef struct{    /* fields related to write functions */    UINT32 qOflowStatBitMask;         /**< overflow status mask */    UINT32 qWriteCount;               /**< queue write count */    /* fields related to read and write functions */    volatile UINT32 *qAccRegAddr;     /**< access register */    volatile UINT32 *qUOStatRegAddr;  /**< status register */    volatile UINT32 *qConfigRegAddr;  /**< config register */    UINT32 qEntrySizeInWords;         /**< queue entry size in words */    UINT32 qSizeInEntries;            /**< queue size in entries */    /* fields related to read functions */    UINT32 qUflowStatBitMask;         /**< underflow status mask */    UINT32 qReadCount;                /**< queue read count */} IxQMgrQInlinedReadWriteInfo;/** * * @ingroup IxQMgrAPI * * @fn ixQMgrQReadMWordsMinus1 (IxQMgrQId qId,			        UINT32 *entry) * * @brief This function reads the remaining of the q entry *        for queues configured with many words. *        (the first word of the entry is already read  *        in the inlined function and the entry pointer already *        incremented * * @param  qId @ref IxQMgrQId [in]  - the queue identifier. * @param  *entry UINT32 [out] - pointer to the entry word(s). * * @return @li IX_SUCCESS, entry was successfully read. * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue * */PUBLIC IX_STATUSixQMgrQReadMWordsMinus1 (IxQMgrQId qId,			 UINT32 *entry);/** * * @ingroup IxQMgrAPI *  * @fn ixQMgrQRead (IxQMgrQId qId,	     UINT32 *entry) * * @brief Fast read of an entry from a queue. * * This function is a heavily streamlined version of ixQMgrQReadWithChecks(), * but performs essentially the same task.  It reads an entire entry from a * queue, returning it in entry which must be a pointer to a previously * allocated array of sufficient size to hold an entry. * * @note - This function is inlined, to reduce unnecessary function call * overhead.  It does not perform any parameter checks, or update any statistics. * Also, it does not check that the queue specified by qId has been configured. * or is in range. It simply reads an entry from the queue, and checks for * underflow. * * @note - IX_QMGR_Q_UNDERFLOW is only returned for queues 0-31 as queues 32-63 * do not have an underflow status maintained. * * @param  qId @ref IxQMgrQId [in] - the queue identifier. * @param  *entry UINT32 [out] - pointer to the entry word(s). * * @return @li IX_SUCCESS, entry was successfully read. * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue * */#ifdef NO_INLINE_APISPUBLIC IX_STATUSixQMgrQRead (IxQMgrQId qId,             UINT32 *entryPtr);#else extern IxQMgrQInlinedReadWriteInfo ixQMgrQInlinedReadWriteInfo[];extern IX_STATUS ixQMgrQReadMWordsMinus1 (IxQMgrQId qId, UINT32 *entryPtr);IX_QMGR_INLINE PUBLIC IX_STATUSixQMgrQRead (IxQMgrQId qId,             UINT32 *entryPtr);#endifIX_QMGR_INLINE PUBLIC IX_STATUSixQMgrQRead (IxQMgrQId qId,	     UINT32 *entryPtr)#ifdef NO_INLINE_APIS    ;#else{    IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];    UINT32 entry, entrySize;    /* get a new entry */    entrySize = infoPtr->qEntrySizeInWords;    entry = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr);    if (entrySize != IX_QMGR_Q_ENTRY_SIZE1)    {		*entryPtr = entry;	/* process the remaining part of the entry */	return ixQMgrQReadMWordsMinus1(qId, entryPtr);    }    /* underflow is available for lower queues only */    if (qId < IX_QMGR_MIN_QUEUPP_QID)    {	/* the counter of queue entries is decremented. In happy 	 * day scenario there are many entries in the queue	 * and the counter does not reach zero.	 */ 	if (infoPtr->qReadCount-- == 0)	{	    /* There is maybe no entry in the queue	     * qReadCount is now negative, but will be corrected before	     * the function returns.	     */	    UINT32 qPtrs; /* queue internal pointers */	    /* when a queue is empty, the hw guarantees to return 	     * a null value. If the value is not null, the queue is	     * not empty.	     */	    if (entry == 0)	    {		/* get the queue status */		UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);			/* check the underflow status */		if (status & infoPtr->qUflowStatBitMask)		{		    /* the queue is empty 		    *  clear the underflow status bit if it was set 		    */		    IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr,					 status & ~infoPtr->qUflowStatBitMask);		    *entryPtr = 0;		    infoPtr->qReadCount = 0;		    return IX_QMGR_Q_UNDERFLOW;		}	    }	    /* store the result */	    *entryPtr = entry;	    /* No underflow occured : someone is filling the queue	     * or the queue contains null entries.	     * The current counter needs to be	     * updated from the current number of entries in the queue	     */	    /* get snapshot of queue pointers */	    qPtrs = IX_QMGR_INLINE_READ_LONG(infoPtr->qConfigRegAddr);	    /* Mod subtraction of pointers to get number of words in Q. */	    qPtrs = (qPtrs - (qPtrs >> 7)) & 0x7f;   	    if (qPtrs == 0)	    {		/* no entry in the queue */		infoPtr->qReadCount = 0;	    }	    else	    {		/* convert the number of words inside the queue		 * to a number of entries 		 */		infoPtr->qReadCount = qPtrs & (infoPtr->qSizeInEntries - 1);	    }	    return IX_SUCCESS;	}    }    *entryPtr = entry;    return IX_SUCCESS;}#endif/** * * @ingroup IxQMgrAPI *  * @fn ixQMgrQBurstRead (IxQMgrQId qId,		  UINT32 numEntries,		  UINT32 *entries) * * @brief Read a number of entries from an AQM queue. * * This function will burst read a number of entries from the specified queue. * The entry size of queue is auto-detected. The function will attempt to * read as many entries as specified by the numEntries parameter and will * return an UNDERFLOW if any one of the individual entry reads fail. * * @warning * IX_QMGR_Q_UNDERFLOW is only returned for queues 0-31 as queues 32-63 * do not have an underflow status maintained, hence there is a potential for * silent failure here. This function must be used with caution. * * @note * This function is intended for fast draining of queues, so to make it * as efficient as possible, it has the following features: * - This function is inlined, to reduce unnecessary function call overhead. * - It does not perform any parameter checks, or update any statistics. * - It does not check that the queue specified by qId has been configured. * - It does not check that the queue has the number of full entries that * have been specified to be read. It will read until it finds a NULL entry or * until the number of specified entries have been read.  It always checks for * underflow after all the reads have been performed. * Therefore, the client should ensure before calling this function that there * are enough entries in the queue to read.  ixQMgrQNumEntriesGet() will * provide the number of full entries in a queue. * ixQMgrQRead() or ixQMgrQReadWithChecks(), which only reads * a single queue entry per call, should be used instead if the user requires * checks for UNDERFLOW after each entry read. * * @param qId @ref IxQMgrQId [in]   - the queue identifier. * @param numEntries unsigned [in] - the number of entries to read.  *                     This number should be greater than 0 * @param *entries UINT32 [out] - the word(s) read. * * @return @li IX_SUCCESS, entries were successfully read. * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue  * */#ifdef NO_INLINE_APIS  PUBLIC IX_STATUSixQMgrQBurstRead (IxQMgrQId qId,                  UINT32 numEntries,                  UINT32 *entries);#elseIX_QMGR_INLINE PUBLIC IX_STATUSixQMgrQBurstRead (IxQMgrQId qId,                  UINT32 numEntries,                  UINT32 *entries);#endif  /* endif NO_INLINE_APIS */IX_QMGR_INLINE PUBLIC IX_STATUSixQMgrQBurstRead (IxQMgrQId qId,		  UINT32 numEntries,		  UINT32 *entries)#ifdef NO_INLINE_APIS;#else{    IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];    UINT32 nullCheckEntry;    if (infoPtr->qEntrySizeInWords == IX_QMGR_Q_ENTRY_SIZE1)    {	volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr;	/* the code is optimized to take care of data dependencies:	 * Durig a read, there are a few cycles needed to get the 	 * read complete. During these cycles, it is poossible to	 * do some CPU, e.g. increment pointers and decrement