ixqmgr.h

AMCC POWERPC 44X系列的U-BOOT文件

	       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_STATUS
ixQMgrQConfig (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_STATUS
ixQMgrQSizeInEntriesGet (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_STATUS
ixQMgrWatermarkSet (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_STATUS
ixQMgrAvailableSramAddressGet (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_STATUS
ixQMgrQReadWithChecks (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_STATUS
ixQMgrQReadMWordsMinus1 (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_APIS
PUBLIC IX_STATUS
ixQMgrQRead (IxQMgrQId qId,
             UINT32 *entryPtr);
#else 
extern IxQMgrQInlinedReadWriteInfo ixQMgrQInlinedReadWriteInfo[];
extern IX_STATUS ixQMgrQReadMWordsMinus1 (IxQMgrQId qId, UINT32 *entryPtr);

IX_QMGR_INLINE PUBLIC IX_STATUS
ixQMgrQRead (IxQMgrQId qId,
             UINT32 *entryPtr);
#endif

IX_QMGR_INLINE PUBLIC IX_STATUS
ixQMgrQRead (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_STATUS
ixQMgrQBurstRead (IxQMgrQId qId,
                  UINT32 numEntries,
                  UINT32 *entries);
#else
IX_QMGR_INLINE PUBLIC IX_STATUS
ixQMgrQBurstRead (IxQMgrQId qId,
                  UINT32 numEntries,
                  UINT32 *entries);
#endif  /* endif NO_INLINE_APIS */

IX_QMGR_INLINE PUBLIC IX_STATUS
ixQMgrQBurstRead (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