cpu/ixp/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  * Redistribution and use in source and binary forms, with or without
  35  * modification, are permitted provided that the following conditions
  36  * are met:
  37  * 1. Redistributions of source code must retain the above copyright
  38  *    notice, this list of conditions and the following disclaimer.
  39  * 2. Redistributions in binary form must reproduce the above copyright
  40  *    notice, this list of conditions and the following disclaimer in the
  41  *    documentation and/or other materials provided with the distribution.
  42  * 3. Neither the name of the Intel Corporation nor the names of its contributors
  43  *    may be used to endorse or promote products derived from this software
  44  *    without specific prior written permission.
  45  *
  46  * @par
  47  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
  48  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  49  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  50  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
  51  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  52  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  53  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  54  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  55  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  56  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  57  * SUCH DAMAGE.
  58  *
  59  * @par
  60  * -- End of Copyright Notice --
  61 */
  62
  63 /* ------------------------------------------------------
  64    Doxygen group definitions
  65    ------------------------------------------------------ */
  66 /**
  67  * @defgroup IxQMgrAPI IXP400 Queue Manager (IxQMgr) API
  68  *
  69  * @brief The public API for the IXP400 QMgr component.
  70  *
  71  * IxQMgr is a low level interface to the AHB Queue Manager
  72  *
  73  * @{
  74  */
  75
  76 #ifndef IXQMGR_H
  77 #define IXQMGR_H
  78
  79 /*
  80  * User defined include files
  81  */
  82
  83 #include "IxOsal.h"
  84
  85 /*
  86  * Define QMgr's IoMem macros, in DC mode if in LE
  87  * regular if in BE. (Note: For Linux LSP gold release
  88  * may need to adjust mode.
  89  */
  90 #if defined (__BIG_ENDIAN)
  91
  92 #define IX_QMGR_INLINE_READ_LONG IX_OSAL_READ_LONG_BE
  93 #define IX_QMGR_INLINE_WRITE_LONG IX_OSAL_WRITE_LONG_BE
  94
  95 #else
  96
  97 #define IX_QMGR_INLINE_READ_LONG IX_OSAL_READ_LONG_LE_DC
  98 #define IX_QMGR_INLINE_WRITE_LONG IX_OSAL_WRITE_LONG_LE_DC
  99
 100 #endif
 101
 102 /*
 103  * #defines and macros
 104  */
 105
 106 /**
 107 *
 108 * @ingroup IxQMgrAPI
 109 *
 110 * @def IX_QMGR_INLINE
 111 *
 112 * @brief Inline definition, for inlining of Queue Access functions on API
 113 *
 114 * Please read the header information in this file for more details on the
 115 * use of function inlining in this component.
 116 *
 117 */
 118
 119 #ifndef __wince
 120
 121 #ifdef IXQMGRQACCESS_C
 122 /* If IXQMGRQACCESS_C is set then the IxQmgrQAccess.c is including this file
 123    and must instantiate a concrete definition for each inlineable API function
 124    whether or not that function actually gets inlined. */
 125 #    ifdef NO_INLINE_APIS
 126 #        undef NO_INLINE_APIS
 127 #    endif
 128 #    define IX_QMGR_INLINE  /* Empty Define */
 129 #else
 130 #    ifndef NO_INLINE_APIS
 131 #       define IX_QMGR_INLINE IX_OSAL_INLINE_EXTERN
 132 #    else
 133 #       define IX_QMGR_INLINE /* Empty Define */
 134 #    endif
 135 #endif
 136
 137 #else /* ndef __wince */
 138
 139 #    ifndef NO_INLINE_APIS
 140 #       define NO_INLINE_APIS
 141 #    endif
 142 #    define IX_QMGR_INLINE
 143
 144 #endif
 145
 146
 147 /**
 148 *
 149 * @ingroup IxQMgrAPI
 150 *
 151 * @def IX_QMGR_MAX_NUM_QUEUES
 152 *
 153 * @brief Number of queues supported by the AQM.
 154 *
 155 * This constant is used to indicate the number of AQM queues
 156 *
 157 */
 158 #define IX_QMGR_MAX_NUM_QUEUES  64
 159
 160 /**
 161 *
 162 * @ingroup IxQMgrAPI
 163 *
 164 * @def IX_QMGR_MIN_QID
 165 *
 166 * @brief Minimum queue identifier.
 167 *
 168 * This constant is used to indicate the smallest queue identifier
 169 *
 170 */
 171 #define IX_QMGR_MIN_QID IX_QMGR_QUEUE_0
 172
 173 /**
 174 *
 175 * @ingroup IxQMgrAPI
 176 *
 177 * @def IX_QMGR_MAX_QID
 178 *
 179 * @brief Maximum queue identifier.
 180 *
 181 * This constant is used to indicate the largest queue identifier
 182 *
 183 */
 184 #define IX_QMGR_MAX_QID IX_QMGR_QUEUE_63
 185
 186 /**
 187 *
 188 * @ingroup IxQMgrAPI
 189 *
 190 * @def IX_QMGR_MIN_QUEUPP_QID
 191 *
 192 * @brief Minimum queue identifier for reduced functionality queues.
 193 *
 194 * This constant is used to indicate Minimum queue identifier for reduced
 195 * functionality queues
 196 *
 197 */
 198 #define IX_QMGR_MIN_QUEUPP_QID 32
 199
 200 /**
 201 *
 202 * @ingroup IxQMgrAPI
 203 *
 204 * @def IX_QMGR_MAX_QNAME_LEN
 205 *
 206 * @brief Maximum queue name length.
 207 *
 208 * This constant is used to indicate the maximum null terminated string length
 209 * (excluding '\0') for a queue name
 210 *
 211 */
 212 #define IX_QMGR_MAX_QNAME_LEN 16
 213
 214 /**
 215  *
 216  * @ingroup IxQMgrAPI
 217  *
 218  * @def IX_QMGR_WARNING
 219  *
 220  * @brief Warning return code.
 221  *
 222  * Execution complete, but there is a special case to handle
 223  *
 224  */
 225 #define IX_QMGR_WARNING 2
 226
 227 /**
 228  *
 229  * @ingroup IxQMgrAPI
 230  *
 231  * @def IX_QMGR_PARAMETER_ERROR
 232  *
 233  * @brief Parameter error return code (NULL pointer etc..).
 234  *
 235  * parameter error out of range/invalid
 236  *
 237  */
 238 #define IX_QMGR_PARAMETER_ERROR 3
 239
 240 /**
 241  *
 242  * @ingroup IxQMgrAPI
 243  *
 244  * @def IX_QMGR_INVALID_Q_ENTRY_SIZE
 245  *
 246  * @brief Invalid entry size return code.
 247  *
 248  * Invalid queue entry size for a queue read/write
 249  *
 250  */
 251 #define IX_QMGR_INVALID_Q_ENTRY_SIZE 4
 252
 253 /**
 254  *
 255  * @ingroup IxQMgrAPI
 256  *
 257  * @def IX_QMGR_INVALID_Q_ID
 258  *
 259  * @brief Invalid queue identifier return code.
 260  *
 261  * Invalid queue id, not in range 0-63
 262  *
 263  */
 264 #define IX_QMGR_INVALID_Q_ID 5
 265
 266 /**
 267  *
 268  * @ingroup IxQMgrAPI
 269  *
 270  * @def IX_QMGR_INVALID_CB_ID
 271  *
 272  * @brief Invalid callback identifier return code.
 273  *
 274  * Invalid callback id
 275  */
 276 #define IX_QMGR_INVALID_CB_ID 6
 277
 278 /**
 279  *
 280  * @ingroup IxQMgrAPI
 281  *
 282  * @def IX_QMGR_CB_ALREADY_SET
 283  *
 284  * @brief Callback set error return code.
 285  *
 286  * The specified callback has already been for this queue
 287  *
 288  */
 289 #define IX_QMGR_CB_ALREADY_SET 7
 290
 291 /**
 292  *
 293  * @ingroup IxQMgrAPI
 294  *
 295  * @def IX_QMGR_NO_AVAILABLE_SRAM
 296  *
 297  * @brief Sram consumed return code.
 298  *
 299  * All AQM Sram is consumed by queue configuration
 300  *
 301  */
 302 #define IX_QMGR_NO_AVAILABLE_SRAM 8
 303
 304 /**
 305  *
 306  * @ingroup IxQMgrAPI
 307  *
 308  * @def IX_QMGR_INVALID_INT_SOURCE_ID
 309  *
 310  * @brief Invalid queue interrupt source identifier return code.
 311  *
 312  * Invalid queue interrupt source given for notification enable
 313  */
 314 #define IX_QMGR_INVALID_INT_SOURCE_ID 9
 315
 316 /**
 317  *
 318  * @ingroup IxQMgrAPI
 319  *
 320  * @def IX_QMGR_INVALID_QSIZE
 321  *
 322  * @brief Invalid queue size error code.
 323  *
 324  * Invalid queue size not one of 16,32, 64, 128
 325  *
 326  *
 327  */
 328 #define IX_QMGR_INVALID_QSIZE 10
 329
 330 /**
 331  *
 332  * @ingroup IxQMgrAPI
 333  *
 334  * @def IX_QMGR_INVALID_Q_WM
 335  *
 336  * @brief Invalid queue watermark return code.
 337  *
 338  * Invalid queue watermark given for watermark set
 339  */
 340 #define IX_QMGR_INVALID_Q_WM 11
 341
 342 /**
 343  *
 344  * @ingroup IxQMgrAPI
 345  *
 346  * @def IX_QMGR_Q_NOT_CONFIGURED
 347  *
 348  * @brief Queue not configured return code.
 349  *
 350  * Returned to the client when a function has been called on an unconfigured
 351  * queue
 352  *
 353  */
 354 #define IX_QMGR_Q_NOT_CONFIGURED 12
 355
 356 /**
 357  *
 358  * @ingroup IxQMgrAPI
 359  *
 360  * @def IX_QMGR_Q_ALREADY_CONFIGURED
 361  *
 362  * @brief Queue already configured return code.
 363  *
 364  * Returned to client to indicate that a queue has already been configured
 365  */
 366 #define IX_QMGR_Q_ALREADY_CONFIGURED 13
 367
 368 /**
 369  *
 370  * @ingroup IxQMgrAPI
 371  *
 372  * @def IX_QMGR_Q_UNDERFLOW
 373  *
 374  * @brief Underflow return code.
 375  *
 376  * Underflow on a queue read has occurred
 377  *
 378  */
 379 #define IX_QMGR_Q_UNDERFLOW 14
 380
 381 /**
 382  *
 383  * @ingroup IxQMgrAPI
 384  *
 385  * @def IX_QMGR_Q_OVERFLOW
 386  *
 387  * @brief Overflow return code.
 388  *
 389  * Overflow on a queue write has occurred
 390  *
 391  */
 392 #define IX_QMGR_Q_OVERFLOW 15
 393
 394 /**
 395  *
 396  * @ingroup IxQMgrAPI
 397  *
 398  * @def IX_QMGR_Q_INVALID_PRIORITY
 399  *
 400  * @brief Invalid priority return code.
 401  *
 402  * Invalid priority, not one of 0,1,2
 403  */
 404 #define IX_QMGR_Q_INVALID_PRIORITY 16
 405
 406 /**
 407  *
 408  * @ingroup IxQMgrAPI
 409  *
 410  * @def IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS
 411  *
 412  * @brief  Entry index out of bounds return code.
 413  *
 414  * Entry index is greater than number of entries in queue.
 415  */
 416 #define IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS 17
 417
 418 /**
 419  *
 420  * @ingroup IxQMgrAPI
 421  *
 422  * @def ixQMgrDispatcherLoopRun
 423  *
 424  * @brief  Map old function name ixQMgrDispatcherLoopRun ()
 425  *         to @ref ixQMgrDispatcherLoopRunA0 ().
 426  *
 427  */
 428 #define ixQMgrDispatcherLoopRun ixQMgrDispatcherLoopRunA0
 429
 430
 431 /**
 432  *
 433  * @ingroup IxQMgrAPI
 434  *
 435  * @def IX_QMGR_QUEUE
 436  *
 437  * @brief  Definition of AQM queue numbers
 438  *
 439  */
 440 #define IX_QMGR_QUEUE_0 (0)      /**< Queue Number 0 */
 441 #define IX_QMGR_QUEUE_1 (1)      /**< Queue Number 1 */
 442 #define IX_QMGR_QUEUE_2 (2)      /**< Queue Number 2 */
 443 #define IX_QMGR_QUEUE_3 (3)      /**< Queue Number 3 */
 444 #define IX_QMGR_QUEUE_4 (4)      /**< Queue Number 4 */
 445 #define IX_QMGR_QUEUE_5 (5)      /**< Queue Number 5 */
 446 #define IX_QMGR_QUEUE_6 (6)      /**< Queue Number 6 */
 447 #define IX_QMGR_QUEUE_7 (7)      /**< Queue Number 7 */
 448 #define IX_QMGR_QUEUE_8 (8)      /**< Queue Number 8 */
 449 #define IX_QMGR_QUEUE_9 (9)      /**< Queue Number 9 */
 450 #define IX_QMGR_QUEUE_10 (10)    /**< Queue Number 10 */
 451 #define IX_QMGR_QUEUE_11 (11)    /**< Queue Number 11 */
 452 #define IX_QMGR_QUEUE_12 (12)    /**< Queue Number 12 */
 453 #define IX_QMGR_QUEUE_13 (13)    /**< Queue Number 13 */
 454 #define IX_QMGR_QUEUE_14 (14)    /**< Queue Number 14 */
 455 #define IX_QMGR_QUEUE_15 (15)    /**< Queue Number 15 */
 456 #define IX_QMGR_QUEUE_16 (16)    /**< Queue Number 16 */
 457 #define IX_QMGR_QUEUE_17 (17)    /**< Queue Number 17 */
 458 #define IX_QMGR_QUEUE_18 (18)    /**< Queue Number 18 */
 459 #define IX_QMGR_QUEUE_19 (19)    /**< Queue Number 19 */
 460 #define IX_QMGR_QUEUE_20 (20)    /**< Queue Number 20 */
 461 #define IX_QMGR_QUEUE_21 (21)    /**< Queue Number 21 */
 462 #define IX_QMGR_QUEUE_22 (22)    /**< Queue Number 22 */
 463 #define IX_QMGR_QUEUE_23 (23)    /**< Queue Number 23 */
 464 #define IX_QMGR_QUEUE_24 (24)    /**< Queue Number 24 */
 465 #define IX_QMGR_QUEUE_25 (25)    /**< Queue Number 25 */
 466 #define IX_QMGR_QUEUE_26 (26)    /**< Queue Number 26 */
 467 #define IX_QMGR_QUEUE_27 (27)    /**< Queue Number 27 */
 468 #define IX_QMGR_QUEUE_28 (28)    /**< Queue Number 28 */
 469 #define IX_QMGR_QUEUE_29 (29)    /**< Queue Number 29 */
 470 #define IX_QMGR_QUEUE_30 (30)    /**< Queue Number 30 */
 471 #define IX_QMGR_QUEUE_31 (31)    /**< Queue Number 31 */
 472 #define IX_QMGR_QUEUE_32 (32)    /**< Queue Number 32 */
 473 #define IX_QMGR_QUEUE_33 (33)    /**< Queue Number 33 */
 474 #define IX_QMGR_QUEUE_34 (34)    /**< Queue Number 34 */
 475 #define IX_QMGR_QUEUE_35 (35)    /**< Queue Number 35 */
 476 #define IX_QMGR_QUEUE_36 (36)    /**< Queue Number 36 */
 477 #define IX_QMGR_QUEUE_37 (37)    /**< Queue Number 37 */
 478 #define IX_QMGR_QUEUE_38 (38)    /**< Queue Number 38 */
 479 #define IX_QMGR_QUEUE_39 (39)    /**< Queue Number 39 */
 480 #define IX_QMGR_QUEUE_40 (40)    /**< Queue Number 40 */
 481 #define IX_QMGR_QUEUE_41 (41)    /**< Queue Number 41 */
 482 #define IX_QMGR_QUEUE_42 (42)    /**< Queue Number 42 */
 483 #define IX_QMGR_QUEUE_43 (43)    /**< Queue Number 43 */
 484 #define IX_QMGR_QUEUE_44 (44)    /**< Queue Number 44 */
 485 #define IX_QMGR_QUEUE_45 (45)    /**< Queue Number 45 */
 486 #define IX_QMGR_QUEUE_46 (46)    /**< Queue Number 46 */
 487 #define IX_QMGR_QUEUE_47 (47)    /**< Queue Number 47 */
 488 #define IX_QMGR_QUEUE_48 (48)    /**< Queue Number 48 */
 489 #define IX_QMGR_QUEUE_49 (49)    /**< Queue Number 49 */
 490 #define IX_QMGR_QUEUE_50 (50)    /**< Queue Number 50 */
 491 #define IX_QMGR_QUEUE_51 (51)    /**< Queue Number 51 */
 492 #define IX_QMGR_QUEUE_52 (52)    /**< Queue Number 52 */
 493 #define IX_QMGR_QUEUE_53 (53)    /**< Queue Number 53 */
 494 #define IX_QMGR_QUEUE_54 (54)    /**< Queue Number 54 */
 495 #define IX_QMGR_QUEUE_55 (55)    /**< Queue Number 55 */
 496 #define IX_QMGR_QUEUE_56 (56)    /**< Queue Number 56 */
 497 #define IX_QMGR_QUEUE_57 (57)    /**< Queue Number 57 */
 498 #define IX_QMGR_QUEUE_58 (58)    /**< Queue Number 58 */
 499 #define IX_QMGR_QUEUE_59 (59)    /**< Queue Number 59 */
 500 #define IX_QMGR_QUEUE_60 (60)    /**< Queue Number 60 */
 501 #define IX_QMGR_QUEUE_61 (61)    /**< Queue Number 61 */
 502 #define IX_QMGR_QUEUE_62 (62)    /**< Queue Number 62 */
 503 #define IX_QMGR_QUEUE_63 (63)    /**< Queue Number 63 */
 504 #define IX_QMGR_QUEUE_INVALID (64)     /**< AQM Queue Number Delimiter */
 505
 506
 507 /*
 508  * Typedefs
 509  */
 510
 511 /**
 512  * @typedef IxQMgrQId
 513  *
 514  * @ingroup IxQMgrAPI
 515  *
 516  * @brief Used in the API to identify the AQM queues.
 517  *
 518  */
 519 typedef int IxQMgrQId;
 520
 521 /**
 522  * @typedef IxQMgrQStatus
 523  *
 524  * @ingroup IxQMgrAPI
 525  *
 526  * @brief Queue status.
 527  *
 528  * A queues status is defined by its relative fullness or relative emptiness.
 529  * Each of the queues 0-31 have Nearly Empty, Nearly Full, Empty, Full,
 530  * Underflow and Overflow status flags. Queues 32-63 have just Nearly Empty and
 531  * Full status flags.
 532  * The flags bit positions are outlined below:
 533  *
 534  *        OF - bit-5<br>
 535  *        UF - bit-4<br>
 536  *         F - bit-3<br>
 537  *        NF - bit-2<br>
 538  *        NE - bit-1<br>
 539  *         E - bit-0<br>
 540  *
 541  */
 542 typedef UINT32 IxQMgrQStatus;
 543
 544 /**
 545  * @enum IxQMgrQStatusMask
 546  *
 547  * @ingroup IxQMgrAPI
 548  *
 549  * @brief Queue status mask.
 550  *
 551  * Masks for extracting the individual status flags from the IxQMgrStatus
 552  * word.
 553  *
 554  */
 555 typedef enum
 556 {
 557     IX_QMGR_Q_STATUS_E_BIT_MASK  = 0x1,
 558     IX_QMGR_Q_STATUS_NE_BIT_MASK = 0x2,
 559     IX_QMGR_Q_STATUS_NF_BIT_MASK = 0x4,
 560     IX_QMGR_Q_STATUS_F_BIT_MASK  = 0x8,
 561     IX_QMGR_Q_STATUS_UF_BIT_MASK = 0x10,
 562     IX_QMGR_Q_STATUS_OF_BIT_MASK = 0x20
 563 } IxQMgrQStatusMask;
 564
 565 /**
 566  * @enum IxQMgrSourceId
 567  *
 568  * @ingroup IxQMgrAPI
 569  *
 570  * @brief Queue interrupt source select.
 571  *
 572  * This enum defines the different source conditions on a queue that result in
 573  * an interupt being fired by the AQM. Interrupt source is configurable for
 574  * queues 0-31 only. The interrupt source for queues 32-63 is hardwired to the
 575  * NE(Nearly Empty) status flag.
 576  *
 577  */
 578 typedef enum
 579 {
 580     IX_QMGR_Q_SOURCE_ID_E = 0,  /**< Queue Empty due to last read             */
 581     IX_QMGR_Q_SOURCE_ID_NE,     /**< Queue Nearly Empty due to last read      */
 582     IX_QMGR_Q_SOURCE_ID_NF,     /**< Queue Nearly Full due to last write      */
 583     IX_QMGR_Q_SOURCE_ID_F,      /**< Queue Full due to last write             */
 584     IX_QMGR_Q_SOURCE_ID_NOT_E,  /**< Queue Not Empty due to last write        */
 585     IX_QMGR_Q_SOURCE_ID_NOT_NE, /**< Queue Not Nearly Empty due to last write */
 586     IX_QMGR_Q_SOURCE_ID_NOT_NF, /**< Queue Not Nearly Full due to last read   */
 587     IX_QMGR_Q_SOURCE_ID_NOT_F   /**< Queue Not Full due to last read          */
 588 } IxQMgrSourceId;
 589
 590 /**
 591  * @enum IxQMgrQEntrySizeInWords
 592  *
 593  * @ingroup IxQMgrAPI
 594  *
 595  * @brief QMgr queue entry sizes.
 596  *
 597  * The entry size of a queue specifies the size of a queues entry in words.
 598  *
 599  */
 600 typedef enum
 601 {
 602     IX_QMGR_Q_ENTRY_SIZE1 = 1,   /**< 1 word entry       */
 603     IX_QMGR_Q_ENTRY_SIZE2 = 2,   /**< 2 word entry       */
 604     IX_QMGR_Q_ENTRY_SIZE4 = 4    /**< 4 word entry       */
 605 } IxQMgrQEntrySizeInWords;
 606
 607 /**
 608  * @enum IxQMgrQSizeInWords
 609  *
 610  * @ingroup IxQMgrAPI
 611  *
 612  * @brief QMgr queue sizes.
 613  *
 614  * These values define the allowed queue sizes for AQM queue. The sizes are
 615  * specified in words.
 616  *
 617  */
 618 typedef enum
 619 {
 620     IX_QMGR_Q_SIZE16 = 16,   /**< 16 word buffer     */
 621     IX_QMGR_Q_SIZE32 = 32,   /**< 32 word buffer     */
 622     IX_QMGR_Q_SIZE64 = 64,   /**< 64 word buffer     */
 623     IX_QMGR_Q_SIZE128 = 128, /**< 128 word buffer    */
 624     IX_QMGR_Q_SIZE_INVALID = 129  /**< Insure that this is greater than largest
 625                                     * queue size supported by the hardware
 626                                     */
 627 } IxQMgrQSizeInWords;
 628
 629 /**
 630  * @enum IxQMgrWMLevel
 631  *
 632  * @ingroup IxQMgrAPI
 633  *
 634  * @brief QMgr watermark levels.
 635  *
 636  * These values define the valid watermark levels(in ENTRIES) for queues. Each
 637  * queue 0-63 have configurable Nearly full and Nearly empty watermarks. For
 638  * queues 32-63 the Nearly full watermark has NO EFFECT.
 639  * If the Nearly full watermark is set to IX_QMGR_Q_WM_LEVEL16 this means that
 640  * the nearly full flag will be set by the hardware when there are >= 16 empty
 641  * entries in the specified queue.
 642  * If the Nearly empty watermark is set to IX_QMGR_Q_WM_LEVEL16 this means that
 643  * the Nearly empty flag will be set by the hardware when there are <= 16 full
 644  * entries in the specified queue.
 645  */
 646 typedef enum
 647 {
 648     IX_QMGR_Q_WM_LEVEL0 = 0,    /**< 0 entry watermark  */
 649     IX_QMGR_Q_WM_LEVEL1 = 1,    /**< 1 entry watermark  */
 650     IX_QMGR_Q_WM_LEVEL2 = 2,    /**< 2 entry watermark  */
 651     IX_QMGR_Q_WM_LEVEL4 = 4,    /**< 4 entry watermark  */
 652     IX_QMGR_Q_WM_LEVEL8 = 8,    /**< 8 entry watermark  */
 653     IX_QMGR_Q_WM_LEVEL16 = 16,  /**< 16 entry watermark */
 654     IX_QMGR_Q_WM_LEVEL32 = 32,  /**< 32 entry watermark */
 655     IX_QMGR_Q_WM_LEVEL64 = 64   /**< 64 entry watermark */
 656 } IxQMgrWMLevel;
 657
 658 /**
 659  * @ingroup IxQMgrAPI
 660  *
 661  * @enum IxQMgrDispatchGroup
 662  *
 663  * @brief QMgr dispatch group select identifiers.
 664  *
 665  * This enum defines the groups over which the  dispatcher will process when
 666  * called. One of the enum values must be used as a input to
 667  * @a ixQMgrDispatcherLoopRunA0, @a ixQMgrDispatcherLoopRunB0
 668  * or @a ixQMgrDispatcherLoopRunB0LLP.
 669  *
 670  */
 671 typedef enum
 672 {
 673     IX_QMGR_QUELOW_GROUP = 0, /**< Queues 0-31  */
 674     IX_QMGR_QUEUPP_GROUP      /**< Queues 32-63 */
 675 } IxQMgrDispatchGroup;
 676
 677 /**
 678  * @ingroup IxQMgrAPI
 679  *
 680  * @enum IxQMgrPriority
 681  *
 682  * @brief Dispatcher priority levels.
 683  *
 684  * This enum defines the different queue dispatch priority levels.
 685  * The lowest priority number (0) is the highest priority level.
 686  *
 687  */
 688 typedef enum
 689 {
 690   IX_QMGR_Q_PRIORITY_0 = 0,  /**< Priority level 0 */
 691   IX_QMGR_Q_PRIORITY_1,      /**< Priority level 1 */
 692   IX_QMGR_Q_PRIORITY_2,      /**< Priority level 2 */
 693   IX_QMGR_Q_PRIORITY_INVALID /**< Invalid Priority level */
 694 } IxQMgrPriority;
 695
 696 /**
 697  * @ingroup IxQMgrAPI
 698  *
 699  * @enum IxQMgrType
 700  *
 701  * @brief Callback types as used with livelock prevention
 702  *
 703  * This enum defines the different callback types.
 704  * These types are only used when Livelock prevention is enabled.
 705  * The default is IX_QMGR_TYPE_REALTIME_OTHER.
 706  *
 707  */
 708
 709 typedef enum
 710 {
 711   IX_QMGR_TYPE_REALTIME_OTHER = 0, /**< Real time callbacks-always allowed run*/
 712   IX_QMGR_TYPE_REALTIME_PERIODIC,  /**< Periodic callbacks-always allowed run */
 713   IX_QMGR_TYPE_REALTIME_SPORADIC   /**< Sporadic callbacks-only run if no
 714                                         periodic callbacks are in progress    */
 715 } IxQMgrType;
 716
 717
 718 /**
 719  * @ingroup IxQMgrAPI
 720  *
 721  * @typedef IxQMgrCallbackId
 722  *
 723  * @brief Uniquely identifies a callback function.
 724  *
 725  * A unique callback identifier associated with each callback
 726  * registered by clients.
 727  *
 728  */
 729 typedef unsigned IxQMgrCallbackId;
 730
 731 /**
 732  * @typedef IxQMgrCallback
 733  *
 734  * @brief QMgr notification callback type.
 735  *
 736  * This defines the interface to all client callback functions.
 737  *
 738  * @param qId @ref IxQMgrQId [in] - the queue identifier
 739  * @param cbId @ref IxQMgrCallbackId [in] - the callback identifier
 740  */
 741 typedef void (*IxQMgrCallback)(IxQMgrQId qId,
 742                                IxQMgrCallbackId cbId);
 743
 744 /**
 745  * @ingroup IxQMgrAPI
 746  *
 747  * @typedef IxQMgrDispatcherFuncPtr
 748  *
 749  * @brief QMgr Dispatcher Loop function pointer.
 750  *
 751  * This defines the interface for QMgr Dispather functions.
 752  *
 753  * @param group @ref IxQMgrDispatchGroup [in] - the group of the
 754  *                  queue of which the dispatcher will run
 755  */
 756 typedef void (*IxQMgrDispatcherFuncPtr)(IxQMgrDispatchGroup group);
 757
 758 /*
 759  * Function Prototypes
 760  */
 761
 762 /* ------------------------------------------------------------
 763    Initialisation related functions
 764    ---------------------------------------------------------- */
 765
 766 /**
 767  *
 768  * @ingroup IxQMgrAPI
 769  *
 770  * @fn ixQMgrInit (void)
 771  *
 772  * @brief Initialise the QMgr.
 773  *
 774  * This function must be called before and other QMgr function. It
 775  * sets up internal data structures.
 776  *
 777  * @return @li IX_SUCCESS, the IxQMgr successfully initialised
 778  * @return @li IX_FAIL, failed to initialize the Qmgr
 779  *
 780  */
 781 PUBLIC IX_STATUS
 782 ixQMgrInit (void);
 783
 784 /**
 785  *
 786  * @ingroup IxQMgrAPI
 787  *
 788  * @fn ixQMgrUnload (void)
 789  *
 790  * @brief Uninitialise the QMgr.
 791  *
 792  * This function will perform the tasks required to unload the QMgr component
 793  * cleanly.  This includes unmapping kernel memory.
 794  * This should be called before a soft reboot or unloading of a kernel module.
 795  *
 796  * @pre It should only be called if @ref ixQMgrInit has already been called.
 797  *
 798  * @post No QMgr functions should be called until ixQMgrInit is called again.
 799  *
 800  * @return @li IX_SUCCESS, the IxQMgr successfully uninitialised
 801  * @return @li IX_FAIL, failed to uninitialize the Qmgr
 802  *
 803  */
 804 PUBLIC IX_STATUS
 805 ixQMgrUnload (void);
 806
 807 /**
 808  *
 809  * @ingroup IxQMgrAPI
 810  *
 811  * @fn ixQMgrShow (void)
 812  *
 813  * @brief Describe queue configuration and statistics for active queues.
 814  *
 815  * This function shows active queues, their configurations and statistics.
 816  *
 817  * @return @li void
 818  *
 819  */
 820 PUBLIC void
 821 ixQMgrShow (void);
 822
 823 /**
 824  *
 825  * @ingroup IxQMgrAPI
 826  *
 827  * @fn ixQMgrQShow (IxQMgrQId qId)
 828  *
 829  * @brief Display aqueue configuration and statistics for a queue.
 830  *
 831  * This function shows queue configuration and statistics for a queue.
 832  *
 833  * @param qId @ref IxQMgrQId [in] - the queue identifier.
 834  *
 835  * @return @li IX_SUCCESS, success
 836  * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
 837  *
 838  */
 839 PUBLIC IX_STATUS
 840 ixQMgrQShow (IxQMgrQId qId);
 841
 842
 843 /* ------------------------------------------------------------
 844    Configuration related functions
 845    ---------------------------------------------------------- */
 846
 847 /**
 848  *
 849  * @ingroup IxQMgrAPI
 850  *
 851  * @fn ixQMgrQConfig (char *qName,
 852                IxQMgrQId qId,
 853                IxQMgrQSizeInWords qSizeInWords,
 854                IxQMgrQEntrySizeInWords qEntrySizeInWords)
 855  *
 856  * @brief Configure an AQM queue.
 857  *
 858  * This function is called by a client to setup a queue. The size and entrySize
 859  * qId and qName(NULL pointer) are checked for valid values. This function must
 860  * be called for each queue, before any queue accesses are made and after
 861  * ixQMgrInit() has been called. qName is assumed to be a '\0' terminated array
 862  * of 16 charachters or less.
 863  *
 864  * @param *qName char [in] - is the name provided by the client and is associated
 865  *                          with a QId by the QMgr.
 866  * @param qId @ref IxQMgrQId [in]  - the qId of this queue
 867  * @param qSizeInWords @ref IxQMgrQSize [in] - the size of the queue can be one of 16,32
 868  *                                       64, 128 words.
 869  * @param qEntrySizeInWords @ref IxQMgrQEntrySizeInWords [in] - the size of a queue entry
 870  *                                                        can be one of 1,2,4 words.
 871  *
 872  * @return @li IX_SUCCESS, a specified queue has been successfully configured.
 873  * @return @li IX_FAIL, IxQMgr has not been initialised.
 874  * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s).
 875  * @return @li IX_QMGR_INVALID_QSIZE, invalid queue size
 876  * @return @li IX_QMGR_INVALID_Q_ID, invalid queue id
 877  * @return @li IX_QMGR_INVALID_Q_ENTRY_SIZE, invalid queue entry size
 878  * @return @li IX_QMGR_Q_ALREADY_CONFIGURED, queue already configured
 879  *
 880  */
 881 PUBLIC IX_STATUS
 882 ixQMgrQConfig (char *qName,
 883                IxQMgrQId qId,
 884                IxQMgrQSizeInWords qSizeInWords,
 885                IxQMgrQEntrySizeInWords qEntrySizeInWords);
 886
 887 /**
 888  * @ingroup IxQMgrAPI
 889  *
 890  * @fn ixQMgrQSizeInEntriesGet (IxQMgrQId qId,
 891                          unsigned *qSizeInEntries)
 892  *
 893  * @brief Return the size of a queue in entries.
 894  *
 895  * This function returns the the size of the queue in entriese.
 896  *
 897  * @param qId @ref IxQMgrQId [in] - the queue identifier
 898  * @param *qSizeInEntries @ref IxQMgrQSize [out] - queue size in entries
 899  *
 900  * @return @li IX_SUCCESS, successfully retrieved the number of full entrie
 901  * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
 902  * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s).
 903  *
 904  */
 905 PUBLIC IX_STATUS
 906 ixQMgrQSizeInEntriesGet (IxQMgrQId qId,
 907                          unsigned *qSizeInEntries);
 908
 909 /**
 910  *
 911  * @ingroup IxQMgrAPI
 912  *
 913  * @fn ixQMgrWatermarkSet (IxQMgrQId qId,
 914                     IxQMgrWMLevel ne,
 915                     IxQMgrWMLevel nf)
 916  *
 917  * @brief Set the Nearly Empty and Nearly Full Watermarks fo a queue.
 918  *
 919  * This function is called by a client to set the watermarks NE and NF for the
 920  * queue specified by qId.
 921  * The queue must be empty at the time this function is called, it is the clients
 922  * responsibility to ensure that the queue is empty.
 923  * This function will read the status of the queue before the watermarks are set
 924  * and again after the watermarks are set. If the status register has changed,
 925  * due to a queue access by an NPE for example, a warning is returned.
 926  * Queues 32-63 only support the NE flag, therefore the value of nf will be ignored
 927  * for these queues.
 928  *
 929  * @param qId @ref IxQMgrQId [in] -  the QId of the queue.
 930  * @param ne @ref IxQMgrWMLevel [in]  - the NE(Nearly Empty) watermark for this
 931  *                                 queue. Valid values are 0,1,2,4,8,16,32 and
 932  *                                 64 entries.
 933  * @param nf @ref IxQMgrWMLevel [in] - the NF(Nearly Full) watermark for this queue.
 934  *                                 Valid values are 0,1,2,4,8,16,32 and 64
 935  *                                 entries.
 936  *
 937  * @return @li IX_SUCCESS, watermarks have been set for the queu
 938  * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
 939  * @return @li IX_QMGR_INVALID_Q_WM, invalid watermark
 940  * @return @li IX_QMGR_WARNING, the status register may not be constistent
 941  *
 942  */
 943 PUBLIC IX_STATUS
 944 ixQMgrWatermarkSet (IxQMgrQId qId,
 945                     IxQMgrWMLevel ne,
 946                     IxQMgrWMLevel nf);
 947
 948 /**
 949  * @ingroup IxQMgrAPI
 950  *
 951  * @fn ixQMgrAvailableSramAddressGet (UINT32 *address,
 952                                unsigned *sizeOfFreeSram)
 953  *
 954  * @brief Return the address of available AQM SRAM.
 955  *
 956  * This function returns the starting address in AQM SRAM not used by the
 957  * current queue configuration and should only be called after all queues
 958  * have been configured.
 959  * Calling this function before all queues have been configured will will return
 960  * the currently available SRAM. A call to configure another queue will use some
 961  * of the available SRAM.
 962  * The amount of SRAM available is specified in sizeOfFreeSram. The address is the
 963  * address of the bottom of available SRAM. Available SRAM extends from address
 964  * from address to address + sizeOfFreeSram.
 965  *
 966  * @param **address UINT32 [out] - the address of the available SRAM, NULL if
 967  *                                none available.
 968  * @param *sizeOfFreeSram unsigned [out]- the size in words of available SRAM
 969  *
 970  * @return @li IX_SUCCESS, there is available SRAM and is pointed to by address
 971  * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s)
 972  * @return @li IX_QMGR_NO_AVAILABLE_SRAM, all AQM SRAM is consumed by the queue
 973  *             configuration.
 974  *
 975  */
 976 PUBLIC IX_STATUS
 977 ixQMgrAvailableSramAddressGet (UINT32 *address,
 978                                unsigned *sizeOfFreeSram);
 979
 980
 981 /* ------------------------------------------------------------
 982    Queue access related functions
 983    ---------------------------------------------------------- */
 984
 985 /**
 986  *
 987  * @ingroup IxQMgrAPI
 988  *
 989  * @fn ixQMgrQReadWithChecks (IxQMgrQId qId,
 990                        UINT32 *entry)
 991  *
 992  * @brief Read an entry from a queue.
 993  *
 994  * This function reads an entire entry from a queue returning it in entry. The
 995  * queue configuration word is read to determine what entry size this queue is
 996  * configured for and then the number of words specified by the entry size is
 997  * read.  entry must be a pointer to a previously allocated array of sufficient
 998  * size to hold an entry.
 999  *
1000  * @note - IX_QMGR_Q_UNDERFLOW is only returned for queues 0-31 as queues 32-63
1001  * do not have an underflow status maintained.
1002  *
1003  * @param  qId @ref IxQMgrQId [in]   - the queue identifier.
1004  * @param  *entry UINT32 [out]  - pointer to the entry word(s).
1005  *
1006  * @return @li IX_SUCCESS, entry was successfully read.
1007  * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s).
1008  * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
1009  * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue
1010  *
1011  */
1012 PUBLIC IX_STATUS
1013 ixQMgrQReadWithChecks (IxQMgrQId qId,
1014                        UINT32 *entry);
1015
1016
1017
1018 /**
1019  * @brief Internal structure to facilitate inlining functions in IxQMgr.h
1020  */
1021 typedef struct
1022 {
1023     /* fields related to write functions */
1024     UINT32 qOflowStatBitMask;         /**< overflow status mask */
1025     UINT32 qWriteCount;               /**< queue write count */
1026
1027     /* fields related to read and write functions */
1028     volatile UINT32 *qAccRegAddr;     /**< access register */
1029     volatile UINT32 *qUOStatRegAddr;  /**< status register */
1030     volatile UINT32 *qConfigRegAddr;  /**< config register */
1031     UINT32 qEntrySizeInWords;         /**< queue entry size in words */
1032     UINT32 qSizeInEntries;            /**< queue size in entries */
1033
1034     /* fields related to read functions */
1035     UINT32 qUflowStatBitMask;         /**< underflow status mask */
1036     UINT32 qReadCount;                /**< queue read count */
1037 } IxQMgrQInlinedReadWriteInfo;
1038
1039
1040 /**
1041  *
1042  * @ingroup IxQMgrAPI
1043  *
1044  * @fn ixQMgrQReadMWordsMinus1 (IxQMgrQId qId,
1045                                 UINT32 *entry)
1046  *
1047  * @brief This function reads the remaining of the q entry
1048  *        for queues configured with many words.
1049  *        (the first word of the entry is already read
1050  *        in the inlined function and the entry pointer already
1051  *        incremented
1052  *
1053  * @param  qId @ref IxQMgrQId [in]  - the queue identifier.
1054  * @param  *entry UINT32 [out] - pointer to the entry word(s).
1055  *
1056  * @return @li IX_SUCCESS, entry was successfully read.
1057  * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue
1058  *
1059  */
1060 PUBLIC IX_STATUS
1061 ixQMgrQReadMWordsMinus1 (IxQMgrQId qId,
1062                          UINT32 *entry);
1063
1064
1065
1066 /**
1067  *
1068  * @ingroup IxQMgrAPI
1069  *
1070  * @fn ixQMgrQRead (IxQMgrQId qId,
1071              UINT32 *entry)
1072  *
1073  * @brief Fast read of an entry from a queue.
1074  *
1075  * This function is a heavily streamlined version of ixQMgrQReadWithChecks(),
1076  * but performs essentially the same task.  It reads an entire entry from a
1077  * queue, returning it in entry which must be a pointer to a previously
1078  * allocated array of sufficient size to hold an entry.
1079  *
1080  * @note - This function is inlined, to reduce unnecessary function call
1081  * overhead.  It does not perform any parameter checks, or update any statistics.
1082  * Also, it does not check that the queue specified by qId has been configured.
1083  * or is in range. It simply reads an entry from the queue, and checks for
1084  * underflow.
1085  *
1086  * @note - IX_QMGR_Q_UNDERFLOW is only returned for queues 0-31 as queues 32-63
1087  * do not have an underflow status maintained.
1088  *
1089  * @param  qId @ref IxQMgrQId [in] - the queue identifier.
1090  * @param  *entry UINT32 [out] - pointer to the entry word(s).
1091  *
1092  * @return @li IX_SUCCESS, entry was successfully read.
1093  * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue
1094  *
1095  */
1096 #ifdef NO_INLINE_APIS
1097 PUBLIC IX_STATUS
1098 ixQMgrQRead (IxQMgrQId qId,
1099              UINT32 *entryPtr);
1100 #else
1101 extern IxQMgrQInlinedReadWriteInfo ixQMgrQInlinedReadWriteInfo[];
1102 extern IX_STATUS ixQMgrQReadMWordsMinus1 (IxQMgrQId qId, UINT32 *entryPtr);
1103
1104 IX_QMGR_INLINE PUBLIC IX_STATUS
1105 ixQMgrQRead (IxQMgrQId qId,
1106              UINT32 *entryPtr);
1107 #endif
1108
1109 IX_QMGR_INLINE PUBLIC IX_STATUS
1110 ixQMgrQRead (IxQMgrQId qId,
1111              UINT32 *entryPtr)
1112 #ifdef NO_INLINE_APIS
1113     ;
1114 #else
1115 {
1116     IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];
1117     UINT32 entry, entrySize;
1118
1119     /* get a new entry */
1120     entrySize = infoPtr->qEntrySizeInWords;
1121     entry = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr);
1122
1123     if (entrySize != IX_QMGR_Q_ENTRY_SIZE1)
1124     {
1125         *entryPtr = entry;
1126         /* process the remaining part of the entry */
1127         return ixQMgrQReadMWordsMinus1(qId, entryPtr);
1128     }
1129
1130     /* underflow is available for lower queues only */
1131     if (qId < IX_QMGR_MIN_QUEUPP_QID)
1132     {
1133         /* the counter of queue entries is decremented. In happy
1134          * day scenario there are many entries in the queue
1135          * and the counter does not reach zero.
1136          */
1137         if (infoPtr->qReadCount-- == 0)
1138         {
1139             /* There is maybe no entry in the queue
1140              * qReadCount is now negative, but will be corrected before
1141              * the function returns.
1142              */
1143             UINT32 qPtrs; /* queue internal pointers */
1144
1145             /* when a queue is empty, the hw guarantees to return
1146              * a null value. If the value is not null, the queue is
1147              * not empty.
1148              */
1149             if (entry == 0)
1150             {
1151                 /* get the queue status */
1152                 UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);
1153
1154                 /* check the underflow status */
1155                 if (status & infoPtr->qUflowStatBitMask)
1156                 {
1157                     /* the queue is empty
1158                     *  clear the underflow status bit if it was set
1159                     */
1160                     IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr,
1161                                          status & ~infoPtr->qUflowStatBitMask);
1162                     *entryPtr = 0;
1163                     infoPtr->qReadCount = 0;
1164                     return IX_QMGR_Q_UNDERFLOW;
1165                 }
1166             }
1167             /* store the result */
1168             *entryPtr = entry;
1169
1170             /* No underflow occured : someone is filling the queue
1171              * or the queue contains null entries.
1172              * The current counter needs to be
1173              * updated from the current number of entries in the queue
1174              */
1175
1176             /* get snapshot of queue pointers */
1177             qPtrs = IX_QMGR_INLINE_READ_LONG(infoPtr->qConfigRegAddr);
1178
1179             /* Mod subtraction of pointers to get number of words in Q. */
1180             qPtrs = (qPtrs - (qPtrs >> 7)) & 0x7f;
1181
1182             if (qPtrs == 0)
1183             {
1184                 /* no entry in the queue */
1185                 infoPtr->qReadCount = 0;
1186             }
1187             else
1188             {
1189                 /* convert the number of words inside the queue
1190                  * to a number of entries
1191                  */
1192                 infoPtr->qReadCount = qPtrs & (infoPtr->qSizeInEntries - 1);
1193             }
1194             return IX_SUCCESS;
1195         }
1196     }
1197     *entryPtr = entry;
1198     return IX_SUCCESS;
1199 }
1200 #endif
1201
1202 /**
1203  *
1204  * @ingroup IxQMgrAPI
1205  *
1206  * @fn ixQMgrQBurstRead (IxQMgrQId qId,
1207                   UINT32 numEntries,
1208                   UINT32 *entries)
1209  *
1210  * @brief Read a number of entries from an AQM queue.
1211  *
1212  * This function will burst read a number of entries from the specified queue.
1213  * The entry size of queue is auto-detected. The function will attempt to
1214  * read as many entries as specified by the numEntries parameter and will
1215  * return an UNDERFLOW if any one of the individual entry reads fail.
1216  *
1217  * @warning
1218  * IX_QMGR_Q_UNDERFLOW is only returned for queues 0-31 as queues 32-63
1219  * do not have an underflow status maintained, hence there is a potential for
1220  * silent failure here. This function must be used with caution.
1221  *
1222  * @note
1223  * This function is intended for fast draining of queues, so to make it
1224  * as efficient as possible, it has the following features:
1225  * - This function is inlined, to reduce unnecessary function call overhead.
1226  * - It does not perform any parameter checks, or update any statistics.
1227  * - It does not check that the queue specified by qId has been configured.
1228  * - It does not check that the queue has the number of full entries that
1229  * have been specified to be read. It will read until it finds a NULL entry or
1230  * until the number of specified entries have been read.  It always checks for
1231  * underflow after all the reads have been performed.
1232  * Therefore, the client should ensure before calling this function that there
1233  * are enough entries in the queue to read.  ixQMgrQNumEntriesGet() will
1234  * provide the number of full entries in a queue.
1235  * ixQMgrQRead() or ixQMgrQReadWithChecks(), which only reads
1236  * a single queue entry per call, should be used instead if the user requires
1237  * checks for UNDERFLOW after each entry read.
1238  *
1239  * @param qId @ref IxQMgrQId [in]   - the queue identifier.
1240  * @param numEntries unsigned [in] - the number of entries to read.
1241  *                     This number should be greater than 0
1242  * @param *entries UINT32 [out] - the word(s) read.
1243  *
1244  * @return @li IX_SUCCESS, entries were successfully read.
1245  * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue
1246  *
1247  */
1248 #ifdef NO_INLINE_APIS
1249 PUBLIC IX_STATUS
1250 ixQMgrQBurstRead (IxQMgrQId qId,
1251                   UINT32 numEntries,
1252                   UINT32 *entries);
1253 #else
1254 IX_QMGR_INLINE PUBLIC IX_STATUS
1255 ixQMgrQBurstRead (IxQMgrQId qId,
1256                   UINT32 numEntries,
1257                   UINT32 *entries);
1258 #endif  /* endif NO_INLINE_APIS */
1259
1260 IX_QMGR_INLINE PUBLIC IX_STATUS
1261 ixQMgrQBurstRead (IxQMgrQId qId,
1262                   UINT32 numEntries,
1263                   UINT32 *entries)
1264 #ifdef NO_INLINE_APIS
1265 ;
1266 #else
1267 {
1268     IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];
1269     UINT32 nullCheckEntry;
1270
1271     if (infoPtr->qEntrySizeInWords == IX_QMGR_Q_ENTRY_SIZE1)
1272     {
1273         volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr;
1274
1275         /* the code is optimized to take care of data dependencies:
1276          * Durig a read, there are a few cycles needed to get the
1277          * read complete. During these cycles, it is poossible to
1278          * do some CPU, e.g. increment pointers and decrement
1279          * counters.
1280          */
1281
1282         /* fetch a queue entry */
1283         nullCheckEntry = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr);
1284
1285         /* iterate the specified number of queue entries */
1286         while (--numEntries)
1287         {
1288             /* check the result of the previous read */
1289             if (nullCheckEntry == 0)
1290             {
1291                 /* if we read a NULL entry, stop. We have underflowed */
1292                 break;
1293             }
1294             else
1295             {
1296                 /* write the entry */
1297                 *entries = nullCheckEntry;
1298                 /* fetch next entry */
1299                 nullCheckEntry = IX_QMGR_INLINE_READ_LONG(qAccRegAddr);
1300                 /* increment the write address */
1301                 entries++;
1302             }
1303         }
1304         /* write the pre-fetched entry */
1305         *entries = nullCheckEntry;
1306     }
1307     else
1308     {
1309         IxQMgrQEntrySizeInWords entrySizeInWords = infoPtr->qEntrySizeInWords;
1310         /* read the specified number of queue entries */
1311         nullCheckEntry = 0;
1312         while (numEntries--)
1313         {
1314             UINT32 i;
1315
1316             for (i = 0; i < (UINT32)entrySizeInWords; i++)
1317             {
1318                 *entries = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr + i);
1319                 nullCheckEntry |= *entries++;
1320             }
1321
1322             /* if we read a NULL entry, stop. We have underflowed */
1323             if (nullCheckEntry == 0)
1324             {
1325                 break;
1326             }
1327             nullCheckEntry = 0;
1328         }
1329     }
1330
1331     /* reset the current read count : next access to the read function
1332      * will force a underflow status check
1333      */
1334     infoPtr->qReadCount = 0;
1335
1336     /* Check if underflow occurred on the read */
1337     if (nullCheckEntry == 0 && qId < IX_QMGR_MIN_QUEUPP_QID)
1338     {
1339         /* get the queue status */
1340         UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);
1341
1342         if (status & infoPtr->qUflowStatBitMask)
1343         {
1344             /* clear the underflow status bit if it was set */
1345             IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr,
1346                                  status & ~infoPtr->qUflowStatBitMask);
1347             return IX_QMGR_Q_UNDERFLOW;
1348         }
1349     }
1350
1351     return IX_SUCCESS;
1352 }
1353 #endif
1354
1355 /**
1356  * @ingroup IxQMgrAPI
1357  *
1358  * @fn ixQMgrQPeek (IxQMgrQId qId,
1359              unsigned int entryIndex,
1360              UINT32 *entry)
1361  *
1362  * @brief Read an entry from a queue without moving the read pointer.
1363  *
1364  * This function inspects an entry in a queue. The entry is inspected directly
1365  * in AQM SRAM and is not read from queue access registers. The entry is NOT removed
1366  * from the queue and the read/write pointers are unchanged.
1367  * N.B: The queue should not be accessed when this function is called.
1368  *
1369  * @param  qId @ref IxQMgrQId [in]   - the queue identifier.
1370  * @param  entryIndex unsigned int [in] - index of entry in queue in the range
1371  *                          [0].......[current number of entries in queue].
1372  * @param  *entry UINT32 [out] - pointer to the entry word(s).
1373  *
1374  * @return @li IX_SUCCESS, entry was successfully inspected.
1375  * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s).
1376  * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId.
1377  * @return @li IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS, an entry does not exist at
1378  *             specified index.
1379  * @return @li IX_FAIL, failed to inpected the queue entry.
1380  */
1381 PUBLIC IX_STATUS
1382 ixQMgrQPeek (IxQMgrQId qId,
1383              unsigned int entryIndex,
1384              UINT32 *entry);
1385
1386 /**
1387  *
1388  * @ingroup IxQMgrAPI
1389  *
1390  * @fn ixQMgrQWriteWithChecks (IxQMgrQId qId,
1391                         UINT32 *entry)
1392  *
1393  * @brief Write an entry to an AQM queue.
1394  *
1395  * This function will write the entry size number of words pointed to by entry to
1396  * the queue specified by qId. The queue configuration word is read to
1397  * determine the entry size of queue and the corresponding number of words is
1398  * then written to the queue.
1399  *
1400  * @note - IX_QMGR_Q_OVERFLOW is only returned for queues 0-31 as queues 32-63
1401  * do not have an overflow status maintained.
1402  *
1403  * @param qId @ref IxQMgrQId [in] - the queue identifier.
1404  * @param *entry UINT32 [in] - the word(s) to write.
1405  *
1406  * @return @li IX_SUCCESS, value was successfully written.
1407  * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s).
1408  * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
1409  * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue
1410  *
1411  */
1412 PUBLIC IX_STATUS
1413 ixQMgrQWriteWithChecks (IxQMgrQId qId,
1414                         UINT32 *entry);
1415
1416 /**
1417  *
1418  * @ingroup IxQMgrAPI
1419  *
1420  * @fn ixQMgrQWrite (IxQMgrQId qId,
1421               UINT32 *entry)
1422  *
1423  * @brief Fast write of an entry to a queue.
1424  *
1425  * This function is a heavily streamlined version of ixQMgrQWriteWithChecks(),
1426  * but performs essentially the same task.  It will write the entry size number
1427  * of words pointed to by entry to the queue specified by qId.
1428  *
1429  * @note - This function is inlined, to reduce unnecessary function call
1430  * overhead.  It does not perform any parameter checks, or update any
1431  * statistics. Also, it does not check that the queue specified by qId has
1432  * been configured. It simply writes an entry to the queue, and checks for
1433  * overflow.
1434  *
1435  * @note - IX_QMGR_Q_OVERFLOW is only returned for queues 0-31 as queues 32-63
1436  * do not have an overflow status maintained.
1437  *
1438  * @param  qId @ref IxQMgrQId [in]   - the queue identifier.
1439  * @param  *entry UINT32 [in] - pointer to the entry word(s).
1440  *
1441  * @return @li IX_SUCCESS, entry was successfully read.
1442  * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue
1443  *
1444  */
1445 #ifdef NO_INLINE_APIS
1446 PUBLIC IX_STATUS
1447 ixQMgrQWrite (IxQMgrQId qId,
1448               UINT32 *entry);
1449 #else
1450 IX_QMGR_INLINE PUBLIC IX_STATUS
1451 ixQMgrQWrite (IxQMgrQId qId,
1452               UINT32 *entry);
1453 #endif /* NO_INLINE_APIS */
1454
1455 IX_QMGR_INLINE PUBLIC IX_STATUS
1456 ixQMgrQWrite (IxQMgrQId qId,
1457               UINT32 *entry)
1458 #ifdef NO_INLINE_APIS
1459     ;
1460 #else
1461 {
1462     IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];
1463     UINT32 entrySize;
1464
1465     /* write the entry */
1466     IX_QMGR_INLINE_WRITE_LONG(infoPtr->qAccRegAddr, *entry);
1467     entrySize = infoPtr->qEntrySizeInWords;
1468
1469     if (entrySize != IX_QMGR_Q_ENTRY_SIZE1)
1470     {
1471         /* process the remaining part of the entry */
1472         volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr;
1473         while (--entrySize)
1474         {
1475             ++entry;
1476             IX_QMGR_INLINE_WRITE_LONG(++qAccRegAddr, *entry);
1477         }
1478         entrySize = infoPtr->qEntrySizeInWords;
1479     }
1480
1481     /* overflow is available for lower queues only */
1482     if (qId < IX_QMGR_MIN_QUEUPP_QID)
1483     {
1484         UINT32 qSize = infoPtr->qSizeInEntries;
1485         /* increment the current number of entries in the queue
1486          * and check for overflow
1487          */
1488         if (infoPtr->qWriteCount++ == qSize)
1489         {
1490             /* the queue may have overflow */
1491             UINT32 qPtrs; /* queue internal pointers */
1492
1493             /* get the queue status */
1494             UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);
1495
1496             /* read the status twice because the status may
1497              * not be immediately ready after the write operation
1498              */
1499             if ((status & infoPtr->qOflowStatBitMask) ||
1500                 ((status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr))
1501                  & infoPtr->qOflowStatBitMask))
1502             {
1503                 /* the queue is full, clear the overflow status
1504                  *  bit if it was set
1505                  */
1506                 IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr,
1507                                      status & ~infoPtr->qOflowStatBitMask);
1508                 infoPtr->qWriteCount = infoPtr->qSizeInEntries;
1509                 return IX_QMGR_Q_OVERFLOW;
1510             }
1511             /* No overflow occured : someone is draining the queue
1512              * and the current counter needs to be
1513              * updated from the current number of entries in the queue
1514              */
1515
1516             /* get q pointer snapshot */
1517             qPtrs = IX_QMGR_INLINE_READ_LONG(infoPtr->qConfigRegAddr);
1518
1519             /* Mod subtraction of pointers to get number of words in Q. */
1520             qPtrs = (qPtrs - (qPtrs >> 7)) & 0x7f;
1521
1522             if (qPtrs == 0)
1523             {
1524                 /* the queue may be full at the time of the
1525                  * snapshot. Next access will check
1526                  * the overflow status again.
1527                  */
1528                 infoPtr->qWriteCount = qSize;
1529             }
1530             else
1531             {
1532                 /* convert the number of words to a number of entries */
1533                 if (entrySize == IX_QMGR_Q_ENTRY_SIZE1)
1534                 {
1535                     infoPtr->qWriteCount = qPtrs & (qSize - 1);
1536                 }
1537                 else
1538                 {
1539                     infoPtr->qWriteCount = (qPtrs / entrySize) & (qSize - 1);
1540                 }
1541             }
1542         }
1543     }
1544     return IX_SUCCESS;
1545 }
1546 #endif
1547
1548 /**
1549  *
1550  * @ingroup IxQMgrAPI
1551  *
1552  * @fn ixQMgrQBurstWrite (IxQMgrQId qId,
1553                    unsigned numEntries,
1554                    UINT32 *entries)
1555  *
1556  * @brief Write a number of entries to an AQM queue.
1557  *
1558  * This function will burst write a number of entries to the specified queue.
1559  * The entry size of queue is auto-detected. The function will attempt to
1560  * write as many entries as specified by the numEntries parameter and will
1561  * return an OVERFLOW if any one of the individual entry writes fail.
1562  *
1563  * @warning
1564  * IX_QMGR_Q_OVERFLOW is only returned for queues 0-31 as queues 32-63
1565  * do not have an overflow status maintained, hence there is a potential for
1566  * silent failure here. This function must be used with caution.
1567  *
1568  * @note
1569  * This function is intended for fast population of queues, so to make it
1570  * as efficient as possible, it has the following features:
1571  * - This function is inlined, to reduce unnecessary function call overhead.
1572  * - It does not perform any parameter checks, or update any statistics.
1573  * - It does not check that the queue specified by qId has been configured.
1574  * - It does not check that the queue has enough free space to hold the entries
1575  * before writing, and only checks for overflow after all writes have been
1576  * performed.  Therefore, the client should ensure before calling this function
1577  * that there is enough free space in the queue to hold the number of entries
1578  * to be written.  ixQMgrQWrite() or ixQMgrQWriteWithChecks(), which only writes
1579  * a single queue entry per call, should be used instead if the user requires
1580  * checks for OVERFLOW after each entry written.
1581  *
1582  * @param qId @ref IxQMgrQId [in]   - the queue identifier.
1583  * @param numEntries unsigned [in] - the number of entries to write.
1584  * @param *entries UINT32 [in]  - the word(s) to write.
1585  *
1586  * @return @li IX_SUCCESS, value was successfully written.
1587  * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue
1588  *
1589  */
1590 #ifdef NO_INLINE_APIS
1591 PUBLIC IX_STATUS
1592 ixQMgrQBurstWrite (IxQMgrQId qId,
1593                    unsigned numEntries,
1594                    UINT32 *entries);
1595 #else
1596 IX_QMGR_INLINE PUBLIC IX_STATUS
1597 ixQMgrQBurstWrite (IxQMgrQId qId,
1598                    unsigned numEntries,
1599                    UINT32 *entries);
1600 #endif /* NO_INLINE_APIS */
1601
1602 IX_QMGR_INLINE PUBLIC IX_STATUS
1603 ixQMgrQBurstWrite (IxQMgrQId qId,
1604                    unsigned numEntries,
1605                    UINT32 *entries)
1606 #ifdef NO_INLINE_APIS
1607 ;
1608 #else
1609 {
1610     IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId];
1611     UINT32 status;
1612
1613     /* update the current write count */
1614     infoPtr->qWriteCount += numEntries;
1615
1616     if (infoPtr->qEntrySizeInWords == IX_QMGR_Q_ENTRY_SIZE1)
1617     {
1618         volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr;
1619         while (numEntries--)
1620         {
1621             IX_QMGR_INLINE_WRITE_LONG(qAccRegAddr, *entries);
1622             entries++;
1623         }
1624     }
1625     else
1626     {
1627         IxQMgrQEntrySizeInWords entrySizeInWords = infoPtr->qEntrySizeInWords;
1628         UINT32 i;
1629
1630         /* write each queue entry */
1631         while (numEntries--)
1632         {
1633             /* write the queueEntrySize number of words for each entry */
1634             for (i = 0; i < (UINT32)entrySizeInWords; i++)
1635             {
1636                 IX_QMGR_INLINE_WRITE_LONG((infoPtr->qAccRegAddr + i), *entries);
1637                 entries++;
1638             }
1639         }
1640     }
1641
1642     /* check if the write count overflows */
1643     if (infoPtr->qWriteCount > infoPtr->qSizeInEntries)
1644     {
1645         /* reset the current write count */
1646         infoPtr->qWriteCount = infoPtr->qSizeInEntries;
1647     }
1648
1649     /* Check if overflow occurred on the write operation */
1650     if (qId < IX_QMGR_MIN_QUEUPP_QID)
1651     {
1652         /* get the queue status */
1653         status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr);
1654
1655         /* read the status twice because the status may
1656          * not be ready at the time of the write
1657          */
1658         if ((status & infoPtr->qOflowStatBitMask) ||
1659             ((status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr))
1660              & infoPtr->qOflowStatBitMask))
1661         {
1662             /* clear the underflow status bit if it was set */
1663             IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr,
1664                                  status & ~infoPtr->qOflowStatBitMask);
1665             return IX_QMGR_Q_OVERFLOW;
1666         }
1667     }
1668
1669     return IX_SUCCESS;
1670 }
1671 #endif
1672
1673 /**
1674  * @ingroup IxQMgrAPI
1675  *
1676  * @fn ixQMgrQPoke (IxQMgrQId qId,
1677              unsigned int entryIndex,
1678              UINT32 *entry)
1679  *
1680  * @brief Write an entry to a queue without moving the write pointer.
1681  *
1682  * This function modifies an entry in a queue. The entry is modified directly
1683  * in AQM SRAM and not using the queue access registers. The entry is NOT added to the
1684  * queue and the read/write pointers are unchanged.
1685  * N.B: The queue should not be accessed when this function is called.
1686  *
1687  * @param qId @ref IxQMgrQId [in]  - the queue identifier.
1688  * @param  entryIndex unsigned int [in] - index of entry in queue in the range
1689  *                          [0].......[current number of entries in queue].
1690  * @param  *entry UINT32 [in] - pointer to the entry word(s).
1691  *
1692  * @return @li IX_SUCCESS, entry was successfully modified.
1693  * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s).
1694  * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId.
1695  * @return @li IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS, an entry does not exist at
1696  *             specified index.
1697  * @return @li IX_FAIL, failed to modify the queue entry.
1698  */
1699 PUBLIC IX_STATUS
1700 ixQMgrQPoke (IxQMgrQId qId,
1701              unsigned int entryIndex,
1702              UINT32 *entry);
1703
1704 /**
1705  *
1706  * @ingroup IxQMgrAPI
1707  *
1708  * @fn ixQMgrQNumEntriesGet (IxQMgrQId qId,
1709                       unsigned *numEntries)
1710  *
1711  * @brief Get a snapshot of the number of entries in a queue.
1712  *
1713  * This function gets the number of entries in a queue.
1714  *
1715  * @param qId @ref IxQMgrQId [in] qId - the queue idenfifier
1716  * @param *numEntries unsigned [out] - the number of entries in a queue
1717  *
1718  * @return @li IX_SUCCESS, got the number of entries for the queue
1719  * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s).
1720  * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured
1721  * @return @li IX_QMGR_WARNING, could not determine num entries at this time
1722  *
1723  */
1724 PUBLIC IX_STATUS
1725 ixQMgrQNumEntriesGet (IxQMgrQId qId,
1726                       unsigned *numEntries);
1727
1728 /**
1729  *
1730  * @ingroup IxQMgrAPI
1731  *
1732  * @fn ixQMgrQStatusGetWithChecks (IxQMgrQId qId,
1733                             IxQMgrQStatus *qStatus)
1734  *
1735  * @brief Get a queues status.
1736  *
1737  * This function reads the specified queues status. A queues status is defined
1738  * by its status flags. For queues 0-31 these flags are E,NE,NF,F. For
1739  * queues 32-63 these flags are NE and F.
1740  *
1741  * @param qId @ref IxQMgrQId [in] - the queue identifier.
1742  * @param &qStatus @ref IxQMgrQStatus [out] - the status of the specified queue.
1743  *
1744  * @return @li IX_SUCCESS, queue status was successfully read.
1745  * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured
1746  * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter.
1747  *
1748  */
1749 PUBLIC IX_STATUS
1750 ixQMgrQStatusGetWithChecks (IxQMgrQId qId,
1751                             IxQMgrQStatus *qStatus);
1752
1753 /**
1754  *
1755  * @ingroup IxQMgrAPI
1756  *
1757  * @fn ixQMgrQStatusGet (IxQMgrQId qId,
1758                   IxQMgrQStatus *qStatus)
1759  *
1760  * @brief Fast get of a queue's status.
1761  *
1762  * This function is a streamlined version of ixQMgrQStatusGetWithChecks(), but
1763  * performs essentially the same task.  It reads the specified queue's status.
1764  * A queues status is defined by its status flags. For queues 0-31 these flags
1765  * are E,NE,NF,F. For queues 32-63 these flags are NE and F.
1766  *
1767  * @note - This function is inlined, to reduce unnecessary function call
1768  * overhead.  It does not perform any parameter checks, or update any
1769  * statistics.  Also, it does not check that the queue specified by qId has
1770  * been configured.  It simply reads the specified queue's status.
1771  *
1772  * @param qId @ref IxQMgrQId [in] - the queue identifier.
1773  * @param *qStatus @ref IxQMgrQStatus [out] - the status of the specified queue.
1774  *
1775  * @return @li void.
1776  *
1777  */
1778
1779 #ifdef NO_INLINE_APIS
1780 PUBLIC IX_STATUS
1781 ixQMgrQStatusGet (IxQMgrQId qId,
1782                   IxQMgrQStatus *qStatus);
1783 #else
1784 extern UINT32 ixQMgrAqmIfQueLowStatRegAddr[];
1785 extern UINT32 ixQMgrAqmIfQueLowStatBitsOffset[];
1786 extern UINT32 ixQMgrAqmIfQueLowStatBitsMask;
1787 extern UINT32 ixQMgrAqmIfQueUppStat0RegAddr;
1788 extern UINT32 ixQMgrAqmIfQueUppStat1RegAddr;
1789 extern UINT32 ixQMgrAqmIfQueUppStat0BitMask[];
1790 extern UINT32 ixQMgrAqmIfQueUppStat1BitMask[];
1791
1792 IX_QMGR_INLINE PUBLIC IX_STATUS
1793 ixQMgrQStatusGet (IxQMgrQId qId,
1794                   IxQMgrQStatus *qStatus);
1795 #endif  /* endif NO_INLINE_APIS */
1796
1797 IX_QMGR_INLINE PUBLIC IX_STATUS
1798 ixQMgrQStatusGet (IxQMgrQId qId,
1799                   IxQMgrQStatus *qStatus)
1800 #ifdef NO_INLINE_APIS
1801     ;
1802 #else
1803 {
1804     /* read the status of a queue in the range 0-31 */
1805     if (qId < IX_QMGR_MIN_QUEUPP_QID)
1806     {
1807         volatile UINT32 *lowStatRegAddr = (UINT32*)ixQMgrAqmIfQueLowStatRegAddr[qId];
1808
1809         UINT32 lowStatBitsOffset = ixQMgrAqmIfQueLowStatBitsOffset[qId];
1810         UINT32 lowStatBitsMask   = ixQMgrAqmIfQueLowStatBitsMask;
1811
1812         /* read the status register for this queue */
1813         *qStatus = IX_QMGR_INLINE_READ_LONG(lowStatRegAddr);
1814
1815         /* mask out the status bits relevant only to this queue */
1816         *qStatus = (*qStatus >> lowStatBitsOffset) & lowStatBitsMask;
1817
1818     }
1819     else /* read status of a queue in the range 32-63 */
1820     {
1821
1822         volatile UINT32 *qNearEmptyStatRegAddr = (UINT32*)ixQMgrAqmIfQueUppStat0RegAddr;
1823         volatile UINT32 *qFullStatRegAddr      = (UINT32*)ixQMgrAqmIfQueUppStat1RegAddr;
1824         int maskIndex = qId - IX_QMGR_MIN_QUEUPP_QID;
1825         UINT32 qNearEmptyStatBitMask = ixQMgrAqmIfQueUppStat0BitMask[maskIndex];
1826         UINT32 qFullStatBitMask      = ixQMgrAqmIfQueUppStat1BitMask[maskIndex];
1827
1828         /* Reset the status bits */
1829         *qStatus = 0;
1830
1831         /* Check if the queue is nearly empty */
1832         if (IX_QMGR_INLINE_READ_LONG(qNearEmptyStatRegAddr) & qNearEmptyStatBitMask)
1833         {
1834             *qStatus |= IX_QMGR_Q_STATUS_NE_BIT_MASK;
1835         }
1836
1837         /* Check if the queue is full */
1838         if (IX_QMGR_INLINE_READ_LONG(qFullStatRegAddr) & qFullStatBitMask)
1839         {
1840             *qStatus |= IX_QMGR_Q_STATUS_F_BIT_MASK;
1841         }
1842     }
1843     return IX_SUCCESS;
1844 }
1845 #endif
1846
1847 /* ------------------------------------------------------------
1848    Queue dispatch related functions
1849    ---------------------------------------------------------- */
1850
1851 /**
1852  *
1853  * @ingroup IxQMgrAPI
1854  *
1855  * @fn ixQMgrDispatcherPrioritySet (IxQMgrQId qId,
1856                              IxQMgrPriority priority)
1857  *
1858  * @brief Set the dispatch priority of a queue.
1859  *
1860  * This function is called to set the dispatch priority of queue. The effect of
1861  * this function is to add a priority change request to a queue. This queue is
1862  * serviced by @a ixQMgrDispatcherLoopRunA0, @a ixQMgrDispatcherLoopRunB0 or
1863  * @a ixQMgrDispatcherLoopRunB0LLP.
1864  *
1865  * This function is re-entrant. and can be used from an interrupt context
1866  *
1867  * @param qId @ref IxQMgrQId [in] - the queue identifier
1868  * @param priority @ref IxQMgrPriority [in] - the new queue dispatch priority
1869  *
1870  * @return @li IX_SUCCESS, priority change request is queued
1871  * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured
1872  * @return @li IX_QMGR_Q_INVALID_PRIORITY, specified priority is invalid
1873  *
1874  */
1875 PUBLIC IX_STATUS
1876 ixQMgrDispatcherPrioritySet (IxQMgrQId qId,
1877                              IxQMgrPriority priority);
1878 /**
1879  *
1880  * @ingroup IxQMgrAPI
1881  *
1882  * @fn ixQMgrNotificationEnable (IxQMgrQId qId,
1883                           IxQMgrSourceId sourceId)
1884  *
1885  * @brief Enable notification on a queue for a specified queue source flag.
1886  *
1887  * This function is called by a client of the QMgr to enable notifications on a
1888  * specified condition.
1889  * If the condition for the notification is set after the client has called this
1890  * function but before the function has enabled the interrupt source, then the
1891  * notification will not occur.
1892  * For queues 32-63 the notification source is fixed to the NE(Nearly Empty) flag
1893  * and cannot be changed so the sourceId parameter is ignored for these queues.
1894  * The status register is read before the notofication is enabled and is read again
1895  * after the notification has been enabled, if they differ then the warning status
1896  * is returned.
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  * @param sourceId @ref IxQMgrSourceId [in] - the interrupt src condition identifier
1902  *
1903  * @return @li IX_SUCCESS, the interrupt has been enabled for the specified source
1904  * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured
1905  * @return @li IX_QMGR_INVALID_INT_SOURCE_ID, interrupt source invalid for this queue
1906  * @return @li IX_QMGR_WARNING, the status register may not be constistent
1907  *
1908  */
1909 PUBLIC IX_STATUS
1910 ixQMgrNotificationEnable (IxQMgrQId qId,
1911                           IxQMgrSourceId sourceId);
1912
1913 /**
1914  * @ingroup IxQMgrAPI
1915  *
1916  * @fn ixQMgrNotificationDisable (IxQMgrQId qId)
1917  *
1918  * @brief Disable notifications on a queue.
1919  *
1920  * This function is called to disable notifications on a specified queue.
1921  *
1922  * This function is re-entrant. and can be used from an interrupt context
1923  *
1924  * @param qId @ref IxQMgrQId [in] - the queue identifier
1925  *
1926  * @return @li IX_SUCCESS, the interrupt has been disabled
1927  * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured
1928  *
1929  */
1930 PUBLIC IX_STATUS
1931 ixQMgrNotificationDisable (IxQMgrQId qId);
1932
1933 /**
1934  *
1935  * @ingroup IxQMgrAPI
1936  *
1937  * @fn ixQMgrDispatcherLoopRunA0 (IxQMgrDispatchGroup group)
1938  *
1939  * @brief Run the callback dispatcher.
1940  *
1941  * This function runs the dispatcher for a group of queues.
1942  * Callbacks are made for interrupts that have occurred on queues within
1943  * the group that have registered callbacks. The order in which queues are
1944  * serviced depends on the queue priorities set by the client.
1945  * This function may be called from interrupt or task context.
1946  * For optimisations that were introduced in IXP42X B0 and supported IXP46X
1947  * the @a ixQMgrDispatcherLoopRunB0, or @a ixQMgrDispatcherLoopRunB0LLP
1948  * should be used.
1949  *
1950  * This function is not re-entrant.
1951  *
1952  * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which the
1953  *                                        dispatcher will run
1954  *
1955  * @return @li void
1956  *
1957  * @note This function may be called from interrupt or task context.
1958  * However, for optimal performance the choice of context depends also on the
1959  * operating system used.
1960  *
1961  */
1962 PUBLIC void
1963 ixQMgrDispatcherLoopRunA0 (IxQMgrDispatchGroup group);
1964
1965 /**
1966  *
1967  * @ingroup IxQMgrAPI
1968  *
1969  * @fn ixQMgrDispatcherLoopRunB0 (IxQMgrDispatchGroup group)
1970  *
1971  * @brief Run the callback dispatcher.
1972  *
1973  * The enhanced version of @a ixQMgrDispatcherLoopRunA0 that is optimised for
1974  * features introduced in IXP42X B0 silicon and supported on IXP46X.
1975  * This is the default dispatcher for IXP42X B0 and IXP46X silicon.
1976  * The function runs the dispatcher for a group of queues.
1977  * Callbacks are made for interrupts that have occurred on queues within
1978  * the group that have registered callbacks. The order in which queues are
1979  * serviced depends on the queue priorities set by the client.
1980  * This  function may be called from interrupt or task context.
1981  *
1982  * This function is not re-entrant.
1983  *
1984  * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which the
1985  *                                        dispatcher will run
1986  *
1987  * @return @li void
1988  *
1989  *
1990  * @note This function may be called from interrupt or task context.
1991  * However, for optimal performance the choice of context depends also on the
1992  * operating system used.
1993  *
1994  */
1995 PUBLIC void
1996 ixQMgrDispatcherLoopRunB0 (IxQMgrDispatchGroup group);
1997
1998 /**
1999  *
2000  * @ingroup IxQMgrAPI
2001  *
2002  * @fn ixQMgrDispatcherLoopRunB0LLP (IxQMgrDispatchGroup group)
2003  *
2004  * @brief Run the callback dispatcher.
2005  *
2006  * This is a version of the optimised dispatcher for IXP42X B0 and IXP46X,
2007  * @a ixQMgrDispatcherLoopRunB0, with added support for livelock prevention.
2008  * This dispatcher will only be used for the IXP42X B0 or IXP46X silicon if
2009  * feature control indicates that IX_FEATURECTRL_ORIGB0_DISPATCHER is set to
2010  * IX_FEATURE_CTRL_SWCONFIG_DISABLED. Otherwise the @a ixQMgrDispatcherLoopRunB0
2011  * dispatcher will be used (Default).
2012  *
2013  * When this dispatcher notifies for a queue that is type
2014  * IX_QMGR_TYPE_REALTIME_PERIODIC, notifications for queues that are set
2015  * as type IX_QMGR_REALTIME_SPORADIC are not processed and disabled.
2016  * This helps prevent any tasks resulting from the notification of the
2017  * IX_QMGR_TYPE_REALTIME_PERIODIC type queue to being subject to livelock.
2018  * The function runs the dispatcher for a group of queues.
2019  * Callbacks are made for interrupts that have occurred on queues within
2020  * the group that have registered callbacks. The order in which queues are
2021  * serviced depends on their type along with the  queue priorities set by the
2022  * client. This function may be called from interrupt or task context.
2023  *
2024  * This function is not re-entrant.
2025  *
2026  * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which
2027  *                                        the dispatcher will run
2028  *
2029  * @return @li void
2030  *
2031  * @note This function may be called from interrupt or task context.
2032  * However, for optimal performance the choice of context depends also on the
2033  * operating system used.
2034  *
2035  */
2036 PUBLIC void
2037 ixQMgrDispatcherLoopRunB0LLP (IxQMgrDispatchGroup group);
2038
2039 /**
2040  *
2041  * @ingroup IxQMgrAPI
2042  *
2043  * @fn ixQMgrNotificationCallbackSet (IxQMgrQId qId,
2044                                IxQMgrCallback callback,
2045                                IxQMgrCallbackId callbackId)
2046  *
2047  * @brief Set the notification callback for a queue.
2048  *
2049  * This function sets the callback for the specified queue. This callback will
2050  * be called by the dispatcher, and may be called in the context of a interrupt
2051  * If callback has a value of NULL the previously registered callback, if one
2052  * exists will be unregistered.
2053  *
2054  * @param qId @ref IxQMgrQId [in] - the queue idenfifier
2055  * @param callback @ref IxQMgrCallback  [in] - the callback registered for this queue
2056  * @param callbackId @ref IxQMgrCallbackId [in] - the callback identifier
2057  *
2058  * @return @li IX_SUCCESS, the callback for the specified queue has been set
2059  * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured
2060  *
2061  */
2062 PUBLIC IX_STATUS
2063 ixQMgrNotificationCallbackSet (IxQMgrQId qId,
2064                                IxQMgrCallback callback,
2065                                IxQMgrCallbackId callbackId);
2066
2067 /**
2068  *
2069  * @ingroup IxQMgrAPI
2070  *
2071  * @fn ixQMgrDispatcherLoopGet (IxQMgrDispatcherFuncPtr *qDispatcherFuncPtr)
2072  *
2073  * @brief Get QMgr DispatcherLoopRun for respective silicon device
2074  *
2075  * This function gets a function pointer to ixQMgrDispatcherLoopRunA0() for IXP42X A0
2076  * Silicon. If the IXP42X B0 or 46X Silicon, the default is the ixQMgrDispatcherLoopRunB0()
2077  * function, however if live lock prevention is enabled a function pointer to
2078  * ixQMgrDispatcherLoopRunB0LLP() is given.
2079  *
2080  * @param *qDispatchFuncPtr @ref IxQMgrDispatcherFuncPtr [out]  -
2081  *              the function pointer of QMgr Dispatcher
2082  *
2083  */
2084 PUBLIC void
2085 ixQMgrDispatcherLoopGet (IxQMgrDispatcherFuncPtr *qDispatcherFuncPtr);
2086
2087 /**
2088  *
2089  * @ingroup IxQMgrAPI
2090  *
2091  * @fn ixQMgrStickyInterruptRegEnable(void)
2092  *
2093  * @brief Enable AQM's sticky interrupt register behaviour only available
2094  *        on B0 Silicon.
2095  *
2096  * When AQM's sticky interrupt register is enabled, interrupt register bit will
2097  * only be cleared when a '1' is written to interrupt register bit and the
2098  * interrupting condition is satisfied, i.e.queue condition does not exist.
2099  *
2100  * @note This function must be called before any queue is enabled.
2101  *       Calling this function after queue is enabled will cause
2102  *       undefined results.
2103  *
2104  * @return none
2105  *
2106  */
2107 PUBLIC void
2108 ixQMgrStickyInterruptRegEnable(void);
2109
2110
2111 /**
2112  * @ingroup IxQMgrAPI
2113  *
2114  * @fn ixQMgrCallbackTypeSet(IxQMgrQId qId,
2115                              IxQMgrType type)
2116  *
2117  * @brief Set the Callback Type of a queue.
2118  *
2119  * This function is only used for live lock prevention.
2120  * This function allows the callback type of a queue to be set. The default for
2121  * all queues is IX_QMGR_TYPE_REALTIME_OTHER. Setting the type to
2122  * IX_QMGR_TYPE_REALTIME_SPORADIC means that this queue will have it's
2123  * notifications disabled while there is a task associated with a
2124  * queue of type IX_QMGR_TYPE_REALTIME_PERIODIC running. As live lock
2125  * prevention operates on lower queues, this function should
2126  * be called for lower queues only.
2127  * This function is not re-entrant.
2128  *
2129  * @param qId @ref IxQMgrQId [in] - the queue identifier
2130  * @param type @ref IxQMgrType [in] - the type of callback
2131  *
2132  * @return @li IX_SUCCESS, successfully set callback type for the queue entry
2133  * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
2134  * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s).
2135  *
2136  */
2137 PUBLIC IX_STATUS
2138 ixQMgrCallbackTypeSet(IxQMgrQId qId,
2139                       IxQMgrType type);
2140
2141 /**
2142  * @ingroup IxQMgrAPI
2143  *
2144  * @fn ixQMgrCallbackTypeGet(IxQMgrQId qId,
2145                              IxQMgrType *type)
2146  *
2147  * @brief Get the Callback Type of a queue.
2148  *
2149  * This function allows the callback type of a queue to be got. As live lock
2150  * prevention operates on lower queues, this function should
2151  * be called for lower queues only.
2152  * This function is re-entrant.
2153  *
2154  * @param qId @ref IxQMgrQId [in] - the queue identifier
2155  * @param *type @ref IxQMgrType [out] - the type of callback
2156  *
2157  * @return @li IX_SUCCESS, successfully set callback type for the queue entry
2158  * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId
2159  * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s)
2160  *
2161  */
2162 PUBLIC IX_STATUS
2163 ixQMgrCallbackTypeGet(IxQMgrQId qId,
2164                       IxQMgrType *type);
2165
2166 /**
2167  * @ingroup IxQMgrAPI
2168  *
2169  * @fn ixQMgrPeriodicDone(void)
2170  *
2171  * @brief Indicate that the Periodic task is completed for LLP
2172  *
2173  * This function is used as part of live lock prevention.
2174  * A periodic task is a task that results from a queue that
2175  * is set as type IX_QMGR_TYPE_REALTIME_PERIODIC. This function
2176  * should be called to indicate to the dispatcher that the
2177  * the periodic task is completed. This ensures that the notifications
2178  * for queues set as type sporadic queues are re-enabled.
2179  * This function is re-entrant.
2180  *
2181  */
2182 PUBLIC void
2183 ixQMgrPeriodicDone(void);
2184
2185
2186 /**
2187  * @ingroup IxQMgrAPI
2188  *
2189  * @fn ixQMgrLLPShow(int resetStats)
2190  *
2191  * @brief Print out the live lock prevention statistics when in debug mode.
2192  *
2193  * This function prints out statistics related to the livelock. These
2194  * statistics are only collected in debug mode.
2195  * This function is not re-entrant.
2196  *
2197  * @param resetStats @ref int [in] - if set the the stats are reset.
2198  *
2199  */
2200 PUBLIC void
2201 ixQMgrLLPShow(int resetStats);
2202
2203
2204 #endif /* IXQMGR_H */
2205
2206 /**
2207  * @} defgroup IxQMgrAPI
2208  */
2209
2210