path: root/Acceleration/include/accel_infra/IxQMgr.h

/**
 * @file    IxQMgr.h
 *
 *
 * @brief This file contains the Moher Software public API of IxQMgr component.
 *
 * 
 * @par
 * This file is provided under a dual BSD/GPLv2 license.  When using or 
 *   redistributing this file, you may do so under either license.
 * 
 *   GPL LICENSE SUMMARY
 * 
 *   Copyright(c) 2007,2008,2009 Intel Corporation. All rights reserved.
 * 
 *   This program is free software; you can redistribute it and/or modify 
 *   it under the terms of version 2 of the GNU General Public License as
 *   published by the Free Software Foundation.
 * 
 *   This program is distributed in the hope that it will be useful, but 
 *   WITHOUT ANY WARRANTY; without even the implied warranty of 
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU 
 *   General Public License for more details.
 * 
 *   You should have received a copy of the GNU General Public License 
 *   along with this program; if not, write to the Free Software 
 *   Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
 *   The full GNU General Public License is included in this distribution 
 *   in the file called LICENSE.GPL.
 * 
 *   Contact Information:
 *   Intel Corporation
 * 
 *   BSD LICENSE 
 * 
 *   Copyright(c) 2007,2008,2009 Intel Corporation. All rights reserved.
 *   All rights reserved.
 * 
 *   Redistribution and use in source and binary forms, with or without 
 *   modification, are permitted provided that the following conditions 
 *   are met:
 * 
 *     * Redistributions of source code must retain the above copyright 
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright 
 *       notice, this list of conditions and the following disclaimer in 
 *       the documentation and/or other materials provided with the 
 *       distribution.
 *     * Neither the name of Intel Corporation nor the names of its 
 *       contributors may be used to endorse or promote products derived 
 *       from this software without specific prior written permission.
 * 
 *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
 *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
 *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
 *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
 *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
 *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
 *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
 *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
 *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
 *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
 *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * 
 *
 */
 
/* ------------------------------------------------------
   Doxygen group definitions
   ------------------------------------------------------ */
/**
 * @defgroup IxQMgrAPI Software Queue Manager (IxQMgr) API
 *
 * @brief The public API for the Software QMgr component.
 *
 * @{
 */

#ifndef IXQMGR_H
#define IXQMGR_H

/*
 * User defined include files
 */
 
 
#include "IxOsal.h"
#include "icp.h"
#include "IxSwQueue.h"


/**
*
* @ingroup IxQMgrAPI
*
* @def IX_COMPONENT_NAME
*
* @brief defines the name of this component
*
*/
#define IX_COMPONENT_NAME IX_QMGR


/*
 * #defines and macros
 */

/**
*
* @ingroup IxQMgrAPI
*
* @def IX_QMGR_INLINE
*
* @brief Inline definition, for inlining of Queue Access functions on API
*
* Please read the header information in this file for more details on the
* use of function inlining in this component.
*
*/
#ifdef IXQMGRQACCESS_C
/* If IXQMGRQACCESS_C is set then the IxQmgrQAccess.c is including this file
   and must instantiate a concrete definition for each inlineable API function
   whether or not that function actually gets inlined. */
#    ifdef NO_INLINE_APIS
#        undef NO_INLINE_APIS
#    endif
#    define IX_QMGR_INLINE  /* Empty Define */
#else
#    ifndef NO_INLINE_APIS
#       define IX_QMGR_INLINE __inline__ extern
#    else
#       define IX_QMGR_INLINE /* Empty Define */
#    endif
#endif


/**
*
* @ingroup IxQMgrAPI
*
* @def IX_QMGR_MAX_NUM_QUEUES
*
* @brief Number of software queues supported by the QMgr component.
*
* This constant is used to indicate the number of queues
*
*/
#define IX_QMGR_MAX_NUM_QUEUES  (512)


/**
*
* @ingroup IxQMgrAPI
*
* @def IX_QMGR_MAX_QNAME_LEN
*
* @brief Maximum queue name length.
*
* This constant is used to indicate the maximum null terminated string length
* (excluding '\0') for a queue name
*
*/
#define IX_QMGR_MAX_QNAME_LEN (16)

/**
 *
 * @ingroup IxQMgrAPI
 *
 * @def IX_QMGR_Q_MAX_SIZE
 *
 * @brief Maximum Allowed Size for a Queue
 * 
 * As Head and Tail are Max 16-bits this figure must be less than 2^16
 * If this size is ever increased > 2^16, additional overflow checks will be
 * required during config.
 */
#define IX_QMGR_Q_MAX_SIZE (32768)


/**
 *
 * @ingroup IxQMgrAPI
 *
 * @def IX_QMGR_Q_MAX_ENTRY_SIZE
 *
 * @brief Maximum Allowed Entry Size for a Queue in words
 *
 * Entry Size will also be limited to 2^n values:   1,2,4,8.
 *
 */
#define IX_QMGR_Q_ENTRY_MAX_SIZE (8)

/**
 *
 * @ingroup IxQMgrAPI
 *
 * @def IX_QMGR_MAX_BYTE_COUNT
 *
 * @brief Max count value of 8-bits 
 *
 */
#define IX_QMGR_MAX_BYTE_COUNT (256) 


/**
 *
 * @ingroup IxQMgrAPI
 *
 * @def IX_QMGR_SIZEOF_WORD
 *
 * @brief The sizeof() a 32-bit word. value in bytes.
 *
 */
#define IX_QMGR_SIZEOF_WORD (4)

/**
 *
 * @ingroup IxQMgrAPI
 *
 * @def IX_QMGR_SIZEOF_BYTE
 *
 * @brief The sizeof() a 8-bit byte. value in bytes.
 *
 */
#define IX_QMGR_SIZEOF_BYTE (1)

/*
 * Mechanism to validate the upper (MAX) and lower (0) bounds
 * of a positive enumeration
 *
 * param int [in] VALUE - the integer value to test
 * param int [in] MAX - the maximum value to test against
 *
 * This macro returns TRUE if the bounds are invalid and FALSE if
 * they are okay. NOTE: MAX will be an invalid value, so check >=
 *
 */
#define IX_QMGR_ENUM_IS_INVALID(VALUE, MAX)   \
        ((((VALUE) < 0) || ((VALUE) >= (MAX))) ? TRUE : FALSE)


/**
 *
 * @ingroup IxQMgrAPI
 *
 * @def IX_QMGR_MASK_8BIT
 *
 * @brief A mask for 8-bits.
 *
 */
#define IX_QMGR_MASK_8BIT (0xFF)


/**
 *
 * @ingroup IxQMgrAPI
 *
 * @def IX_QMGR_MASK_16BIT
 *
 * @brief A mask for 16-bits.
 *
 */
#define IX_QMGR_MASK_16BIT (0xFFFF)

/*
 * Typedefs
 */

/**
 *
 * @typedef IxQMgrQId
 *
 * @ingroup IxQMgrAPI
 *
 * @brief Generic identifiers for queues.
 *
 * This defines generic identifiers for the queues.
 */
typedef UINT32 IxQMgrQId;


/**
 *
 * @typedef IxQMgrQEntryType
 *
 * @ingroup IxQMgrAPI
 *
 * @brief Entry Type for all Queue Entries
 *
 * This defines generic Entry for the queues.
 */
typedef UINT32 IxQMgrQEntryType;


/**
 * @enum IxQMgrNotificationCondition
 *
 * @ingroup IxQMgrAPI
 *
 * @brief Queue interrupt condition.
 *
 * This enum defines the different conditions on a queue that the client can register for
 * a callback notification by the dispatcher.
 *
 */
typedef enum
{
    IX_QMGR_Q_SOURCE_ID_E = 0,       /**< Queue Empty due to last read */
    IX_QMGR_Q_SOURCE_ID_NOT_E,  /**< Queue Not Empty  */
    IX_QMGR_Q_SOURCE_ID_BW,     /**< Queue Number of entries Below Watermark */
    IX_QMGR_Q_SOURCE_ID_AW,     /**< Queue Number of entries Above Watermark */
    IX_QMGR_Q_SOURCE_ID_NOT_F,  /**< Queue Not Full  */
    IX_QMGR_Q_SOURCE_ID_F,      /**< Queue Full  */
    IX_QMGR_Q_SOURCE_INVALID	/**< For Parameter validation purposes only */
} IxQMgrNotificationCondition;

/**
 * @typedef IxQMgrQState
 *
 * @ingroup IxQMgrAPI
 *
 * @brief Queue state.
 *
 * A queues status is defined by its relative fullness or relative emptiness.
 * Each of the queues can be in the following states: Below Watermark, 
 * Above Watermark, Empty, Full.
 *
 */
typedef enum
{
   IX_QMGR_Q_STATE_E = IX_QMGR_Q_SOURCE_ID_E,  /**< Queue Empty  */
   IX_QMGR_Q_STATE_BW = IX_QMGR_Q_SOURCE_ID_BW,     /**< Queue Number of Entries Below Watermark */
   IX_QMGR_Q_STATE_AW = IX_QMGR_Q_SOURCE_ID_AW,     /**< Queue Number of entries Above Watermark */
   IX_QMGR_Q_STATE_F = IX_QMGR_Q_SOURCE_ID_F        /**< Queue Full */
} IxQMgrQState;

/**
 * @typedef IxQMgrQSize
 *
 * @ingroup IxQMgrAPI
 *
 * @brief QMgr queue sizes.
 *
 * These values define the allowed queue sizes for a queue. The sizes are
 * specified in words, 1 word per entry. The Queue Size must be equal to 2^n. 
 * the theoritical maximum size for a queue will be 2^15 as the last bit 
 * is reserved and the queue counter used to manipulate the queues are 16 bits long.
 * however native size for xscale is 32 bits, so for better efficiency 32 bit 
 * long variables are used.
 *
 */
typedef UINT32 IxQMgrQSize;


/**
 * @typedef IxQMgrQEntrySizeInWords
 *
 * @ingroup IxQMgrAPI
 *
 * @brief QMgr queue entry sizes in owrds.
 *
 * These values define the allowed queue entry sizes for a queue. The Entry Size 
 * must be equal to 2^n. The maximum size for a queue will be 
 * IX_QMGR_Q_ENTRY_MAX_SIZE
 *
 */
typedef UINT32 IxQMgrQEntrySizeInWords;


/**
 * @typedef IxQMgrWMLevel
 *
 * @ingroup IxQMgrAPI
 *
 * @brief QMgr watermark levels.
 *
 * defines the watermark level for queues, 
 * the level will be limited to a range from 1 to the Queue Size minus 1.
 * This restriction will be enforced when setting the watermark level.
 */
typedef UINT32 IxQMgrWMLevel;


/**
 * @ingroup IxQMgrAPI
 * 
 * @typedef IxQMgrDispatchGroup
 *
 * @brief QMgr dispatch group identifiers.
 *
 * This type defines the logical groups of queues which the  dispatcher should 
 * process when called. each queue belongs to a single group. A group will be 
 * used as an input to ixQMgrDispatcherLoopRun().When configuring a Queue, 
 * the client will specify the group which it belongs to. 
 * valid group ID will be between 0 and MAX_DISPATCH_GRP_ID.
 *
 */
typedef UINT32 IxQMgrDispatchGroup;


/**
 *
 * @ingroup IxQMgrAPI
 *
 * @def IX_QMGR_DISPATCH_ETH
 *
 * @brief Reserved Dispatch Group ID for Ethernet 10/100 feature
 *
 */
#define IX_QMGR_DISPATCH_ETH (0)



/**
 *
 * @ingroup IxQMgrAPI
 *
 * @def IX_QMGR_DISPATCH_HSS
 *
 * @brief Reserved Dispatch Group ID for HSS feature Transmit Queues
 *
 */
#define IX_QMGR_DISPATCH_TX_HSS (1)



/**
 *
 * @ingroup IxQMgrAPI
 *
 * @def IX_QMGR_DISPATCH_HSS
 *
 * @brief Reserved Dispatch Group ID for HSS feature Voice Receive Queues
 *
 */
#define IX_QMGR_DISPATCH_VOICE_RX_HSS (2)


/**
 *
 * @ingroup IxQMgrAPI
 *
 * @def IX_QMGR_DISPATCH_HSS
 *
 * @brief Reserved Dispatch Group ID for HSS feature HDLC Receive Queues
 *
 */
#define IX_QMGR_DISPATCH_HDLC_RX_HSS (3)



/**
 *
 * @ingroup IxQMgrAPI
 *
 * @def IX_QMGR_MAX_DISPATCH_GRP_ID
 *
 * @brief Maximum Dispatch group ID authorised
 *
 */
#define IX_QMGR_MAX_NUM_DISPATCH_GRP (IX_QMGR_MAX_NUM_QUEUES)


/**
 * @ingroup IxQMgrAPI
 * 
 * @typedef IxQMgrCallbackId
 *
 * @brief Uniquely identifies a callback function.
 *
 * A unique callback identifier associated with each callback
 * registered by clients.
 *
 */
typedef UINT32 IxQMgrCallbackId;


/**
 * 
 * @ingroup IxQMgrAPI
 * 
 * @typedef IxQMgrCallback
 *
 * @brief QMgr notification callback type.
 *
 * This defines the interface to all client callback functions.
 *
 * @param IxQMgrQId qId(in) - the queue identifier
 * @param IxQMgrCallbackId cbId(in) - the callback identifier
 */
typedef void (*IxQMgrCallback)(IxQMgrQId qId,
                               IxQMgrCallbackId cbId);

/**
 * @ingroup IxQMgrAPI
 * 
 * @typedef IxSwQueueOfType_IxQMgrQEntryType
 * 
 * @brief the macro used here creates the Software Queue Type used 
 * throughout the Queue Manager.
 */
IX_SWQ_TYPE(IxQMgrQEntryType,IxQMgrSwQueue);


/**
 * @ingroup IxQMgrAPI
 * 
 * @typedef IxQMgrHeadAndTailCountFormat
 * 
 * @brief The count type of the Head and Tail pointer 
 *
 * This enum is used to indicate whether the Head and Tail pointers for a queue
 * count by the number of bytes or by the number of entries.
 */
typedef enum
{
   IX_QMGR_Q_COUNT_BYTES = 0,  
   IX_QMGR_Q_COUNT_ENTRIES,
   IX_QMGR_Q_COUNT_INVALID
   
} IxQMgrHeadAndTailCountFormat;

/**
 * @ingroup IxQMgrAPI
 * 
 * @typedef IxQMgrHeadAndTailAlignment
 * 
 * @brief The alignment of the Head and Tail
 *
 * This enum is used to indicate the alignment of the Head and Tail pointers of 
 * a queue. Note that in the case of Word alignment, only 16-bits are actually
 * used for counting. 
 */
typedef enum
{
   IX_QMGR_Q_ALIGN_BYTE = 0,  
   IX_QMGR_Q_ALIGN_WORD, 
   IX_QMGR_Q_ALIGN_INVALID
} IxQMgrHeadAndTailAlignment;


/**
 * @ingroup IxQMgrAPI
 * 
 * @typedef IxQMgrShadowCounter
 *
 * @brief Data Structure containing the shadowing information (the shadow tail 
 * and the real tail counters) for a queue.
 *
 */
 
typedef struct
{
    union
    {
         UINT8 byteShadowTailCounter;
         UINT32 wordShadowTailCounter;
    };
    union
    {
         volatile UINT8 *byteRealTailCounter;
         volatile UINT32 *wordRealTailCounter;
    };    
        
} IxQMgrShadowCounter;



/**
 * @ingroup IxQMgrAPI
 * 
 * @typedef IxQMgrHeadAndTailShadowing
 * 
 * @brief The shadowing of the queue counters 
 *
 * This enum is used to indicate the type of shadowing that should be usd for a 
 * queue. 
 */
typedef enum
{
   IX_QMGR_Q_NO_SHADOWING = 0,  
   IX_QMGR_Q_SHADOW_TAIL_ONLY, 
   IX_QMGR_Q_SHADOW_HEAD_ONLY,    
   IX_QMGR_Q_SHADOW_HEAD_TAIL,   
   IX_QMGR_Q_SHADOW_INVALID
} IxQMgrHeadAndTailShadowing;
/**
 * @ingroup IxQMgrAPI
 * 
 * @typedef IxQMgrQueue
 *
 * @brief Data Structure containing all the relevant information regarding a queue
 *
 */
typedef struct
{
    char qName[IX_QMGR_MAX_QNAME_LEN];          /**< name of the queue */
    IxQMgrQSize qSize;			        /**< queue size in entries */
    IxQMgrQEntrySizeInWords qEntrySize;		/**< queue entry size in words */
    IxQMgrSwQueue queue;			/**< the queue */
    IxQMgrDispatchGroup group;			/**< the group the queue belongs to*/
    IxQMgrQId nextQId;				/**< the next Q in the list for 
						   the group the Q belongs to, only 
						   set once notification is enabled */
    IxQMgrQId prevQId;				/**< the previous Q in the list */ 
    IxQMgrCallback callback;		        /**< the callback function to be 
						   used in case of notification */
    IxQMgrCallbackId callbackId;	        /**< the Id to be used when using 
						   the callback */
    IxQMgrWMLevel waterMark;		        /**< the watermark level for this queue */
    IxQMgrNotificationCondition notifCond;	/**< The condition that will 
						   trigger a notif by the dispatcher*/
    IxQMgrHeadAndTailCountFormat htCountFormat; /**<the head (write) and tail 
                                                (read) count format*/
    IxQMgrHeadAndTailAlignment htAlignment;     /**<the head (write) and tail 
                                                (read) alignment */
    IxQMgrHeadAndTailShadowing shadowing;       /**<the head (write) and tail 
                                                (read) shadowing */
    IxQMgrShadowCounter shadowInfo;             /**<the shadowing data struct */
} IxQMgrQueue;


/* for inline function include the private queue data */
#ifndef NO_INLINE_APIS
extern IxQMgrQueue ixQMgrQueues [IX_QMGR_MAX_NUM_QUEUES]; 
#endif


/*
 * Function Prototypes
 */


/* ------------------------------------------------------------
   Initialisation related functions
   ---------------------------------------------------------- */
/**
 *
 * @ingroup IxQMgrAPI
 *
 * @fn ixQMgrInit (void)
 *
 * @brief Initialise the QMgr.
 *
 * This function must be called before any other QMgr function. It
 * sets up internal data structures.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_SUCCESS, the IxQMgr successfully initialised
 * @return @li ICP_STATUS_FAIL, failed to initialize the QMgr
 *
 */
icp_status_t
ixQMgrInit (void);

/**
 *
 * @ingroup IxQMgrAPI
 *
 * @fn ixQMgrUnload (void)
 *
 * @brief Uninitialise the QMgr.
 *
 * This function will perform the tasks required to unload the QMgr component
 * cleanly.  This should be called before a soft reboot or unloading of a 
 * kernel module.
 * It is normal behaviour for this function to return a fail if it cannot be 
 * unloaded due to it being still used by another client. 
 *
 * @pre It should only be called if @ref ixQMgrInit has already been called. It 
 * will only be successful if all groups of queues that were configured have 
 * been unconfigured using the ixQMgrUnconfigGroup() function.
 * 
 *
 * @post No QMgr functions should be called until ixQMgrInit is called again.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_SUCCESS, the IxQMgr successfully uninitialised
 * @return @li ICP_STATUS_FAIL, failed to uninitialize the Qmgr
 * @return @li ICP_STATUS_RESOURCE, A configure queue operation is in progress, 
 *                             IxQMgr cannot be unloaded at this time
 *
 */
 
icp_status_t
ixQMgrUnload (void);

/**
 *
 * @ingroup IxQMgrAPI
 *
 * @fn ixQMgrShow (void)
 *
 * @brief Describe queue configuration and statistics.
 *
 * This function shows configured queues, their configurations and overall statistics.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li void
 *
 */
 void
ixQMgrShow (void);

/**
 *
 * @ingroup IxQMgrAPI
 *
 * @fn ixQMgrQShow (IxQMgrQId qId)
 *
 * @brief Display a queue configuration and current state.
 *
 * This function shows queue configuration.
 *
 * @param IxQMgrQId (in)qId - the queue identifier.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_SUCCESS, success
 * @return @li ICP_STATUS_INVALID_PARAM, queue not configured for this QId
 *
 */
icp_status_t
ixQMgrQShow (IxQMgrQId qId);


/**
 *
 * @ingroup IxQMgrAPI
 *
 * @fn ixQMgrGroupMemoryConfig (IxQMgrDispatchGroup group, void * baseAddressToFlush, void * baseAddressToInvalidate, UINT32 size)
 *
 * @brief Sets the base address and the size of the memory area that will be invalidated when the dispatch loop function will run.
 *
 * @param IxQMgrDispatchGroup (in)group - the Dispatch Group Identifier
 * @param void * (in)baseAddress - address of the start of the cached memory
 * @param UINT32 (in)size - size of cache.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_SUCCESS, success
 * @return @li ICP_STATUS_INVALID_PARAMOR, invalid parameter
 *
 */
icp_status_t
ixQMgrGroupMemoryConfig (IxQMgrDispatchGroup group, 
			 void * baseAddressToFlush,
			 void * baseAddressToInvalidate,
			 UINT32 size);


/* ------------------------------------------------------------
   Configuration related functions
   ---------------------------------------------------------- */ 
/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQConfig (char *qName,
	       IxQMgrQId *qId,
	       IxQMgrQSize qSize,
	       IxQMgrQEntrySizeInWords qEntrySize,
	       IxQMgrHeadAndTailCountFormat htCountFormat,
   	       IxQMgrHeadAndTailAlignment htAlignment,
	       IxQMgrDispatchGroup group,
	       IxQMgrHeadAndTailShadowing shadowing,
	       void *qBaseAddress,
	       void *qHeadCountPtr,
	       void *qTailCountPtr)
 *
 * @brief Configure a Software queue.
 *
 * This function is called by a client to setup a queue, the queue stores 
 * entries in memory, each entry will be of size qEntrySize words. All parameters
 * 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 characters or less.
 * The Queue Manager component allocates a QId on configuration and returns
 * it to the client. Both Head and Tail Counter are 16bits, the queue manager component
 * will only support these counters in Big Endian mode, there will be no support 
 * for Little Endian.
 *
 * @param char(in) *qName - is the name provided by the client and is associated
 *                          with a QId by the QMgr.
 * @param IxQMgrQId(out)  *qId - the returned qId of this queue
 * @param IxQMgrQSize(in) qSize - the 2^n number of entries of the queue. 
 * @param IxQMgrQEntrySizeInWords(in) qEntrySize - the 2^n size of the queue entry 
 * can be up to 8 words (i.e. must be 1,2,4 or 8 words in size).
 * @param IxQMgrHeadAndTailCountFormat(in) htCountFormat - the format that Head 
 * and Tail counters will use. Either count by bytes or count by entries.
 * @param IxQMgrHeadAndTailAlignment(in) htAlignment - the alignment of the Head 
 * and Tail Counters. Either Word or byte aligned.
 * @param IxQMgrDispatchGroup(in) group - the group this queue belongs to. this 
 * will be used by the dispatcher to determine which queues to service.
 * @param IxQMgrHeadAndTailShadowing(in) shadowing - the counters that should be 
 * shadowed 
 * @param void*(in) qBaseAddress - The address of the area of memory to use for the 
 * Queue entries, the client allocates the memory, it will need to 
 * allocate "qSize" words of data.
 * @param void* (in)qHeadCountPtr - the pointer to the area of memory for the 
 * Head Counter, the client should allocate a single word, its location 
 * must be word-aligned.
 * @param void* (in)qTailCountPtr - the pointer to the area of memory for 
 * the Tail Counter, the client should allocate a single word, its location
 * must be word aligned.
 * 
 * @Note The total size of a queue (number of entries * size of each entry) 
 * can be up to 32768 words.
 *
 * @Note the head and tail counters are 16 bits in size (lower part of a word),
 *  however the QMgr is NOT designed to be able to handle non-word aligned pointers
 *
 * @Note the head and tail counters will be stored in big endian format
 *
 * - Reentrant    - yes
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_SUCCESS, a specified queue has been successfully configured.
 * @return @li ICP_STATUS_FAIL, component not initialised.
 * @return @li ICP_RESOURCE_ERR, all available queues are already configured, a 
 *         different queue configure operation is in progress - please retry.,
 * @return @li ICP_STATUS_INVALID_PARAM, invalid queue size
 * @return @li ICP_STATUS_INVALID_PARAM invalid queue entry size
 * @return @li ICP_STATUS_INVALID_PARAM, queue already configured
 * @return @li ICP_STATUS_INVALID_PARAM, Base Address is invalid
 * @return @li ICP_STATUS_INVALID_PARAM, Counter Ptr is invalid
 *
 */
icp_status_t
ixQMgrQConfig (char *qName,
	       IxQMgrQId *qId,
	       IxQMgrQSize qSize,
	       IxQMgrQEntrySizeInWords qEntrySize,
	       IxQMgrHeadAndTailCountFormat htCountFormat,
   	       IxQMgrHeadAndTailAlignment htAlignment,
	       IxQMgrDispatchGroup group,
	       IxQMgrHeadAndTailShadowing shadowing,
	       void *qBaseAddress,
	       void *qHeadCountPtr,
	       void *qTailCountPtr);
	       
/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQSizeReconfig (IxQMgrQId qId,
			IxQMgrQSize qSize)

 *
 * @brief Reconfigures the max number of entries in a Software queue. 
 *
 *
 * This function is called by the client in order to resize the max number of 
 * entries in an existing queue. 
 * 
 * Preconditions to successfully calling this function are as follows:
 * 1. The QMgr must be initialised 
 * 2. The queue must have been successfully configured using ixQMgrQConfig()
 * 3. The queue must be empty
 * 4. The queue must have it's Notifications disabled. (default)
 * 5. The memory pool allocated by the client for ixQMgrQConfig should be big 
 *    enough to accomodate the new number of entries. 
 * 
 * Conditions 1-4 are checked and the function will return with an
 * appropriate error code should any of conditions not be met.
 * Condition 5 is not checked. It is the clients responsiblity to ensurse the 
 * buffer it allcoated for this queue that was passed as an argument to 
 * ixQMgrQConfig() is of sufficient size for this queue.
 *
 * The qSize will be checked against the selected Head and Tail alignment and 
 * counting format (entries or bytes). It will return an error if it is possible 
 * that the qSize could be greater than the Head and Tail can count. 
 *
 * Postconditions to successfully calling this function are as follows: 
 * 1. The queue will have a max number of entries as specified by qSize. 
 * 2. The Head and Tail pointers for the queue will be reset.
 * 3. The watermark for the queue will be reset.
 * 4. Any registered queue callbacks and callbackId's will be unchanged.
 *
 *
 * @param IxQMgrQId(in)  qId - the qId 
 * @param IxQMgrQSize(in) qSize - the new amount of entries in the queue. 
 * qSize must = 2^n, where n is a positive integer. 
 * 
 * @Note The total size of a queue (number of entries * size of each entry) 
 * can be up to 32768 words.
 *
 * @Note The queue entry size cannot be reconfigured using this function 
 *
 * - Reentrant    - yes
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_SUCCESS, a specified queue has been successfully configured.
 * @return @li ICP_STATUS_FAIL, component not initialised.
 * @return @li ICP_STATUS_INVALID_PARAM , invalid queue, invalid queue size
 * @return @li ICP_STATUS_RESOURCE, Q is not empty, Q Notifications are not disabled
 *
 */
icp_status_t
ixQMgrQSizeReconfig (IxQMgrQId qId,
		     IxQMgrQSize qSize);




/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrUnconfigGroup (IxQMgrDispatchGroup group)
 *
 * @brief Unconfigures the queues in a group
 *
 * This function is called by the client in order to unconfigure a group of 
 * queues. It should be called when a group of queues are no longer needed by 
 * the client. 
 * 
 * Preconditions to successfully calling this function are as follows:
 * 1. The QMgr must be initialised 
 * 
 * It is not explicitly checked but this function is only useful if the there
 * are queues configured in the group that is being unconfigured. 
 *
 * Postconditions to successfully calling this function are as follows: 
 * 1. All queues that had their group set to the parameter will be completely
 *    reset. Reseting means that the all counters will be cleared and the QMgr 
 *    will remove it's association with queue buffer. The qId of each queue will 
 *    be available for reuse through the ixQMgrQConfig function. 
 *
 * @param IxQMgrDispatchGroup(in)  group - the queue group 
 * 
 * @Note This function should be called before calling ixQMgrUnload
 *
 * @Note Memory allocation/freeing is the clients responsiblity. 
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_SUCCESS, the group has been unconfigured
 * @return @li ICP_STATUS_FAIL, component not initialised.
 * @return @li ICP_STATUS_INVALID_PARAM , invalid group
 *
 */
 icp_status_t
ixQMgrUnconfigGroup(IxQMgrDispatchGroup group);



/**
 * 
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQSizeGet (IxQMgrQId qId,
		IxQMgrQSize *qSize)
 *
 * @brief Return the size of a queue.
 *
 * This function returns the the size of the queue in entries.
 *
 * @param IxQMgrQId(in) qId - the queue identifier
 * @param IxQMgrQSize(out) *qSize - queue size in entries
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_SUCCESS, successfully retrieved the size
 * @return @li ICP_STATUS_INVALID_PARAM, invalid queue id
 * @return @li ICP_STATUS_INVALID_PARAM, queue not configured for this QId
 * @return @li ICP_STATUS_INVALID_PARAM, invalid parameter(s).
 *
 */
 icp_status_t
ixQMgrQSizeGet (IxQMgrQId qId,
		IxQMgrQSize *qSize);




/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrWatermarkSet (IxQMgrQId qId,
		    IxQMgrWMLevel waterM)
 *
 * @brief Set the Watermark of a queue.
 *
 * This function is called by a client to set the watermark 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.
 *
 * @param IxQMgrQId(in) qId -  the QId of the queue.
 * @param IxQMgrWMLevel(in) waterM  - range (1..qSize-1) the watermark for this queue.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_SUCCESS, watermark have been set for the queue
 * @return @li ICP_STATUS_INVALID_PARAM, invalid queue id
 * @return @li ICP_STATUS_INVALID_PARAM, queue not configured for this QId
 * @return @li ICP_STATUS_INVALID_PARAM, invalid watermark
 *
 */
 icp_status_t
ixQMgrWatermarkSet (IxQMgrQId qId,
		    IxQMgrWMLevel waterM);


/* ------------------------------------------------------------
   Queue access related functions
   ---------------------------------------------------------- */

/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQReadWithChecks (IxQMgrQId qId,
                       IxQMgrQEntryType *entryPtr)
 *
 * @brief Read an entry from a queue.
 *
 * This function reads an entire entry from a queue returning it in *entryPtr. 
 *
 *
 * @param  IxQMgrQId(in)  qId   - the queue identifier.
 * @param  IxQMgrQEntryType(out) *entryPtr - array to copy the entry word(s) into.
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @return @li ICP_STATUS_SUCCESS, entry was successfully read.
 * @return @li ICP_STATUS_INVALID_PARAM, invalid paramter(s).
 * @return @li ICP_STATUS_INVALID_PARAM, queue not configured for this QId
 * @return @li ICP_STATUS_UNDERFLOW, attempt to read from an empty queue
 *
 */
icp_status_t
ixQMgrQReadWithChecks (IxQMgrQId qId,
                       IxQMgrQEntryType *entryPtr);


/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQRead (IxQMgrQId qId,
	     IxQMgrQEntryType *entryPtr)
 *
 * @brief Fast read of an entry from a queue.
 *
 * This function is a heavily streamlined version of ixQMgrQReadWithChecks(),
 * This function reads an entire entry from a queue returning it in *entryPtr. 
 * 
 *
 * @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 checks for underflow and reads an entry from the queue.
 *
 *
 * @param  IxQMgrQId(in)  qId - the queue identifier.
 * @param  IxQMgrQEntryType(out) *entryPtr - pointer to the entry word(s).
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @return @li ICP_STATUS_SUCCESS, entry was successfully read.
 * @return @li ICP_STATUS_UNDERFLOW, attempt to read from an empty queue
 *
 */
IX_QMGR_INLINE  icp_status_t
ixQMgrQRead (IxQMgrQId qId,
	     IxQMgrQEntryType *entryPtr)
#ifdef NO_INLINE_APIS
    ;
#else
{
    IxQMgrQueue *info = &ixQMgrQueues[qId];
           
           
    if (info->htCountFormat == IX_QMGR_Q_COUNT_BYTES)
    {    
        /* 
         * Currently the only layer using this type of queue will have 
         * invalidate and flush done in the dispatcher 
         */  
                      
        if (IX_SWQ_WA_CB_QUEUE_EMPTY(info->queue))
        {
    	    return ICP_STATUS_UNDERFLOW;
        }
        IX_SWQ_WA_CB_ENTRY_DEQUEUE(info->queue, entryPtr);
        

    }  
    else  
    {  

          
        if(info->htAlignment == IX_QMGR_Q_ALIGN_WORD) 
        {  
            IX_SWQ_WA_HEAD_INVALIDATE(info->queue);   
                                      
            if (IX_SWQ_WA_CE_QUEUE_EMPTY(info->queue))
            {
        	    return ICP_STATUS_UNDERFLOW;
            }
            IX_SWQ_WA_CE_ENTRY_DEQUEUE(info->queue, entryPtr);
            
            IX_SWQ_WA_TAIL_FLUSH(info->queue);
        }  
        else  
        {  
            IX_SWQ_BA_HEAD_INVALIDATE(info->queue);   
                          
            if (IX_SWQ_BA_CE_QUEUE_EMPTY(info->queue))
            {
        	    return ICP_STATUS_UNDERFLOW;
            }
            IX_SWQ_BA_CE_ENTRY_DEQUEUE(info->queue, entryPtr);
            
            IX_SWQ_BA_TAIL_FLUSH(info->queue);            
        }  
        

    }  


    return ICP_STATUS_SUCCESS;
}
#endif




/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQBurstRead (IxQMgrQId qId,
		  UINT32 numEntries,
		  IxQMgrQEntryType *entriesPtr)
 *
 * @brief Read a number of entries from a software queue.
 *
 * This function will burst read a number of entries from the specified queue.
 * The function will attempt to read as many entries as specified by the 
 * numEntries parameter and will return an UNDERFLOW if the sufficient number 
 * of entries is not in the queue at the start of the function.
 * This function reads a number of entries from a queue returning them in entriesPtr.
 *
 * @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 apart from underflow, 
 * or update any statistics.
 * - It does not check that the queue specified by qId has been configured.
 * - It will only check there are enough entries to fulfill the clients request
 *
 * @param IxQMgrQId(in) qId   - the queue identifier.
 * @param UINT32(in) numEntries - the number of entries to read. 
 *                     This number should be greater than 0
 * @param IxQMgrQEntryType(out) *entriesPtr - array with the entries read.
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @return @li ICP_STATUS_SUCCESS, entries were successfully read.
 * @return @li ICP_STATUS_UNDERFLOW, the component will check before read any 
 * entries that there are enough entries in teh queue to satisfy the burst read.
 *
 */
IX_QMGR_INLINE  icp_status_t
ixQMgrQBurstRead (IxQMgrQId qId,
		  UINT32 numEntries,
		  IxQMgrQEntryType *entriesPtr)
#ifdef NO_INLINE_APIS
;
#else
{
    IxQMgrQueue *info = &ixQMgrQueues[qId];
    VUINT32 *qEntry = NULL;
#ifndef NDEBUG
    UINT32 qEntries = 0;
#endif
	UINT32 xfrSizeWords = 0;
	VUINT32 *lastEntry = NULL;
	
    
    if (info->htCountFormat == IX_QMGR_Q_COUNT_BYTES)
    {
        /* 
         * This code is specific to queues which Head and Tails are 
         *  word aligned and count in bytes 
         */                                   
        qEntry = &IX_SWQ_WA_CB_TAIL_ENTRY_GET((info->queue));
    
#ifndef NDEBUG
        IX_SWQ_WA_CB_NUM_ENTRIES_GET(info->queue, qEntries);
        if (numEntries > qEntries)
        {
    	    return ICP_STATUS_UNDERFLOW;
        }
#endif

        /* preload the first cache line */
        IX_OSAL_CACHE_PRELOAD((void *)qEntry, 0);
        
        /* Compare head and tail, if head is greater than tail then there is 
           no wrap around and the all entries to be read are situated in the 
           same block of memory that can be read in one go. if head is not 
           greater than tail then the head counter has wrapped around and the 
           entries will have to be read one at a time as they are not situated 
           in consecutives addresses in memory.*/
        if ( IX_SWQ_WA_CB_HEAD(info->queue) > IX_SWQ_WA_CB_TAIL(info->queue) ) 
        {
        	xfrSizeWords = numEntries * info->qEntrySize;
        	lastEntry = qEntry + xfrSizeWords;
        
        	/* preload */
        	IX_OSAL_CACHE_PRELOAD(qEntry, xfrSizeWords << IX_SWQ_BYTES_POW_IN_WORD);
        
        	/* memcpy */
        	while( lastEntry != qEntry )
        	{
        	    *entriesPtr++ = *qEntry++;
        	}
        
        	/* invalidate the queue memory just being read */
        	IX_SWQ_WA_CB_TAIL_INVALIDATE_AFTER_DEQUEUE(info->queue, numEntries);
        	/* move the queue counter */
        	IX_SWQ_WA_CB_TAIL_ADVANCE(info->queue, numEntries);
        }
        else
        {
        	while(numEntries > 0)
        	{     
                numEntries--;
        	    IX_SWQ_WA_CB_ENTRY_DEQUEUE(info->queue, entriesPtr);
        	    entriesPtr = entriesPtr + (info->qEntrySize);
        	}
        }                            
    }
    else
    {
        if(info->htAlignment == IX_QMGR_Q_ALIGN_WORD) 
        {
            IX_SWQ_WA_HEAD_INVALIDATE(info->queue);                               
            /* 
             * This code is specific to queues which Head and Tails are 
             *  word aligned and count in entries 
             */                                   
             qEntry = &IX_SWQ_WA_CE_TAIL_ENTRY_GET((info->queue));
        
#ifndef NDEBUG
            IX_SWQ_WA_CE_NUM_ENTRIES_GET(info->queue, qEntries);
            if (numEntries > qEntries)
            {
        	return ICP_STATUS_UNDERFLOW;
            }
#endif
        
            /* preload the first cache line */
            IX_OSAL_CACHE_PRELOAD((void *)qEntry, 0);
            
            /* Compare head and tail, if head is greater than tail then there 
               is no wrap around and the all entries to be read are situated 
               in the same block of memory that can be read in one go. if head 
               is not greater than tail then the head counter has wrapped around
               and the entries will have to be read one at a time as they are 
               not situated in consecutives addresses in memory.*/
            if (IX_SWQ_WA_CE_HEAD(info->queue) > IX_SWQ_WA_CE_TAIL(info->queue)) 
            {
            	xfrSizeWords = numEntries * info->qEntrySize;
            	lastEntry = qEntry + xfrSizeWords;
            
            	/* preload */
            	IX_OSAL_CACHE_PRELOAD(qEntry, xfrSizeWords << IX_SWQ_BYTES_POW_IN_WORD);
            
            	/* memcpy */
            	while( lastEntry != qEntry )
            	{
            	    *entriesPtr++ = *qEntry++;
            	}
            
            	/* invalidate the queue memory just being read */
            	IX_SWQ_WA_CE_TAIL_INVALIDATE_AFTER_DEQUEUE(info->queue, numEntries);
            	/* move the queue counter */
            	IX_SWQ_WA_CE_TAIL_ADVANCE(info->queue, numEntries);
            }
            else
            {
            	while(numEntries > 0)
            	{     
                    numEntries--;
            	    IX_SWQ_WA_CE_ENTRY_DEQUEUE(info->queue, entriesPtr);
            	    entriesPtr = entriesPtr + (info->qEntrySize);
            	}
            }     
            IX_SWQ_WA_TAIL_FLUSH(info->queue);                           
        }
        else
        {
            IX_SWQ_BA_HEAD_INVALIDATE(info->queue);              
            /* 
             * This code is specific to queues which Head and Tails are 
             *  byte aligned and count in entries 
             */                                   
            qEntry = &IX_SWQ_BA_CE_TAIL_ENTRY_GET((info->queue));
        
#ifndef NDEBUG
            IX_SWQ_BA_CE_NUM_ENTRIES_GET(info->queue, qEntries);
            if (numEntries > qEntries)
            {
        	   return ICP_STATUS_UNDERFLOW;
            }
#endif
        
            /* preload the first cache line */
            IX_OSAL_CACHE_PRELOAD((void *)qEntry, 0);
            
            /* Compare head and tail, if head is greater than tail then there 
               is no wrap around and the all entries to be read are situated 
               in the same block of memory that can be read in one go. if head 
               is not greater than tail then the head counter has wrapped around
               and the entries will have to be read one at a time as they are 
               not situated in consecutives addresses in memory.*/
            if (IX_SWQ_BA_CE_HEAD(info->queue) > IX_SWQ_BA_CE_TAIL(info->queue)) 
            {
            	xfrSizeWords = numEntries * info->qEntrySize;
            	lastEntry = qEntry + xfrSizeWords;
            
            	/* preload */
            	IX_OSAL_CACHE_PRELOAD(qEntry, xfrSizeWords << IX_SWQ_BYTES_POW_IN_WORD);
            
            	/* memcpy */
            	while( lastEntry != qEntry )
            	{
            	    *entriesPtr++ = *qEntry++;
            	}
            
            	/* invalidate the queue memory just being read */
            	IX_SWQ_BA_CE_TAIL_INVALIDATE_AFTER_DEQUEUE(info->queue, numEntries);
            	/* move the queue counter */
            	IX_SWQ_BA_CE_TAIL_ADVANCE(info->queue, numEntries);
            }
            else
            {
            	while(numEntries > 0)
            	{
                    numEntries--;     
            	    IX_SWQ_BA_CE_ENTRY_DEQUEUE(info->queue, entriesPtr);
            	    entriesPtr = entriesPtr + (info->qEntrySize);
            	}
            }   
            IX_SWQ_BA_TAIL_FLUSH(info->queue);                   
        }

    }

    return ICP_STATUS_SUCCESS;
}
#endif

/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQReadAdvance (IxQMgrQId qId,
		           UINT32 numEntries)
 *
 * @brief Advance the Queue Read pointer a number of entries
 *
 * This function will advance the tail pointer of a specific Queue. In doing so
 * it will seem like numEntries entries have been read from queue. The benefits
 * of this is that the overhead of actually reading the Queue entries is avoided
 * It will return an UNDERFLOW if the sufficient number of entries is not in the 
 * queue at the start of the function.
 *
 * @note
 * This function is intended for very 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 apart from underflow, 
 * or update any statistics.
 * - It does not check that the queue specified by qId has been configured.
 * - It doesn't bother reading the Queue Entries themselves
 * - It will only check there are enough entries to fulfill the clients request
 *
 * @param IxQMgrQId(in) qId   - the queue identifier.
 * @param UINT32(in) numEntries - the number of entries to advance the tail
 * count by. This number should be greater than 0
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @return @li ICP_STATUS_SUCCESS, entries were successfully read.
 * @return @li ICP_STATUS_UNDERFLOW, the component will check before read any 
 * entries that there are enough entries in teh queue to satisfy the burst read.
 *
 */
IX_QMGR_INLINE  icp_status_t
ixQMgrQReadAdvance (IxQMgrQId qId,
		    UINT32 numEntries)
#ifdef NO_INLINE_APIS
;
#else
{
    IxQMgrQueue *info = &ixQMgrQueues[qId];
    UINT32 qEntries;


    if (info->htCountFormat == IX_QMGR_Q_COUNT_BYTES)
    {
        IX_SWQ_WA_CB_NUM_ENTRIES_GET(info->queue, qEntries);
        if (numEntries > qEntries)
        {
    	   return ICP_STATUS_UNDERFLOW;
        }
        IX_SWQ_WA_CB_TAIL_ADVANCE((info->queue), numEntries); 
    }  
    else  
    {  
        if(info->htAlignment == IX_QMGR_Q_ALIGN_WORD) 
        {  
            IX_SWQ_WA_HEAD_INVALIDATE(info->queue);    
                                         
            IX_SWQ_WA_CE_NUM_ENTRIES_GET(info->queue, qEntries);
            if (numEntries > qEntries)
            {
        	   return ICP_STATUS_UNDERFLOW;
            }
            IX_SWQ_WA_CE_TAIL_ADVANCE((info->queue), numEntries); 
            
            IX_SWQ_WA_TAIL_FLUSH(info->queue);             
        }  
        else  
        {  
            IX_SWQ_BA_HEAD_INVALIDATE(info->queue);    
                          
            IX_SWQ_BA_CE_NUM_ENTRIES_GET(info->queue, qEntries);
            if (numEntries > qEntries)
            {
        	   return ICP_STATUS_UNDERFLOW;
            }
            IX_SWQ_BA_CE_TAIL_ADVANCE((info->queue), numEntries); 
            IX_SWQ_BA_TAIL_FLUSH(info->queue);             
        }  
    }  

    return ICP_STATUS_SUCCESS;
}
#endif


/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQWriteWithChecks (IxQMgrQId qId,
			       IxQMgrQEntryType *entry)
 *
 * @brief Write an entry to a Software Queue.
 *
 * This function will write the entry to the queue specified by qId.
 *
 * @param IxQMgrQId(in) qId - the queue identifier.
 * @param IxQMgrQEntryType(in) entry - Pointer to the entry word(s) to write.
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @return @li ICP_STATUS_SUCCESS, value was successfully written.
 * @return @li ICP_STATUS_INVALID_PARAM, invalid paramter(s).
 * @return @li ICP_STATUS_INVALID_PARAM, queue not configured for this QId
 * @return @li ICP_STATUS_OVERFLOW, attempt to write to a full queue
 *
 */
icp_status_t
ixQMgrQWriteWithChecks (IxQMgrQId qId,
                        IxQMgrQEntryType *entry);


/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQWrite (IxQMgrQId qId,
                     IxQMgrQEntryType *entry)
 *
 * @brief Fast write of an entry to a queue.
 *
 * This function is a heavily streamlined version of ixQMgrQWriteWithChecks(),
 * but performs essentially the same task.  It will write the entry word(s)
 * to the queue specified by qId.
 *
 * @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. It simply writes an entry to the queue, and checks for
 * overflow.
 *
 *
 * @param  IxQMgrQId(in)  qId   - the queue identifier.
 * @param  IxQMgrQEntryType(in) *entry - array holding entry word(s) to be written
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 *
 * @return @li ICP_STATUS_SUCCESS, entry was successfully read.
 * @return @li ICP_STATUS_OVERFLOW, attempt to write to a full queue
 *
 */

IX_QMGR_INLINE icp_status_t
ixQMgrQWrite (IxQMgrQId qId,
	      IxQMgrQEntryType *entry)
#ifdef NO_INLINE_APIS
    ;
#else
{
    IxQMgrQueue *info = &ixQMgrQueues[qId];
    if (info->htCountFormat == IX_QMGR_Q_COUNT_BYTES)
    {
        if ( IX_SWQ_WA_CB_QUEUE_FULL(info->queue) )
        {
    	return ICP_STATUS_OVERFLOW;
        }
        IX_SWQ_WA_CB_ENTRY_ENQUEUE(info->queue, entry);
    }  
    else  
    {  

                  
        if(info->htAlignment == IX_QMGR_Q_ALIGN_WORD) 
        {  
            IX_SWQ_WA_TAIL_INVALIDATE(info->queue);                             
            
            if ( IX_SWQ_WA_CE_QUEUE_FULL(info->queue) )
            {
        	return ICP_STATUS_OVERFLOW;
            }
            IX_SWQ_WA_CE_ENTRY_ENQUEUE(info->queue, entry);

            IX_SWQ_WA_HEAD_FLUSH(info->queue);            
        }  
        else  
        {  
            IX_SWQ_BA_TAIL_INVALIDATE(info->queue);
                          
            if ( IX_SWQ_BA_CE_QUEUE_FULL(info->queue) )
            {
        	return ICP_STATUS_OVERFLOW;
            }
            IX_SWQ_BA_CE_ENTRY_ENQUEUE(info->queue, entry);

            IX_SWQ_BA_HEAD_FLUSH(info->queue);            
        }  
    }  

    return ICP_STATUS_SUCCESS;
}
#endif

/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQBurstWrite (IxQMgrQId qId,
		   UINT32 numEntries,
		   IxQMgrQEntryType *entriesPtr)
 *
 * @brief Write a number of entries to a Software queue.
 *
 * This function will burst write a number of entries to the specified queue.
 * The function will attempt to write as many entries as specified 
 * by the numEntries parameter and will return an OVERFLOW if 
 * there isnt sufficient space in the queue.
 *
 * @note
 * This function is intended for fast population 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 only checks that the queue has enough free space to hold the entries
 * before writing performed.Therefore, the client should ensure before calling this function
 * that there is enough free space in the queue to hold the number of entries
 * to be written.  ixQMgrQWrite() or ixQMgrQWriteWithChecks(), which only writes
 * a single queue entry per call, should be used instead if the user requires
 * checks for OVERFLOW before each entry written.
 *
 * @param IxQMgrQId(in) qId   - the queue identifier.
 * @param UINT32(in) numEntries - the number of entries to write.
 * @param IxQMgrQEntryType(in) *entriesPtr - the list of entries to write.
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @return @li ICP_STATUS_SUCCESS, value was successfully written.
 * @return @li ICP_STATUS_OVERFLOW, attempt to write to a queue with an 
 * insufficient number of free entries
 *
 */
IX_QMGR_INLINE  icp_status_t
ixQMgrQBurstWrite (IxQMgrQId qId,
		   UINT32 numEntries,
		   IxQMgrQEntryType *entriesPtr)
#ifdef NO_INLINE_APIS
;
#else
{
 
    IxQMgrQueue* info = &ixQMgrQueues[qId];
    UINT32 qEntries;

    if (info->htCountFormat == IX_QMGR_Q_COUNT_BYTES)
    {
        IX_SWQ_WA_CB_NUM_ENTRIES_GET(info->queue, qEntries);
        if (numEntries > (IX_SWQ_SIZE(info->queue) - qEntries))
        {
    	    return ICP_STATUS_OVERFLOW;
        }
        
        /* write each queue entry */
        while (numEntries)
        {
            numEntries--;
    	    IX_SWQ_WA_CB_ENTRY_ENQUEUE(info->queue, entriesPtr);
    	    entriesPtr = entriesPtr + (info->qEntrySize);
        }
    }  
    else  
    {  
        if(info->htAlignment == IX_QMGR_Q_ALIGN_WORD) 
        {  
            IX_SWQ_WA_TAIL_INVALIDATE(info->queue); 
                                         
            IX_SWQ_WA_CE_NUM_ENTRIES_GET(info->queue, qEntries);
            if (numEntries > (IX_SWQ_SIZE(info->queue) - qEntries))
            {
        	return ICP_STATUS_OVERFLOW;
            }
            
            /* write each queue entry */
            while (numEntries)
            {
                numEntries--;
        	    IX_SWQ_WA_CE_ENTRY_ENQUEUE(info->queue, entriesPtr);
        	    entriesPtr = entriesPtr + (info->qEntrySize);
            }
            /*Head flush done in IX_SWQ_WA_CE_ENTRY_ENQUEUE macro*/

        }  
        else  
        {  
            IX_SWQ_BA_TAIL_INVALIDATE(info->queue); 
                          
            IX_SWQ_BA_CE_NUM_ENTRIES_GET(info->queue, qEntries);
            if (numEntries > (IX_SWQ_SIZE(info->queue) - qEntries))
            {
        	return ICP_STATUS_OVERFLOW;
            }
            
            /* write each queue entry */
            while (numEntries)
            {
                numEntries--;
        	    IX_SWQ_BA_CE_ENTRY_ENQUEUE(info->queue, entriesPtr);
        	    entriesPtr = entriesPtr + (info->qEntrySize);
            }

            /*Head flush done in IX_SWQ_WA_CE_ENTRY_ENQUEUE macro*/
        }  
    }  

    return ICP_STATUS_SUCCESS;
}
#endif


/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQNumEntriesGetWithChecks (IxQMgrQId qId,
		      UINT32 *numEntries)
 *
 * @brief Get a snapshot of the number of entries in a queue.
 *
 * This function gets the number of entries in a queue.
 *
 * @param IxQMgrQId(in) qId - the queue idenfifier
 * @param UINT32(out) *numEntries - the number of entries in a queue
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @return @li ICP_STATUS_SUCCESS, got the number of entries for the queue
 * @return @li ICP_STATUS_INVALID_PARAM, invalid paramter(s).
 * @return @li ICP_STATUS_INVALID_PARAM, the specified qId has not been configured
 *
 */
icp_status_t
ixQMgrQNumEntriesGetWithChecks (IxQMgrQId qId,
				UINT32 *numEntries);


/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQNumEntriesGet (IxQMgrQId qId,
		      UINT32 *numEntries)
 *
 * @brief Get a snapshot of the number of entries in a queue. this 
 * is an inlined version of ixQMgrQNumEntriesGetWithChecks. it does 
 * not perform any checks on the parameters given, the client must 
 * ensure that these are correct.
 *
 * This function gets the number of entries in a queue.
 *
 * @param IxQMgrQId(in) qId - the queue idenfifier
 * @param UINT32(out) *numEntries - the number of entries in a queue
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @return @li ICP_STATUS_SUCCESS, got the number of entries for the queue
 *
 */
IX_QMGR_INLINE  icp_status_t
ixQMgrQNumEntriesGet (IxQMgrQId qId,
		      UINT32 *numEntries)
#ifdef NO_INLINE_APIS
;
#else
{
    IxQMgrQueue *info = &ixQMgrQueues[qId];
if (info->htCountFormat == IX_QMGR_Q_COUNT_BYTES)
    {
        IX_SWQ_WA_CB_NUM_ENTRIES_GET(info->queue, (*numEntries));
    }  
    else  
    {  
        if(info->htAlignment == IX_QMGR_Q_ALIGN_WORD) 
        {  
           IX_SWQ_WA_HEAD_INVALIDATE(info->queue);
           IX_SWQ_WA_TAIL_INVALIDATE(info->queue);                                                         
           IX_SWQ_WA_CE_NUM_ENTRIES_GET(info->queue, (*numEntries));
        }  
        else  
        {  
           IX_SWQ_BA_HEAD_INVALIDATE(info->queue);
           IX_SWQ_BA_TAIL_INVALIDATE(info->queue);               
           IX_SWQ_BA_CE_NUM_ENTRIES_GET(info->queue, (*numEntries));
        }  
    }  
    return ICP_STATUS_SUCCESS;
}
#endif

/**
 *
 * @ingroup IxQMgrAPI
 *
 * @fn ixQMgrQStatusGetWithChecks (IxQMgrQId qId,
                            IxQMgrQState *qState)
 *
 * @brief Get a queues status.
 *
 * This function computes the specified queues status using its head and tail counters.
 *  A queues status is defined as E,AW,BW,or F.
 *
 * @param IxQMgrQId(in) qId - the queue identifier.
 * @param IxQMgrQState(out) *qState - the status of the specified queue.
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @return @li ICP_STATUS_SUCCESS, queue status was successfully read.
 * @return @li ICP_STATUS_INVALID_PARAM, the specified qId has not been configured
 * @return @li ICP_STATUS_INVALID_PARAM, invalid paramter.
 *
 */
icp_status_t
ixQMgrQStatusGetWithChecks (IxQMgrQId qId,
                            IxQMgrQState *qState);

/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrQStatusGet (IxQMgrQId qId,
		  IxQMgrQState *qState)
 *
 * @brief Fast get of a queue's status.
 *
 * This function is a streamlined version of ixQMgrQStatusGetWithChecks(), but
 * performs essentially the same task.  It computes the specified queue's status.
 * A queues status is defined by its Head and Tail Counters. The Queue's state 
 * can be E,AW,BW,F. 
 *
 * @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.  It simply returns the specified queue's status.
 *
 * @param IxQMgrQId(in) qId - the queue identifier.
 * @param IxQMgrQState(out) *qState - the status of the specified queue.
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @return @li ICP_STATUS_SUCCESS, queue status was successfully read.
 *
 */

#ifdef NO_INLINE_APIS
icp_status_t
ixQMgrQStatusGet (IxQMgrQId qId,
		  IxQMgrQState *qState);
#else  
IX_QMGR_INLINE  icp_status_t
ixQMgrQStatusGet (IxQMgrQId qId,
		  IxQMgrQState *qState)
{
    IxQMgrQueue *info = &ixQMgrQueues[qId];
    UINT32 num_entries;

    if (info->htCountFormat == IX_QMGR_Q_COUNT_BYTES)
    {
       IX_SWQ_WA_CB_NUM_ENTRIES_GET(info->queue, num_entries);
       
    }  
    else  
    {  
        if(info->htAlignment == IX_QMGR_Q_ALIGN_WORD) 
        {  
           IX_SWQ_WA_HEAD_INVALIDATE(info->queue);
           IX_SWQ_WA_TAIL_INVALIDATE(info->queue);                               
           IX_SWQ_WA_CE_NUM_ENTRIES_GET(info->queue, num_entries);

        }  
        else  
        {  
           IX_SWQ_BA_HEAD_INVALIDATE(info->queue);
           IX_SWQ_BA_TAIL_INVALIDATE(info->queue);                
           IX_SWQ_BA_CE_NUM_ENTRIES_GET(info->queue, num_entries);       
        }  
    }  

    /* Calculate number of enqueued entries */
    /* Compare to E,F and W to get status */
    if (num_entries == info->qSize)
    {
	*qState = IX_QMGR_Q_STATE_F;	
    }
    else if (num_entries == 0)
    {
	*qState = IX_QMGR_Q_STATE_E;	
    }
    else if ( num_entries < info->waterMark)
    {
	*qState = IX_QMGR_Q_STATE_BW;
    }
    else
    {
	*qState = IX_QMGR_Q_STATE_AW;
    }
    
    return ICP_STATUS_SUCCESS;
}
#endif




/* ------------------------------------------------------------
   Queue dispatch related functions
   ---------------------------------------------------------- */
/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrNotificationEnable (IxQMgrQId qId,
			  IxQMgrNotificationCondition sourceId)
 *
 * @brief Enable notification on a queue for a specified queue State.
 *
 * This function is called by a client of the QMgr to enable notifications on a
 * specified condition.
 *
 *
 * This function is re-entrant. and can be used from an interrupt context
 *
 * - Reentrant    - yes
 * - ISR Callable - yes
 *
 * @param IxQMgrQId(in) qId - the queue identifier
 * @param IxQMgrNotificationCondition(in) sourceId - the notification condition identifier
 *
 * @return @li ICP_STATUS_SUCCESS, the notification has been enabled for the specified condition
 * @return @li ICP_STATUS_INVALID_PARAM, the specified qId has not been configured
 * @return @li ICP_STATUS_INVALID_PARAM, interrupt source invalid for this queue
 *
 */
icp_status_t
ixQMgrNotificationEnable (IxQMgrQId qId,
			  IxQMgrNotificationCondition sourceId);

/**
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrNotificationDisable (IxQMgrQId qId)
 *
 * @brief Disable notifications on a queue.
 *
 * This function is called to disable notifications on a specified queue.
 *
 * This function is re-entrant. and can be used from an interrupt context
 *
 * - Reentrant    - yes
 * - ISR Callable - yes
 *
 * @param IxQMgrQId(in) qId - the queue identifier
 *
 * @return @li ICP_STATUS_SUCCESS, the notification has been disabled
 * @return @li ICP_STATUS_INVALID_PARAM, the specified qId has not been configured
 *
 */
icp_status_t
ixQMgrNotificationDisable (IxQMgrQId qId);

/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrDispatcherLoopRun (IxQMgrDispatchGroup group)
 *
 * @brief Run the callback dispatcher, 
 * service the first queue enabled in the group first.
 *
 * The function runs the dispatcher for a group of queues.
 * Callbacks are made for conditions fulfilled on queues within
 * the group that have registered callbacks. The order in which queues are
 * serviced is fixed.
 * This  function may be called from interrupt or task context. the function 
 * could be called within the context of a polling mechanism based on a timer 
 * interrupt or could be called in the context of an ISR called in the event 
 * of a HW interrupt. However, for optimal performance the choice of context 
 * depends also on the operating system used.
 *
 * This function is not re-entrant.
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @param IxQMgrDispatchGroup(in) group - the group of queues over which the
 *                                        dispatcher will run
 *
 * @return @li void
 *
 */
void
ixQMgrDispatcherLoopRun (IxQMgrDispatchGroup group);

/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrDispatcherLoopRunReverse (IxQMgrDispatchGroup group)
 *
 * @brief Run the callback dispatcher, 
 * service the last Queue Enabled in the group first.
 *
 * The function runs the dispatcher for a group of queues.
 * Callbacks are made for conditions fulfilled on queues within
 * the group that have registered callbacks. The order in which queues are
 * serviced is fixed.
 * This  function may be called from interrupt or task context. the function 
 * could be called within the context of a polling mechanism based on a timer 
 * interrupt or could be called in the context of an ISR called in the event 
 * of a HW mailbox interrupt
 *
 * This function is not re-entrant. This function may be called from interrupt 
 * or task context.
 * However, for optimal performance the choice of context depends also on the
 * operating system used.
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @param IxQMgrDispatchGroup(in) group - the group of queues over which the
 *                                        dispatcher will run
 *
 * @return @li void
 *
 */
void
ixQMgrDispatcherLoopRunReverse (IxQMgrDispatchGroup group);



/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrNotificationCallbackSet (IxQMgrQId qId,
			       IxQMgrCallback callback,
			       IxQMgrCallbackId callbackId)
 *
 * @brief Set the notification callback for a queue.
 *
 * This function sets the callback for the specified queue. This callback will
 * be called by the dispatcher, and may be called in the context of a interrupt
 * If callback has a value of NULL the previously registered callback, if one
 * exists will be unregistered.
 *
 * It is possible to change the callback function 'on the fly' at any time, 
 * and from any context (interrupt or task) when the application needs to 
 * register a new callback function which has a different behaviour than
 * the current one. Typical scenarios include dropping received data or
 * handling transmission timeouts.
 *
 * - Reentrant    - yes
 * - ISR Callable - yes
 *
 * @param IxQMgrQId(in) qId - the queue idenfifier
 * @param IxQMgrCallback(in) callback - the callback registered for this queue
 * @param IxQMgrCallbackId(in) callbackid - the callback identifier
 *
 * @return @li ICP_STATUS_SUCCESS, the callback for the specified queue has been set
 * @return @li ICP_STATUS_INVALID_PARAM, the specified qId has not been configured
 *
 */
icp_status_t
ixQMgrNotificationCallbackSet (IxQMgrQId qId,
			       IxQMgrCallback callback,
			       IxQMgrCallbackId callbackId);

/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrShadowAdvanceWithChecks(IxQMgrQId qId, 
                                     IxQMgrHeadAndTailShadowing shadowingCounterType, 
                                     UINT32 numEntries)
 *
 * @brief Advances the shadow counter by the specifed number of entries. 
 *
 *
 * This function is called by the client in order to advance a shadow counter. 
 * At present only a shadow tail is supported. This function will only ever 
 * advance the head or tail shadow counter. Seperate call would be required to 
 * advance both. 
 * 
 * This function is a non-inline version of ixQMgrShadowAdvance.
 *
 * Preconditions to successfully calling this function are as follows:
 * 1. The QMgr must be initialised 
 * 2. The queue must have been successfully configured using ixQMgrQConfig()
 * 3. The queue must have configured to use an shadow counter config that is 
 *    equal or a superset of of shadowingCounter.
 * 4. When the queue was configured using the ixQMgrQConfig() function, it 
 * must have been configured to queue whose head and tail counters count by 
 * entries, as shadowing is only supported on these types of queues.
 * 
 * Conditions 1-4 are checked in this function. 
 * Also checked in this function are
 * 1. That numEntries is greater than 0.
 * 2. That numEntries is not greater then the max amount of entries.
 *
 * Postconditions to successfully calling this function are as follows: 
 * 1. If there is at least numEntries delta between the shadow and real counter,
 * the shadow counter will be advanced by numEntries.
 * 2. If there is less then numEntries delta between the shadow and real 
 * counters, the shadow counter will not be advanced.
 *
 *
 * @param IxQMgrQId(in)  qId - the qId 
 * @param IxQMgrHeadAndTailShadowing(in) shadowingCounterType - the counter to be   
 * advanced
 * @param UINT32(in) numEntries - the amount of entries to advance the 
 * shadow counter  
 * 
 * @Note At present tail shadowing only is supported 
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_INVALID_PARAM, the specified queue is not configured,  
 * numEntries ==0, numEntries > max amount of entries.
 * @return @li ICP_STATUS_RESOURCE, the queue does not use shadowing, the queue uses 
 * a count by bytes format for it's counters. 
 * @return @li ICP_STATUS_SUCCESS, the queue's counter has been advanced by numEntries
 * @return @li ICP_STATUS_FAIL, the ixQMgr is not initialised, or it was not possible
 * to advance shadow counter by numEntries as the delta between the shadow and 
 * real counters was less then numEntries. 
 *
 */
icp_status_t
ixQMgrShadowAdvanceWithChecks(IxQMgrQId qId, 
                              IxQMgrHeadAndTailShadowing shadowingCounterType, 
                              UINT32 numEntries);
 
 

/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrShadowAdvance(IxQMgrQId qId, 
                           IxQMgrHeadAndTailShadowing shadowingCounterType, 
                           UINT32 numEntries)
 *
 * @brief Advances the shadow counter by the specifed number of entries. 
 *
 *
 * This function is called by the client in order to advance a shadow counter. 
 *
 * 
 * Preconditions to successfully calling this function are as follows:
 * 1. The QMgr must be initialised 
 * 2. The queue must have been successfully configured using ixQMgrQConfig()
 * 3. The queue must have configured to use an shadow counter config that is 
 *    equal or a superset of shadowingCounter.
 * 4. The queue must have been configured to have its head and tail counters to 
 *    count by entries.
 * 
 * Conditions 1-4 are not checked in this function. 
 * This function is expected to be called on the data path and such it does not 
 * contain checks. A non-inline version of this function which includes checks 
 * can used by calling ixQMgrShadowAdvanceWithChecks instead.
 *
 * 
 * Postconditions to successfully calling this function are as follows: 
 * 1. If there is at least numEntries delta between the shadow and real counter,
 * the shadow counter will be advance by numEntries.
 * 2. If there is less then numEntries delta between the shadow and real 
 * counters, the shadow counter will not be advanced.
 *
 *
 * @param IxQMgrQId(in)  qId - the qId 
 * @param IxQMgrHeadAndTailShadowing(in) shadowingCounterType - the counter to be   
 * advanced
 * @param UINT32(in) numEntries - the amount of entries to advance the 
 * shadow counter  
 * 
 * @Note At present tail shadowing only is supported 
 *
 * @Note The shadowingCounterType parameter is not used in this function. It is 
 * a parameter in this function so that ixQMgrShadowAdvance() and 
 * ixQMgrShadowAdvanceWithChecks() have the same signatures.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_SUCCESS, the queue's counter has been advanced by numEntries
 * @return @li ICP_STATUS_FAIL, it was not possible to advance shadow counter by 
 * numEntries as the delta between the shadow and real counters was less then numEntries. 
 *
 */
IX_QMGR_INLINE  icp_status_t
ixQMgrShadowAdvance(IxQMgrQId qId, 
                    IxQMgrHeadAndTailShadowing shadowingCounterType, 
                    UINT32 numEntries)
#ifdef NO_INLINE_APIS
;
#else
{  
    IxQMgrQueue *info = &ixQMgrQueues[qId]; 
    UINT32 shadowRealDelta = 0;

    if (info->htAlignment == IX_QMGR_Q_ALIGN_BYTE)
    {
         /*Invalidate the real tail*/
         IX_SWQ_CACHE_INVALIDATE((info->shadowInfo.byteRealTailCounter),IX_QMGR_SIZEOF_BYTE);
         /*
          * Test the delta between the shadow tail and the real tail up until 
          * the number of entries 
          */ 
          shadowRealDelta = 
              (IX_OSAL_READ_BE_SHARED_BYTE(info->shadowInfo.byteRealTailCounter)) - 
              (IX_OSAL_READ_BE_SHARED_BYTE(&(info->shadowInfo.byteShadowTailCounter)));      
          /*
           * shadowRealDelta is an unsigned => overflow implicitly handled 
           * IX_QMGR_Q_ALIGN_BYTE means we must only use 8-bits
           */  
          if ((shadowRealDelta & IX_QMGR_MASK_8BIT) >= numEntries)
          {
             IX_SWQ_BA_CE_TAIL_ADVANCE(info->queue,numEntries);    
                        
             return ICP_STATUS_SUCCESS;                               
          }
          else
          {
              return ICP_STATUS_UNDERFLOW;    
          }                                                  
    }
    else
    {
         /*Invalidate the real tail*/
         IX_SWQ_CACHE_INVALIDATE((info->shadowInfo.wordRealTailCounter),IX_QMGR_SIZEOF_WORD);
         /*
          * Test the delta between the shadow tail and the real tail up until 
          * the number of entries 
          */ 
          shadowRealDelta = 
              (IX_OSAL_READ_BE_SHARED_LONG(info->shadowInfo.wordRealTailCounter)) - 
              (IX_OSAL_READ_BE_SHARED_LONG(&(info->shadowInfo.wordShadowTailCounter)));  

          /*
           * shadowRealDelta is an unsigned => overflow implicitly handled 
           * IX_QMGR_Q_ALIGN_WORD, but we only use 16-bits for counters
           */                     
          if ((shadowRealDelta & IX_QMGR_MASK_16BIT) >= numEntries)
          {
             IX_SWQ_WA_CE_TAIL_ADVANCE(info->queue,numEntries);          
               
             return ICP_STATUS_SUCCESS;                               
          }
          else
          {
              return ICP_STATUS_UNDERFLOW;    
          }   
    }
}    
#endif

/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrShadowDeltaGetWithChecks(IxQMgrQId qId, 
                           IxQMgrHeadAndTailShadowing shadowingCounterType, 
                           UINT32 *numEntries)
 *
 * @brief Gets the amount of entries that the shadow counter is behind the real 
 * counter 
 *
 * This function is a non-inline version of ixQMgrShadowDeltaGet.
 *
 * This function is called by the client in order to get the amount of entries 
 * that the shadow is behind the real counter 
 * 
 * Preconditions to successfully calling this function are as follows:
 * 1. The QMgr must be initialised 
 * 2. The queue must have been successfully configured using ixQMgrQConfig()
 * 3. The queue must have configured to use a shadow counter config that is 
 *    equal or a superset of of shadowingCounter.
 * 4. The queue must have been configured to have its head and tail counters to 
 *    count by entries.
 * 5. That numEntries is a valid pointer.
 * 
 * Conditions 1-4 are checked in this function. 
 * Also checked in this function are
 * 1. That numEntries is a valid pointer
 *
 * Postconditions to successfully calling this function are as follows: 
 * 1. The numEntries parameter will be set to the the amount of entires that 
 * the shadow counter trails behind the real counter. 
 *
 *
 * @param IxQMgrQId(in)  qId - the qId 
 * @param IxQMgrHeadAndTailShadowing(in) shadowingCounterType - the counter to be 
 * checked
 * @param UINT32(out) *numEntries - the amount of entries the shadow 
 * counter trails the real counter by 
 * 
 * @Note At present tail shadowing only is supported 
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_INVALID_PARAM, the queue manager is not initialised, 
 * the specified queue is not configured, numEntries ==0, numEntries > max 
 * amount of entries.
 * @return @li ICP_STATUS_RESOURCE, the queue does not use shadowing, the queue 
 * uses a count by bytes format for it's counters.  
 * @return @li ICP_STATUS_SUCCESS, numEntries has been updated with to indicate the 
 * amount of entries that the shadow counter trails the real counter by. 
 * @return @li ICP_STATUS_FAIL, the ixQMgr is not initialised. 
 *
 */
icp_status_t
ixQMgrShadowDeltaGetWithChecks(IxQMgrQId qId, 
                               IxQMgrHeadAndTailShadowing shadowingCounterType, 
                               UINT32 *numEntries);

/**
 *
 * @ingroup IxQMgrAPI
 * 
 * @fn ixQMgrShadowDeltaGet(IxQMgrQId qId, 
                           IxQMgrHeadAndTailShadowing shadowingCounterType, 
                           UINT32 *numEntries)

 *
 * @brief Gets the amount of entries that the shadow counter is behind the real 
 * counter 
 *
 *
 * This function is called by the client in order to get the amount of entries 
 * that the shadow is behind the real counter 
 * 
 * Preconditions to successfully calling this function are as follows:
 * 1. The QMgr must be initialised 
 * 2. The queue must have been successfully configured using ixQMgrQConfig()
 * 3. The queue must have configured to use a shadow counter config that is 
 *    equal or a superset of of shadowingCounter.
 * 4. The queue must have been configured to have its head and tail counters to 
 *    count by entries.
 * 
 * Conditions 1-4 are not checked in this function. 
 * This function is expected to be called on the data path and such it does not 
 * contain checks. A non-inline version of this function which includes checks 
 * can used by calling ixQMgrShadowDeltaGetWithChecks instead.
 *
 * 
 * Postconditions to successfully calling this function are as follows: 
 * 1. The numEntries parameter will be set to the the amount of entires that 
 * the shadow counter trails behind the real counter. 
 *
 *
 * @param IxQMgrQId(in)  qId - the qId 
 * @param IxQMgrHeadAndTailShadowing(in) shadowingCounterType - the counter to be 
 * checked
 * @param UINT32(out) *numEntries - the amount of entries the shadow 
 * counter trails the real counter by 
 * 
 * @Note At present tail shadowing only is supported 
 *
 * @Note The shadowingCounterType parameter is not used in this function. It is 
 * a parameter in this function so that ixQMgrShadowDeltaGet() and 
 * ixQMgrShadowDeltaGetWithChecks() have the same signatures.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_SUCCESS, this function always return this value, but it 
 * used so that the inline and non-inline versions of this function will have 
 * the same signature 
 *
 */
IX_QMGR_INLINE  icp_status_t
ixQMgrShadowDeltaGet(IxQMgrQId qId, 
                     IxQMgrHeadAndTailShadowing shadowingCounterType, 
                     UINT32 *numEntries)
#ifdef NO_INLINE_APIS
;
#else
{
    IxQMgrQueue *info = &ixQMgrQueues[qId];
    UINT32 temp =0; 

    if (info->htAlignment == IX_QMGR_Q_ALIGN_BYTE)
    {
         /*Invalidate the real tail*/
         IX_SWQ_CACHE_INVALIDATE((info->shadowInfo.byteRealTailCounter),IX_QMGR_SIZEOF_BYTE);
         
         /* Get the delta between the shadow tail and the real tail. */
         temp = 
              (IX_OSAL_READ_BE_SHARED_BYTE(info->shadowInfo.byteRealTailCounter)) - 
              (IX_OSAL_READ_BE_SHARED_BYTE(&(info->shadowInfo.byteShadowTailCounter)));  
         /*In case of overflow, this is byte aligned */     
         *numEntries = (temp & 0xFF);    
         return ICP_STATUS_SUCCESS;                                                                    
     }
     else
     {
         /*Invalidate the real tail*/
         IX_SWQ_CACHE_INVALIDATE((info->shadowInfo.wordRealTailCounter),IX_QMGR_SIZEOF_WORD);

         /* Get the delta between the shadow tail and the real tail. */
         temp = 
              (IX_OSAL_READ_BE_SHARED_LONG(info->shadowInfo.wordRealTailCounter)) - 
              (IX_OSAL_READ_BE_SHARED_LONG(&(info->shadowInfo.wordShadowTailCounter)));    
         /*In case of overflow, this is 4 byte (word) aligned, but only 16-bits are used */       
         *numEntries = (temp & 0xFFFF);
         return ICP_STATUS_SUCCESS;            
     }                                                                                                                                   
}
#endif


/**
 *
 * @ingroup IxQMgrAPI
 *
 * @fn ixQMgrQWriteRollbackWithChecks (IxQMgrQId qId,
                                       UINT32 numEntries)
 *
 * @brief Rollback the last entries written to the specified queue. 
 *
 * This function moves back the write/head counter by the specfied number of 
 * entries.
 *
 * This function is a non-inline version of ixQMgrQWriteRollback.
 * 
 * Preconditions to successfully calling this function:
 * 1. The QMgr must be initialised 
 * 2. The queue must have been successfully configured using ixQMgrQConfig()
 * 3. The queue must have configured to use an shadow counter.
 * 4. The queue must have been configured to have its head and tail counters to 
 *    count by entries.                 
 * 
 * Conditions 1-4 are checked in this function. 
 *
 * Postconditions to successfully calling this function are as follows: 
 * 1. If there is at least numEntries delta between the head counter and 
 * the shadow tail counter, the head counter will have numEntries 
 * subtracted from it. 
 * 2. If there is less then numEntries delta between the head counter and the 
 * shadow tail counter, the head counter will not be modified. 
 *
 * @param IxQMgrQId(in) qId - the queue identifier.
 * @param UINT32(in) numEntries - the number of entries that should be rolled back
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @return @li ICP_STATUS_INVALID_PARAM, the queue manager is not initialised, 
 * the specified queue is not configured, the queue does not use shadowing, 
 * numEntries ==0, numEntries > max possible amount of entries, 
 * . 
 * @return @li ICP_STATUS_SUCCESS, queue status was successfully read.
 * @return @li ICP_STATUS_RESOURCE, the queue uses a count by bytes format for it's 
 *                             counters, shadowing is not enabled on the queue, 
 * @return @li ICP_STATUS_FAIL, the number of entries to rollback would corrupt the queue
 *
 */
IX_QMGR_INLINE icp_status_t
ixQMgrQWriteRollbackWithChecks (IxQMgrQId qId,
		                        UINT32 numEntries);
		      
		      
		      
/**
 *
 * @ingroup IxQMgrAPI
 *
 * @fn ixQMgrQWriteR (IxQMgrQId qId,
                      UINT32 numEntries)
 *
 * @brief Rollback the last entries written to the specified queue. 
 *
 * This function moves back the write/head counter by the specfied number of 
 * entries.
 * 
 * Preconditions to successfully calling this function:
 * 1. The QMgr must be initialised 
 * 2. The queue must have been successfully configured using ixQMgrQConfig()
 * 3. The queue must have been configured to have its head and tail counters to 
 *    count by entries.                 
 * 
 * Conditions 1-3 are not checked in this function. 
 * This function is expected to be called on the data path and such it does not 
 * contain checks for these preconditions. A non-inline version of this function 
 * which includes checks can used by calling ixQMgrQWriteRollbackWithChecks instead.
 *
 * Postconditions to successfully calling this function are as follows: 
 * 1. If there is at least numEntries delta between the write/head counter and 
 * the shadow tail counter, the head counter will be will have numEntries 
 * subtracted from it. 
 * 2. If there is less then numEntries delta between the head counter and the 
 * shadow tail counter, the head counter will not be modified. 
 *
 * @param IxQMgrQId(in) qId - the queue identifier.
 * @param UINT32(in) numEntries - the number of entries that should be rolled back
 *
 * - Reentrant    - no
 * - ISR Callable - yes
 *
 * @return @li ICP_STATUS_SUCCESS, queue status was successfully read.
 * @return @li ICP_STATUS_FAIL, the number of entries to rollback would corrupt the queue
 *
 *
 * @Note this function checks that the rollback will not go beyond the real 
 * tail counter as to do so would corrupt the queue.
 *
 *
 */
IX_QMGR_INLINE icp_status_t
ixQMgrQWriteRollback (IxQMgrQId qId, UINT32 numEntries)
#ifdef NO_INLINE_APIS
;
#else
{
    IxQMgrQueue *info = &ixQMgrQueues[qId];     
    UINT32  entryCount = 0;

    if (info->htAlignment == IX_QMGR_Q_ALIGN_BYTE)
    {
      IX_SWQ_BA_TAIL_INVALIDATE(info->queue);
      
      /* Get the current number of entries */
      IX_SWQ_BA_CE_NUM_ENTRIES_GET(info->queue,entryCount);  
      
      if((UINT8) numEntries > (UINT8) entryCount)
        {
          /*not enough entries to rollback by numEntries*/   
          return ICP_STATUS_FAIL;               
        }
      else
        {
          /*rollback the head. set it to (present head val - numEntries)*/
          IX_SWQ_BA_CE_HEAD_SET(info->queue,(IX_SWQ_BE_SHARED_BYTE_READ(IX_SWQ_BA_CE_HEAD_PTR(info->queue))) - (UINT8) numEntries);
          
          IX_SWQ_BA_HEAD_FLUSH(info->queue);             
          return ICP_STATUS_SUCCESS;
        }
    }
    else
      {
        
         /*invalidate real tail counter*/
         IX_SWQ_WA_TAIL_INVALIDATE(info->queue);
         
         /* Get the current number of entries */
         IX_SWQ_WA_CE_NUM_ENTRIES_GET(info->queue,entryCount);

         if(numEntries > entryCount)
         {
             /*not enough entries to rollback by numEntries*/     
             return ICP_STATUS_FAIL;               
         }
         else
         {
         
             /*rollback the head. set it to (present head val - numEntries)*/
             IX_SWQ_WA_CE_HEAD_SET(info->queue,((IX_SWQ_BE_SHARED_LONG_READ(IX_SWQ_WA_CE_HEAD_PTR(info->queue))) - numEntries));
             IX_SWQ_WA_HEAD_FLUSH(info->queue);
             return ICP_STATUS_SUCCESS;
         }        
    } 
}
#endif



/* Restore IX_COMPONENT_NAME */
#undef IX_COMPONENT_NAME
#define IX_COMPONENT_NAME IX_QMGR_SAVED_COMPONENT_NAME

#endif /* IXQMGR_H */

/**
 * @} defgroup IxQMgrAPI
 */