diff options
Diffstat (limited to 'arch/arm/cpu/ixp/npe/include/IxQMgr.h')
| -rw-r--r-- | arch/arm/cpu/ixp/npe/include/IxQMgr.h | 2210 |
1 files changed, 2210 insertions, 0 deletions
diff --git a/arch/arm/cpu/ixp/npe/include/IxQMgr.h b/arch/arm/cpu/ixp/npe/include/IxQMgr.h new file mode 100644 index 0000000000..165ed96e54 --- /dev/null +++ b/arch/arm/cpu/ixp/npe/include/IxQMgr.h @@ -0,0 +1,2210 @@ +/** + * @file IxQMgr.h + * + * @date 30-Oct-2001 + * + * @brief This file contains the public API of IxQMgr component. + * + * Some functions contained in this module are inline to achieve better + * data-path performance. For this to work, the function definitions are + * contained in this header file. The "normal" use of inline functions + * is to use the inline functions in the module in which they are + * defined. In this case these inline functions are used in external + * modules and therefore the use of "inline extern". What this means + * is as follows: if a function foo is declared as "inline extern" this + * definition is only used for inlining, in no case is the function + * compiled on its own. If the compiler cannot inline the function it + * becomes an external reference. Therefore in IxQMgrQAccess.c all + * inline functions are defined without the "inline extern" specifier + * and so define the external references. In all other source files + * including this header file, these funtions are defined as "inline + * extern". + * + * + * @par + * IXP400 SW Release version 2.0 + * + * -- Copyright Notice -- + * + * @par + * Copyright 2001-2005, Intel Corporation. + * All rights reserved. + * + * @par + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. 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. + * 3. Neither the name of the 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. + * + * @par + * 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. + * + * @par + * -- End of Copyright Notice -- +*/ + +/* ------------------------------------------------------ + Doxygen group definitions + ------------------------------------------------------ */ +/** + * @defgroup IxQMgrAPI IXP400 Queue Manager (IxQMgr) API + * + * @brief The public API for the IXP400 QMgr component. + * + * IxQMgr is a low level interface to the AHB Queue Manager + * + * @{ + */ + +#ifndef IXQMGR_H +#define IXQMGR_H + +/* + * User defined include files + */ + +#include "IxOsal.h" + +/* + * Define QMgr's IoMem macros, in DC mode if in LE + * regular if in BE. (Note: For Linux LSP gold release + * may need to adjust mode. + */ +#if defined (__BIG_ENDIAN) + +#define IX_QMGR_INLINE_READ_LONG IX_OSAL_READ_LONG_BE +#define IX_QMGR_INLINE_WRITE_LONG IX_OSAL_WRITE_LONG_BE + +#else + +#define IX_QMGR_INLINE_READ_LONG IX_OSAL_READ_LONG_LE_DC +#define IX_QMGR_INLINE_WRITE_LONG IX_OSAL_WRITE_LONG_LE_DC + +#endif + +/* + * #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. +* +*/ + +#ifndef __wince + +#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 IX_OSAL_INLINE_EXTERN +# else +# define IX_QMGR_INLINE /* Empty Define */ +# endif +#endif + +#else /* ndef __wince */ + +# ifndef NO_INLINE_APIS +# define NO_INLINE_APIS +# endif +# define IX_QMGR_INLINE + +#endif + + +/** +* +* @ingroup IxQMgrAPI +* +* @def IX_QMGR_MAX_NUM_QUEUES +* +* @brief Number of queues supported by the AQM. +* +* This constant is used to indicate the number of AQM queues +* +*/ +#define IX_QMGR_MAX_NUM_QUEUES 64 + +/** +* +* @ingroup IxQMgrAPI +* +* @def IX_QMGR_MIN_QID +* +* @brief Minimum queue identifier. +* +* This constant is used to indicate the smallest queue identifier +* +*/ +#define IX_QMGR_MIN_QID IX_QMGR_QUEUE_0 + +/** +* +* @ingroup IxQMgrAPI +* +* @def IX_QMGR_MAX_QID +* +* @brief Maximum queue identifier. +* +* This constant is used to indicate the largest queue identifier +* +*/ +#define IX_QMGR_MAX_QID IX_QMGR_QUEUE_63 + +/** +* +* @ingroup IxQMgrAPI +* +* @def IX_QMGR_MIN_QUEUPP_QID +* +* @brief Minimum queue identifier for reduced functionality queues. +* +* This constant is used to indicate Minimum queue identifier for reduced +* functionality queues +* +*/ +#define IX_QMGR_MIN_QUEUPP_QID 32 + +/** +* +* @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_WARNING + * + * @brief Warning return code. + * + * Execution complete, but there is a special case to handle + * + */ +#define IX_QMGR_WARNING 2 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_PARAMETER_ERROR + * + * @brief Parameter error return code (NULL pointer etc..). + * + * parameter error out of range/invalid + * + */ +#define IX_QMGR_PARAMETER_ERROR 3 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_INVALID_Q_ENTRY_SIZE + * + * @brief Invalid entry size return code. + * + * Invalid queue entry size for a queue read/write + * + */ +#define IX_QMGR_INVALID_Q_ENTRY_SIZE 4 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_INVALID_Q_ID + * + * @brief Invalid queue identifier return code. + * + * Invalid queue id, not in range 0-63 + * + */ +#define IX_QMGR_INVALID_Q_ID 5 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_INVALID_CB_ID + * + * @brief Invalid callback identifier return code. + * + * Invalid callback id + */ +#define IX_QMGR_INVALID_CB_ID 6 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_CB_ALREADY_SET + * + * @brief Callback set error return code. + * + * The specified callback has already been for this queue + * + */ +#define IX_QMGR_CB_ALREADY_SET 7 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_NO_AVAILABLE_SRAM + * + * @brief Sram consumed return code. + * + * All AQM Sram is consumed by queue configuration + * + */ +#define IX_QMGR_NO_AVAILABLE_SRAM 8 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_INVALID_INT_SOURCE_ID + * + * @brief Invalid queue interrupt source identifier return code. + * + * Invalid queue interrupt source given for notification enable + */ +#define IX_QMGR_INVALID_INT_SOURCE_ID 9 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_INVALID_QSIZE + * + * @brief Invalid queue size error code. + * + * Invalid queue size not one of 16,32, 64, 128 + * + * + */ +#define IX_QMGR_INVALID_QSIZE 10 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_INVALID_Q_WM + * + * @brief Invalid queue watermark return code. + * + * Invalid queue watermark given for watermark set + */ +#define IX_QMGR_INVALID_Q_WM 11 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_Q_NOT_CONFIGURED + * + * @brief Queue not configured return code. + * + * Returned to the client when a function has been called on an unconfigured + * queue + * + */ +#define IX_QMGR_Q_NOT_CONFIGURED 12 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_Q_ALREADY_CONFIGURED + * + * @brief Queue already configured return code. + * + * Returned to client to indicate that a queue has already been configured + */ +#define IX_QMGR_Q_ALREADY_CONFIGURED 13 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_Q_UNDERFLOW + * + * @brief Underflow return code. + * + * Underflow on a queue read has occurred + * + */ +#define IX_QMGR_Q_UNDERFLOW 14 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_Q_OVERFLOW + * + * @brief Overflow return code. + * + * Overflow on a queue write has occurred + * + */ +#define IX_QMGR_Q_OVERFLOW 15 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_Q_INVALID_PRIORITY + * + * @brief Invalid priority return code. + * + * Invalid priority, not one of 0,1,2 + */ +#define IX_QMGR_Q_INVALID_PRIORITY 16 + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS + * + * @brief Entry index out of bounds return code. + * + * Entry index is greater than number of entries in queue. + */ +#define IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS 17 + +/** + * + * @ingroup IxQMgrAPI + * + * @def ixQMgrDispatcherLoopRun + * + * @brief Map old function name ixQMgrDispatcherLoopRun () + * to @ref ixQMgrDispatcherLoopRunA0 (). + * + */ +#define ixQMgrDispatcherLoopRun ixQMgrDispatcherLoopRunA0 + + +/** + * + * @ingroup IxQMgrAPI + * + * @def IX_QMGR_QUEUE + * + * @brief Definition of AQM queue numbers + * + */ +#define IX_QMGR_QUEUE_0 (0) /**< Queue Number 0 */ +#define IX_QMGR_QUEUE_1 (1) /**< Queue Number 1 */ +#define IX_QMGR_QUEUE_2 (2) /**< Queue Number 2 */ +#define IX_QMGR_QUEUE_3 (3) /**< Queue Number 3 */ +#define IX_QMGR_QUEUE_4 (4) /**< Queue Number 4 */ +#define IX_QMGR_QUEUE_5 (5) /**< Queue Number 5 */ +#define IX_QMGR_QUEUE_6 (6) /**< Queue Number 6 */ +#define IX_QMGR_QUEUE_7 (7) /**< Queue Number 7 */ +#define IX_QMGR_QUEUE_8 (8) /**< Queue Number 8 */ +#define IX_QMGR_QUEUE_9 (9) /**< Queue Number 9 */ +#define IX_QMGR_QUEUE_10 (10) /**< Queue Number 10 */ +#define IX_QMGR_QUEUE_11 (11) /**< Queue Number 11 */ +#define IX_QMGR_QUEUE_12 (12) /**< Queue Number 12 */ +#define IX_QMGR_QUEUE_13 (13) /**< Queue Number 13 */ +#define IX_QMGR_QUEUE_14 (14) /**< Queue Number 14 */ +#define IX_QMGR_QUEUE_15 (15) /**< Queue Number 15 */ +#define IX_QMGR_QUEUE_16 (16) /**< Queue Number 16 */ +#define IX_QMGR_QUEUE_17 (17) /**< Queue Number 17 */ +#define IX_QMGR_QUEUE_18 (18) /**< Queue Number 18 */ +#define IX_QMGR_QUEUE_19 (19) /**< Queue Number 19 */ +#define IX_QMGR_QUEUE_20 (20) /**< Queue Number 20 */ +#define IX_QMGR_QUEUE_21 (21) /**< Queue Number 21 */ +#define IX_QMGR_QUEUE_22 (22) /**< Queue Number 22 */ +#define IX_QMGR_QUEUE_23 (23) /**< Queue Number 23 */ +#define IX_QMGR_QUEUE_24 (24) /**< Queue Number 24 */ +#define IX_QMGR_QUEUE_25 (25) /**< Queue Number 25 */ +#define IX_QMGR_QUEUE_26 (26) /**< Queue Number 26 */ +#define IX_QMGR_QUEUE_27 (27) /**< Queue Number 27 */ +#define IX_QMGR_QUEUE_28 (28) /**< Queue Number 28 */ +#define IX_QMGR_QUEUE_29 (29) /**< Queue Number 29 */ +#define IX_QMGR_QUEUE_30 (30) /**< Queue Number 30 */ +#define IX_QMGR_QUEUE_31 (31) /**< Queue Number 31 */ +#define IX_QMGR_QUEUE_32 (32) /**< Queue Number 32 */ +#define IX_QMGR_QUEUE_33 (33) /**< Queue Number 33 */ +#define IX_QMGR_QUEUE_34 (34) /**< Queue Number 34 */ +#define IX_QMGR_QUEUE_35 (35) /**< Queue Number 35 */ +#define IX_QMGR_QUEUE_36 (36) /**< Queue Number 36 */ +#define IX_QMGR_QUEUE_37 (37) /**< Queue Number 37 */ +#define IX_QMGR_QUEUE_38 (38) /**< Queue Number 38 */ +#define IX_QMGR_QUEUE_39 (39) /**< Queue Number 39 */ +#define IX_QMGR_QUEUE_40 (40) /**< Queue Number 40 */ +#define IX_QMGR_QUEUE_41 (41) /**< Queue Number 41 */ +#define IX_QMGR_QUEUE_42 (42) /**< Queue Number 42 */ +#define IX_QMGR_QUEUE_43 (43) /**< Queue Number 43 */ +#define IX_QMGR_QUEUE_44 (44) /**< Queue Number 44 */ +#define IX_QMGR_QUEUE_45 (45) /**< Queue Number 45 */ +#define IX_QMGR_QUEUE_46 (46) /**< Queue Number 46 */ +#define IX_QMGR_QUEUE_47 (47) /**< Queue Number 47 */ +#define IX_QMGR_QUEUE_48 (48) /**< Queue Number 48 */ +#define IX_QMGR_QUEUE_49 (49) /**< Queue Number 49 */ +#define IX_QMGR_QUEUE_50 (50) /**< Queue Number 50 */ +#define IX_QMGR_QUEUE_51 (51) /**< Queue Number 51 */ +#define IX_QMGR_QUEUE_52 (52) /**< Queue Number 52 */ +#define IX_QMGR_QUEUE_53 (53) /**< Queue Number 53 */ +#define IX_QMGR_QUEUE_54 (54) /**< Queue Number 54 */ +#define IX_QMGR_QUEUE_55 (55) /**< Queue Number 55 */ +#define IX_QMGR_QUEUE_56 (56) /**< Queue Number 56 */ +#define IX_QMGR_QUEUE_57 (57) /**< Queue Number 57 */ +#define IX_QMGR_QUEUE_58 (58) /**< Queue Number 58 */ +#define IX_QMGR_QUEUE_59 (59) /**< Queue Number 59 */ +#define IX_QMGR_QUEUE_60 (60) /**< Queue Number 60 */ +#define IX_QMGR_QUEUE_61 (61) /**< Queue Number 61 */ +#define IX_QMGR_QUEUE_62 (62) /**< Queue Number 62 */ +#define IX_QMGR_QUEUE_63 (63) /**< Queue Number 63 */ +#define IX_QMGR_QUEUE_INVALID (64) /**< AQM Queue Number Delimiter */ + + +/* + * Typedefs + */ + +/** + * @typedef IxQMgrQId + * + * @ingroup IxQMgrAPI + * + * @brief Used in the API to identify the AQM queues. + * + */ +typedef int IxQMgrQId; + +/** + * @typedef IxQMgrQStatus + * + * @ingroup IxQMgrAPI + * + * @brief Queue status. + * + * A queues status is defined by its relative fullness or relative emptiness. + * Each of the queues 0-31 have Nearly Empty, Nearly Full, Empty, Full, + * Underflow and Overflow status flags. Queues 32-63 have just Nearly Empty and + * Full status flags. + * The flags bit positions are outlined below: + * + * OF - bit-5<br> + * UF - bit-4<br> + * F - bit-3<br> + * NF - bit-2<br> + * NE - bit-1<br> + * E - bit-0<br> + * + */ +typedef UINT32 IxQMgrQStatus; + +/** + * @enum IxQMgrQStatusMask + * + * @ingroup IxQMgrAPI + * + * @brief Queue status mask. + * + * Masks for extracting the individual status flags from the IxQMgrStatus + * word. + * + */ +typedef enum +{ + IX_QMGR_Q_STATUS_E_BIT_MASK = 0x1, + IX_QMGR_Q_STATUS_NE_BIT_MASK = 0x2, + IX_QMGR_Q_STATUS_NF_BIT_MASK = 0x4, + IX_QMGR_Q_STATUS_F_BIT_MASK = 0x8, + IX_QMGR_Q_STATUS_UF_BIT_MASK = 0x10, + IX_QMGR_Q_STATUS_OF_BIT_MASK = 0x20 +} IxQMgrQStatusMask; + +/** + * @enum IxQMgrSourceId + * + * @ingroup IxQMgrAPI + * + * @brief Queue interrupt source select. + * + * This enum defines the different source conditions on a queue that result in + * an interupt being fired by the AQM. Interrupt source is configurable for + * queues 0-31 only. The interrupt source for queues 32-63 is hardwired to the + * NE(Nearly Empty) status flag. + * + */ +typedef enum +{ + IX_QMGR_Q_SOURCE_ID_E = 0, /**< Queue Empty due to last read */ + IX_QMGR_Q_SOURCE_ID_NE, /**< Queue Nearly Empty due to last read */ + IX_QMGR_Q_SOURCE_ID_NF, /**< Queue Nearly Full due to last write */ + IX_QMGR_Q_SOURCE_ID_F, /**< Queue Full due to last write */ + IX_QMGR_Q_SOURCE_ID_NOT_E, /**< Queue Not Empty due to last write */ + IX_QMGR_Q_SOURCE_ID_NOT_NE, /**< Queue Not Nearly Empty due to last write */ + IX_QMGR_Q_SOURCE_ID_NOT_NF, /**< Queue Not Nearly Full due to last read */ + IX_QMGR_Q_SOURCE_ID_NOT_F /**< Queue Not Full due to last read */ +} IxQMgrSourceId; + +/** + * @enum IxQMgrQEntrySizeInWords + * + * @ingroup IxQMgrAPI + * + * @brief QMgr queue entry sizes. + * + * The entry size of a queue specifies the size of a queues entry in words. + * + */ +typedef enum +{ + IX_QMGR_Q_ENTRY_SIZE1 = 1, /**< 1 word entry */ + IX_QMGR_Q_ENTRY_SIZE2 = 2, /**< 2 word entry */ + IX_QMGR_Q_ENTRY_SIZE4 = 4 /**< 4 word entry */ +} IxQMgrQEntrySizeInWords; + +/** + * @enum IxQMgrQSizeInWords + * + * @ingroup IxQMgrAPI + * + * @brief QMgr queue sizes. + * + * These values define the allowed queue sizes for AQM queue. The sizes are + * specified in words. + * + */ +typedef enum +{ + IX_QMGR_Q_SIZE16 = 16, /**< 16 word buffer */ + IX_QMGR_Q_SIZE32 = 32, /**< 32 word buffer */ + IX_QMGR_Q_SIZE64 = 64, /**< 64 word buffer */ + IX_QMGR_Q_SIZE128 = 128, /**< 128 word buffer */ + IX_QMGR_Q_SIZE_INVALID = 129 /**< Insure that this is greater than largest + * queue size supported by the hardware + */ +} IxQMgrQSizeInWords; + +/** + * @enum IxQMgrWMLevel + * + * @ingroup IxQMgrAPI + * + * @brief QMgr watermark levels. + * + * These values define the valid watermark levels(in ENTRIES) for queues. Each + * queue 0-63 have configurable Nearly full and Nearly empty watermarks. For + * queues 32-63 the Nearly full watermark has NO EFFECT. + * If the Nearly full watermark is set to IX_QMGR_Q_WM_LEVEL16 this means that + * the nearly full flag will be set by the hardware when there are >= 16 empty + * entries in the specified queue. + * If the Nearly empty watermark is set to IX_QMGR_Q_WM_LEVEL16 this means that + * the Nearly empty flag will be set by the hardware when there are <= 16 full + * entries in the specified queue. + */ +typedef enum +{ + IX_QMGR_Q_WM_LEVEL0 = 0, /**< 0 entry watermark */ + IX_QMGR_Q_WM_LEVEL1 = 1, /**< 1 entry watermark */ + IX_QMGR_Q_WM_LEVEL2 = 2, /**< 2 entry watermark */ + IX_QMGR_Q_WM_LEVEL4 = 4, /**< 4 entry watermark */ + IX_QMGR_Q_WM_LEVEL8 = 8, /**< 8 entry watermark */ + IX_QMGR_Q_WM_LEVEL16 = 16, /**< 16 entry watermark */ + IX_QMGR_Q_WM_LEVEL32 = 32, /**< 32 entry watermark */ + IX_QMGR_Q_WM_LEVEL64 = 64 /**< 64 entry watermark */ +} IxQMgrWMLevel; + +/** + * @ingroup IxQMgrAPI + * + * @enum IxQMgrDispatchGroup + * + * @brief QMgr dispatch group select identifiers. + * + * This enum defines the groups over which the dispatcher will process when + * called. One of the enum values must be used as a input to + * @a ixQMgrDispatcherLoopRunA0, @a ixQMgrDispatcherLoopRunB0 + * or @a ixQMgrDispatcherLoopRunB0LLP. + * + */ +typedef enum +{ + IX_QMGR_QUELOW_GROUP = 0, /**< Queues 0-31 */ + IX_QMGR_QUEUPP_GROUP /**< Queues 32-63 */ +} IxQMgrDispatchGroup; + +/** + * @ingroup IxQMgrAPI + * + * @enum IxQMgrPriority + * + * @brief Dispatcher priority levels. + * + * This enum defines the different queue dispatch priority levels. + * The lowest priority number (0) is the highest priority level. + * + */ +typedef enum +{ + IX_QMGR_Q_PRIORITY_0 = 0, /**< Priority level 0 */ + IX_QMGR_Q_PRIORITY_1, /**< Priority level 1 */ + IX_QMGR_Q_PRIORITY_2, /**< Priority level 2 */ + IX_QMGR_Q_PRIORITY_INVALID /**< Invalid Priority level */ +} IxQMgrPriority; + +/** + * @ingroup IxQMgrAPI + * + * @enum IxQMgrType + * + * @brief Callback types as used with livelock prevention + * + * This enum defines the different callback types. + * These types are only used when Livelock prevention is enabled. + * The default is IX_QMGR_TYPE_REALTIME_OTHER. + * + */ + +typedef enum +{ + IX_QMGR_TYPE_REALTIME_OTHER = 0, /**< Real time callbacks-always allowed run*/ + IX_QMGR_TYPE_REALTIME_PERIODIC, /**< Periodic callbacks-always allowed run */ + IX_QMGR_TYPE_REALTIME_SPORADIC /**< Sporadic callbacks-only run if no + periodic callbacks are in progress */ +} IxQMgrType; + + +/** + * @ingroup IxQMgrAPI + * + * @typedef IxQMgrCallbackId + * + * @brief Uniquely identifies a callback function. + * + * A unique callback identifier associated with each callback + * registered by clients. + * + */ +typedef unsigned IxQMgrCallbackId; + +/** + * @typedef IxQMgrCallback + * + * @brief QMgr notification callback type. + * + * This defines the interface to all client callback functions. + * + * @param qId @ref IxQMgrQId [in] - the queue identifier + * @param cbId @ref IxQMgrCallbackId [in] - the callback identifier + */ +typedef void (*IxQMgrCallback)(IxQMgrQId qId, + IxQMgrCallbackId cbId); + +/** + * @ingroup IxQMgrAPI + * + * @typedef IxQMgrDispatcherFuncPtr + * + * @brief QMgr Dispatcher Loop function pointer. + * + * This defines the interface for QMgr Dispather functions. + * + * @param group @ref IxQMgrDispatchGroup [in] - the group of the + * queue of which the dispatcher will run + */ +typedef void (*IxQMgrDispatcherFuncPtr)(IxQMgrDispatchGroup group); + +/* + * Function Prototypes + */ + +/* ------------------------------------------------------------ + Initialisation related functions + ---------------------------------------------------------- */ + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrInit (void) + * + * @brief Initialise the QMgr. + * + * This function must be called before and other QMgr function. It + * sets up internal data structures. + * + * @return @li IX_SUCCESS, the IxQMgr successfully initialised + * @return @li IX_FAIL, failed to initialize the Qmgr + * + */ +PUBLIC IX_STATUS +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 includes unmapping kernel memory. + * This should be called before a soft reboot or unloading of a kernel module. + * + * @pre It should only be called if @ref ixQMgrInit has already been called. + * + * @post No QMgr functions should be called until ixQMgrInit is called again. + * + * @return @li IX_SUCCESS, the IxQMgr successfully uninitialised + * @return @li IX_FAIL, failed to uninitialize the Qmgr + * + */ +PUBLIC IX_STATUS +ixQMgrUnload (void); + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrShow (void) + * + * @brief Describe queue configuration and statistics for active queues. + * + * This function shows active queues, their configurations and statistics. + * + * @return @li void + * + */ +PUBLIC void +ixQMgrShow (void); + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrQShow (IxQMgrQId qId) + * + * @brief Display aqueue configuration and statistics for a queue. + * + * This function shows queue configuration and statistics for a queue. + * + * @param qId @ref IxQMgrQId [in] - the queue identifier. + * + * @return @li IX_SUCCESS, success + * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId + * + */ +PUBLIC IX_STATUS +ixQMgrQShow (IxQMgrQId qId); + + +/* ------------------------------------------------------------ + Configuration related functions + ---------------------------------------------------------- */ + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrQConfig (char *qName, + IxQMgrQId qId, + 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 + * counters. + */ + + /* fetch a queue entry */ + nullCheckEntry = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr); + + /* iterate the specified number of queue entries */ + while (--numEntries) + { + /* check the result of the previous read */ + if (nullCheckEntry == 0) + { + /* if we read a NULL entry, stop. We have underflowed */ + break; + } + else + { + /* write the entry */ + *entries = nullCheckEntry; + /* fetch next entry */ + nullCheckEntry = IX_QMGR_INLINE_READ_LONG(qAccRegAddr); + /* increment the write address */ + entries++; + } + } + /* write the pre-fetched entry */ + *entries = nullCheckEntry; + } + else + { + IxQMgrQEntrySizeInWords entrySizeInWords = infoPtr->qEntrySizeInWords; + /* read the specified number of queue entries */ + nullCheckEntry = 0; + while (numEntries--) + { + UINT32 i; + + for (i = 0; i < (UINT32)entrySizeInWords; i++) + { + *entries = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr + i); + nullCheckEntry |= *entries++; + } + + /* if we read a NULL entry, stop. We have underflowed */ + if (nullCheckEntry == 0) + { + break; + } + nullCheckEntry = 0; + } + } + + /* reset the current read count : next access to the read function + * will force a underflow status check + */ + infoPtr->qReadCount = 0; + + /* Check if underflow occurred on the read */ + if (nullCheckEntry == 0 && qId < IX_QMGR_MIN_QUEUPP_QID) + { + /* get the queue status */ + UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr); + + if (status & infoPtr->qUflowStatBitMask) + { + /* clear the underflow status bit if it was set */ + IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr, + status & ~infoPtr->qUflowStatBitMask); + return IX_QMGR_Q_UNDERFLOW; + } + } + + return IX_SUCCESS; +} +#endif + +/** + * @ingroup IxQMgrAPI + * + * @fn ixQMgrQPeek (IxQMgrQId qId, + unsigned int entryIndex, + UINT32 *entry) + * + * @brief Read an entry from a queue without moving the read pointer. + * + * This function inspects an entry in a queue. The entry is inspected directly + * in AQM SRAM and is not read from queue access registers. The entry is NOT removed + * from the queue and the read/write pointers are unchanged. + * N.B: The queue should not be accessed when this function is called. + * + * @param qId @ref IxQMgrQId [in] - the queue identifier. + * @param entryIndex unsigned int [in] - index of entry in queue in the range + * [0].......[current number of entries in queue]. + * @param *entry UINT32 [out] - pointer to the entry word(s). + * + * @return @li IX_SUCCESS, entry was successfully inspected. + * @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_ENTRY_INDEX_OUT_OF_BOUNDS, an entry does not exist at + * specified index. + * @return @li IX_FAIL, failed to inpected the queue entry. + */ +PUBLIC IX_STATUS +ixQMgrQPeek (IxQMgrQId qId, + unsigned int entryIndex, + UINT32 *entry); + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrQWriteWithChecks (IxQMgrQId qId, + UINT32 *entry) + * + * @brief Write an entry to an AQM queue. + * + * This function will write the entry size number of words pointed to by entry to + * the queue specified by qId. The queue configuration word is read to + * determine the entry size of queue and the corresponding number of words is + * then written to the queue. + * + * @note - IX_QMGR_Q_OVERFLOW is only returned for queues 0-31 as queues 32-63 + * do not have an overflow status maintained. + * + * @param qId @ref IxQMgrQId [in] - the queue identifier. + * @param *entry UINT32 [in] - the word(s) to write. + * + * @return @li IX_SUCCESS, value was successfully written. + * @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_OVERFLOW, attempt to write to a full queue + * + */ +PUBLIC IX_STATUS +ixQMgrQWriteWithChecks (IxQMgrQId qId, + UINT32 *entry); + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrQWrite (IxQMgrQId qId, + UINT32 *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 size number + * of words pointed to by entry 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. + * + * @note - IX_QMGR_Q_OVERFLOW is only returned for queues 0-31 as queues 32-63 + * do not have an overflow status maintained. + * + * @param qId @ref IxQMgrQId [in] - the queue identifier. + * @param *entry UINT32 [in] - pointer to the entry word(s). + * + * @return @li IX_SUCCESS, entry was successfully read. + * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue + * + */ +#ifdef NO_INLINE_APIS +PUBLIC IX_STATUS +ixQMgrQWrite (IxQMgrQId qId, + UINT32 *entry); +#else +IX_QMGR_INLINE PUBLIC IX_STATUS +ixQMgrQWrite (IxQMgrQId qId, + UINT32 *entry); +#endif /* NO_INLINE_APIS */ + +IX_QMGR_INLINE PUBLIC IX_STATUS +ixQMgrQWrite (IxQMgrQId qId, + UINT32 *entry) +#ifdef NO_INLINE_APIS + ; +#else +{ + IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId]; + UINT32 entrySize; + + /* write the entry */ + IX_QMGR_INLINE_WRITE_LONG(infoPtr->qAccRegAddr, *entry); + entrySize = infoPtr->qEntrySizeInWords; + + if (entrySize != IX_QMGR_Q_ENTRY_SIZE1) + { + /* process the remaining part of the entry */ + volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr; + while (--entrySize) + { + ++entry; + IX_QMGR_INLINE_WRITE_LONG(++qAccRegAddr, *entry); + } + entrySize = infoPtr->qEntrySizeInWords; + } + + /* overflow is available for lower queues only */ + if (qId < IX_QMGR_MIN_QUEUPP_QID) + { + UINT32 qSize = infoPtr->qSizeInEntries; + /* increment the current number of entries in the queue + * and check for overflow + */ + if (infoPtr->qWriteCount++ == qSize) + { + /* the queue may have overflow */ + UINT32 qPtrs; /* queue internal pointers */ + + /* get the queue status */ + UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr); + + /* read the status twice because the status may + * not be immediately ready after the write operation + */ + if ((status & infoPtr->qOflowStatBitMask) || + ((status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr)) + & infoPtr->qOflowStatBitMask)) + { + /* the queue is full, clear the overflow status + * bit if it was set + */ + IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr, + status & ~infoPtr->qOflowStatBitMask); + infoPtr->qWriteCount = infoPtr->qSizeInEntries; + return IX_QMGR_Q_OVERFLOW; + } + /* No overflow occured : someone is draining the queue + * and the current counter needs to be + * updated from the current number of entries in the queue + */ + + /* get q pointer snapshot */ + 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) + { + /* the queue may be full at the time of the + * snapshot. Next access will check + * the overflow status again. + */ + infoPtr->qWriteCount = qSize; + } + else + { + /* convert the number of words to a number of entries */ + if (entrySize == IX_QMGR_Q_ENTRY_SIZE1) + { + infoPtr->qWriteCount = qPtrs & (qSize - 1); + } + else + { + infoPtr->qWriteCount = (qPtrs / entrySize) & (qSize - 1); + } + } + } + } + return IX_SUCCESS; +} +#endif + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrQBurstWrite (IxQMgrQId qId, + unsigned numEntries, + UINT32 *entries) + * + * @brief Write a number of entries to an AQM queue. + * + * This function will burst write a number of entries to the specified queue. + * The entry size of queue is auto-detected. The function will attempt to + * write as many entries as specified by the numEntries parameter and will + * return an OVERFLOW if any one of the individual entry writes fail. + * + * @warning + * IX_QMGR_Q_OVERFLOW is only returned for queues 0-31 as queues 32-63 + * do not have an overflow 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 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 does not check that the queue has enough free space to hold the entries + * before writing, and only checks for overflow after all writes have been + * 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 after each entry written. + * + * @param qId @ref IxQMgrQId [in] - the queue identifier. + * @param numEntries unsigned [in] - the number of entries to write. + * @param *entries UINT32 [in] - the word(s) to write. + * + * @return @li IX_SUCCESS, value was successfully written. + * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue + * + */ +#ifdef NO_INLINE_APIS +PUBLIC IX_STATUS +ixQMgrQBurstWrite (IxQMgrQId qId, + unsigned numEntries, + UINT32 *entries); +#else +IX_QMGR_INLINE PUBLIC IX_STATUS +ixQMgrQBurstWrite (IxQMgrQId qId, + unsigned numEntries, + UINT32 *entries); +#endif /* NO_INLINE_APIS */ + +IX_QMGR_INLINE PUBLIC IX_STATUS +ixQMgrQBurstWrite (IxQMgrQId qId, + unsigned numEntries, + UINT32 *entries) +#ifdef NO_INLINE_APIS +; +#else +{ + IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId]; + UINT32 status; + + /* update the current write count */ + infoPtr->qWriteCount += numEntries; + + if (infoPtr->qEntrySizeInWords == IX_QMGR_Q_ENTRY_SIZE1) + { + volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr; + while (numEntries--) + { + IX_QMGR_INLINE_WRITE_LONG(qAccRegAddr, *entries); + entries++; + } + } + else + { + IxQMgrQEntrySizeInWords entrySizeInWords = infoPtr->qEntrySizeInWords; + UINT32 i; + + /* write each queue entry */ + while (numEntries--) + { + /* write the queueEntrySize number of words for each entry */ + for (i = 0; i < (UINT32)entrySizeInWords; i++) + { + IX_QMGR_INLINE_WRITE_LONG((infoPtr->qAccRegAddr + i), *entries); + entries++; + } + } + } + + /* check if the write count overflows */ + if (infoPtr->qWriteCount > infoPtr->qSizeInEntries) + { + /* reset the current write count */ + infoPtr->qWriteCount = infoPtr->qSizeInEntries; + } + + /* Check if overflow occurred on the write operation */ + if (qId < IX_QMGR_MIN_QUEUPP_QID) + { + /* get the queue status */ + status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr); + + /* read the status twice because the status may + * not be ready at the time of the write + */ + if ((status & infoPtr->qOflowStatBitMask) || + ((status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr)) + & infoPtr->qOflowStatBitMask)) + { + /* clear the underflow status bit if it was set */ + IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr, + status & ~infoPtr->qOflowStatBitMask); + return IX_QMGR_Q_OVERFLOW; + } + } + + return IX_SUCCESS; +} +#endif + +/** + * @ingroup IxQMgrAPI + * + * @fn ixQMgrQPoke (IxQMgrQId qId, + unsigned int entryIndex, + UINT32 *entry) + * + * @brief Write an entry to a queue without moving the write pointer. + * + * This function modifies an entry in a queue. The entry is modified directly + * in AQM SRAM and not using the queue access registers. The entry is NOT added to the + * queue and the read/write pointers are unchanged. + * N.B: The queue should not be accessed when this function is called. + * + * @param qId @ref IxQMgrQId [in] - the queue identifier. + * @param entryIndex unsigned int [in] - index of entry in queue in the range + * [0].......[current number of entries in queue]. + * @param *entry UINT32 [in] - pointer to the entry word(s). + * + * @return @li IX_SUCCESS, entry was successfully modified. + * @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_ENTRY_INDEX_OUT_OF_BOUNDS, an entry does not exist at + * specified index. + * @return @li IX_FAIL, failed to modify the queue entry. + */ +PUBLIC IX_STATUS +ixQMgrQPoke (IxQMgrQId qId, + unsigned int entryIndex, + UINT32 *entry); + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrQNumEntriesGet (IxQMgrQId qId, + unsigned *numEntries) + * + * @brief Get a snapshot of the number of entries in a queue. + * + * This function gets the number of entries in a queue. + * + * @param qId @ref IxQMgrQId [in] qId - the queue idenfifier + * @param *numEntries unsigned [out] - the number of entries in a queue + * + * @return @li IX_SUCCESS, got the number of entries for the queue + * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s). + * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured + * @return @li IX_QMGR_WARNING, could not determine num entries at this time + * + */ +PUBLIC IX_STATUS +ixQMgrQNumEntriesGet (IxQMgrQId qId, + unsigned *numEntries); + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrQStatusGetWithChecks (IxQMgrQId qId, + IxQMgrQStatus *qStatus) + * + * @brief Get a queues status. + * + * This function reads the specified queues status. A queues status is defined + * by its status flags. For queues 0-31 these flags are E,NE,NF,F. For + * queues 32-63 these flags are NE and F. + * + * @param qId @ref IxQMgrQId [in] - the queue identifier. + * @param &qStatus @ref IxQMgrQStatus [out] - the status of the specified queue. + * + * @return @li IX_SUCCESS, queue status was successfully read. + * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured + * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter. + * + */ +PUBLIC IX_STATUS +ixQMgrQStatusGetWithChecks (IxQMgrQId qId, + IxQMgrQStatus *qStatus); + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrQStatusGet (IxQMgrQId qId, + IxQMgrQStatus *qStatus) + * + * @brief Fast get of a queue's status. + * + * This function is a streamlined version of ixQMgrQStatusGetWithChecks(), but + * performs essentially the same task. It reads the specified queue's status. + * A queues status is defined by its status flags. For queues 0-31 these flags + * are E,NE,NF,F. For queues 32-63 these flags are NE and 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 reads the specified queue's status. + * + * @param qId @ref IxQMgrQId [in] - the queue identifier. + * @param *qStatus @ref IxQMgrQStatus [out] - the status of the specified queue. + * + * @return @li void. + * + */ + +#ifdef NO_INLINE_APIS +PUBLIC IX_STATUS +ixQMgrQStatusGet (IxQMgrQId qId, + IxQMgrQStatus *qStatus); +#else +extern UINT32 ixQMgrAqmIfQueLowStatRegAddr[]; +extern UINT32 ixQMgrAqmIfQueLowStatBitsOffset[]; +extern UINT32 ixQMgrAqmIfQueLowStatBitsMask; +extern UINT32 ixQMgrAqmIfQueUppStat0RegAddr; +extern UINT32 ixQMgrAqmIfQueUppStat1RegAddr; +extern UINT32 ixQMgrAqmIfQueUppStat0BitMask[]; +extern UINT32 ixQMgrAqmIfQueUppStat1BitMask[]; + +IX_QMGR_INLINE PUBLIC IX_STATUS +ixQMgrQStatusGet (IxQMgrQId qId, + IxQMgrQStatus *qStatus); +#endif /* endif NO_INLINE_APIS */ + +IX_QMGR_INLINE PUBLIC IX_STATUS +ixQMgrQStatusGet (IxQMgrQId qId, + IxQMgrQStatus *qStatus) +#ifdef NO_INLINE_APIS + ; +#else +{ + /* read the status of a queue in the range 0-31 */ + if (qId < IX_QMGR_MIN_QUEUPP_QID) + { + volatile UINT32 *lowStatRegAddr = (UINT32*)ixQMgrAqmIfQueLowStatRegAddr[qId]; + + UINT32 lowStatBitsOffset = ixQMgrAqmIfQueLowStatBitsOffset[qId]; + UINT32 lowStatBitsMask = ixQMgrAqmIfQueLowStatBitsMask; + + /* read the status register for this queue */ + *qStatus = IX_QMGR_INLINE_READ_LONG(lowStatRegAddr); + + /* mask out the status bits relevant only to this queue */ + *qStatus = (*qStatus >> lowStatBitsOffset) & lowStatBitsMask; + + } + else /* read status of a queue in the range 32-63 */ + { + + volatile UINT32 *qNearEmptyStatRegAddr = (UINT32*)ixQMgrAqmIfQueUppStat0RegAddr; + volatile UINT32 *qFullStatRegAddr = (UINT32*)ixQMgrAqmIfQueUppStat1RegAddr; + int maskIndex = qId - IX_QMGR_MIN_QUEUPP_QID; + UINT32 qNearEmptyStatBitMask = ixQMgrAqmIfQueUppStat0BitMask[maskIndex]; + UINT32 qFullStatBitMask = ixQMgrAqmIfQueUppStat1BitMask[maskIndex]; + + /* Reset the status bits */ + *qStatus = 0; + + /* Check if the queue is nearly empty */ + if (IX_QMGR_INLINE_READ_LONG(qNearEmptyStatRegAddr) & qNearEmptyStatBitMask) + { + *qStatus |= IX_QMGR_Q_STATUS_NE_BIT_MASK; + } + + /* Check if the queue is full */ + if (IX_QMGR_INLINE_READ_LONG(qFullStatRegAddr) & qFullStatBitMask) + { + *qStatus |= IX_QMGR_Q_STATUS_F_BIT_MASK; + } + } + return IX_SUCCESS; +} +#endif + +/* ------------------------------------------------------------ + Queue dispatch related functions + ---------------------------------------------------------- */ + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrDispatcherPrioritySet (IxQMgrQId qId, + IxQMgrPriority priority) + * + * @brief Set the dispatch priority of a queue. + * + * This function is called to set the dispatch priority of queue. The effect of + * this function is to add a priority change request to a queue. This queue is + * serviced by @a ixQMgrDispatcherLoopRunA0, @a ixQMgrDispatcherLoopRunB0 or + * @a ixQMgrDispatcherLoopRunB0LLP. + * + * This function is re-entrant. and can be used from an interrupt context + * + * @param qId @ref IxQMgrQId [in] - the queue identifier + * @param priority @ref IxQMgrPriority [in] - the new queue dispatch priority + * + * @return @li IX_SUCCESS, priority change request is queued + * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured + * @return @li IX_QMGR_Q_INVALID_PRIORITY, specified priority is invalid + * + */ +PUBLIC IX_STATUS +ixQMgrDispatcherPrioritySet (IxQMgrQId qId, + IxQMgrPriority priority); +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrNotificationEnable (IxQMgrQId qId, + IxQMgrSourceId sourceId) + * + * @brief Enable notification on a queue for a specified queue source flag. + * + * This function is called by a client of the QMgr to enable notifications on a + * specified condition. + * If the condition for the notification is set after the client has called this + * function but before the function has enabled the interrupt source, then the + * notification will not occur. + * For queues 32-63 the notification source is fixed to the NE(Nearly Empty) flag + * and cannot be changed so the sourceId parameter is ignored for these queues. + * The status register is read before the notofication is enabled and is read again + * after the notification has been enabled, if they differ then the warning status + * is returned. + * + * This function is re-entrant. and can be used from an interrupt context + * + * @param qId @ref IxQMgrQId [in] - the queue identifier + * @param sourceId @ref IxQMgrSourceId [in] - the interrupt src condition identifier + * + * @return @li IX_SUCCESS, the interrupt has been enabled for the specified source + * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured + * @return @li IX_QMGR_INVALID_INT_SOURCE_ID, interrupt source invalid for this queue + * @return @li IX_QMGR_WARNING, the status register may not be constistent + * + */ +PUBLIC IX_STATUS +ixQMgrNotificationEnable (IxQMgrQId qId, + IxQMgrSourceId 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 + * + * @param qId @ref IxQMgrQId [in] - the queue identifier + * + * @return @li IX_SUCCESS, the interrupt has been disabled + * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured + * + */ +PUBLIC IX_STATUS +ixQMgrNotificationDisable (IxQMgrQId qId); + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrDispatcherLoopRunA0 (IxQMgrDispatchGroup group) + * + * @brief Run the callback dispatcher. + * + * This function runs the dispatcher for a group of queues. + * Callbacks are made for interrupts that have occurred on queues within + * the group that have registered callbacks. The order in which queues are + * serviced depends on the queue priorities set by the client. + * This function may be called from interrupt or task context. + * For optimisations that were introduced in IXP42X B0 and supported IXP46X + * the @a ixQMgrDispatcherLoopRunB0, or @a ixQMgrDispatcherLoopRunB0LLP + * should be used. + * + * This function is not re-entrant. + * + * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which the + * dispatcher will run + * + * @return @li void + * + * @note 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. + * + */ +PUBLIC void +ixQMgrDispatcherLoopRunA0 (IxQMgrDispatchGroup group); + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrDispatcherLoopRunB0 (IxQMgrDispatchGroup group) + * + * @brief Run the callback dispatcher. + * + * The enhanced version of @a ixQMgrDispatcherLoopRunA0 that is optimised for + * features introduced in IXP42X B0 silicon and supported on IXP46X. + * This is the default dispatcher for IXP42X B0 and IXP46X silicon. + * The function runs the dispatcher for a group of queues. + * Callbacks are made for interrupts that have occurred on queues within + * the group that have registered callbacks. The order in which queues are + * serviced depends on the queue priorities set by the client. + * This function may be called from interrupt or task context. + * + * This function is not re-entrant. + * + * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which the + * dispatcher will run + * + * @return @li void + * + * + * @note 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. + * + */ +PUBLIC void +ixQMgrDispatcherLoopRunB0 (IxQMgrDispatchGroup group); + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrDispatcherLoopRunB0LLP (IxQMgrDispatchGroup group) + * + * @brief Run the callback dispatcher. + * + * This is a version of the optimised dispatcher for IXP42X B0 and IXP46X, + * @a ixQMgrDispatcherLoopRunB0, with added support for livelock prevention. + * This dispatcher will only be used for the IXP42X B0 or IXP46X silicon if + * feature control indicates that IX_FEATURECTRL_ORIGB0_DISPATCHER is set to + * IX_FEATURE_CTRL_SWCONFIG_DISABLED. Otherwise the @a ixQMgrDispatcherLoopRunB0 + * dispatcher will be used (Default). + * + * When this dispatcher notifies for a queue that is type + * IX_QMGR_TYPE_REALTIME_PERIODIC, notifications for queues that are set + * as type IX_QMGR_REALTIME_SPORADIC are not processed and disabled. + * This helps prevent any tasks resulting from the notification of the + * IX_QMGR_TYPE_REALTIME_PERIODIC type queue to being subject to livelock. + * The function runs the dispatcher for a group of queues. + * Callbacks are made for interrupts that have occurred on queues within + * the group that have registered callbacks. The order in which queues are + * serviced depends on their type along with the queue priorities set by the + * client. This function may be called from interrupt or task context. + * + * This function is not re-entrant. + * + * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which + * the dispatcher will run + * + * @return @li void + * + * @note 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. + * + */ +PUBLIC void +ixQMgrDispatcherLoopRunB0LLP (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. + * + * @param qId @ref IxQMgrQId [in] - the queue idenfifier + * @param callback @ref IxQMgrCallback [in] - the callback registered for this queue + * @param callbackId @ref IxQMgrCallbackId [in] - the callback identifier + * + * @return @li IX_SUCCESS, the callback for the specified queue has been set + * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured + * + */ +PUBLIC IX_STATUS +ixQMgrNotificationCallbackSet (IxQMgrQId qId, + IxQMgrCallback callback, + IxQMgrCallbackId callbackId); + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrDispatcherLoopGet (IxQMgrDispatcherFuncPtr *qDispatcherFuncPtr) + * + * @brief Get QMgr DispatcherLoopRun for respective silicon device + * + * This function gets a function pointer to ixQMgrDispatcherLoopRunA0() for IXP42X A0 + * Silicon. If the IXP42X B0 or 46X Silicon, the default is the ixQMgrDispatcherLoopRunB0() + * function, however if live lock prevention is enabled a function pointer to + * ixQMgrDispatcherLoopRunB0LLP() is given. + * + * @param *qDispatchFuncPtr @ref IxQMgrDispatcherFuncPtr [out] - + * the function pointer of QMgr Dispatcher + * + */ +PUBLIC void +ixQMgrDispatcherLoopGet (IxQMgrDispatcherFuncPtr *qDispatcherFuncPtr); + +/** + * + * @ingroup IxQMgrAPI + * + * @fn ixQMgrStickyInterruptRegEnable(void) + * + * @brief Enable AQM's sticky interrupt register behaviour only available + * on B0 Silicon. + * + * When AQM's sticky interrupt register is enabled, interrupt register bit will + * only be cleared when a '1' is written to interrupt register bit and the + * interrupting condition is satisfied, i.e.queue condition does not exist. + * + * @note This function must be called before any queue is enabled. + * Calling this function after queue is enabled will cause + * undefined results. + * + * @return none + * + */ +PUBLIC void +ixQMgrStickyInterruptRegEnable(void); + + +/** + * @ingroup IxQMgrAPI + * + * @fn ixQMgrCallbackTypeSet(IxQMgrQId qId, + IxQMgrType type) + * + * @brief Set the Callback Type of a queue. + * + * This function is only used for live lock prevention. + * This function allows the callback type of a queue to be set. The default for + * all queues is IX_QMGR_TYPE_REALTIME_OTHER. Setting the type to + * IX_QMGR_TYPE_REALTIME_SPORADIC means that this queue will have it's + * notifications disabled while there is a task associated with a + * queue of type IX_QMGR_TYPE_REALTIME_PERIODIC running. As live lock + * prevention operates on lower queues, this function should + * be called for lower queues only. + * This function is not re-entrant. + * + * @param qId @ref IxQMgrQId [in] - the queue identifier + * @param type @ref IxQMgrType [in] - the type of callback + * + * @return @li IX_SUCCESS, successfully set callback type for the queue entry + * @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 +ixQMgrCallbackTypeSet(IxQMgrQId qId, + IxQMgrType type); + +/** + * @ingroup IxQMgrAPI + * + * @fn ixQMgrCallbackTypeGet(IxQMgrQId qId, + IxQMgrType *type) + * + * @brief Get the Callback Type of a queue. + * + * This function allows the callback type of a queue to be got. As live lock + * prevention operates on lower queues, this function should + * be called for lower queues only. + * This function is re-entrant. + * + * @param qId @ref IxQMgrQId [in] - the queue identifier + * @param *type @ref IxQMgrType [out] - the type of callback + * + * @return @li IX_SUCCESS, successfully set callback type for the queue entry + * @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 +ixQMgrCallbackTypeGet(IxQMgrQId qId, + IxQMgrType *type); + +/** + * @ingroup IxQMgrAPI + * + * @fn ixQMgrPeriodicDone(void) + * + * @brief Indicate that the Periodic task is completed for LLP + * + * This function is used as part of live lock prevention. + * A periodic task is a task that results from a queue that + * is set as type IX_QMGR_TYPE_REALTIME_PERIODIC. This function + * should be called to indicate to the dispatcher that the + * the periodic task is completed. This ensures that the notifications + * for queues set as type sporadic queues are re-enabled. + * This function is re-entrant. + * + */ +PUBLIC void +ixQMgrPeriodicDone(void); + + +/** + * @ingroup IxQMgrAPI + * + * @fn ixQMgrLLPShow(int resetStats) + * + * @brief Print out the live lock prevention statistics when in debug mode. + * + * This function prints out statistics related to the livelock. These + * statistics are only collected in debug mode. + * This function is not re-entrant. + * + * @param resetStats @ref int [in] - if set the the stats are reset. + * + */ +PUBLIC void +ixQMgrLLPShow(int resetStats); + + +#endif /* IXQMGR_H */ + +/** + * @} defgroup IxQMgrAPI + */ + + |
