drivers/net/npe/include/IxQMgr.h

   1 /**
   2  * @file    IxQMgr.h
   3  *
   4  * @date    30-Oct-2001
   5  *
   6  * @brief This file contains the public API of IxQMgr component.
   7  *
   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
  21  * extern".
  22  *
  23  *
  24  * @par
  25  * IXP400 SW Release version 2.0
  26  *
  27  * -- Copyright Notice --
  28  *
  29  * @par
  30  * Copyright 2001-2005, Intel Corporation.
  31  * All rights reserved.
  32  *
  33  * @par
  34  * SPDX-License-Identifier:     BSD-3-Clause
  35  * @par
  36  * -- End of Copyright Notice --
  37 */
  38
  39 /* ------------------------------------------------------
  40    Doxygen group definitions
  41    ------------------------------------------------------ */
  42 /**
  43  * @defgroup IxQMgrAPI IXP400 Queue Manager (IxQMgr) API
  44  *
  45  * @brief The public API for the IXP400 QMgr component.
  46  *
  47  * IxQMgr is a low level interface to the AHB Queue Manager
  48  *
  49  * @{
  50  */
  51
  52 #ifndef IXQMGR_H
  53 #define IXQMGR_H
  54
  55 /*
  56  * User defined include files
  57  */
  58
  59 #include "IxOsal.h"
  60
  61 /*
  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.
  65  */
  66 #if defined (__BIG_ENDIAN)
  67
  68 #define IX_QMGR_INLINE_READ_LONG IX_OSAL_READ_LONG_BE
  69 #define IX_QMGR_INLINE_WRITE_LONG IX_OSAL_WRITE_LONG_BE
  70
  71 #else
  72
  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
  75
  76 #endif
  77
  78 /*
  79  * #defines and macros
  80  */
  81
  82 /**
  83 *
  84 * @ingroup IxQMgrAPI
  85 *
  86 * @def IX_QMGR_INLINE
  87 *
  88 * @brief Inline definition, for inlining of Queue Access functions on API
  89 *
  90 * Please read the header information in this file for more details on the
  91 * use of function inlining in this component.
  92 *
  93 */
  94
  95 #ifndef __wince
  96
  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
 103 #    endif
 104 #    define IX_QMGR_INLINE  /* Empty Define */
 105 #else
 106 #    ifndef NO_INLINE_APIS
 107 #       define IX_QMGR_INLINE IX_OSAL_INLINE_EXTERN
 108 #    else
 109 #       define IX_QMGR_INLINE /* Empty Define */
 110 #    endif
 111 #endif
 112
 113 #else /* ndef __wince */
 114
 115 #    ifndef NO_INLINE_APIS
 116 #       define NO_INLINE_APIS
 117 #    endif
 118 #    define IX_QMGR_INLINE
 119
 120 #endif
 121
 122
 123 /**
 124 *
 125 * @ingroup IxQMgrAPI
 126 *
 127 * @def IX_QMGR_MAX_NUM_QUEUES
 128 *
 129 * @brief Number of queues supported by the AQM.
 130 *
 131 * This constant is used to indicate the number of AQM queues
 132 *
 133 */
 134 #define IX_QMGR_MAX_NUM_QUEUES  64
 135
 136 /**
 137 *
 138 * @ingroup IxQMgrAPI
 139 *
 140 * @def IX_QMGR_MIN_QID
 141 *
 142 * @brief Minimum queue identifier.
 143 *
 144 * This constant is used to indicate the smallest queue identifier
 145 *
 146 */
 147 #define IX_QMGR_MIN_QID IX_QMGR_QUEUE_0
 148
 149 /**
 150 *
 151 * @ingroup IxQMgrAPI
 152 *
 153 * @def IX_QMGR_MAX_QID
 154 *
 155 * @brief Maximum queue identifier.
 156 *
 157 * This constant is used to indicate the largest queue identifier
 158 *
 159 */
 160 #define IX_QMGR_MAX_QID IX_QMGR_QUEUE_63
 161
 162 /**
 163 *
 164 * @ingroup IxQMgrAPI
 165 *
 166 * @def IX_QMGR_MIN_QUEUPP_QID
 167 *
 168 * @brief Minimum queue identifier for reduced functionality queues.
 169 *
 170 * This constant is used to indicate Minimum queue identifier for reduced
 171 * functionality queues
 172 *
 173 */
 174 #define IX_QMGR_MIN_QUEUPP_QID 32
 175
 176 /**
 177 *
 178 * @ingroup IxQMgrAPI
 179 *
 180 * @def IX_QMGR_MAX_QNAME_LEN
 181 *
 182 * @brief Maximum queue name length.
 183 *
 184 * This constant is used to indicate the maximum null terminated string length
 185 * (excluding '\0') for a queue name
 186 *
 187 */
 188 #define IX_QMGR_MAX_QNAME_LEN 16
 189
 190 /**
 191  *
 192  * @ingroup IxQMgrAPI
 193  *
 194  * @def IX_QMGR_WARNING
 195  *
 196  * @brief Warning return code.
 197  *
 198  * Execution complete, but there is a special case to handle
 199  *
 200  */
 201 #define IX_QMGR_WARNING 2
 202
 203 /**
 204  *
 205  * @ingroup IxQMgrAPI
 206  *
 207  * @def IX_QMGR_PARAMETER_ERROR
 208  *
 209  * @brief Parameter error return code (NULL pointer etc..).
 210  *
 211  * parameter error out of range/invalid
 212  *
 213  */
 214 #define IX_QMGR_PARAMETER_ERROR 3
 215
 216 /**
 217  *
 218  * @ingroup IxQMgrAPI
 219  *
 220  * @def IX_QMGR_INVALID_Q_ENTRY_SIZE
 221  *
 222  * @brief Invalid entry size return code.
 223  *
 224  * Invalid queue entry size for a queue read/write
 225  *
 226  */
 227 #define IX_QMGR_INVALID_Q_ENTRY_SIZE 4
 228
 229 /**
 230  *
 231  * @ingroup IxQMgrAPI
 232  *
 233  * @def IX_QMGR_INVALID_Q_ID
 234  *
 235  * @brief Invalid queue identifier return code.
 236  *
 237  * Invalid queue id, not in range 0-63
 238  *
 239  */
 240 #define IX_QMGR_INVALID_Q_ID 5
 241
 242 /**
 243  *
 244  * @ingroup IxQMgrAPI
 245  *
 246  * @def IX_QMGR_INVALID_CB_ID
 247  *
 248  * @brief Invalid callback identifier return code.
 249  *
 250  * Invalid callback id
 251  */
 252 #define IX_QMGR_INVALID_CB_ID 6
 253
 254 /**
 255  *
 256  * @ingroup IxQMgrAPI
 257  *
 258  * @def IX_QMGR_CB_ALREADY_SET
 259  *
 260  * @brief Callback set error return code.
 261  *
 262  * The specified callback has already been for this queue
 263  *
 264  */
 265 #define IX_QMGR_CB_ALREADY_SET 7
 266
 267 /**
 268  *
 269  * @ingroup IxQMgrAPI
 270  *
 271  * @def IX_QMGR_NO_AVAILABLE_SRAM
 272  *
 273  * @brief Sram consumed return code.
 274  *
 275  * All AQM Sram is consumed by queue configuration
 276  *
 277  */
 278 #define IX_QMGR_NO_AVAILABLE_SRAM 8
 279
 280 /**
 281  *
 282  * @ingroup IxQMgrAPI
 283  *
 284  * @def IX_QMGR_INVALID_INT_SOURCE_ID
 285  *
 286  * @brief Invalid queue interrupt source identifier return code.
 287  *
 288  * Invalid queue interrupt source given for notification enable
 289  */
 290 #define IX_QMGR_INVALID_INT_SOURCE_ID 9
 291
 292 /**
 293  *
 294  * @ingroup IxQMgrAPI
 295  *
 296  * @def IX_QMGR_INVALID_QSIZE
 297  *
 298  * @brief Invalid queue size error code.
 299  *
 300  * Invalid queue size not one of 16,32, 64, 128
 301  *
 302  *
 303  */
 304 #define IX_QMGR_INVALID_QSIZE 10
 305
 306 /**
 307  *
 308  * @ingroup IxQMgrAPI
 309  *
 310  * @def IX_QMGR_INVALID_Q_WM
 311  *
 312  * @brief Invalid queue watermark return code.
 313  *
 314  * Invalid queue watermark given for watermark set
 315  */
 316 #define IX_QMGR_INVALID_Q_WM 11
 317
 318 /**
 319  *
 320  * @ingroup IxQMgrAPI
 321  *
 322  * @def IX_QMGR_Q_NOT_CONFIGURED
 323  *
 324  * @brief Queue not configured return code.
 325  *
 326  * Returned to the client when a function has been called on an unconfigured
 327  * queue
 328  *
 329  */
 330 #define IX_QMGR_Q_NOT_CONFIGURED 12
 331
 332 /**
 333  *
 334  * @ingroup IxQMgrAPI
 335  *
 336  * @def IX_QMGR_Q_ALREADY_CONFIGURED
 337  *
 338  * @brief Queue already configured return code.
 339  *
 340  * Returned to client to indicate that a queue has already been configured
 341  */
 342 #define IX_QMGR_Q_ALREADY_CONFIGURED 13
 343
 344 /**
 345  *
 346  * @ingroup IxQMgrAPI
 347  *
 348  * @def IX_QMGR_Q_UNDERFLOW
 349  *
 350  * @brief Underflow return code.
 351  *
 352  * Underflow on a queue read has occurred
 353  *
 354  */
 355 #define IX_QMGR_Q_UNDERFLOW 14
 356
 357 /**
 358  *
 359  * @ingroup IxQMgrAPI
 360  *
 361  * @def IX_QMGR_Q_OVERFLOW
 362  *
 363  * @brief Overflow return code.
 364  *
 365  * Overflow on a queue write has occurred
 366  *
 367  */
 368 #define IX_QMGR_Q_OVERFLOW 15
 369
 370 /**
 371  *
 372  * @ingroup IxQMgrAPI
 373  *
 374  * @def IX_QMGR_Q_INVALID_PRIORITY
 375  *
 376  * @brief Invalid priority return code.
 377  *
 378  * Invalid priority, not one of 0,1,2
 379  */
 380 #define IX_QMGR_Q_INVALID_PRIORITY 16
 381
 382 /**
 383  *
 384  * @ingroup IxQMgrAPI
 385  *
 386  * @def IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS
 387  *
 388  * @brief  Entry index out of bounds return code.
 389  *
 390  * Entry index is greater than number of entries in queue.
 391  */
 392 #define IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS 17
 393
 394 /**
 395  *
 396  * @ingroup IxQMgrAPI
 397  *
 398  * @def ixQMgrDispatcherLoopRun
 399  *
 400  * @brief  Map old function name ixQMgrDispatcherLoopRun ()
 401  *         to @ref ixQMgrDispatcherLoopRunA0 ().
 402  *
 403  */
 404 #define ixQMgrDispatcherLoopRun ixQMgrDispatcherLoopRunA0
 405
 406
 407 /**
 408  *
 409  * @ingroup IxQMgrAPI
 410  *
 411  * @def IX_QMGR_QUEUE
 412  *
 413  * @brief  Definition of AQM queue numbers
 414  *
 415  */
 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 */
 481
 482
 483 /*
 484  * Typedefs
 485  */
 486
 487 /**
 488  * @typedef IxQMgrQId
 489  *
 490  * @ingroup IxQMgrAPI
 491  *
 492  * @brief Used in the API to identify the AQM queues.
 493  *
 494  */
 495 typedef int IxQMgrQId;
 496
 497 /**
 498  * @typedef IxQMgrQStatus
 499  *
 500  * @ingroup IxQMgrAPI
 501  *
 502  * @brief Queue status.
 503  *
 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
 507  * Full status flags.
 508  * The flags bit positions are outlined below:
 509  *
 510  *        OF - bit-5<br>
 511  *        UF - bit-4<br>
 512  *         F - bit-3<br>
 513  *        NF - bit-2<br>
 514  *        NE - bit-1<br>
 515  *         E - bit-0<br>
 516  *
 517  */
 518 typedef UINT32 IxQMgrQStatus;
 519
 520 /**
 521  * @enum IxQMgrQStatusMask
 522  *
 523  * @ingroup IxQMgrAPI
 524  *
 525  * @brief Queue status mask.
 526  *
 527  * Masks for extracting the individual status flags from the IxQMgrStatus
 528  * word.
 529  *
 530  */
 531 typedef enum
 532 {
 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
 539 } IxQMgrQStatusMask;
 540
 541 /**
 542  * @enum IxQMgrSourceId
 543  *
 544  * @ingroup IxQMgrAPI
 545  *
 546  * @brief Queue interrupt source select.
 547  *
 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.
 552  *
 553  */
 554 typedef enum
 555 {
 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          */
 564 } IxQMgrSourceId;
 565
 566 /**
 567  * @enum IxQMgrQEntrySizeInWords
 568  *
 569  * @ingroup IxQMgrAPI
 570  *
 571  * @brief QMgr queue entry sizes.
 572  *
 573  * The entry size of a queue specifies the size of a queues entry in words.
 574  *
 575  */
 576 typedef enum
 577 {
 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;
 582
 583 /**
 584  * @enum IxQMgrQSizeInWords
 585  *
 586  * @ingroup IxQMgrAPI
 587  *
 588  * @brief QMgr queue sizes.
 589  *
 590  * These values define the allowed queue sizes for AQM queue. The sizes are
 591  * specified in words.
 592  *
 593  */
 594 typedef enum
 595 {
 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
 602                                     */
 603 } IxQMgrQSizeInWords;
 604
 605 /**
 606  * @enum IxQMgrWMLevel
 607  *
 608  * @ingroup IxQMgrAPI
 609  *
 610  * @brief QMgr watermark levels.
 611  *
 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.
 621  */
 622 typedef enum
 623 {
 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 */
 632 } IxQMgrWMLevel;
 633
 634 /**
 635  * @ingroup IxQMgrAPI
 636  *
 637  * @enum IxQMgrDispatchGroup
 638  *
 639  * @brief QMgr dispatch group select identifiers.
 640  *
 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.
 645  *
 646  */
 647 typedef enum
 648 {
 649     IX_QMGR_QUELOW_GROUP = 0, /**< Queues 0-31  */
 650     IX_QMGR_QUEUPP_GROUP      /**< Queues 32-63 */
 651 } IxQMgrDispatchGroup;
 652
 653 /**
 654  * @ingroup IxQMgrAPI
 655  *
 656  * @enum IxQMgrPriority
 657  *
 658  * @brief Dispatcher priority levels.
 659  *
 660  * This enum defines the different queue dispatch priority levels.
 661  * The lowest priority number (0) is the highest priority level.
 662  *
 663  */
 664 typedef enum
 665 {
 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 */
 670 } IxQMgrPriority;
 671
 672 /**
 673  * @ingroup IxQMgrAPI
 674  *
 675  * @enum IxQMgrType
 676  *
 677  * @brief Callback types as used with livelock prevention
 678  *
 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.
 682  *
 683  */
 684
 685 typedef enum
 686 {
 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    */
 691 } IxQMgrType;
 692
 693
 694 /**
 695  * @ingroup IxQMgrAPI
 696  *
 697  * @typedef IxQMgrCallbackId
 698  *
 699  * @brief Uniquely identifies a callback function.
 700  *
 701  * A unique callback identifier associated with each callback
 702  * registered by clients.
 703  *
 704  */
 705 typedef unsigned IxQMgrCallbackId;
 706
 707 /**
 708  * @typedef IxQMgrCallback
 709  *
 710  * @brief QMgr notification callback type.
 711  *
 712  * This defines the interface to all client callback functions.
 713  *
 714  * @param qId @ref IxQMgrQId [in] - the queue identifier
 715  * @param cbId @ref IxQMgrCallbackId [in] - the callback identifier
 716  */
 717 typedef void (*IxQMgrCallback)(IxQMgrQId qId,
 718                                IxQMgrCallbackId cbId);
 719
 720 /**
 721  * @ingroup IxQMgrAPI
 722  *
 723  * @typedef IxQMgrDispatcherFuncPtr
 724  *
 725  * @brief QMgr Dispatcher Loop function pointer.
 726  *
 727  * This defines the interface for QMgr Dispather functions.
 728  *
 729  * @param group @ref IxQMgrDispatchGroup [in] - the group of the
 730  *                  queue of which the dispatcher will run
 731  */
 732 typedef void (*IxQMgrDispatcherFuncPtr)(IxQMgrDispatchGroup group);
 733
 734 /*
 735  * Function Prototypes
 736  */
 737
 738 /* ------------------------------------------------------------
 739    Initialisation related functions
 740    ---------------------------------------------------------- */
 741
 742 /**
 743  *
 744  * @ingroup IxQMgrAPI
 745  *
 746  * @fn ixQMgrInit (void)
 747  *
 748  * @brief Initialise the QMgr.
 749  *
 750  * This function must be called before and other QMgr function. It
 751  * sets up internal data structures.
 752  *
 753  * @return @li IX_SUCCESS, the IxQMgr successfully initialised
 754  * @return @li IX_FAIL, failed to initialize the Qmgr
 755  *
 756  */
 757 PUBLIC IX_STATUS
 758 ixQMgrInit (void);
 759
 760 /**
 761  *
 762  * @ingroup IxQMgrAPI
 763  *
 764  * @fn ixQMgrUnload (void)
 765  *
 766  * @brief Uninitialise the QMgr.
 767  *
 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.
 771  *
 772  * @pre It should only be called if @ref ixQMgrInit has already been called.
 773  *
 774  * @post No QMgr functions should be called until ixQMgrInit is called again.
 775  *
 776  * @return @li IX_SUCCESS, the IxQMgr successfully uninitialised
 777  * @return @li IX_FAIL, failed to uninitialize the Qmgr
 778  *
 779  */
 780 PUBLIC IX_STATUS
 781 ixQMgrUnload (void);
 782
 783 /**
 784  *
 785  * @ingroup IxQMgrAPI
 786  *
 787  * @fn ixQMgrShow (void)
 788  *
 789  * @brief Describe queue configuration and statistics for active queues.
 790  *
 791  * This function shows active queues, their configurations and statistics.
 792  *
 793  * @return @li void
 794  *
 795  */
 796 PUBLIC void
 797 ixQMgrShow (void);
 798
 799 /**
 800  *
 801  * @ingroup IxQMgrAPI
 802  *
 803  * @fn ixQMgrQShow (IxQMgrQId qId)
 804  *
 805  * @brief Display aqueue configuration and statistics for a queue.
 806  *
 807  * This function shows queue configuration and statistics for a queue.
 808  *
 809  * @param qId @ref IxQMgrQId [in] - the queue identifier.
 810  *
 811  * @return @li IX_SUCCESS, success
 812  * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
 813  *
 814  */
 815 PUBLIC IX_STATUS
 816 ixQMgrQShow (IxQMgrQId qId);
 817
 818
 819 /* ------------------------------------------------------------
 820    Configuration related functions
 821    ---------------------------------------------------------- */
 822
 823 /**
 824  *
 825  * @ingroup IxQMgrAPI
 826  *
 827  * @fn ixQMgrQConfig (char *qName,
 828                IxQMgrQId qId,
 829                IxQMgrQSizeInWords qSizeInWords,
 830                IxQMgrQEntrySizeInWords qEntrySizeInWords)
 831  *
 832  * @brief Configure an AQM queue.
 833  *
 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.
 839  *
 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
 844  *                                       64, 128 words.
 845  * @param qEntrySizeInWords @ref IxQMgrQEntrySizeInWords [in] - the size of a queue entry
 846  *                                                        can be one of 1,2,4 words.
 847  *
 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
 855  *
 856  */
 857 PUBLIC IX_STATUS
 858 ixQMgrQConfig (char *qName,
 859                IxQMgrQId qId,
 860                IxQMgrQSizeInWords qSizeInWords,
 861                IxQMgrQEntrySizeInWords qEntrySizeInWords);
 862
 863 /**
 864  * @ingroup IxQMgrAPI
 865  *
 866  * @fn ixQMgrQSizeInEntriesGet (IxQMgrQId qId,
 867                          unsigned *qSizeInEntries)
 868  *
 869  * @brief Return the size of a queue in entries.
 870  *
 871  * This function returns the the size of the queue in entriese.
 872  *
 873  * @param qId @ref IxQMgrQId [in] - the queue identifier
 874  * @param *qSizeInEntries @ref IxQMgrQSize [out] - queue size in entries
 875  *
 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).
 879  *
 880  */
 881 PUBLIC IX_STATUS
 882 ixQMgrQSizeInEntriesGet (IxQMgrQId qId,
 883                          unsigned *qSizeInEntries);
 884
 885 /**
 886  *
 887  * @ingroup IxQMgrAPI
 888  *
 889  * @fn ixQMgrWatermarkSet (IxQMgrQId qId,
 890                     IxQMgrWMLevel ne,
 891                     IxQMgrWMLevel nf)
 892  *
 893  * @brief Set the Nearly Empty and Nearly Full Watermarks fo a queue.
 894  *
 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
 903  * for these queues.
 904  *
 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
 908  *                                 64 entries.
 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
 911  *                                 entries.
 912  *
 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
 917  *
 918  */
 919 PUBLIC IX_STATUS
 920 ixQMgrWatermarkSet (IxQMgrQId qId,
 921                     IxQMgrWMLevel ne,
 922                     IxQMgrWMLevel nf);
 923
 924 /**
 925  * @ingroup IxQMgrAPI
 926  *
 927  * @fn ixQMgrAvailableSramAddressGet (UINT32 *address,
 928                                unsigned *sizeOfFreeSram)
 929  *
 930  * @brief Return the address of available AQM SRAM.
 931  *
 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.
 941  *
 942  * @param **address UINT32 [out] - the address of the available SRAM, NULL if
 943  *                                none available.
 944  * @param *sizeOfFreeSram unsigned [out]- the size in words of available SRAM
 945  *
 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
 949  *             configuration.
 950  *
 951  */
 952 PUBLIC IX_STATUS
 953 ixQMgrAvailableSramAddressGet (UINT32 *address,
 954                                unsigned *sizeOfFreeSram);
 955
 956
 957 /* ------------------------------------------------------------
 958    Queue access related functions
 959    ---------------------------------------------------------- */
 960
 961 /**
 962  *
 963  * @ingroup IxQMgrAPI
 964  *
 965  * @fn ixQMgrQReadWithChecks (IxQMgrQId qId,
 966                        UINT32 *entry)
 967  *
 968  * @brief Read an entry from a queue.
 969  *
 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.
 975  *
 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.
 978  *
 979  * @param  qId @ref IxQMgrQId [in]   - the queue identifier.
 980  * @param  *entry UINT32 [out]  - pointer to the entry word(s).
 981  *
 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
 986  *
 987  */
 988 PUBLIC IX_STATUS
 989 ixQMgrQReadWithChecks (IxQMgrQId qId,
 990                        UINT32 *entry);
 991
 992
 993
 994 /**
 995  * @brief Internal structure to facilitate inlining functions in IxQMgr.h
 996  */
 997 typedef struct
 998 {
 999     /* fields related to write functions */
1000     UINT32 qOflowStatBitMask;         /**< overflow status mask */
1001     UINT32 qWriteCount;               /**< queue write count */
1002
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 */
1009
1010     /* fields related to read functions */
1011     UINT32 qUflowStatBitMask;         /**< underflow status mask */
1012     UINT32 qReadCount;                /**< queue read count */
1013 } IxQMgrQInlinedReadWriteInfo;
1014
1015
1016 /**
1017  *
1018  * @ingroup IxQMgrAPI
1019  *
1020  * @fn ixQMgrQReadMWordsMinus1 (IxQMgrQId qId,
1021                                 UINT32 *entry)
1022  *
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
1027  *        incremented
1028  *
1029  * @param  qId @ref IxQMgrQId [in]  - the queue identifier.
1030  * @param  *entry UINT32 [out] - pointer to the entry word(s).
1031  *
1032  * @return @li IX_SUCCESS, entry was successfully read.
1033  * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue
1034  *
1035  */
1036 PUBLIC IX_STATUS
1037 ixQMgrQReadMWordsMinus1 (IxQMgrQId qId,
1038                          UINT32 *entry);
1039
1040
1041
1042 /**
1043  *
1044  * @ingroup IxQMgrAPI
1045  *
1046  * @fn ixQMgrQRead (IxQMgrQId qId,
1047              UINT32 *entry)
1048  *
1049  * @brief Fast read of an entry from a queue.
1050  *
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.
1055  *
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
1060  * underflow.
1061  *
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.
1064  *
1065  * @param  qId @ref IxQMgrQId [in] - the queue identifier.
1066  * @param  *entry UINT32 [out] - pointer to the entry word(s).
1067  *
1068  * @return @li IX_SUCCESS, entry was successfully read.
1069  * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue
1070  *
1071  */
1072 #ifdef NO_INLINE_APIS
1073 PUBLIC IX_STATUS
1074 ixQMgrQRead (IxQMgrQId qId,
1075              UINT32 *entryPtr);
1076 #else
1077 extern IxQMgrQInlinedReadWriteInfo ixQMgrQInlinedReadWriteInfo[];
1078 extern IX_STATUS ixQMgrQReadMWordsMinus1 (IxQMgrQId qId, UINT32 *entryPtr);
1079
1080 IX_QMGR_INLINE PUBLIC IX_STATUS
1081 ixQMgrQRead (IxQMgrQId qId,
1082              UINT32 *entryPtr);
1083 #endif
1084
1085 IX_QMGR_INLINE PUBLIC IX_STATUS
1086 ixQMgrQRead (IxQMgrQId qId,
1087              UINT32 *entryPtr)
1088 #ifdef NO_INLINE_APIS
1089     ;
1090 #else
1091 {
1092     IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];
1093     UINT32 entry, entrySize;
1094
1095     /* get a new entry */
1096     entrySize = infoPtr->qEntrySizeInWords;
1097     entry = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr);
1098
1099     if (entrySize != IX_QMGR_Q_ENTRY_SIZE1)
1100     {
1101         *entryPtr = entry;
1102         /* process the remaining part of the entry */
1103         return ixQMgrQReadMWordsMinus1(qId, entryPtr);
1104     }
1105
1106     /* underflow is available for lower queues only */
1107     if (qId < IX_QMGR_MIN_QUEUPP_QID)
1108     {
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.
1112          */
1113         if (infoPtr->qReadCount-- == 0)
1114         {
1115             /* There is maybe no entry in the queue
1116              * qReadCount is now negative, but will be corrected before
1117              * the function returns.
1118              */
1119             UINT32 qPtrs; /* queue internal pointers */
1120
1121             /* when a queue is empty, the hw guarantees to return
1122              * a null value. If the value is not null, the queue is
1123              * not empty.
1124              */
1125             if (entry == 0)
1126             {
1127                 /* get the queue status */
1128                 UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);
1129
1130                 /* check the underflow status */
1131                 if (status & infoPtr->qUflowStatBitMask)
1132                 {
1133                     /* the queue is empty
1134                     *  clear the underflow status bit if it was set
1135                     */
1136                     IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr,
1137                                          status & ~infoPtr->qUflowStatBitMask);
1138                     *entryPtr = 0;
1139                     infoPtr->qReadCount = 0;
1140                     return IX_QMGR_Q_UNDERFLOW;
1141                 }
1142             }
1143             /* store the result */
1144             *entryPtr = entry;
1145
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
1150              */
1151
1152             /* get snapshot of queue pointers */
1153             qPtrs = IX_QMGR_INLINE_READ_LONG(infoPtr->qConfigRegAddr);
1154
1155             /* Mod subtraction of pointers to get number of words in Q. */
1156             qPtrs = (qPtrs - (qPtrs >> 7)) & 0x7f;
1157
1158             if (qPtrs == 0)
1159             {
1160                 /* no entry in the queue */
1161                 infoPtr->qReadCount = 0;
1162             }
1163             else
1164             {
1165                 /* convert the number of words inside the queue
1166                  * to a number of entries
1167                  */
1168                 infoPtr->qReadCount = qPtrs & (infoPtr->qSizeInEntries - 1);
1169             }
1170             return IX_SUCCESS;
1171         }
1172     }
1173     *entryPtr = entry;
1174     return IX_SUCCESS;
1175 }
1176 #endif
1177
1178 /**
1179  *
1180  * @ingroup IxQMgrAPI
1181  *
1182  * @fn ixQMgrQBurstRead (IxQMgrQId qId,
1183                   UINT32 numEntries,
1184                   UINT32 *entries)
1185  *
1186  * @brief Read a number of entries from an AQM queue.
1187  *
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.
1192  *
1193  * @warning
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.
1197  *
1198  * @note
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.
1214  *
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.
1219  *
1220  * @return @li IX_SUCCESS, entries were successfully read.
1221  * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue
1222  *
1223  */
1224 #ifdef NO_INLINE_APIS
1225 PUBLIC IX_STATUS
1226 ixQMgrQBurstRead (IxQMgrQId qId,
1227                   UINT32 numEntries,
1228                   UINT32 *entries);
1229 #else
1230 IX_QMGR_INLINE PUBLIC IX_STATUS
1231 ixQMgrQBurstRead (IxQMgrQId qId,
1232                   UINT32 numEntries,
1233                   UINT32 *entries);
1234 #endif  /* endif NO_INLINE_APIS */
1235
1236 IX_QMGR_INLINE PUBLIC IX_STATUS
1237 ixQMgrQBurstRead (IxQMgrQId qId,
1238                   UINT32 numEntries,
1239                   UINT32 *entries)
1240 #ifdef NO_INLINE_APIS
1241 ;
1242 #else
1243 {
1244     IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];
1245     UINT32 nullCheckEntry;
1246
1247     if (infoPtr->qEntrySizeInWords == IX_QMGR_Q_ENTRY_SIZE1)
1248     {
1249         volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr;
1250
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
1255          * counters.
1256          */
1257
1258         /* fetch a queue entry */
1259         nullCheckEntry = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr);
1260
1261         /* iterate the specified number of queue entries */
1262         while (--numEntries)
1263         {
1264             /* check the result of the previous read */
1265             if (nullCheckEntry == 0)
1266             {
1267                 /* if we read a NULL entry, stop. We have underflowed */
1268                 break;
1269             }
1270             else
1271             {
1272                 /* write the entry */
1273                 *entries = nullCheckEntry;
1274                 /* fetch next entry */
1275                 nullCheckEntry = IX_QMGR_INLINE_READ_LONG(qAccRegAddr);
1276                 /* increment the write address */
1277                 entries++;
1278             }
1279         }
1280         /* write the pre-fetched entry */
1281         *entries = nullCheckEntry;
1282     }
1283     else
1284     {
1285         IxQMgrQEntrySizeInWords entrySizeInWords = infoPtr->qEntrySizeInWords;
1286         /* read the specified number of queue entries */
1287         nullCheckEntry = 0;
1288         while (numEntries--)
1289         {
1290             UINT32 i;
1291
1292             for (i = 0; i < (UINT32)entrySizeInWords; i++)
1293             {
1294                 *entries = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr + i);
1295                 nullCheckEntry |= *entries++;
1296             }
1297
1298             /* if we read a NULL entry, stop. We have underflowed */
1299             if (nullCheckEntry == 0)
1300             {
1301                 break;
1302             }
1303             nullCheckEntry = 0;
1304         }
1305     }
1306
1307     /* reset the current read count : next access to the read function
1308      * will force a underflow status check
1309      */
1310     infoPtr->qReadCount = 0;
1311
1312     /* Check if underflow occurred on the read */
1313     if (nullCheckEntry == 0 && qId < IX_QMGR_MIN_QUEUPP_QID)
1314     {
1315         /* get the queue status */
1316         UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);
1317
1318         if (status & infoPtr->qUflowStatBitMask)
1319         {
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;
1324         }
1325     }
1326
1327     return IX_SUCCESS;
1328 }
1329 #endif
1330
1331 /**
1332  * @ingroup IxQMgrAPI
1333  *
1334  * @fn ixQMgrQPeek (IxQMgrQId qId,
1335              unsigned int entryIndex,
1336              UINT32 *entry)
1337  *
1338  * @brief Read an entry from a queue without moving the read pointer.
1339  *
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.
1344  *
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).
1349  *
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
1354  *             specified index.
1355  * @return @li IX_FAIL, failed to inpected the queue entry.
1356  */
1357 PUBLIC IX_STATUS
1358 ixQMgrQPeek (IxQMgrQId qId,
1359              unsigned int entryIndex,
1360              UINT32 *entry);
1361
1362 /**
1363  *
1364  * @ingroup IxQMgrAPI
1365  *
1366  * @fn ixQMgrQWriteWithChecks (IxQMgrQId qId,
1367                         UINT32 *entry)
1368  *
1369  * @brief Write an entry to an AQM queue.
1370  *
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.
1375  *
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.
1378  *
1379  * @param qId @ref IxQMgrQId [in] - the queue identifier.
1380  * @param *entry UINT32 [in] - the word(s) to write.
1381  *
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
1386  *
1387  */
1388 PUBLIC IX_STATUS
1389 ixQMgrQWriteWithChecks (IxQMgrQId qId,
1390                         UINT32 *entry);
1391
1392 /**
1393  *
1394  * @ingroup IxQMgrAPI
1395  *
1396  * @fn ixQMgrQWrite (IxQMgrQId qId,
1397               UINT32 *entry)
1398  *
1399  * @brief Fast write of an entry to a queue.
1400  *
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.
1404  *
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
1409  * overflow.
1410  *
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.
1413  *
1414  * @param  qId @ref IxQMgrQId [in]   - the queue identifier.
1415  * @param  *entry UINT32 [in] - pointer to the entry word(s).
1416  *
1417  * @return @li IX_SUCCESS, entry was successfully read.
1418  * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue
1419  *
1420  */
1421 #ifdef NO_INLINE_APIS
1422 PUBLIC IX_STATUS
1423 ixQMgrQWrite (IxQMgrQId qId,
1424               UINT32 *entry);
1425 #else
1426 IX_QMGR_INLINE PUBLIC IX_STATUS
1427 ixQMgrQWrite (IxQMgrQId qId,
1428               UINT32 *entry);
1429 #endif /* NO_INLINE_APIS */
1430
1431 IX_QMGR_INLINE PUBLIC IX_STATUS
1432 ixQMgrQWrite (IxQMgrQId qId,
1433               UINT32 *entry)
1434 #ifdef NO_INLINE_APIS
1435     ;
1436 #else
1437 {
1438     IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];
1439     UINT32 entrySize;
1440
1441     /* write the entry */
1442     IX_QMGR_INLINE_WRITE_LONG(infoPtr->qAccRegAddr, *entry);
1443     entrySize = infoPtr->qEntrySizeInWords;
1444
1445     if (entrySize != IX_QMGR_Q_ENTRY_SIZE1)
1446     {
1447         /* process the remaining part of the entry */
1448         volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr;
1449         while (--entrySize)
1450         {
1451             ++entry;
1452             IX_QMGR_INLINE_WRITE_LONG(++qAccRegAddr, *entry);
1453         }
1454         entrySize = infoPtr->qEntrySizeInWords;
1455     }
1456
1457     /* overflow is available for lower queues only */
1458     if (qId < IX_QMGR_MIN_QUEUPP_QID)
1459     {
1460         UINT32 qSize = infoPtr->qSizeInEntries;
1461         /* increment the current number of entries in the queue
1462          * and check for overflow
1463          */
1464         if (infoPtr->qWriteCount++ == qSize)
1465         {
1466             /* the queue may have overflow */
1467             UINT32 qPtrs; /* queue internal pointers */
1468
1469             /* get the queue status */
1470             UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);
1471
1472             /* read the status twice because the status may
1473              * not be immediately ready after the write operation
1474              */
1475             if ((status & infoPtr->qOflowStatBitMask) ||
1476                 ((status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr))
1477                  & infoPtr->qOflowStatBitMask))
1478             {
1479                 /* the queue is full, clear the overflow status
1480                  *  bit if it was set
1481                  */
1482                 IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr,
1483                                      status & ~infoPtr->qOflowStatBitMask);
1484                 infoPtr->qWriteCount = infoPtr->qSizeInEntries;
1485                 return IX_QMGR_Q_OVERFLOW;
1486             }
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
1490              */
1491
1492             /* get q pointer snapshot */
1493             qPtrs = IX_QMGR_INLINE_READ_LONG(infoPtr->qConfigRegAddr);
1494
1495             /* Mod subtraction of pointers to get number of words in Q. */
1496             qPtrs = (qPtrs - (qPtrs >> 7)) & 0x7f;
1497
1498             if (qPtrs == 0)
1499             {
1500                 /* the queue may be full at the time of the
1501                  * snapshot. Next access will check
1502                  * the overflow status again.
1503                  */
1504                 infoPtr->qWriteCount = qSize;
1505             }
1506             else
1507             {
1508                 /* convert the number of words to a number of entries */
1509                 if (entrySize == IX_QMGR_Q_ENTRY_SIZE1)
1510                 {
1511                     infoPtr->qWriteCount = qPtrs & (qSize - 1);
1512                 }
1513                 else
1514                 {
1515                     infoPtr->qWriteCount = (qPtrs / entrySize) & (qSize - 1);
1516                 }
1517             }
1518         }
1519     }
1520     return IX_SUCCESS;
1521 }
1522 #endif
1523
1524 /**
1525  *
1526  * @ingroup IxQMgrAPI
1527  *
1528  * @fn ixQMgrQBurstWrite (IxQMgrQId qId,
1529                    unsigned numEntries,
1530                    UINT32 *entries)
1531  *
1532  * @brief Write a number of entries to an AQM queue.
1533  *
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.
1538  *
1539  * @warning
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.
1543  *
1544  * @note
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.
1557  *
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.
1561  *
1562  * @return @li IX_SUCCESS, value was successfully written.
1563  * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue
1564  *
1565  */
1566 #ifdef NO_INLINE_APIS
1567 PUBLIC IX_STATUS
1568 ixQMgrQBurstWrite (IxQMgrQId qId,
1569                    unsigned numEntries,
1570                    UINT32 *entries);
1571 #else
1572 IX_QMGR_INLINE PUBLIC IX_STATUS
1573 ixQMgrQBurstWrite (IxQMgrQId qId,
1574                    unsigned numEntries,
1575                    UINT32 *entries);
1576 #endif /* NO_INLINE_APIS */
1577
1578 IX_QMGR_INLINE PUBLIC IX_STATUS
1579 ixQMgrQBurstWrite (IxQMgrQId qId,
1580                    unsigned numEntries,
1581                    UINT32 *entries)
1582 #ifdef NO_INLINE_APIS
1583 ;
1584 #else
1585 {
1586     IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];
1587     UINT32 status;
1588
1589     /* update the current write count */
1590     infoPtr->qWriteCount += numEntries;
1591
1592     if (infoPtr->qEntrySizeInWords == IX_QMGR_Q_ENTRY_SIZE1)
1593     {
1594         volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr;
1595         while (numEntries--)
1596         {
1597             IX_QMGR_INLINE_WRITE_LONG(qAccRegAddr, *entries);
1598             entries++;
1599         }
1600     }
1601     else
1602     {
1603         IxQMgrQEntrySizeInWords entrySizeInWords = infoPtr->qEntrySizeInWords;
1604         UINT32 i;
1605
1606         /* write each queue entry */
1607         while (numEntries--)
1608         {
1609             /* write the queueEntrySize number of words for each entry */
1610             for (i = 0; i < (UINT32)entrySizeInWords; i++)
1611             {
1612                 IX_QMGR_INLINE_WRITE_LONG((infoPtr->qAccRegAddr + i), *entries);
1613                 entries++;
1614             }
1615         }
1616     }
1617
1618     /* check if the write count overflows */
1619     if (infoPtr->qWriteCount > infoPtr->qSizeInEntries)
1620     {
1621         /* reset the current write count */
1622         infoPtr->qWriteCount = infoPtr->qSizeInEntries;
1623     }
1624
1625     /* Check if overflow occurred on the write operation */
1626     if (qId < IX_QMGR_MIN_QUEUPP_QID)
1627     {
1628         /* get the queue status */
1629         status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);
1630
1631         /* read the status twice because the status may
1632          * not be ready at the time of the write
1633          */
1634         if ((status & infoPtr->qOflowStatBitMask) ||
1635             ((status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr))
1636              & infoPtr->qOflowStatBitMask))
1637         {
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;
1642         }
1643     }
1644
1645     return IX_SUCCESS;
1646 }
1647 #endif
1648
1649 /**
1650  * @ingroup IxQMgrAPI
1651  *
1652  * @fn ixQMgrQPoke (IxQMgrQId qId,
1653              unsigned int entryIndex,
1654              UINT32 *entry)
1655  *
1656  * @brief Write an entry to a queue without moving the write pointer.
1657  *
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.
1662  *
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).
1667  *
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
1672  *             specified index.
1673  * @return @li IX_FAIL, failed to modify the queue entry.
1674  */
1675 PUBLIC IX_STATUS
1676 ixQMgrQPoke (IxQMgrQId qId,
1677              unsigned int entryIndex,
1678              UINT32 *entry);
1679
1680 /**
1681  *
1682  * @ingroup IxQMgrAPI
1683  *
1684  * @fn ixQMgrQNumEntriesGet (IxQMgrQId qId,
1685                       unsigned *numEntries)
1686  *
1687  * @brief Get a snapshot of the number of entries in a queue.
1688  *
1689  * This function gets the number of entries in a queue.
1690  *
1691  * @param qId @ref IxQMgrQId [in] qId - the queue idenfifier
1692  * @param *numEntries unsigned [out] - the number of entries in a queue
1693  *
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
1698  *
1699  */
1700 PUBLIC IX_STATUS
1701 ixQMgrQNumEntriesGet (IxQMgrQId qId,
1702                       unsigned *numEntries);
1703
1704 /**
1705  *
1706  * @ingroup IxQMgrAPI
1707  *
1708  * @fn ixQMgrQStatusGetWithChecks (IxQMgrQId qId,
1709                             IxQMgrQStatus *qStatus)
1710  *
1711  * @brief Get a queues status.
1712  *
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.
1716  *
1717  * @param qId @ref IxQMgrQId [in] - the queue identifier.
1718  * @param &qStatus @ref IxQMgrQStatus [out] - the status of the specified queue.
1719  *
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.
1723  *
1724  */
1725 PUBLIC IX_STATUS
1726 ixQMgrQStatusGetWithChecks (IxQMgrQId qId,
1727                             IxQMgrQStatus *qStatus);
1728
1729 /**
1730  *
1731  * @ingroup IxQMgrAPI
1732  *
1733  * @fn ixQMgrQStatusGet (IxQMgrQId qId,
1734                   IxQMgrQStatus *qStatus)
1735  *
1736  * @brief Fast get of a queue's status.
1737  *
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.
1742  *
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.
1747  *
1748  * @param qId @ref IxQMgrQId [in] - the queue identifier.
1749  * @param *qStatus @ref IxQMgrQStatus [out] - the status of the specified queue.
1750  *
1751  * @return @li void.
1752  *
1753  */
1754
1755 #ifdef NO_INLINE_APIS
1756 PUBLIC IX_STATUS
1757 ixQMgrQStatusGet (IxQMgrQId qId,
1758                   IxQMgrQStatus *qStatus);
1759 #else
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[];
1767
1768 IX_QMGR_INLINE PUBLIC IX_STATUS
1769 ixQMgrQStatusGet (IxQMgrQId qId,
1770                   IxQMgrQStatus *qStatus);
1771 #endif  /* endif NO_INLINE_APIS */
1772
1773 IX_QMGR_INLINE PUBLIC IX_STATUS
1774 ixQMgrQStatusGet (IxQMgrQId qId,
1775                   IxQMgrQStatus *qStatus)
1776 #ifdef NO_INLINE_APIS
1777     ;
1778 #else
1779 {
1780     /* read the status of a queue in the range 0-31 */
1781     if (qId < IX_QMGR_MIN_QUEUPP_QID)
1782     {
1783         volatile UINT32 *lowStatRegAddr = (UINT32*)ixQMgrAqmIfQueLowStatRegAddr[qId];
1784
1785         UINT32 lowStatBitsOffset = ixQMgrAqmIfQueLowStatBitsOffset[qId];
1786         UINT32 lowStatBitsMask   = ixQMgrAqmIfQueLowStatBitsMask;
1787
1788         /* read the status register for this queue */
1789         *qStatus = IX_QMGR_INLINE_READ_LONG(lowStatRegAddr);
1790
1791         /* mask out the status bits relevant only to this queue */
1792         *qStatus = (*qStatus >> lowStatBitsOffset) & lowStatBitsMask;
1793
1794     }
1795     else /* read status of a queue in the range 32-63 */
1796     {
1797
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];
1803
1804         /* Reset the status bits */
1805         *qStatus = 0;
1806
1807         /* Check if the queue is nearly empty */
1808         if (IX_QMGR_INLINE_READ_LONG(qNearEmptyStatRegAddr) & qNearEmptyStatBitMask)
1809         {
1810             *qStatus |= IX_QMGR_Q_STATUS_NE_BIT_MASK;
1811         }
1812
1813         /* Check if the queue is full */
1814         if (IX_QMGR_INLINE_READ_LONG(qFullStatRegAddr) & qFullStatBitMask)
1815         {
1816             *qStatus |= IX_QMGR_Q_STATUS_F_BIT_MASK;
1817         }
1818     }
1819     return IX_SUCCESS;
1820 }
1821 #endif
1822
1823 /* ------------------------------------------------------------
1824    Queue dispatch related functions
1825    ---------------------------------------------------------- */
1826
1827 /**
1828  *
1829  * @ingroup IxQMgrAPI
1830  *
1831  * @fn ixQMgrDispatcherPrioritySet (IxQMgrQId qId,
1832                              IxQMgrPriority priority)
1833  *
1834  * @brief Set the dispatch priority of a queue.
1835  *
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.
1840  *
1841  * This function is re-entrant. and can be used from an interrupt context
1842  *
1843  * @param qId @ref IxQMgrQId [in] - the queue identifier
1844  * @param priority @ref IxQMgrPriority [in] - the new queue dispatch priority
1845  *
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
1849  *
1850  */
1851 PUBLIC IX_STATUS
1852 ixQMgrDispatcherPrioritySet (IxQMgrQId qId,
1853                              IxQMgrPriority priority);
1854 /**
1855  *
1856  * @ingroup IxQMgrAPI
1857  *
1858  * @fn ixQMgrNotificationEnable (IxQMgrQId qId,
1859                           IxQMgrSourceId sourceId)
1860  *
1861  * @brief Enable notification on a queue for a specified queue source flag.
1862  *
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
1872  * is returned.
1873  *
1874  * This function is re-entrant. and can be used from an interrupt context
1875  *
1876  * @param qId @ref IxQMgrQId [in] - the queue identifier
1877  * @param sourceId @ref IxQMgrSourceId [in] - the interrupt src condition identifier
1878  *
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
1883  *
1884  */
1885 PUBLIC IX_STATUS
1886 ixQMgrNotificationEnable (IxQMgrQId qId,
1887                           IxQMgrSourceId sourceId);
1888
1889 /**
1890  * @ingroup IxQMgrAPI
1891  *
1892  * @fn ixQMgrNotificationDisable (IxQMgrQId qId)
1893  *
1894  * @brief Disable notifications on a queue.
1895  *
1896  * This function is called to disable notifications on a specified queue.
1897  *
1898  * This function is re-entrant. and can be used from an interrupt context
1899  *
1900  * @param qId @ref IxQMgrQId [in] - the queue identifier
1901  *
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
1904  *
1905  */
1906 PUBLIC IX_STATUS
1907 ixQMgrNotificationDisable (IxQMgrQId qId);
1908
1909 /**
1910  *
1911  * @ingroup IxQMgrAPI
1912  *
1913  * @fn ixQMgrDispatcherLoopRunA0 (IxQMgrDispatchGroup group)
1914  *
1915  * @brief Run the callback dispatcher.
1916  *
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
1924  * should be used.
1925  *
1926  * This function is not re-entrant.
1927  *
1928  * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which the
1929  *                                        dispatcher will run
1930  *
1931  * @return @li void
1932  *
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.
1936  *
1937  */
1938 PUBLIC void
1939 ixQMgrDispatcherLoopRunA0 (IxQMgrDispatchGroup group);
1940
1941 /**
1942  *
1943  * @ingroup IxQMgrAPI
1944  *
1945  * @fn ixQMgrDispatcherLoopRunB0 (IxQMgrDispatchGroup group)
1946  *
1947  * @brief Run the callback dispatcher.
1948  *
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.
1957  *
1958  * This function is not re-entrant.
1959  *
1960  * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which the
1961  *                                        dispatcher will run
1962  *
1963  * @return @li void
1964  *
1965  *
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.
1969  *
1970  */
1971 PUBLIC void
1972 ixQMgrDispatcherLoopRunB0 (IxQMgrDispatchGroup group);
1973
1974 /**
1975  *
1976  * @ingroup IxQMgrAPI
1977  *
1978  * @fn ixQMgrDispatcherLoopRunB0LLP (IxQMgrDispatchGroup group)
1979  *
1980  * @brief Run the callback dispatcher.
1981  *
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).
1988  *
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.
1999  *
2000  * This function is not re-entrant.
2001  *
2002  * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which
2003  *                                        the dispatcher will run
2004  *
2005  * @return @li void
2006  *
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.
2010  *
2011  */
2012 PUBLIC void
2013 ixQMgrDispatcherLoopRunB0LLP (IxQMgrDispatchGroup group);
2014
2015 /**
2016  *
2017  * @ingroup IxQMgrAPI
2018  *
2019  * @fn ixQMgrNotificationCallbackSet (IxQMgrQId qId,
2020                                IxQMgrCallback callback,
2021                                IxQMgrCallbackId callbackId)
2022  *
2023  * @brief Set the notification callback for a queue.
2024  *
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.
2029  *
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
2033  *
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
2036  *
2037  */
2038 PUBLIC IX_STATUS
2039 ixQMgrNotificationCallbackSet (IxQMgrQId qId,
2040                                IxQMgrCallback callback,
2041                                IxQMgrCallbackId callbackId);
2042
2043 /**
2044  *
2045  * @ingroup IxQMgrAPI
2046  *
2047  * @fn ixQMgrDispatcherLoopGet (IxQMgrDispatcherFuncPtr *qDispatcherFuncPtr)
2048  *
2049  * @brief Get QMgr DispatcherLoopRun for respective silicon device
2050  *
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.
2055  *
2056  * @param *qDispatchFuncPtr @ref IxQMgrDispatcherFuncPtr [out]  -
2057  *              the function pointer of QMgr Dispatcher
2058  *
2059  */
2060 PUBLIC void
2061 ixQMgrDispatcherLoopGet (IxQMgrDispatcherFuncPtr *qDispatcherFuncPtr);
2062
2063 /**
2064  *
2065  * @ingroup IxQMgrAPI
2066  *
2067  * @fn ixQMgrStickyInterruptRegEnable(void)
2068  *
2069  * @brief Enable AQM's sticky interrupt register behaviour only available
2070  *        on B0 Silicon.
2071  *
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.
2075  *
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.
2079  *
2080  * @return none
2081  *
2082  */
2083 PUBLIC void
2084 ixQMgrStickyInterruptRegEnable(void);
2085
2086
2087 /**
2088  * @ingroup IxQMgrAPI
2089  *
2090  * @fn ixQMgrCallbackTypeSet(IxQMgrQId qId,
2091                              IxQMgrType type)
2092  *
2093  * @brief Set the Callback Type of a queue.
2094  *
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.
2104  *
2105  * @param qId @ref IxQMgrQId [in] - the queue identifier
2106  * @param type @ref IxQMgrType [in] - the type of callback
2107  *
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).
2111  *
2112  */
2113 PUBLIC IX_STATUS
2114 ixQMgrCallbackTypeSet(IxQMgrQId qId,
2115                       IxQMgrType type);
2116
2117 /**
2118  * @ingroup IxQMgrAPI
2119  *
2120  * @fn ixQMgrCallbackTypeGet(IxQMgrQId qId,
2121                              IxQMgrType *type)
2122  *
2123  * @brief Get the Callback Type of a queue.
2124  *
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.
2129  *
2130  * @param qId @ref IxQMgrQId [in] - the queue identifier
2131  * @param *type @ref IxQMgrType [out] - the type of callback
2132  *
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)
2136  *
2137  */
2138 PUBLIC IX_STATUS
2139 ixQMgrCallbackTypeGet(IxQMgrQId qId,
2140                       IxQMgrType *type);
2141
2142 /**
2143  * @ingroup IxQMgrAPI
2144  *
2145  * @fn ixQMgrPeriodicDone(void)
2146  *
2147  * @brief Indicate that the Periodic task is completed for LLP
2148  *
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.
2156  *
2157  */
2158 PUBLIC void
2159 ixQMgrPeriodicDone(void);
2160
2161
2162 /**
2163  * @ingroup IxQMgrAPI
2164  *
2165  * @fn ixQMgrLLPShow(int resetStats)
2166  *
2167  * @brief Print out the live lock prevention statistics when in debug mode.
2168  *
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.
2172  *
2173  * @param resetStats @ref int [in] - if set the the stats are reset.
2174  *
2175  */
2176 PUBLIC void
2177 ixQMgrLLPShow(int resetStats);
2178
2179
2180 #endif /* IXQMGR_H */
2181
2182 /**
2183  * @} defgroup IxQMgrAPI
2184  */
2185
2186