6 * @brief This file contains the public API of IxQMgr component.
8 * Some functions contained in this module are inline to achieve better
9 * data-path performance. For this to work, the function definitions are
10 * contained in this header file. The "normal" use of inline functions
11 * is to use the inline functions in the module in which they are
12 * defined. In this case these inline functions are used in external
13 * modules and therefore the use of "inline extern". What this means
14 * is as follows: if a function foo is declared as "inline extern" this
15 * definition is only used for inlining, in no case is the function
16 * compiled on its own. If the compiler cannot inline the function it
17 * becomes an external reference. Therefore in IxQMgrQAccess.c all
18 * inline functions are defined without the "inline extern" specifier
19 * and so define the external references. In all other source files
20 * including this header file, these funtions are defined as "inline
25 * IXP400 SW Release version 2.0
27 * -- Copyright Notice --
30 * Copyright 2001-2005, Intel Corporation.
31 * All rights reserved.
34 * SPDX-License-Identifier: BSD-3-Clause
36 * -- End of Copyright Notice --
39 /* ------------------------------------------------------
40 Doxygen group definitions
41 ------------------------------------------------------ */
43 * @defgroup IxQMgrAPI IXP400 Queue Manager (IxQMgr) API
45 * @brief The public API for the IXP400 QMgr component.
47 * IxQMgr is a low level interface to the AHB Queue Manager
56 * User defined include files
62 * Define QMgr's IoMem macros, in DC mode if in LE
63 * regular if in BE. (Note: For Linux LSP gold release
64 * may need to adjust mode.
66 #if defined (__BIG_ENDIAN)
68 #define IX_QMGR_INLINE_READ_LONG IX_OSAL_READ_LONG_BE
69 #define IX_QMGR_INLINE_WRITE_LONG IX_OSAL_WRITE_LONG_BE
73 #define IX_QMGR_INLINE_READ_LONG IX_OSAL_READ_LONG_LE_DC
74 #define IX_QMGR_INLINE_WRITE_LONG IX_OSAL_WRITE_LONG_LE_DC
88 * @brief Inline definition, for inlining of Queue Access functions on API
90 * Please read the header information in this file for more details on the
91 * use of function inlining in this component.
97 #ifdef IXQMGRQACCESS_C
98 /* If IXQMGRQACCESS_C is set then the IxQmgrQAccess.c is including this file
99 and must instantiate a concrete definition for each inlineable API function
100 whether or not that function actually gets inlined. */
101 # ifdef NO_INLINE_APIS
102 # undef NO_INLINE_APIS
104 # define IX_QMGR_INLINE /* Empty Define */
106 # ifndef NO_INLINE_APIS
107 # define IX_QMGR_INLINE IX_OSAL_INLINE_EXTERN
109 # define IX_QMGR_INLINE /* Empty Define */
113 #else /* ndef __wince */
115 # ifndef NO_INLINE_APIS
116 # define NO_INLINE_APIS
118 # define IX_QMGR_INLINE
127 * @def IX_QMGR_MAX_NUM_QUEUES
129 * @brief Number of queues supported by the AQM.
131 * This constant is used to indicate the number of AQM queues
134 #define IX_QMGR_MAX_NUM_QUEUES 64
140 * @def IX_QMGR_MIN_QID
142 * @brief Minimum queue identifier.
144 * This constant is used to indicate the smallest queue identifier
147 #define IX_QMGR_MIN_QID IX_QMGR_QUEUE_0
153 * @def IX_QMGR_MAX_QID
155 * @brief Maximum queue identifier.
157 * This constant is used to indicate the largest queue identifier
160 #define IX_QMGR_MAX_QID IX_QMGR_QUEUE_63
166 * @def IX_QMGR_MIN_QUEUPP_QID
168 * @brief Minimum queue identifier for reduced functionality queues.
170 * This constant is used to indicate Minimum queue identifier for reduced
171 * functionality queues
174 #define IX_QMGR_MIN_QUEUPP_QID 32
180 * @def IX_QMGR_MAX_QNAME_LEN
182 * @brief Maximum queue name length.
184 * This constant is used to indicate the maximum null terminated string length
185 * (excluding '\0') for a queue name
188 #define IX_QMGR_MAX_QNAME_LEN 16
194 * @def IX_QMGR_WARNING
196 * @brief Warning return code.
198 * Execution complete, but there is a special case to handle
201 #define IX_QMGR_WARNING 2
207 * @def IX_QMGR_PARAMETER_ERROR
209 * @brief Parameter error return code (NULL pointer etc..).
211 * parameter error out of range/invalid
214 #define IX_QMGR_PARAMETER_ERROR 3
220 * @def IX_QMGR_INVALID_Q_ENTRY_SIZE
222 * @brief Invalid entry size return code.
224 * Invalid queue entry size for a queue read/write
227 #define IX_QMGR_INVALID_Q_ENTRY_SIZE 4
233 * @def IX_QMGR_INVALID_Q_ID
235 * @brief Invalid queue identifier return code.
237 * Invalid queue id, not in range 0-63
240 #define IX_QMGR_INVALID_Q_ID 5
246 * @def IX_QMGR_INVALID_CB_ID
248 * @brief Invalid callback identifier return code.
250 * Invalid callback id
252 #define IX_QMGR_INVALID_CB_ID 6
258 * @def IX_QMGR_CB_ALREADY_SET
260 * @brief Callback set error return code.
262 * The specified callback has already been for this queue
265 #define IX_QMGR_CB_ALREADY_SET 7
271 * @def IX_QMGR_NO_AVAILABLE_SRAM
273 * @brief Sram consumed return code.
275 * All AQM Sram is consumed by queue configuration
278 #define IX_QMGR_NO_AVAILABLE_SRAM 8
284 * @def IX_QMGR_INVALID_INT_SOURCE_ID
286 * @brief Invalid queue interrupt source identifier return code.
288 * Invalid queue interrupt source given for notification enable
290 #define IX_QMGR_INVALID_INT_SOURCE_ID 9
296 * @def IX_QMGR_INVALID_QSIZE
298 * @brief Invalid queue size error code.
300 * Invalid queue size not one of 16,32, 64, 128
304 #define IX_QMGR_INVALID_QSIZE 10
310 * @def IX_QMGR_INVALID_Q_WM
312 * @brief Invalid queue watermark return code.
314 * Invalid queue watermark given for watermark set
316 #define IX_QMGR_INVALID_Q_WM 11
322 * @def IX_QMGR_Q_NOT_CONFIGURED
324 * @brief Queue not configured return code.
326 * Returned to the client when a function has been called on an unconfigured
330 #define IX_QMGR_Q_NOT_CONFIGURED 12
336 * @def IX_QMGR_Q_ALREADY_CONFIGURED
338 * @brief Queue already configured return code.
340 * Returned to client to indicate that a queue has already been configured
342 #define IX_QMGR_Q_ALREADY_CONFIGURED 13
348 * @def IX_QMGR_Q_UNDERFLOW
350 * @brief Underflow return code.
352 * Underflow on a queue read has occurred
355 #define IX_QMGR_Q_UNDERFLOW 14
361 * @def IX_QMGR_Q_OVERFLOW
363 * @brief Overflow return code.
365 * Overflow on a queue write has occurred
368 #define IX_QMGR_Q_OVERFLOW 15
374 * @def IX_QMGR_Q_INVALID_PRIORITY
376 * @brief Invalid priority return code.
378 * Invalid priority, not one of 0,1,2
380 #define IX_QMGR_Q_INVALID_PRIORITY 16
386 * @def IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS
388 * @brief Entry index out of bounds return code.
390 * Entry index is greater than number of entries in queue.
392 #define IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS 17
398 * @def ixQMgrDispatcherLoopRun
400 * @brief Map old function name ixQMgrDispatcherLoopRun ()
401 * to @ref ixQMgrDispatcherLoopRunA0 ().
404 #define ixQMgrDispatcherLoopRun ixQMgrDispatcherLoopRunA0
413 * @brief Definition of AQM queue numbers
416 #define IX_QMGR_QUEUE_0 (0) /**< Queue Number 0 */
417 #define IX_QMGR_QUEUE_1 (1) /**< Queue Number 1 */
418 #define IX_QMGR_QUEUE_2 (2) /**< Queue Number 2 */
419 #define IX_QMGR_QUEUE_3 (3) /**< Queue Number 3 */
420 #define IX_QMGR_QUEUE_4 (4) /**< Queue Number 4 */
421 #define IX_QMGR_QUEUE_5 (5) /**< Queue Number 5 */
422 #define IX_QMGR_QUEUE_6 (6) /**< Queue Number 6 */
423 #define IX_QMGR_QUEUE_7 (7) /**< Queue Number 7 */
424 #define IX_QMGR_QUEUE_8 (8) /**< Queue Number 8 */
425 #define IX_QMGR_QUEUE_9 (9) /**< Queue Number 9 */
426 #define IX_QMGR_QUEUE_10 (10) /**< Queue Number 10 */
427 #define IX_QMGR_QUEUE_11 (11) /**< Queue Number 11 */
428 #define IX_QMGR_QUEUE_12 (12) /**< Queue Number 12 */
429 #define IX_QMGR_QUEUE_13 (13) /**< Queue Number 13 */
430 #define IX_QMGR_QUEUE_14 (14) /**< Queue Number 14 */
431 #define IX_QMGR_QUEUE_15 (15) /**< Queue Number 15 */
432 #define IX_QMGR_QUEUE_16 (16) /**< Queue Number 16 */
433 #define IX_QMGR_QUEUE_17 (17) /**< Queue Number 17 */
434 #define IX_QMGR_QUEUE_18 (18) /**< Queue Number 18 */
435 #define IX_QMGR_QUEUE_19 (19) /**< Queue Number 19 */
436 #define IX_QMGR_QUEUE_20 (20) /**< Queue Number 20 */
437 #define IX_QMGR_QUEUE_21 (21) /**< Queue Number 21 */
438 #define IX_QMGR_QUEUE_22 (22) /**< Queue Number 22 */
439 #define IX_QMGR_QUEUE_23 (23) /**< Queue Number 23 */
440 #define IX_QMGR_QUEUE_24 (24) /**< Queue Number 24 */
441 #define IX_QMGR_QUEUE_25 (25) /**< Queue Number 25 */
442 #define IX_QMGR_QUEUE_26 (26) /**< Queue Number 26 */
443 #define IX_QMGR_QUEUE_27 (27) /**< Queue Number 27 */
444 #define IX_QMGR_QUEUE_28 (28) /**< Queue Number 28 */
445 #define IX_QMGR_QUEUE_29 (29) /**< Queue Number 29 */
446 #define IX_QMGR_QUEUE_30 (30) /**< Queue Number 30 */
447 #define IX_QMGR_QUEUE_31 (31) /**< Queue Number 31 */
448 #define IX_QMGR_QUEUE_32 (32) /**< Queue Number 32 */
449 #define IX_QMGR_QUEUE_33 (33) /**< Queue Number 33 */
450 #define IX_QMGR_QUEUE_34 (34) /**< Queue Number 34 */
451 #define IX_QMGR_QUEUE_35 (35) /**< Queue Number 35 */
452 #define IX_QMGR_QUEUE_36 (36) /**< Queue Number 36 */
453 #define IX_QMGR_QUEUE_37 (37) /**< Queue Number 37 */
454 #define IX_QMGR_QUEUE_38 (38) /**< Queue Number 38 */
455 #define IX_QMGR_QUEUE_39 (39) /**< Queue Number 39 */
456 #define IX_QMGR_QUEUE_40 (40) /**< Queue Number 40 */
457 #define IX_QMGR_QUEUE_41 (41) /**< Queue Number 41 */
458 #define IX_QMGR_QUEUE_42 (42) /**< Queue Number 42 */
459 #define IX_QMGR_QUEUE_43 (43) /**< Queue Number 43 */
460 #define IX_QMGR_QUEUE_44 (44) /**< Queue Number 44 */
461 #define IX_QMGR_QUEUE_45 (45) /**< Queue Number 45 */
462 #define IX_QMGR_QUEUE_46 (46) /**< Queue Number 46 */
463 #define IX_QMGR_QUEUE_47 (47) /**< Queue Number 47 */
464 #define IX_QMGR_QUEUE_48 (48) /**< Queue Number 48 */
465 #define IX_QMGR_QUEUE_49 (49) /**< Queue Number 49 */
466 #define IX_QMGR_QUEUE_50 (50) /**< Queue Number 50 */
467 #define IX_QMGR_QUEUE_51 (51) /**< Queue Number 51 */
468 #define IX_QMGR_QUEUE_52 (52) /**< Queue Number 52 */
469 #define IX_QMGR_QUEUE_53 (53) /**< Queue Number 53 */
470 #define IX_QMGR_QUEUE_54 (54) /**< Queue Number 54 */
471 #define IX_QMGR_QUEUE_55 (55) /**< Queue Number 55 */
472 #define IX_QMGR_QUEUE_56 (56) /**< Queue Number 56 */
473 #define IX_QMGR_QUEUE_57 (57) /**< Queue Number 57 */
474 #define IX_QMGR_QUEUE_58 (58) /**< Queue Number 58 */
475 #define IX_QMGR_QUEUE_59 (59) /**< Queue Number 59 */
476 #define IX_QMGR_QUEUE_60 (60) /**< Queue Number 60 */
477 #define IX_QMGR_QUEUE_61 (61) /**< Queue Number 61 */
478 #define IX_QMGR_QUEUE_62 (62) /**< Queue Number 62 */
479 #define IX_QMGR_QUEUE_63 (63) /**< Queue Number 63 */
480 #define IX_QMGR_QUEUE_INVALID (64) /**< AQM Queue Number Delimiter */
492 * @brief Used in the API to identify the AQM queues.
495 typedef int IxQMgrQId;
498 * @typedef IxQMgrQStatus
502 * @brief Queue status.
504 * A queues status is defined by its relative fullness or relative emptiness.
505 * Each of the queues 0-31 have Nearly Empty, Nearly Full, Empty, Full,
506 * Underflow and Overflow status flags. Queues 32-63 have just Nearly Empty and
508 * The flags bit positions are outlined below:
518 typedef UINT32 IxQMgrQStatus;
521 * @enum IxQMgrQStatusMask
525 * @brief Queue status mask.
527 * Masks for extracting the individual status flags from the IxQMgrStatus
533 IX_QMGR_Q_STATUS_E_BIT_MASK = 0x1,
534 IX_QMGR_Q_STATUS_NE_BIT_MASK = 0x2,
535 IX_QMGR_Q_STATUS_NF_BIT_MASK = 0x4,
536 IX_QMGR_Q_STATUS_F_BIT_MASK = 0x8,
537 IX_QMGR_Q_STATUS_UF_BIT_MASK = 0x10,
538 IX_QMGR_Q_STATUS_OF_BIT_MASK = 0x20
542 * @enum IxQMgrSourceId
546 * @brief Queue interrupt source select.
548 * This enum defines the different source conditions on a queue that result in
549 * an interrupt being fired by the AQM. Interrupt source is configurable for
550 * queues 0-31 only. The interrupt source for queues 32-63 is hardwired to the
551 * NE(Nearly Empty) status flag.
556 IX_QMGR_Q_SOURCE_ID_E = 0, /**< Queue Empty due to last read */
557 IX_QMGR_Q_SOURCE_ID_NE, /**< Queue Nearly Empty due to last read */
558 IX_QMGR_Q_SOURCE_ID_NF, /**< Queue Nearly Full due to last write */
559 IX_QMGR_Q_SOURCE_ID_F, /**< Queue Full due to last write */
560 IX_QMGR_Q_SOURCE_ID_NOT_E, /**< Queue Not Empty due to last write */
561 IX_QMGR_Q_SOURCE_ID_NOT_NE, /**< Queue Not Nearly Empty due to last write */
562 IX_QMGR_Q_SOURCE_ID_NOT_NF, /**< Queue Not Nearly Full due to last read */
563 IX_QMGR_Q_SOURCE_ID_NOT_F /**< Queue Not Full due to last read */
567 * @enum IxQMgrQEntrySizeInWords
571 * @brief QMgr queue entry sizes.
573 * The entry size of a queue specifies the size of a queues entry in words.
578 IX_QMGR_Q_ENTRY_SIZE1 = 1, /**< 1 word entry */
579 IX_QMGR_Q_ENTRY_SIZE2 = 2, /**< 2 word entry */
580 IX_QMGR_Q_ENTRY_SIZE4 = 4 /**< 4 word entry */
581 } IxQMgrQEntrySizeInWords;
584 * @enum IxQMgrQSizeInWords
588 * @brief QMgr queue sizes.
590 * These values define the allowed queue sizes for AQM queue. The sizes are
591 * specified in words.
596 IX_QMGR_Q_SIZE16 = 16, /**< 16 word buffer */
597 IX_QMGR_Q_SIZE32 = 32, /**< 32 word buffer */
598 IX_QMGR_Q_SIZE64 = 64, /**< 64 word buffer */
599 IX_QMGR_Q_SIZE128 = 128, /**< 128 word buffer */
600 IX_QMGR_Q_SIZE_INVALID = 129 /**< Insure that this is greater than largest
601 * queue size supported by the hardware
603 } IxQMgrQSizeInWords;
606 * @enum IxQMgrWMLevel
610 * @brief QMgr watermark levels.
612 * These values define the valid watermark levels(in ENTRIES) for queues. Each
613 * queue 0-63 have configurable Nearly full and Nearly empty watermarks. For
614 * queues 32-63 the Nearly full watermark has NO EFFECT.
615 * If the Nearly full watermark is set to IX_QMGR_Q_WM_LEVEL16 this means that
616 * the nearly full flag will be set by the hardware when there are >= 16 empty
617 * entries in the specified queue.
618 * If the Nearly empty watermark is set to IX_QMGR_Q_WM_LEVEL16 this means that
619 * the Nearly empty flag will be set by the hardware when there are <= 16 full
620 * entries in the specified queue.
624 IX_QMGR_Q_WM_LEVEL0 = 0, /**< 0 entry watermark */
625 IX_QMGR_Q_WM_LEVEL1 = 1, /**< 1 entry watermark */
626 IX_QMGR_Q_WM_LEVEL2 = 2, /**< 2 entry watermark */
627 IX_QMGR_Q_WM_LEVEL4 = 4, /**< 4 entry watermark */
628 IX_QMGR_Q_WM_LEVEL8 = 8, /**< 8 entry watermark */
629 IX_QMGR_Q_WM_LEVEL16 = 16, /**< 16 entry watermark */
630 IX_QMGR_Q_WM_LEVEL32 = 32, /**< 32 entry watermark */
631 IX_QMGR_Q_WM_LEVEL64 = 64 /**< 64 entry watermark */
637 * @enum IxQMgrDispatchGroup
639 * @brief QMgr dispatch group select identifiers.
641 * This enum defines the groups over which the dispatcher will process when
642 * called. One of the enum values must be used as a input to
643 * @a ixQMgrDispatcherLoopRunA0, @a ixQMgrDispatcherLoopRunB0
644 * or @a ixQMgrDispatcherLoopRunB0LLP.
649 IX_QMGR_QUELOW_GROUP = 0, /**< Queues 0-31 */
650 IX_QMGR_QUEUPP_GROUP /**< Queues 32-63 */
651 } IxQMgrDispatchGroup;
656 * @enum IxQMgrPriority
658 * @brief Dispatcher priority levels.
660 * This enum defines the different queue dispatch priority levels.
661 * The lowest priority number (0) is the highest priority level.
666 IX_QMGR_Q_PRIORITY_0 = 0, /**< Priority level 0 */
667 IX_QMGR_Q_PRIORITY_1, /**< Priority level 1 */
668 IX_QMGR_Q_PRIORITY_2, /**< Priority level 2 */
669 IX_QMGR_Q_PRIORITY_INVALID /**< Invalid Priority level */
677 * @brief Callback types as used with livelock prevention
679 * This enum defines the different callback types.
680 * These types are only used when Livelock prevention is enabled.
681 * The default is IX_QMGR_TYPE_REALTIME_OTHER.
687 IX_QMGR_TYPE_REALTIME_OTHER = 0, /**< Real time callbacks-always allowed run*/
688 IX_QMGR_TYPE_REALTIME_PERIODIC, /**< Periodic callbacks-always allowed run */
689 IX_QMGR_TYPE_REALTIME_SPORADIC /**< Sporadic callbacks-only run if no
690 periodic callbacks are in progress */
697 * @typedef IxQMgrCallbackId
699 * @brief Uniquely identifies a callback function.
701 * A unique callback identifier associated with each callback
702 * registered by clients.
705 typedef unsigned IxQMgrCallbackId;
708 * @typedef IxQMgrCallback
710 * @brief QMgr notification callback type.
712 * This defines the interface to all client callback functions.
714 * @param qId @ref IxQMgrQId [in] - the queue identifier
715 * @param cbId @ref IxQMgrCallbackId [in] - the callback identifier
717 typedef void (*IxQMgrCallback)(IxQMgrQId qId,
718 IxQMgrCallbackId cbId);
723 * @typedef IxQMgrDispatcherFuncPtr
725 * @brief QMgr Dispatcher Loop function pointer.
727 * This defines the interface for QMgr Dispather functions.
729 * @param group @ref IxQMgrDispatchGroup [in] - the group of the
730 * queue of which the dispatcher will run
732 typedef void (*IxQMgrDispatcherFuncPtr)(IxQMgrDispatchGroup group);
735 * Function Prototypes
738 /* ------------------------------------------------------------
739 Initialisation related functions
740 ---------------------------------------------------------- */
746 * @fn ixQMgrInit (void)
748 * @brief Initialise the QMgr.
750 * This function must be called before and other QMgr function. It
751 * sets up internal data structures.
753 * @return @li IX_SUCCESS, the IxQMgr successfully initialised
754 * @return @li IX_FAIL, failed to initialize the Qmgr
764 * @fn ixQMgrUnload (void)
766 * @brief Uninitialise the QMgr.
768 * This function will perform the tasks required to unload the QMgr component
769 * cleanly. This includes unmapping kernel memory.
770 * This should be called before a soft reboot or unloading of a kernel module.
772 * @pre It should only be called if @ref ixQMgrInit has already been called.
774 * @post No QMgr functions should be called until ixQMgrInit is called again.
776 * @return @li IX_SUCCESS, the IxQMgr successfully uninitialised
777 * @return @li IX_FAIL, failed to uninitialize the Qmgr
787 * @fn ixQMgrShow (void)
789 * @brief Describe queue configuration and statistics for active queues.
791 * This function shows active queues, their configurations and statistics.
803 * @fn ixQMgrQShow (IxQMgrQId qId)
805 * @brief Display aqueue configuration and statistics for a queue.
807 * This function shows queue configuration and statistics for a queue.
809 * @param qId @ref IxQMgrQId [in] - the queue identifier.
811 * @return @li IX_SUCCESS, success
812 * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
816 ixQMgrQShow (IxQMgrQId qId);
819 /* ------------------------------------------------------------
820 Configuration related functions
821 ---------------------------------------------------------- */
827 * @fn ixQMgrQConfig (char *qName,
829 IxQMgrQSizeInWords qSizeInWords,
830 IxQMgrQEntrySizeInWords qEntrySizeInWords)
832 * @brief Configure an AQM queue.
834 * This function is called by a client to setup a queue. The size and entrySize
835 * qId and qName(NULL pointer) are checked for valid values. This function must
836 * be called for each queue, before any queue accesses are made and after
837 * ixQMgrInit() has been called. qName is assumed to be a '\0' terminated array
838 * of 16 charachters or less.
840 * @param *qName char [in] - is the name provided by the client and is associated
841 * with a QId by the QMgr.
842 * @param qId @ref IxQMgrQId [in] - the qId of this queue
843 * @param qSizeInWords @ref IxQMgrQSize [in] - the size of the queue can be one of 16,32
845 * @param qEntrySizeInWords @ref IxQMgrQEntrySizeInWords [in] - the size of a queue entry
846 * can be one of 1,2,4 words.
848 * @return @li IX_SUCCESS, a specified queue has been successfully configured.
849 * @return @li IX_FAIL, IxQMgr has not been initialised.
850 * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s).
851 * @return @li IX_QMGR_INVALID_QSIZE, invalid queue size
852 * @return @li IX_QMGR_INVALID_Q_ID, invalid queue id
853 * @return @li IX_QMGR_INVALID_Q_ENTRY_SIZE, invalid queue entry size
854 * @return @li IX_QMGR_Q_ALREADY_CONFIGURED, queue already configured
858 ixQMgrQConfig (char *qName,
860 IxQMgrQSizeInWords qSizeInWords,
861 IxQMgrQEntrySizeInWords qEntrySizeInWords);
866 * @fn ixQMgrQSizeInEntriesGet (IxQMgrQId qId,
867 unsigned *qSizeInEntries)
869 * @brief Return the size of a queue in entries.
871 * This function returns the the size of the queue in entriese.
873 * @param qId @ref IxQMgrQId [in] - the queue identifier
874 * @param *qSizeInEntries @ref IxQMgrQSize [out] - queue size in entries
876 * @return @li IX_SUCCESS, successfully retrieved the number of full entrie
877 * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
878 * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s).
882 ixQMgrQSizeInEntriesGet (IxQMgrQId qId,
883 unsigned *qSizeInEntries);
889 * @fn ixQMgrWatermarkSet (IxQMgrQId qId,
893 * @brief Set the Nearly Empty and Nearly Full Watermarks fo a queue.
895 * This function is called by a client to set the watermarks NE and NF for the
896 * queue specified by qId.
897 * The queue must be empty at the time this function is called, it is the clients
898 * responsibility to ensure that the queue is empty.
899 * This function will read the status of the queue before the watermarks are set
900 * and again after the watermarks are set. If the status register has changed,
901 * due to a queue access by an NPE for example, a warning is returned.
902 * Queues 32-63 only support the NE flag, therefore the value of nf will be ignored
905 * @param qId @ref IxQMgrQId [in] - the QId of the queue.
906 * @param ne @ref IxQMgrWMLevel [in] - the NE(Nearly Empty) watermark for this
907 * queue. Valid values are 0,1,2,4,8,16,32 and
909 * @param nf @ref IxQMgrWMLevel [in] - the NF(Nearly Full) watermark for this queue.
910 * Valid values are 0,1,2,4,8,16,32 and 64
913 * @return @li IX_SUCCESS, watermarks have been set for the queu
914 * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
915 * @return @li IX_QMGR_INVALID_Q_WM, invalid watermark
916 * @return @li IX_QMGR_WARNING, the status register may not be constistent
920 ixQMgrWatermarkSet (IxQMgrQId qId,
927 * @fn ixQMgrAvailableSramAddressGet (UINT32 *address,
928 unsigned *sizeOfFreeSram)
930 * @brief Return the address of available AQM SRAM.
932 * This function returns the starting address in AQM SRAM not used by the
933 * current queue configuration and should only be called after all queues
934 * have been configured.
935 * Calling this function before all queues have been configured will will return
936 * the currently available SRAM. A call to configure another queue will use some
937 * of the available SRAM.
938 * The amount of SRAM available is specified in sizeOfFreeSram. The address is the
939 * address of the bottom of available SRAM. Available SRAM extends from address
940 * from address to address + sizeOfFreeSram.
942 * @param **address UINT32 [out] - the address of the available SRAM, NULL if
944 * @param *sizeOfFreeSram unsigned [out]- the size in words of available SRAM
946 * @return @li IX_SUCCESS, there is available SRAM and is pointed to by address
947 * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s)
948 * @return @li IX_QMGR_NO_AVAILABLE_SRAM, all AQM SRAM is consumed by the queue
953 ixQMgrAvailableSramAddressGet (UINT32 *address,
954 unsigned *sizeOfFreeSram);
957 /* ------------------------------------------------------------
958 Queue access related functions
959 ---------------------------------------------------------- */
965 * @fn ixQMgrQReadWithChecks (IxQMgrQId qId,
968 * @brief Read an entry from a queue.
970 * This function reads an entire entry from a queue returning it in entry. The
971 * queue configuration word is read to determine what entry size this queue is
972 * configured for and then the number of words specified by the entry size is
973 * read. entry must be a pointer to a previously allocated array of sufficient
974 * size to hold an entry.
976 * @note - IX_QMGR_Q_UNDERFLOW is only returned for queues 0-31 as queues 32-63
977 * do not have an underflow status maintained.
979 * @param qId @ref IxQMgrQId [in] - the queue identifier.
980 * @param *entry UINT32 [out] - pointer to the entry word(s).
982 * @return @li IX_SUCCESS, entry was successfully read.
983 * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s).
984 * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
985 * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue
989 ixQMgrQReadWithChecks (IxQMgrQId qId,
995 * @brief Internal structure to facilitate inlining functions in IxQMgr.h
999 /* fields related to write functions */
1000 UINT32 qOflowStatBitMask; /**< overflow status mask */
1001 UINT32 qWriteCount; /**< queue write count */
1003 /* fields related to read and write functions */
1004 volatile UINT32 *qAccRegAddr; /**< access register */
1005 volatile UINT32 *qUOStatRegAddr; /**< status register */
1006 volatile UINT32 *qConfigRegAddr; /**< config register */
1007 UINT32 qEntrySizeInWords; /**< queue entry size in words */
1008 UINT32 qSizeInEntries; /**< queue size in entries */
1010 /* fields related to read functions */
1011 UINT32 qUflowStatBitMask; /**< underflow status mask */
1012 UINT32 qReadCount; /**< queue read count */
1013 } IxQMgrQInlinedReadWriteInfo;
1018 * @ingroup IxQMgrAPI
1020 * @fn ixQMgrQReadMWordsMinus1 (IxQMgrQId qId,
1023 * @brief This function reads the remaining of the q entry
1024 * for queues configured with many words.
1025 * (the first word of the entry is already read
1026 * in the inlined function and the entry pointer already
1029 * @param qId @ref IxQMgrQId [in] - the queue identifier.
1030 * @param *entry UINT32 [out] - pointer to the entry word(s).
1032 * @return @li IX_SUCCESS, entry was successfully read.
1033 * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue
1037 ixQMgrQReadMWordsMinus1 (IxQMgrQId qId,
1044 * @ingroup IxQMgrAPI
1046 * @fn ixQMgrQRead (IxQMgrQId qId,
1049 * @brief Fast read of an entry from a queue.
1051 * This function is a heavily streamlined version of ixQMgrQReadWithChecks(),
1052 * but performs essentially the same task. It reads an entire entry from a
1053 * queue, returning it in entry which must be a pointer to a previously
1054 * allocated array of sufficient size to hold an entry.
1056 * @note - This function is inlined, to reduce unnecessary function call
1057 * overhead. It does not perform any parameter checks, or update any statistics.
1058 * Also, it does not check that the queue specified by qId has been configured.
1059 * or is in range. It simply reads an entry from the queue, and checks for
1062 * @note - IX_QMGR_Q_UNDERFLOW is only returned for queues 0-31 as queues 32-63
1063 * do not have an underflow status maintained.
1065 * @param qId @ref IxQMgrQId [in] - the queue identifier.
1066 * @param *entry UINT32 [out] - pointer to the entry word(s).
1068 * @return @li IX_SUCCESS, entry was successfully read.
1069 * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue
1072 #ifdef NO_INLINE_APIS
1074 ixQMgrQRead (IxQMgrQId qId,
1077 extern IxQMgrQInlinedReadWriteInfo ixQMgrQInlinedReadWriteInfo[];
1078 extern IX_STATUS ixQMgrQReadMWordsMinus1 (IxQMgrQId qId, UINT32 *entryPtr);
1080 IX_QMGR_INLINE PUBLIC IX_STATUS
1081 ixQMgrQRead (IxQMgrQId qId,
1085 IX_QMGR_INLINE PUBLIC IX_STATUS
1086 ixQMgrQRead (IxQMgrQId qId,
1088 #ifdef NO_INLINE_APIS
1092 IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];
1093 UINT32 entry, entrySize;
1095 /* get a new entry */
1096 entrySize = infoPtr->qEntrySizeInWords;
1097 entry = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr);
1099 if (entrySize != IX_QMGR_Q_ENTRY_SIZE1)
1102 /* process the remaining part of the entry */
1103 return ixQMgrQReadMWordsMinus1(qId, entryPtr);
1106 /* underflow is available for lower queues only */
1107 if (qId < IX_QMGR_MIN_QUEUPP_QID)
1109 /* the counter of queue entries is decremented. In happy
1110 * day scenario there are many entries in the queue
1111 * and the counter does not reach zero.
1113 if (infoPtr->qReadCount-- == 0)
1115 /* There is maybe no entry in the queue
1116 * qReadCount is now negative, but will be corrected before
1117 * the function returns.
1119 UINT32 qPtrs; /* queue internal pointers */
1121 /* when a queue is empty, the hw guarantees to return
1122 * a null value. If the value is not null, the queue is
1127 /* get the queue status */
1128 UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);
1130 /* check the underflow status */
1131 if (status & infoPtr->qUflowStatBitMask)
1133 /* the queue is empty
1134 * clear the underflow status bit if it was set
1136 IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr,
1137 status & ~infoPtr->qUflowStatBitMask);
1139 infoPtr->qReadCount = 0;
1140 return IX_QMGR_Q_UNDERFLOW;
1143 /* store the result */
1146 /* No underflow occured : someone is filling the queue
1147 * or the queue contains null entries.
1148 * The current counter needs to be
1149 * updated from the current number of entries in the queue
1152 /* get snapshot of queue pointers */
1153 qPtrs = IX_QMGR_INLINE_READ_LONG(infoPtr->qConfigRegAddr);
1155 /* Mod subtraction of pointers to get number of words in Q. */
1156 qPtrs = (qPtrs - (qPtrs >> 7)) & 0x7f;
1160 /* no entry in the queue */
1161 infoPtr->qReadCount = 0;
1165 /* convert the number of words inside the queue
1166 * to a number of entries
1168 infoPtr->qReadCount = qPtrs & (infoPtr->qSizeInEntries - 1);
1180 * @ingroup IxQMgrAPI
1182 * @fn ixQMgrQBurstRead (IxQMgrQId qId,
1186 * @brief Read a number of entries from an AQM queue.
1188 * This function will burst read a number of entries from the specified queue.
1189 * The entry size of queue is auto-detected. The function will attempt to
1190 * read as many entries as specified by the numEntries parameter and will
1191 * return an UNDERFLOW if any one of the individual entry reads fail.
1194 * IX_QMGR_Q_UNDERFLOW is only returned for queues 0-31 as queues 32-63
1195 * do not have an underflow status maintained, hence there is a potential for
1196 * silent failure here. This function must be used with caution.
1199 * This function is intended for fast draining of queues, so to make it
1200 * as efficient as possible, it has the following features:
1201 * - This function is inlined, to reduce unnecessary function call overhead.
1202 * - It does not perform any parameter checks, or update any statistics.
1203 * - It does not check that the queue specified by qId has been configured.
1204 * - It does not check that the queue has the number of full entries that
1205 * have been specified to be read. It will read until it finds a NULL entry or
1206 * until the number of specified entries have been read. It always checks for
1207 * underflow after all the reads have been performed.
1208 * Therefore, the client should ensure before calling this function that there
1209 * are enough entries in the queue to read. ixQMgrQNumEntriesGet() will
1210 * provide the number of full entries in a queue.
1211 * ixQMgrQRead() or ixQMgrQReadWithChecks(), which only reads
1212 * a single queue entry per call, should be used instead if the user requires
1213 * checks for UNDERFLOW after each entry read.
1215 * @param qId @ref IxQMgrQId [in] - the queue identifier.
1216 * @param numEntries unsigned [in] - the number of entries to read.
1217 * This number should be greater than 0
1218 * @param *entries UINT32 [out] - the word(s) read.
1220 * @return @li IX_SUCCESS, entries were successfully read.
1221 * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue
1224 #ifdef NO_INLINE_APIS
1226 ixQMgrQBurstRead (IxQMgrQId qId,
1230 IX_QMGR_INLINE PUBLIC IX_STATUS
1231 ixQMgrQBurstRead (IxQMgrQId qId,
1234 #endif /* endif NO_INLINE_APIS */
1236 IX_QMGR_INLINE PUBLIC IX_STATUS
1237 ixQMgrQBurstRead (IxQMgrQId qId,
1240 #ifdef NO_INLINE_APIS
1244 IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];
1245 UINT32 nullCheckEntry;
1247 if (infoPtr->qEntrySizeInWords == IX_QMGR_Q_ENTRY_SIZE1)
1249 volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr;
1251 /* the code is optimized to take care of data dependencies:
1252 * Durig a read, there are a few cycles needed to get the
1253 * read complete. During these cycles, it is poossible to
1254 * do some CPU, e.g. increment pointers and decrement
1258 /* fetch a queue entry */
1259 nullCheckEntry = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr);
1261 /* iterate the specified number of queue entries */
1262 while (--numEntries)
1264 /* check the result of the previous read */
1265 if (nullCheckEntry == 0)
1267 /* if we read a NULL entry, stop. We have underflowed */
1272 /* write the entry */
1273 *entries = nullCheckEntry;
1274 /* fetch next entry */
1275 nullCheckEntry = IX_QMGR_INLINE_READ_LONG(qAccRegAddr);
1276 /* increment the write address */
1280 /* write the pre-fetched entry */
1281 *entries = nullCheckEntry;
1285 IxQMgrQEntrySizeInWords entrySizeInWords = infoPtr->qEntrySizeInWords;
1286 /* read the specified number of queue entries */
1288 while (numEntries--)
1292 for (i = 0; i < (UINT32)entrySizeInWords; i++)
1294 *entries = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr + i);
1295 nullCheckEntry |= *entries++;
1298 /* if we read a NULL entry, stop. We have underflowed */
1299 if (nullCheckEntry == 0)
1307 /* reset the current read count : next access to the read function
1308 * will force a underflow status check
1310 infoPtr->qReadCount = 0;
1312 /* Check if underflow occurred on the read */
1313 if (nullCheckEntry == 0 && qId < IX_QMGR_MIN_QUEUPP_QID)
1315 /* get the queue status */
1316 UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);
1318 if (status & infoPtr->qUflowStatBitMask)
1320 /* clear the underflow status bit if it was set */
1321 IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr,
1322 status & ~infoPtr->qUflowStatBitMask);
1323 return IX_QMGR_Q_UNDERFLOW;
1332 * @ingroup IxQMgrAPI
1334 * @fn ixQMgrQPeek (IxQMgrQId qId,
1335 unsigned int entryIndex,
1338 * @brief Read an entry from a queue without moving the read pointer.
1340 * This function inspects an entry in a queue. The entry is inspected directly
1341 * in AQM SRAM and is not read from queue access registers. The entry is NOT removed
1342 * from the queue and the read/write pointers are unchanged.
1343 * N.B: The queue should not be accessed when this function is called.
1345 * @param qId @ref IxQMgrQId [in] - the queue identifier.
1346 * @param entryIndex unsigned int [in] - index of entry in queue in the range
1347 * [0].......[current number of entries in queue].
1348 * @param *entry UINT32 [out] - pointer to the entry word(s).
1350 * @return @li IX_SUCCESS, entry was successfully inspected.
1351 * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s).
1352 * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId.
1353 * @return @li IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS, an entry does not exist at
1355 * @return @li IX_FAIL, failed to inpected the queue entry.
1358 ixQMgrQPeek (IxQMgrQId qId,
1359 unsigned int entryIndex,
1364 * @ingroup IxQMgrAPI
1366 * @fn ixQMgrQWriteWithChecks (IxQMgrQId qId,
1369 * @brief Write an entry to an AQM queue.
1371 * This function will write the entry size number of words pointed to by entry to
1372 * the queue specified by qId. The queue configuration word is read to
1373 * determine the entry size of queue and the corresponding number of words is
1374 * then written to the queue.
1376 * @note - IX_QMGR_Q_OVERFLOW is only returned for queues 0-31 as queues 32-63
1377 * do not have an overflow status maintained.
1379 * @param qId @ref IxQMgrQId [in] - the queue identifier.
1380 * @param *entry UINT32 [in] - the word(s) to write.
1382 * @return @li IX_SUCCESS, value was successfully written.
1383 * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s).
1384 * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
1385 * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue
1389 ixQMgrQWriteWithChecks (IxQMgrQId qId,
1394 * @ingroup IxQMgrAPI
1396 * @fn ixQMgrQWrite (IxQMgrQId qId,
1399 * @brief Fast write of an entry to a queue.
1401 * This function is a heavily streamlined version of ixQMgrQWriteWithChecks(),
1402 * but performs essentially the same task. It will write the entry size number
1403 * of words pointed to by entry to the queue specified by qId.
1405 * @note - This function is inlined, to reduce unnecessary function call
1406 * overhead. It does not perform any parameter checks, or update any
1407 * statistics. Also, it does not check that the queue specified by qId has
1408 * been configured. It simply writes an entry to the queue, and checks for
1411 * @note - IX_QMGR_Q_OVERFLOW is only returned for queues 0-31 as queues 32-63
1412 * do not have an overflow status maintained.
1414 * @param qId @ref IxQMgrQId [in] - the queue identifier.
1415 * @param *entry UINT32 [in] - pointer to the entry word(s).
1417 * @return @li IX_SUCCESS, entry was successfully read.
1418 * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue
1421 #ifdef NO_INLINE_APIS
1423 ixQMgrQWrite (IxQMgrQId qId,
1426 IX_QMGR_INLINE PUBLIC IX_STATUS
1427 ixQMgrQWrite (IxQMgrQId qId,
1429 #endif /* NO_INLINE_APIS */
1431 IX_QMGR_INLINE PUBLIC IX_STATUS
1432 ixQMgrQWrite (IxQMgrQId qId,
1434 #ifdef NO_INLINE_APIS
1438 IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];
1441 /* write the entry */
1442 IX_QMGR_INLINE_WRITE_LONG(infoPtr->qAccRegAddr, *entry);
1443 entrySize = infoPtr->qEntrySizeInWords;
1445 if (entrySize != IX_QMGR_Q_ENTRY_SIZE1)
1447 /* process the remaining part of the entry */
1448 volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr;
1452 IX_QMGR_INLINE_WRITE_LONG(++qAccRegAddr, *entry);
1454 entrySize = infoPtr->qEntrySizeInWords;
1457 /* overflow is available for lower queues only */
1458 if (qId < IX_QMGR_MIN_QUEUPP_QID)
1460 UINT32 qSize = infoPtr->qSizeInEntries;
1461 /* increment the current number of entries in the queue
1462 * and check for overflow
1464 if (infoPtr->qWriteCount++ == qSize)
1466 /* the queue may have overflow */
1467 UINT32 qPtrs; /* queue internal pointers */
1469 /* get the queue status */
1470 UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);
1472 /* read the status twice because the status may
1473 * not be immediately ready after the write operation
1475 if ((status & infoPtr->qOflowStatBitMask) ||
1476 ((status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr))
1477 & infoPtr->qOflowStatBitMask))
1479 /* the queue is full, clear the overflow status
1482 IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr,
1483 status & ~infoPtr->qOflowStatBitMask);
1484 infoPtr->qWriteCount = infoPtr->qSizeInEntries;
1485 return IX_QMGR_Q_OVERFLOW;
1487 /* No overflow occured : someone is draining the queue
1488 * and the current counter needs to be
1489 * updated from the current number of entries in the queue
1492 /* get q pointer snapshot */
1493 qPtrs = IX_QMGR_INLINE_READ_LONG(infoPtr->qConfigRegAddr);
1495 /* Mod subtraction of pointers to get number of words in Q. */
1496 qPtrs = (qPtrs - (qPtrs >> 7)) & 0x7f;
1500 /* the queue may be full at the time of the
1501 * snapshot. Next access will check
1502 * the overflow status again.
1504 infoPtr->qWriteCount = qSize;
1508 /* convert the number of words to a number of entries */
1509 if (entrySize == IX_QMGR_Q_ENTRY_SIZE1)
1511 infoPtr->qWriteCount = qPtrs & (qSize - 1);
1515 infoPtr->qWriteCount = (qPtrs / entrySize) & (qSize - 1);
1526 * @ingroup IxQMgrAPI
1528 * @fn ixQMgrQBurstWrite (IxQMgrQId qId,
1529 unsigned numEntries,
1532 * @brief Write a number of entries to an AQM queue.
1534 * This function will burst write a number of entries to the specified queue.
1535 * The entry size of queue is auto-detected. The function will attempt to
1536 * write as many entries as specified by the numEntries parameter and will
1537 * return an OVERFLOW if any one of the individual entry writes fail.
1540 * IX_QMGR_Q_OVERFLOW is only returned for queues 0-31 as queues 32-63
1541 * do not have an overflow status maintained, hence there is a potential for
1542 * silent failure here. This function must be used with caution.
1545 * This function is intended for fast population of queues, so to make it
1546 * as efficient as possible, it has the following features:
1547 * - This function is inlined, to reduce unnecessary function call overhead.
1548 * - It does not perform any parameter checks, or update any statistics.
1549 * - It does not check that the queue specified by qId has been configured.
1550 * - It does not check that the queue has enough free space to hold the entries
1551 * before writing, and only checks for overflow after all writes have been
1552 * performed. Therefore, the client should ensure before calling this function
1553 * that there is enough free space in the queue to hold the number of entries
1554 * to be written. ixQMgrQWrite() or ixQMgrQWriteWithChecks(), which only writes
1555 * a single queue entry per call, should be used instead if the user requires
1556 * checks for OVERFLOW after each entry written.
1558 * @param qId @ref IxQMgrQId [in] - the queue identifier.
1559 * @param numEntries unsigned [in] - the number of entries to write.
1560 * @param *entries UINT32 [in] - the word(s) to write.
1562 * @return @li IX_SUCCESS, value was successfully written.
1563 * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue
1566 #ifdef NO_INLINE_APIS
1568 ixQMgrQBurstWrite (IxQMgrQId qId,
1569 unsigned numEntries,
1572 IX_QMGR_INLINE PUBLIC IX_STATUS
1573 ixQMgrQBurstWrite (IxQMgrQId qId,
1574 unsigned numEntries,
1576 #endif /* NO_INLINE_APIS */
1578 IX_QMGR_INLINE PUBLIC IX_STATUS
1579 ixQMgrQBurstWrite (IxQMgrQId qId,
1580 unsigned numEntries,
1582 #ifdef NO_INLINE_APIS
1586 IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];
1589 /* update the current write count */
1590 infoPtr->qWriteCount += numEntries;
1592 if (infoPtr->qEntrySizeInWords == IX_QMGR_Q_ENTRY_SIZE1)
1594 volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr;
1595 while (numEntries--)
1597 IX_QMGR_INLINE_WRITE_LONG(qAccRegAddr, *entries);
1603 IxQMgrQEntrySizeInWords entrySizeInWords = infoPtr->qEntrySizeInWords;
1606 /* write each queue entry */
1607 while (numEntries--)
1609 /* write the queueEntrySize number of words for each entry */
1610 for (i = 0; i < (UINT32)entrySizeInWords; i++)
1612 IX_QMGR_INLINE_WRITE_LONG((infoPtr->qAccRegAddr + i), *entries);
1618 /* check if the write count overflows */
1619 if (infoPtr->qWriteCount > infoPtr->qSizeInEntries)
1621 /* reset the current write count */
1622 infoPtr->qWriteCount = infoPtr->qSizeInEntries;
1625 /* Check if overflow occurred on the write operation */
1626 if (qId < IX_QMGR_MIN_QUEUPP_QID)
1628 /* get the queue status */
1629 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);
1631 /* read the status twice because the status may
1632 * not be ready at the time of the write
1634 if ((status & infoPtr->qOflowStatBitMask) ||
1635 ((status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr))
1636 & infoPtr->qOflowStatBitMask))
1638 /* clear the underflow status bit if it was set */
1639 IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr,
1640 status & ~infoPtr->qOflowStatBitMask);
1641 return IX_QMGR_Q_OVERFLOW;
1650 * @ingroup IxQMgrAPI
1652 * @fn ixQMgrQPoke (IxQMgrQId qId,
1653 unsigned int entryIndex,
1656 * @brief Write an entry to a queue without moving the write pointer.
1658 * This function modifies an entry in a queue. The entry is modified directly
1659 * in AQM SRAM and not using the queue access registers. The entry is NOT added to the
1660 * queue and the read/write pointers are unchanged.
1661 * N.B: The queue should not be accessed when this function is called.
1663 * @param qId @ref IxQMgrQId [in] - the queue identifier.
1664 * @param entryIndex unsigned int [in] - index of entry in queue in the range
1665 * [0].......[current number of entries in queue].
1666 * @param *entry UINT32 [in] - pointer to the entry word(s).
1668 * @return @li IX_SUCCESS, entry was successfully modified.
1669 * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s).
1670 * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId.
1671 * @return @li IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS, an entry does not exist at
1673 * @return @li IX_FAIL, failed to modify the queue entry.
1676 ixQMgrQPoke (IxQMgrQId qId,
1677 unsigned int entryIndex,
1682 * @ingroup IxQMgrAPI
1684 * @fn ixQMgrQNumEntriesGet (IxQMgrQId qId,
1685 unsigned *numEntries)
1687 * @brief Get a snapshot of the number of entries in a queue.
1689 * This function gets the number of entries in a queue.
1691 * @param qId @ref IxQMgrQId [in] qId - the queue idenfifier
1692 * @param *numEntries unsigned [out] - the number of entries in a queue
1694 * @return @li IX_SUCCESS, got the number of entries for the queue
1695 * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s).
1696 * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured
1697 * @return @li IX_QMGR_WARNING, could not determine num entries at this time
1701 ixQMgrQNumEntriesGet (IxQMgrQId qId,
1702 unsigned *numEntries);
1706 * @ingroup IxQMgrAPI
1708 * @fn ixQMgrQStatusGetWithChecks (IxQMgrQId qId,
1709 IxQMgrQStatus *qStatus)
1711 * @brief Get a queues status.
1713 * This function reads the specified queues status. A queues status is defined
1714 * by its status flags. For queues 0-31 these flags are E,NE,NF,F. For
1715 * queues 32-63 these flags are NE and F.
1717 * @param qId @ref IxQMgrQId [in] - the queue identifier.
1718 * @param &qStatus @ref IxQMgrQStatus [out] - the status of the specified queue.
1720 * @return @li IX_SUCCESS, queue status was successfully read.
1721 * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured
1722 * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter.
1726 ixQMgrQStatusGetWithChecks (IxQMgrQId qId,
1727 IxQMgrQStatus *qStatus);
1731 * @ingroup IxQMgrAPI
1733 * @fn ixQMgrQStatusGet (IxQMgrQId qId,
1734 IxQMgrQStatus *qStatus)
1736 * @brief Fast get of a queue's status.
1738 * This function is a streamlined version of ixQMgrQStatusGetWithChecks(), but
1739 * performs essentially the same task. It reads the specified queue's status.
1740 * A queues status is defined by its status flags. For queues 0-31 these flags
1741 * are E,NE,NF,F. For queues 32-63 these flags are NE and F.
1743 * @note - This function is inlined, to reduce unnecessary function call
1744 * overhead. It does not perform any parameter checks, or update any
1745 * statistics. Also, it does not check that the queue specified by qId has
1746 * been configured. It simply reads the specified queue's status.
1748 * @param qId @ref IxQMgrQId [in] - the queue identifier.
1749 * @param *qStatus @ref IxQMgrQStatus [out] - the status of the specified queue.
1755 #ifdef NO_INLINE_APIS
1757 ixQMgrQStatusGet (IxQMgrQId qId,
1758 IxQMgrQStatus *qStatus);
1760 extern UINT32 ixQMgrAqmIfQueLowStatRegAddr[];
1761 extern UINT32 ixQMgrAqmIfQueLowStatBitsOffset[];
1762 extern UINT32 ixQMgrAqmIfQueLowStatBitsMask;
1763 extern UINT32 ixQMgrAqmIfQueUppStat0RegAddr;
1764 extern UINT32 ixQMgrAqmIfQueUppStat1RegAddr;
1765 extern UINT32 ixQMgrAqmIfQueUppStat0BitMask[];
1766 extern UINT32 ixQMgrAqmIfQueUppStat1BitMask[];
1768 IX_QMGR_INLINE PUBLIC IX_STATUS
1769 ixQMgrQStatusGet (IxQMgrQId qId,
1770 IxQMgrQStatus *qStatus);
1771 #endif /* endif NO_INLINE_APIS */
1773 IX_QMGR_INLINE PUBLIC IX_STATUS
1774 ixQMgrQStatusGet (IxQMgrQId qId,
1775 IxQMgrQStatus *qStatus)
1776 #ifdef NO_INLINE_APIS
1780 /* read the status of a queue in the range 0-31 */
1781 if (qId < IX_QMGR_MIN_QUEUPP_QID)
1783 volatile UINT32 *lowStatRegAddr = (UINT32*)ixQMgrAqmIfQueLowStatRegAddr[qId];
1785 UINT32 lowStatBitsOffset = ixQMgrAqmIfQueLowStatBitsOffset[qId];
1786 UINT32 lowStatBitsMask = ixQMgrAqmIfQueLowStatBitsMask;
1788 /* read the status register for this queue */
1789 *qStatus = IX_QMGR_INLINE_READ_LONG(lowStatRegAddr);
1791 /* mask out the status bits relevant only to this queue */
1792 *qStatus = (*qStatus >> lowStatBitsOffset) & lowStatBitsMask;
1795 else /* read status of a queue in the range 32-63 */
1798 volatile UINT32 *qNearEmptyStatRegAddr = (UINT32*)ixQMgrAqmIfQueUppStat0RegAddr;
1799 volatile UINT32 *qFullStatRegAddr = (UINT32*)ixQMgrAqmIfQueUppStat1RegAddr;
1800 int maskIndex = qId - IX_QMGR_MIN_QUEUPP_QID;
1801 UINT32 qNearEmptyStatBitMask = ixQMgrAqmIfQueUppStat0BitMask[maskIndex];
1802 UINT32 qFullStatBitMask = ixQMgrAqmIfQueUppStat1BitMask[maskIndex];
1804 /* Reset the status bits */
1807 /* Check if the queue is nearly empty */
1808 if (IX_QMGR_INLINE_READ_LONG(qNearEmptyStatRegAddr) & qNearEmptyStatBitMask)
1810 *qStatus |= IX_QMGR_Q_STATUS_NE_BIT_MASK;
1813 /* Check if the queue is full */
1814 if (IX_QMGR_INLINE_READ_LONG(qFullStatRegAddr) & qFullStatBitMask)
1816 *qStatus |= IX_QMGR_Q_STATUS_F_BIT_MASK;
1823 /* ------------------------------------------------------------
1824 Queue dispatch related functions
1825 ---------------------------------------------------------- */
1829 * @ingroup IxQMgrAPI
1831 * @fn ixQMgrDispatcherPrioritySet (IxQMgrQId qId,
1832 IxQMgrPriority priority)
1834 * @brief Set the dispatch priority of a queue.
1836 * This function is called to set the dispatch priority of queue. The effect of
1837 * this function is to add a priority change request to a queue. This queue is
1838 * serviced by @a ixQMgrDispatcherLoopRunA0, @a ixQMgrDispatcherLoopRunB0 or
1839 * @a ixQMgrDispatcherLoopRunB0LLP.
1841 * This function is re-entrant. and can be used from an interrupt context
1843 * @param qId @ref IxQMgrQId [in] - the queue identifier
1844 * @param priority @ref IxQMgrPriority [in] - the new queue dispatch priority
1846 * @return @li IX_SUCCESS, priority change request is queued
1847 * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured
1848 * @return @li IX_QMGR_Q_INVALID_PRIORITY, specified priority is invalid
1852 ixQMgrDispatcherPrioritySet (IxQMgrQId qId,
1853 IxQMgrPriority priority);
1856 * @ingroup IxQMgrAPI
1858 * @fn ixQMgrNotificationEnable (IxQMgrQId qId,
1859 IxQMgrSourceId sourceId)
1861 * @brief Enable notification on a queue for a specified queue source flag.
1863 * This function is called by a client of the QMgr to enable notifications on a
1864 * specified condition.
1865 * If the condition for the notification is set after the client has called this
1866 * function but before the function has enabled the interrupt source, then the
1867 * notification will not occur.
1868 * For queues 32-63 the notification source is fixed to the NE(Nearly Empty) flag
1869 * and cannot be changed so the sourceId parameter is ignored for these queues.
1870 * The status register is read before the notofication is enabled and is read again
1871 * after the notification has been enabled, if they differ then the warning status
1874 * This function is re-entrant. and can be used from an interrupt context
1876 * @param qId @ref IxQMgrQId [in] - the queue identifier
1877 * @param sourceId @ref IxQMgrSourceId [in] - the interrupt src condition identifier
1879 * @return @li IX_SUCCESS, the interrupt has been enabled for the specified source
1880 * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured
1881 * @return @li IX_QMGR_INVALID_INT_SOURCE_ID, interrupt source invalid for this queue
1882 * @return @li IX_QMGR_WARNING, the status register may not be constistent
1886 ixQMgrNotificationEnable (IxQMgrQId qId,
1887 IxQMgrSourceId sourceId);
1890 * @ingroup IxQMgrAPI
1892 * @fn ixQMgrNotificationDisable (IxQMgrQId qId)
1894 * @brief Disable notifications on a queue.
1896 * This function is called to disable notifications on a specified queue.
1898 * This function is re-entrant. and can be used from an interrupt context
1900 * @param qId @ref IxQMgrQId [in] - the queue identifier
1902 * @return @li IX_SUCCESS, the interrupt has been disabled
1903 * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured
1907 ixQMgrNotificationDisable (IxQMgrQId qId);
1911 * @ingroup IxQMgrAPI
1913 * @fn ixQMgrDispatcherLoopRunA0 (IxQMgrDispatchGroup group)
1915 * @brief Run the callback dispatcher.
1917 * This function runs the dispatcher for a group of queues.
1918 * Callbacks are made for interrupts that have occurred on queues within
1919 * the group that have registered callbacks. The order in which queues are
1920 * serviced depends on the queue priorities set by the client.
1921 * This function may be called from interrupt or task context.
1922 * For optimisations that were introduced in IXP42X B0 and supported IXP46X
1923 * the @a ixQMgrDispatcherLoopRunB0, or @a ixQMgrDispatcherLoopRunB0LLP
1926 * This function is not re-entrant.
1928 * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which the
1929 * dispatcher will run
1933 * @note This function may be called from interrupt or task context.
1934 * However, for optimal performance the choice of context depends also on the
1935 * operating system used.
1939 ixQMgrDispatcherLoopRunA0 (IxQMgrDispatchGroup group);
1943 * @ingroup IxQMgrAPI
1945 * @fn ixQMgrDispatcherLoopRunB0 (IxQMgrDispatchGroup group)
1947 * @brief Run the callback dispatcher.
1949 * The enhanced version of @a ixQMgrDispatcherLoopRunA0 that is optimised for
1950 * features introduced in IXP42X B0 silicon and supported on IXP46X.
1951 * This is the default dispatcher for IXP42X B0 and IXP46X silicon.
1952 * The function runs the dispatcher for a group of queues.
1953 * Callbacks are made for interrupts that have occurred on queues within
1954 * the group that have registered callbacks. The order in which queues are
1955 * serviced depends on the queue priorities set by the client.
1956 * This function may be called from interrupt or task context.
1958 * This function is not re-entrant.
1960 * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which the
1961 * dispatcher will run
1966 * @note This function may be called from interrupt or task context.
1967 * However, for optimal performance the choice of context depends also on the
1968 * operating system used.
1972 ixQMgrDispatcherLoopRunB0 (IxQMgrDispatchGroup group);
1976 * @ingroup IxQMgrAPI
1978 * @fn ixQMgrDispatcherLoopRunB0LLP (IxQMgrDispatchGroup group)
1980 * @brief Run the callback dispatcher.
1982 * This is a version of the optimised dispatcher for IXP42X B0 and IXP46X,
1983 * @a ixQMgrDispatcherLoopRunB0, with added support for livelock prevention.
1984 * This dispatcher will only be used for the IXP42X B0 or IXP46X silicon if
1985 * feature control indicates that IX_FEATURECTRL_ORIGB0_DISPATCHER is set to
1986 * IX_FEATURE_CTRL_SWCONFIG_DISABLED. Otherwise the @a ixQMgrDispatcherLoopRunB0
1987 * dispatcher will be used (Default).
1989 * When this dispatcher notifies for a queue that is type
1990 * IX_QMGR_TYPE_REALTIME_PERIODIC, notifications for queues that are set
1991 * as type IX_QMGR_REALTIME_SPORADIC are not processed and disabled.
1992 * This helps prevent any tasks resulting from the notification of the
1993 * IX_QMGR_TYPE_REALTIME_PERIODIC type queue to being subject to livelock.
1994 * The function runs the dispatcher for a group of queues.
1995 * Callbacks are made for interrupts that have occurred on queues within
1996 * the group that have registered callbacks. The order in which queues are
1997 * serviced depends on their type along with the queue priorities set by the
1998 * client. This function may be called from interrupt or task context.
2000 * This function is not re-entrant.
2002 * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which
2003 * the dispatcher will run
2007 * @note This function may be called from interrupt or task context.
2008 * However, for optimal performance the choice of context depends also on the
2009 * operating system used.
2013 ixQMgrDispatcherLoopRunB0LLP (IxQMgrDispatchGroup group);
2017 * @ingroup IxQMgrAPI
2019 * @fn ixQMgrNotificationCallbackSet (IxQMgrQId qId,
2020 IxQMgrCallback callback,
2021 IxQMgrCallbackId callbackId)
2023 * @brief Set the notification callback for a queue.
2025 * This function sets the callback for the specified queue. This callback will
2026 * be called by the dispatcher, and may be called in the context of a interrupt
2027 * If callback has a value of NULL the previously registered callback, if one
2028 * exists will be unregistered.
2030 * @param qId @ref IxQMgrQId [in] - the queue idenfifier
2031 * @param callback @ref IxQMgrCallback [in] - the callback registered for this queue
2032 * @param callbackId @ref IxQMgrCallbackId [in] - the callback identifier
2034 * @return @li IX_SUCCESS, the callback for the specified queue has been set
2035 * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured
2039 ixQMgrNotificationCallbackSet (IxQMgrQId qId,
2040 IxQMgrCallback callback,
2041 IxQMgrCallbackId callbackId);
2045 * @ingroup IxQMgrAPI
2047 * @fn ixQMgrDispatcherLoopGet (IxQMgrDispatcherFuncPtr *qDispatcherFuncPtr)
2049 * @brief Get QMgr DispatcherLoopRun for respective silicon device
2051 * This function gets a function pointer to ixQMgrDispatcherLoopRunA0() for IXP42X A0
2052 * Silicon. If the IXP42X B0 or 46X Silicon, the default is the ixQMgrDispatcherLoopRunB0()
2053 * function, however if live lock prevention is enabled a function pointer to
2054 * ixQMgrDispatcherLoopRunB0LLP() is given.
2056 * @param *qDispatchFuncPtr @ref IxQMgrDispatcherFuncPtr [out] -
2057 * the function pointer of QMgr Dispatcher
2061 ixQMgrDispatcherLoopGet (IxQMgrDispatcherFuncPtr *qDispatcherFuncPtr);
2065 * @ingroup IxQMgrAPI
2067 * @fn ixQMgrStickyInterruptRegEnable(void)
2069 * @brief Enable AQM's sticky interrupt register behaviour only available
2072 * When AQM's sticky interrupt register is enabled, interrupt register bit will
2073 * only be cleared when a '1' is written to interrupt register bit and the
2074 * interrupting condition is satisfied, i.e.queue condition does not exist.
2076 * @note This function must be called before any queue is enabled.
2077 * Calling this function after queue is enabled will cause
2078 * undefined results.
2084 ixQMgrStickyInterruptRegEnable(void);
2088 * @ingroup IxQMgrAPI
2090 * @fn ixQMgrCallbackTypeSet(IxQMgrQId qId,
2093 * @brief Set the Callback Type of a queue.
2095 * This function is only used for live lock prevention.
2096 * This function allows the callback type of a queue to be set. The default for
2097 * all queues is IX_QMGR_TYPE_REALTIME_OTHER. Setting the type to
2098 * IX_QMGR_TYPE_REALTIME_SPORADIC means that this queue will have it's
2099 * notifications disabled while there is a task associated with a
2100 * queue of type IX_QMGR_TYPE_REALTIME_PERIODIC running. As live lock
2101 * prevention operates on lower queues, this function should
2102 * be called for lower queues only.
2103 * This function is not re-entrant.
2105 * @param qId @ref IxQMgrQId [in] - the queue identifier
2106 * @param type @ref IxQMgrType [in] - the type of callback
2108 * @return @li IX_SUCCESS, successfully set callback type for the queue entry
2109 * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
2110 * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s).
2114 ixQMgrCallbackTypeSet(IxQMgrQId qId,
2118 * @ingroup IxQMgrAPI
2120 * @fn ixQMgrCallbackTypeGet(IxQMgrQId qId,
2123 * @brief Get the Callback Type of a queue.
2125 * This function allows the callback type of a queue to be got. As live lock
2126 * prevention operates on lower queues, this function should
2127 * be called for lower queues only.
2128 * This function is re-entrant.
2130 * @param qId @ref IxQMgrQId [in] - the queue identifier
2131 * @param *type @ref IxQMgrType [out] - the type of callback
2133 * @return @li IX_SUCCESS, successfully set callback type for the queue entry
2134 * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
2135 * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s)
2139 ixQMgrCallbackTypeGet(IxQMgrQId qId,
2143 * @ingroup IxQMgrAPI
2145 * @fn ixQMgrPeriodicDone(void)
2147 * @brief Indicate that the Periodic task is completed for LLP
2149 * This function is used as part of live lock prevention.
2150 * A periodic task is a task that results from a queue that
2151 * is set as type IX_QMGR_TYPE_REALTIME_PERIODIC. This function
2152 * should be called to indicate to the dispatcher that the
2153 * the periodic task is completed. This ensures that the notifications
2154 * for queues set as type sporadic queues are re-enabled.
2155 * This function is re-entrant.
2159 ixQMgrPeriodicDone(void);
2163 * @ingroup IxQMgrAPI
2165 * @fn ixQMgrLLPShow(int resetStats)
2167 * @brief Print out the live lock prevention statistics when in debug mode.
2169 * This function prints out statistics related to the livelock. These
2170 * statistics are only collected in debug mode.
2171 * This function is not re-entrant.
2173 * @param resetStats @ref int [in] - if set the the stats are reset.
2177 ixQMgrLLPShow(int resetStats);
2180 #endif /* IXQMGR_H */
2183 * @} defgroup IxQMgrAPI