drivers/net/npe/include/IxAtmdAccCtrl.h

   1
   2 /**
   3  * @file    IxAtmdAccCtrl.h
   4  *
   5  * @date    20-Mar-2002
   6  *
   7  * @brief IxAtmdAcc Public API
   8  *
   9  * This file contains the public API of IxAtmdAcc, related to the
  10  * control functions of the component.
  11  *
  12  *
  13  * @par
  14  * IXP400 SW Release version 2.0
  15  *
  16  * -- Copyright Notice --
  17  *
  18  * @par
  19  * Copyright 2001-2005, Intel Corporation.
  20  * All rights reserved.
  21  *
  22  * @par
  23  * SPDX-License-Identifier:     BSD-3-Clause
  24  * @par
  25  * -- End of Copyright Notice --
  26  */
  27
  28 /* ------------------------------------------------------
  29    Doxygen group definitions
  30    ------------------------------------------------------ */
  31
  32 /**
  33  *
  34  * @defgroup IxAtmdAccCtrlAPI IXP400 ATM Driver Access (IxAtmdAcc) Control API
  35  *
  36  * @brief The public API for the IXP400 Atm Driver Control component
  37  *
  38  * IxAtmdAcc is the low level interface by which AAL PDU get transmitted
  39  * to,and received from the Utopia bus
  40  *
  41  * This part is related to the Control configuration
  42  *
  43  * @{
  44  */
  45
  46 #ifndef IXATMDACCCTRL_H
  47 #define IXATMDACCCTRL_H
  48
  49 #include "IxAtmdAcc.h"
  50
  51 /* ------------------------------------------------------
  52    AtmdAccCtrl Data Types definition
  53    ------------------------------------------------------ */
  54
  55 /**
  56 *
  57 * @ingroup IxAtmdAccCtrlAPI
  58 *
  59 * @def IX_ATMDACC_PORT_DISABLE_IN_PROGRESS
  60 *
  61 * @brief Port enable return code
  62 *
  63 * This constant is used to tell IxAtmDAcc user that the port disable
  64 * functions are not complete. The user can call ixAtmdAccPortDisableComplete()
  65 * to find out when the disable has finished. The port enable can then proceed.
  66 *
  67 */
  68 #define IX_ATMDACC_PORT_DISABLE_IN_PROGRESS 5
  69
  70 /**
  71 *
  72 * @ingroup IxAtmdAccCtrlAPI
  73 *
  74 * @def IX_ATMDACC_ALLPDUS
  75 *
  76 * @brief All PDUs
  77 *
  78 * This constant is used to tell IxAtmDAcc to process all PDUs from
  79 * the RX queue or the TX Done
  80 *
  81 * @sa IxAtmdAccRxDispatcher
  82 * @sa IxAtmdAccTxDoneDispatcher
  83 *
  84 */
  85 #define IX_ATMDACC_ALLPDUS 0xffffffff
  86
  87 /* ------------------------------------------------------
  88    Part of the IxAtmdAcc interface related to RX traffic
  89    ------------------------------------------------------ */
  90
  91 /**
  92  *
  93  * @ingroup IxAtmdAccCtrlAPI
  94  *
  95  * @brief Callback prototype for notification of available PDUs for
  96  * an Rx Q.
  97  *
  98  * This a protoype for a function which is called when there is at
  99  * least one Pdu available for processing on a particular Rx Q.
 100  *
 101  * This function should call @a ixAtmdAccRxDispatch() with
 102  * the aprropriate number of parameters to read and process the Rx Q.
 103  *
 104  * @sa ixAtmdAccRxDispatch
 105  * @sa ixAtmdAccRxVcConnect
 106  * @sa ixAtmdAccRxDispatcherRegister
 107  *
 108  * @param rxQueueId @ref IxAtmRxQueueId [in] indicates which RX queue to has Pdus to process.
 109  * @param numberOfPdusToProcess unsigned int [in] indicates the minimum number of
 110  *        PDUs available to process all PDUs from the queue.
 111  * @param reservedPtr unsigned int* [out] pointer to a int location which can
 112  *        be written to, but does not retain written values. This is
 113  *        provided to make this prototype compatible
 114  *        with @a ixAtmdAccRxDispatch()
 115  *
 116  * @return @li int - ignored.
 117  *
 118  */
 119 typedef IX_STATUS (*IxAtmdAccRxDispatcher) (IxAtmRxQueueId rxQueueId,
 120                          unsigned int numberOfPdusToProcess,
 121                          unsigned int *reservedPtr);
 122
 123 /* ------------------------------------------------------
 124    Part of the IxAtmdAcc interface related to TX traffic
 125    ------------------------------------------------------ */
 126
 127 /**
 128  *
 129  * @ingroup IxAtmdAccCtrlAPI
 130  *
 131  * @brief Callback prototype for transmitted mbuf when threshold level is
 132  *        crossed.
 133  *
 134  * IxAtmdAccTxDoneDispatcher is the prototype of the user function
 135  * which get called when pdus are completely transmitted. This function
 136  * is likely to call the @a ixAtmdAccTxDoneDispatch() function.
 137  *
 138  * This function is called when the number of available pdus for
 139  * reception is crossing the threshold level as defined
 140  * in @a ixAtmdAccTxDoneDispatcherRegister()
 141  *
 142  * This function is called inside an Qmgr dispatch context. No system
 143  * resource or interrupt-unsafe feature should be used inside this
 144  * callback.
 145  *
 146  * Transmitted buffers recycling implementation is a sytem-wide mechanism
 147  * and needs to be set before any traffic is started. If this threshold
 148  * mechanism is not used, the user is responsible for polling the
 149  * transmitted buffers with @a ixAtmdAccTxDoneDispatch()
 150  * and @a ixAtmdAccTxDoneLevelQuery() functions.
 151  *
 152  * @sa ixAtmdAccTxDoneDispatcherRegister
 153  * @sa ixAtmdAccTxDoneDispatch
 154  * @sa ixAtmdAccTxDoneLevelQuery
 155  *
 156  * @param numberOfPdusToProcess unsigned int [in] - The current number of pdus currently
 157  *        available for recycling
 158  * @param *reservedPtr unsigned int [out] - pointer to a int location which can be
 159  *        written to but does not retain written values. This is provided
 160  *        to make this prototype compatible
 161  *        with @a ixAtmdAccTxDoneDispatch()
 162  *
 163  * @return @li IX_SUCCESS This is provided to make
 164  *    this prototype compatible with @a ixAtmdAccTxDoneDispatch()
 165  * @return @li IX_FAIL invalid parameters or some unspecified internal
 166  *    error occured. This is provided to make
 167  *    this prototype compatible with @a ixAtmdAccTxDoneDispatch()
 168  *
 169  */
 170 typedef IX_STATUS (*IxAtmdAccTxDoneDispatcher) (unsigned int numberOfPdusToProcess,
 171                                                 unsigned int *reservedPtr);
 172
 173 /**
 174 *
 175 * @ingroup IxAtmdAccCtrlAPI
 176 *
 177 * @brief Notification that the threshold number of scheduled cells
 178 * remains in a port's transmit Q.
 179 *
 180 * The is the prototype for of the user notification function which
 181 * gets called on a per-port basis, when the number of remaining
 182 * scheduled cells to be transmitted decreases to the threshold level.
 183 * The number of cells passed as a parameter can be used for scheduling
 184 * purposes as the maximum number of cells that can be passed in a
 185 * schedule table to the @a ixAtmdAccPortTxProcess() function.
 186 *
 187 * @sa ixAtmdAccPortTxCallbackRegister
 188 * @sa ixAtmdAccPortTxProcess
 189 * @sa ixAtmdAccPortTxFreeEntriesQuery
 190 *
 191 * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 192 * @param numberOfAvailableCells unsigned int [in] - number of available
 193 *        cell entries.for the port
 194 *
 195 * @note - This functions shall not use system resources when used
 196 *         inside an interrupt context.
 197 *
 198 */
 199 typedef void (*IxAtmdAccPortTxLowCallback) (IxAtmLogicalPort port,
 200                            unsigned int numberOfAvailableCells);
 201
 202 /**
 203 *
 204 * @ingroup IxAtmdAccCtrlAPI
 205 *
 206 * @brief  Prototype to submit cells for transmission
 207 *
 208 * IxAtmdAccTxVcDemandUpdateCallback is the prototype of the callback
 209 * function used by AtmD to notify an ATM Scheduler that the user of
 210 * a VC has submitted cells for transmission.
 211 *
 212 * @sa IxAtmdAccTxVcDemandUpdateCallback
 213 * @sa IxAtmdAccTxVcDemandClearCallback
 214 * @sa IxAtmdAccTxSchVcIdGetCallback
 215 * @sa ixAtmdAccPortTxScheduledModeEnable
 216 *
 217 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be updated
 218 *        is established
 219 * @param vcId int [in] - Identifies the VC to be updated. This is the value
 220 *        returned by the @a IxAtmdAccTxSchVcIdGetCallback() call .
 221 * @param numberOfCells unsigned int [in] - Indicates how many ATM cells should be added
 222 *        to the queue for this VC.
 223 *
 224 * @return @li IX_SUCCESS the function is registering the cell demand for
 225 *        this VC.
 226 * @return @li IX_FAIL the function cannot register cell for this VC : the
 227 *         scheduler maybe overloaded or misconfigured
 228 *
 229 */
 230 typedef IX_STATUS (*IxAtmdAccTxVcDemandUpdateCallback) (IxAtmLogicalPort port,
 231                         int vcId,
 232                         unsigned int numberOfCells);
 233
 234 /**
 235 *
 236 * @ingroup IxAtmdAccCtrlAPI
 237 *
 238 * @brief  prototype to  remove all currently queued cells from a
 239 * registered VC
 240 *
 241 * IxAtmdAccTxVcDemandClearCallback is the prototype of the function
 242 * to remove all currently queued cells from a registered VC. The
 243 * pending cell count for the specified VC is reset to zero. After the
 244 * use of this callback, the scheduler shall not schedule more cells
 245 * for this VC.
 246 *
 247 * This callback function is called during a VC disconnection
 248 * @a ixAtmdAccTxVcTryDisconnect()
 249 *
 250 * @sa IxAtmdAccTxVcDemandUpdateCallback
 251 * @sa IxAtmdAccTxVcDemandClearCallback
 252 * @sa IxAtmdAccTxSchVcIdGetCallback
 253 * @sa ixAtmdAccPortTxScheduledModeEnable
 254 * @sa ixAtmdAccTxVcTryDisconnect
 255 *
 256 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be cleared
 257 *        is established
 258 * @param vcId int [in] - Identifies the VC to be cleared. This is the value
 259 *        returned by the @a IxAtmdAccTxSchVcIdGetCallback() call .
 260 *
 261 * @return none
 262 *
 263 */
 264 typedef void (*IxAtmdAccTxVcDemandClearCallback) (IxAtmLogicalPort port,
 265                              int vcId);
 266
 267 /**
 268 *
 269 * @ingroup IxAtmdAccCtrlAPI
 270 *
 271 * @brief  prototype to get a scheduler vc id
 272 *
 273 * IxAtmdAccTxSchVcIdGetCallback is the prototype of the function to get
 274 * a scheduler vcId
 275 *
 276 * @sa IxAtmdAccTxVcDemandUpdateCallback
 277 * @sa IxAtmdAccTxVcDemandClearCallback
 278 * @sa IxAtmdAccTxSchVcIdGetCallback
 279 * @sa ixAtmdAccPortTxScheduledModeEnable
 280 *
 281 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM logical port on which the VC is
 282 *        established
 283 * @param vpi unsigned int [in] - For AAL0/AAL5 specifies the ATM vpi on which the
 284 *                 VC is established.
 285 *                 For OAM specifies the dedicated "OAM Tx channel" VPI.
 286 * @param vci unsigned int [in] - For AAL0/AAL5 specifies the ATM vci on which the
 287 *                 VC is established.
 288 *                 For OAM specifies the dedicated "OAM Tx channel" VCI.
 289 * @param connId @ref IxAtmConnId [in] - specifies the IxAtmdAcc connection Id already
 290 *        associated with this VC
 291 * @param vcId int* [out] - pointer to a vcId
 292 *
 293 * @return @li IX_SUCCESS the function is returning a Scheduler vcId for this
 294 *         VC
 295 * @return @li IX_FAIL the function cannot process scheduling for this VC.
 296 *                 the contents of vcId is unspecified
 297 *
 298 */
 299 typedef IX_STATUS (*IxAtmdAccTxSchVcIdGetCallback) (IxAtmLogicalPort port,
 300                                unsigned int vpi,
 301                                unsigned int vci,
 302                                IxAtmConnId connId,
 303                                int *vcId);
 304
 305 /* ------------------------------------------------------
 306    Part of the IxAtmdAcc interface related to RX traffic
 307    ------------------------------------------------------ */
 308
 309 /**
 310  *
 311  * @ingroup IxAtmdAccCtrlAPI
 312  *
 313  * @fn ixAtmdAccRxDispatcherRegister (
 314                           IxAtmRxQueueId queueId,
 315                           IxAtmdAccRxDispatcher callback)
 316  *
 317  * @brief Register a notification callback to be invoked when there is
 318  * at least one entry on a particular Rx queue.
 319  *
 320  * This function registers a callback to be invoked when there is at
 321  * least one entry in a particular queue. The registered callback is
 322  * called every time when the hardware adds one or more pdus to the
 323  * specified Rx queue.
 324  *
 325  * This function cannot be used when a Rx Vc using this queue is
 326  * already existing.
 327  *
 328  * @note -The callback function can be the API function
 329  *       @a ixAtmdAccRxDispatch() : every time the threhold level
 330  *       of the queue is reached, the ixAtmdAccRxDispatch() is
 331  *       invoked to remove all entries from the queue.
 332  *
 333  * @sa ixAtmdAccRxDispatch
 334  * @sa IxAtmdAccRxDispatcher
 335  *
 336  * @param queueId @ref IxAtmRxQueueId [in] RX queue identification
 337  * @param callback @ref IxAtmdAccRxDispatcher [in] function triggering the delivery of incoming
 338  *        traffic. This parameter cannot be a null pointer.
 339  *
 340  * @return @li IX_SUCCESS Successful call to @a ixAtmdAccRxDispatcherRegister()
 341  * @return @li IX_FAIL error in the parameters, or there is an
 342  *             already active RX VC for this queue or some unspecified
 343  *             internal error occurred.
 344  *
 345  */
 346 PUBLIC IX_STATUS ixAtmdAccRxDispatcherRegister (
 347                           IxAtmRxQueueId queueId,
 348                           IxAtmdAccRxDispatcher callback);
 349
 350 /**
 351  *
 352  * @ingroup IxAtmdAccCtrlAPI
 353  *
 354  * @fn ixAtmdAccRxDispatch (IxAtmRxQueueId rxQueueId,
 355     unsigned int numberOfPdusToProcess,
 356     unsigned int *numberOfPdusProcessedPtr)
 357  *
 358  *
 359  * @brief Control function which executes Rx processing for a particular
 360  * Rx stream.
 361  *
 362  * The @a IxAtmdAccRxDispatch() function is used to process received Pdus
 363  * available from one of the two incoming RX streams. When this function
 364  * is invoked, the incoming traffic (up to the number of PDUs passed as
 365  * a parameter) will be transferred to the IxAtmdAcc users through the
 366  * callback @a IxAtmdAccRxVcRxCallback(), as registered during the
 367  * @a ixAtmdAccRxVcConnect() call.
 368  *
 369  * The user receive callbacks will be executed in the context of this
 370  * function.
 371  *
 372  * Failing to use this function on a regular basis when there is traffic
 373  * will block incoming traffic and can result in Pdus being dropped by
 374  * the hardware.
 375  *
 376  * This should be used to control when received pdus are handed off from
 377  * the hardware to Aal users from a particluar stream. The function can
 378  * be used from a timer context, or can be registered as a callback in
 379  * response to an rx stream threshold event, or can be used inside an
 380  * active polling mechanism which is under user control.
 381  *
 382  * @note - The signature of this function is directly compatible with the
 383  * callback prototype which can be register with @a ixAtmdAccRxDispatcherRegister().
 384  *
 385  * @sa ixAtmdAccRxDispatcherRegister
 386  * @sa IxAtmdAccRxVcRxCallback
 387  * @sa ixAtmdAccRxVcFreeEntriesQuery
 388  *
 389  * @param rxQueueId @ref IxAtmRxQueueId [in] - indicates which RX queue to process.
 390  * @param numberOfPdusToProcess unsigned int [in] - indicates the maxiumum number of PDU to
 391  *     remove from the RX queue. A value of IX_ATMDACC_ALLPDUS indicates
 392  *     to process all PDUs from the queue. This includes at least the PDUs
 393  *     in the queue when the fuction is invoked. Because of real-time
 394  *     constraints, there is no guarantee thatthe queue will be empty
 395  *     when the function exits. If this parameter is greater than the
 396  *     number of entries of the queues, the function will succeed
 397  *     and the parameter numberOfPdusProcessedPtr will reflect the exact
 398  *     number of PDUs processed.
 399  * @param *numberOfPdusProcessedPtr unsigned int [out] - indicates the actual number of PDU
 400  *     processed during this call. This parameter cannot be a null
 401  *     pointer.
 402  *
 403  * @return @li IX_SUCCESS the number of PDUs as indicated in
 404  *     numberOfPdusProcessedPtr are removed from the RX queue and the VC callback
 405  *     are called.
 406  * @return @li IX_FAIL invalid parameters or some unspecified internal
 407  *     error occured.
 408  *
 409  */
 410 PUBLIC IX_STATUS ixAtmdAccRxDispatch (IxAtmRxQueueId rxQueueId,
 411     unsigned int numberOfPdusToProcess,
 412     unsigned int *numberOfPdusProcessedPtr);
 413
 414 /**
 415  *
 416  * @ingroup IxAtmdAccCtrlAPI
 417  *
 418  * @fn ixAtmdAccRxLevelQuery (IxAtmRxQueueId rxQueueId,
 419                      unsigned int *numberOfPdusPtr)
 420  *
 421  * @brief Query the number of entries in a particular RX queue.
 422  *
 423  * This function is used to retrieve the number of pdus received by
 424  * the hardware and ready for distribution to users.
 425  *
 426  * @param rxQueueId @ref IxAtmRxQueueId [in] - indicates which of two RX queues to query.
 427  * @param numberOfPdusPtr unsigned int* [out] - Pointer to store the number of available
 428  *        PDUs in the RX queue. This parameter cannot be a null pointer.
 429  *
 430  * @return @li IX_SUCCESS the value in numberOfPdusPtr specifies the
 431  *         number of incoming pdus waiting in this queue
 432  * @return @li IX_FAIL an error occurs during processing.
 433  *         The value in numberOfPdusPtr is unspecified.
 434  *
 435  * @note - This function is reentrant, doesn't use system resources
 436  *         and can be used from an interrupt context.
 437  *
 438  */
 439 PUBLIC IX_STATUS ixAtmdAccRxLevelQuery (IxAtmRxQueueId rxQueueId,
 440                      unsigned int *numberOfPdusPtr);
 441
 442 /**
 443  *
 444  * @ingroup IxAtmdAccCtrlAPI
 445  *
 446  * @fn ixAtmdAccRxQueueSizeQuery (IxAtmRxQueueId rxQueueId,
 447                      unsigned int *numberOfPdusPtr)
 448  *
 449  * @brief Query the size of a particular RX queue.
 450  *
 451  * This function is used to retrieve the number of pdus the system is
 452  * able to queue when reception is complete.
 453  *
 454  * @param rxQueueId @ref IxAtmRxQueueId [in] - indicates which of two RX queues to query.
 455  * @param numberOfPdusPtr unsigned int* [out] - Pointer to store the number of pdus
 456  *         the system is able to queue in the RX queue. This parameter
 457  *         cannot be a null pointer.
 458  *
 459  * @return @li IX_SUCCESS the value in numberOfPdusPtr specifies the
 460  *         number of pdus the system is able to queue.
 461  * @return @li IX_FAIL an error occurs during processing.
 462  *         The value in numberOfPdusPtr is unspecified.
 463  *
 464  * @note - This function is reentrant, doesn't use system resources
 465  *         and can be used from an interrupt context.
 466  *
 467  */
 468 PUBLIC IX_STATUS ixAtmdAccRxQueueSizeQuery (IxAtmRxQueueId rxQueueId,
 469                      unsigned int *numberOfPdusPtr);
 470
 471 /* ------------------------------------------------------
 472    Part of the IxAtmdAcc interface related to TX traffic
 473    ------------------------------------------------------ */
 474
 475 /**
 476  *
 477  * @ingroup IxAtmdAccCtrlAPI
 478  *
 479  * @fn ixAtmdAccPortTxFreeEntriesQuery (IxAtmLogicalPort port,
 480                          unsigned int *numberOfCellsPtr)
 481  *
 482  * @brief Get the number of available cells the system can accept for
 483  *       transmission.
 484  *
 485  * The function is used to retrieve the number of cells that can be
 486  * queued for transmission to the hardware.
 487  *
 488  * This number is based on the worst schedule table where one cell
 489  * is stored in one schedule table entry, depending on the pdus size
 490  * and mbuf size and fragmentation.
 491  *
 492  * This function doesn't use system resources and can be used from a
 493  * timer context, or can be associated with a threshold event, or can
 494  * be used inside an active polling mechanism
 495  *
 496  * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 497  * @param numberOfCellsPtr unsigned int* [out] - number of available cells.
 498  *                   This parameter cannot be a null pointer.
 499  *
 500  * @sa ixAtmdAccPortTxProcess
 501  *
 502  * @return @li IX_SUCCESS numberOfCellsPtr contains the number of cells that can be scheduled
 503  *         for this port.
 504  * @return @li IX_FAIL error in the parameters, or some processing error
 505  *         occured.
 506  *
 507  */
 508 PUBLIC IX_STATUS ixAtmdAccPortTxFreeEntriesQuery (IxAtmLogicalPort port,
 509                          unsigned int *numberOfCellsPtr);
 510
 511 /**
 512  *
 513  * @ingroup IxAtmdAccCtrlAPI
 514  *
 515  * @fn ixAtmdAccPortTxCallbackRegister (IxAtmLogicalPort port,
 516                        unsigned int numberOfCells,
 517                        IxAtmdAccPortTxLowCallback callback)
 518  *
 519  * @brief Configure the Tx port threshold value and register a callback to handle
 520  * threshold notifications.
 521  *
 522  * This function sets the threshold in cells
 523  *
 524  * @sa ixAtmdAccPortTxCallbackRegister
 525  * @sa ixAtmdAccPortTxProcess
 526  * @sa ixAtmdAccPortTxFreeEntriesQuery
 527  *
 528  * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 529  * @param numberOfCells unsigned int [in] - threshold value which triggers the callback
 530  *        invocation, This number has to be one of the
 531  *        values 0,1,2,4,8,16,32 ....
 532  *        The maximum value cannot be more than half of the txVc queue
 533  *        size (which can be retrieved using @a ixAtmdAccPortTxFreeEntriesQuery()
 534  *        before any Tx traffic is sent for this port)
 535  * @param callback @ref IxAtmdAccPortTxLowCallback [in] - callback function to invoke when the threshold
 536  *                 level is reached.
 537  *                 This parameter cannot be a null pointer.
 538  *
 539  * @return @li IX_SUCCESS Successful call to @a ixAtmdAccPortTxCallbackRegister()
 540  * @return @li IX_FAIL error in the parameters, Tx channel already set for this port
 541  *             threshold level is not correct or within the range regarding the
 542  *             queue size:or unspecified error during processing:
 543  *
 544  * @note - This callback function get called when the threshold level drops from
 545  *         (numberOfCells+1) cells to (numberOfCells) cells
 546  *
 547  * @note - This function should be called during system initialisation,
 548  *         outside an interrupt context
 549  *
 550  */
 551 PUBLIC IX_STATUS ixAtmdAccPortTxCallbackRegister (IxAtmLogicalPort port,
 552                        unsigned int numberOfCells,
 553                        IxAtmdAccPortTxLowCallback callback);
 554
 555 /**
 556  *
 557  * @ingroup IxAtmdAccCtrlAPI
 558  *
 559  * @fn ixAtmdAccPortTxScheduledModeEnable (IxAtmLogicalPort port,
 560     IxAtmdAccTxVcDemandUpdateCallback vcDemandUpdateCallback,
 561     IxAtmdAccTxVcDemandClearCallback vcDemandClearCallback,
 562     IxAtmdAccTxSchVcIdGetCallback vcIdGetCallback)
 563  *
 564  * @brief Put the port into Scheduled Mode
 565  *
 566  * This function puts the specified port into scheduled mode of
 567  * transmission which means an external s/w entity controls the
 568  * transmission of cells on this port. This faciltates traffic shaping on
 569  * the port.
 570  *
 571  * Any buffers submitted on a VC for this port will be queued in IxAtmdAcc.
 572  * The transmission of these buffers to and by the hardware will be driven
 573  * by a transmit schedule submitted regulary in calls to
 574  * @a ixAtmdAccPortTxProcess() by traffic shaping entity.
 575  *
 576  * The transmit schedule is expected to be dynamic in nature based on
 577  * the demand in cells for each VC on the port. Hence the callback
 578  * parameters provided to this function allow IxAtmdAcc to inform the
 579  * shaping entity of demand changes for each VC on the port.
 580  *
 581  * By default a port is in Unscheduled Mode so if this function is not
 582  * called, transmission of data is done without sheduling rules, on a
 583  * first-come, first-out basis.
 584  *
 585  * Once a port is put in scheduled mode it cannot be reverted to
 586  * un-scheduled mode. Note that unscheduled mode is not supported
 587  * in ixp425 1.0
 588  *
 589  * @note - This function should be called before any VCs have be
 590  * connected on a port. Otherwise this function call will return failure.
 591  *
 592  * @note - This function uses internal locks and should not be called from
 593  * an interrupt context
 594  *
 595  * @sa IxAtmdAccTxVcDemandUpdateCallback
 596  * @sa IxAtmdAccTxVcDemandClearCallback
 597  * @sa IxAtmdAccTxSchVcIdGetCallback
 598  * @sa ixAtmdAccPortTxProcess
 599  *
 600  * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 601  * @param vcDemandUpdateCallback @ref IxAtmdAccTxVcDemandUpdateCallback [in] - callback function used to update
 602  *     the number of outstanding cells for transmission. This parameter
 603  *     cannot be a null pointer.
 604  * @param vcDemandClearCallback @ref IxAtmdAccTxVcDemandClearCallback [in] - callback function used to remove all
 605  *     clear the number of outstanding cells for a VC. This parameter
 606  *     cannot be a null pointer.
 607  * @param vcIdGetCallback @ref IxAtmdAccTxSchVcIdGetCallback [in] - callback function used to exchange vc
 608  *     Identifiers between IxAtmdAcc and the entity supplying the
 609  *     transmit schedule. This parameter cannot be a null pointer.
 610  *
 611  * @return @li IX_SUCCESS scheduler registration is complete and the port
 612  *         is now in scheduled mode.
 613  * @return @li IX_FAIL failed (wrong parameters, or traffic is already
 614  *         enabled on this port, possibly without ATM shaping)
 615  *
 616  */
 617 PUBLIC IX_STATUS ixAtmdAccPortTxScheduledModeEnable (IxAtmLogicalPort port,
 618     IxAtmdAccTxVcDemandUpdateCallback vcDemandUpdateCallback,
 619     IxAtmdAccTxVcDemandClearCallback vcDemandClearCallback,
 620     IxAtmdAccTxSchVcIdGetCallback vcIdGetCallback);
 621
 622 /**
 623  *
 624  * @ingroup IxAtmdAccCtrlAPI
 625  *
 626  * @fn ixAtmdAccPortTxProcess (IxAtmLogicalPort port,
 627     IxAtmScheduleTable* scheduleTablePtr)
 628  *
 629  * @brief Transmit queue cells to the H/W based on the supplied schedule
 630  *        table.
 631  *
 632  * This function @a ixAtmdAccPortTxProcess() process the schedule
 633  * table provided as a parameter to the function. As a result cells are
 634  * sent to the underlaying hardware for transmission.
 635  *
 636  * The schedule table is executed in its entirety or not at all. So the
 637  * onus is on the caller not to submit a table containing more cells than
 638  * can be transmitted at that point. The maximum numbers that can be
 639  * transmitted is guaranteed to be the number of cells as returned by the
 640  * function @a ixAtmdAccPortTxFreeEntriesQuery().
 641  *
 642  * When the scheduler is invoked on a threshold level, IxAtmdAcc gives the
 643  * minimum number of cells (to ensure the callback will fire again later)
 644  * and the maximum number of cells that @a ixAtmdAccPortTxProcess()
 645  * will be able to process (assuming the ATM scheduler is able
 646  * to produce the worst-case schedule table, i.e. one entry per cell).
 647  *
 648  * When invoked ouside a threshold level, the overall number of cells of
 649  * the schedule table should be less than the number of cells returned
 650  * by the @a ixAtmdAccPortTxFreeEntriesQuery() function.
 651  *
 652  * After invoking the @a ixAtmdAccPortTxProcess() function, it is the
 653  * user choice to query again the queue level with the function
 654  * @a ixAtmdAccPortTxFreeEntriesQuery() and, depending on a new cell
 655  * number, submit an other schedule table.
 656  *
 657  * IxAtmdAcc will check that the number of cells in the schedule table
 658  * is compatible with the current transmit level. If the
 659  *
 660  * Obsolete or invalid connection Id will be silently discarded.
 661  *
 662  * This function is not reentrant for the same port.
 663  *
 664  * This functions doesn't use system resources and can be used inside an
 665  * interrupt context.
 666  *
 667  * This function is used as a response to the hardware requesting more
 668  * cells to transmit.
 669  *
 670  * @sa ixAtmdAccPortTxScheduledModeEnable
 671  * @sa ixAtmdAccPortTxFreeEntriesQuery
 672  * @sa ixAtmdAccPortTxCallbackRegister
 673  * @sa ixAtmdAccPortEnable
 674  *
 675  * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 676  * @param scheduleTablePtr @ref IxAtmScheduleTable* [in] - pointer to a scheduler update table. The
 677  *     content of this table is not modified by this function. This
 678  *     parameter cannot be a null pointer.
 679  *
 680  * @return @li IX_SUCCESS the schedule table process is complete
 681  *             and cells are transmitted to the hardware
 682  * @return @li IX_ATMDACC_WARNING : Traffic will be dropped: the schedule table exceed
 683  *     the hardware capacity  If this error is ignored, further traffic
 684  *     and schedule will work correctly.
 685  *     Overscheduling does not occur when the schedule table does
 686  *     not contain more entries that the number of free entries returned
 687  *     by @a ixAtmdAccPortTxFreeEntriesQuery().
 688  *     However, Disconnect attempts just after this error will fail permanently
 689  *     with the error code @a IX_ATMDACC_RESOURCES_STILL_ALLOCATED, and it is
 690  *     necessary to disable the port to make @a ixAtmdAccTxVcTryDisconnect()
 691  *     successful.
 692  * @return @li IX_FAIL a wrong parameter is supplied, or the format of
 693  *     the schedule table is invalid, or the port is not Enabled, or
 694  *     an internal severe error occured. No cells is transmitted to the hardware
 695  *
 696  * @note - If the failure is linked to an overschedule of data cells
 697  *     the result is an inconsistency in the output traffic (one or many
 698  *     cells may be missing and the traffic contract is not respected).
 699  *
 700  */
 701 PUBLIC IX_STATUS ixAtmdAccPortTxProcess (IxAtmLogicalPort port,
 702     IxAtmScheduleTable* scheduleTablePtr);
 703
 704 /**
 705  *
 706  * @ingroup IxAtmdAccCtrlAPI
 707  *
 708  * @fn ixAtmdAccTxDoneDispatch (unsigned int numberOfPdusToProcess,
 709                 unsigned int *numberOfPdusProcessedPtr)
 710  *
 711  * @brief Process a number of pending transmit done pdus from the hardware.
 712  *
 713  * As a by-product of Atm transmit operation buffers which transmission
 714  * is complete need to be recycled to users. This function is invoked
 715  * to service the oustanding list of transmitted buffers and pass them
 716  * to VC users.
 717  *
 718  * Users are handed back pdus by invoking the free callback registered
 719  * during the @a ixAtmdAccTxVcConnect() call.
 720  *
 721  * There is a single Tx done stream servicing all active Atm Tx ports
 722  * which can contain a maximum of 64 entries. If this stream fills port
 723  * transmission will stop so this function must be call sufficently
 724  * frequently to ensure no disruption to the transmit operation.
 725  *
 726  * This function can be used from a timer context, or can be associated
 727  * with a TxDone level threshold event (see @a ixAtmdAccTxDoneDispatcherRegister() ),
 728  * or can be used inside an active polling mechanism under user control.
 729  *
 730  * For ease of use the signature of this function is compatible with the
 731  * TxDone threshold event callback prototype.
 732  *
 733  * This functions can be used inside an interrupt context.
 734  *
 735  * @sa ixAtmdAccTxDoneDispatcherRegister
 736  * @sa IxAtmdAccTxVcBufferReturnCallback
 737  * @sa ixAtmdAccTxDoneLevelQuery
 738  *
 739  * @param numberOfPdusToProcess unsigned int [in] - maxiumum number of pdus to remove
 740  *     from the TX Done queue
 741  * @param *numberOfPdusProcessedPtr unsigned int [out] - number of pdus removed from
 742  *     the TX Done queue. This parameter cannot be a null pointer.
 743  *
 744  * @return @li IX_SUCCESS the number of pdus as indicated in
 745  *     numberOfPdusToProcess are removed from the TX Done hardware
 746  *     and passed to the user through the Tx Done callback registered
 747  *     during a call to @a ixAtmdAccTxVcConnect()
 748  * @return @li IX_FAIL invalid parameters or numberOfPdusProcessedPtr is
 749  *     a null pointer or some unspecified internal error occured.
 750  *
 751  */
 752 PUBLIC IX_STATUS
 753 ixAtmdAccTxDoneDispatch (unsigned int numberOfPdusToProcess,
 754                 unsigned int *numberOfPdusProcessedPtr);
 755
 756 /**
 757  *
 758  * @ingroup IxAtmdAccCtrlAPI
 759  *
 760  * @fn ixAtmdAccTxDoneLevelQuery (unsigned int *numberOfPdusPtr)
 761  *
 762  * @brief Query the current number of transmit pdus ready for
 763  *        recycling.
 764  *
 765  * This function is used to get the number of transmitted pdus which
 766  * the hardware is ready to hand back to user.
 767  *
 768  * This function can be used from a timer context, or can be associated
 769  * with a threshold event, on can be used inside an active polling
 770  * mechanism
 771  *
 772  * @sa ixAtmdAccTxDoneDispatch
 773  *
 774  * @param *numberOfPdusPtr unsigned int [out] - Pointer to the number of pdus transmitted
 775  *        at the time of this function call, and ready for recycling
 776  *        This parameter cannot be a null pointer.
 777  *
 778  * @return @li IX_SUCCESS numberOfPdusPtr contains the number of pdus
 779  *        ready for recycling at the time of this function call
 780  *
 781  * @return @li IX_FAIL wrong parameter (null pointer as parameter).or
 782  *         unspecified rocessing error occurs..The value in numberOfPdusPtr
 783  *         is unspecified.
 784  *
 785  */
 786 PUBLIC IX_STATUS
 787 ixAtmdAccTxDoneLevelQuery (unsigned int *numberOfPdusPtr);
 788
 789 /**
 790  *
 791  * @ingroup IxAtmdAccCtrlAPI
 792  *
 793  * @fn ixAtmdAccTxDoneQueueSizeQuery (unsigned int *numberOfPdusPtr)
 794  *
 795  * @brief Query the TxDone queue size.
 796  *
 797  * This function is used to get the number of pdus which
 798  * the hardware is able to store after transmission is complete
 799  *
 800  * The returned value can be used to set a threshold and enable
 801  * a callback to be notified when the number of pdus is going over
 802  * the threshold.
 803  *
 804  * @sa ixAtmdAccTxDoneDispatcherRegister
 805  *
 806  * @param *numberOfPdusPtr unsigned int [out] - Pointer to the number of pdus the system
 807  *        is able to queue after transmission
 808  *
 809  * @return @li IX_SUCCESS numberOfPdusPtr contains the the number of
 810  *        pdus the system is able to queue after transmission
 811  * @return @li IX_FAIL wrong parameter (null pointer as parameter).or
 812  *         unspecified rocessing error occurs..The value in numberOfPdusPtr
 813  *         is unspecified.
 814  *
 815  * @note - This function is reentrant, doesn't use system resources
 816  *         and can be used from an interrupt context.
 817  */
 818 PUBLIC IX_STATUS
 819 ixAtmdAccTxDoneQueueSizeQuery (unsigned int *numberOfPdusPtr);
 820
 821 /**
 822  *
 823  * @ingroup IxAtmdAccCtrlAPI
 824  *
 825  * @fn ixAtmdAccTxDoneDispatcherRegister (unsigned int numberOfPdus,
 826    IxAtmdAccTxDoneDispatcher notificationCallback)
 827  *
 828  * @brief Configure the Tx Done stream threshold value and register a
 829  * callback to handle threshold notifications.
 830  *
 831  * This function sets the threshold level in term of number of pdus at
 832  * which the supplied notification function should be called.
 833  *
 834  * The higher the threshold value is, the less events will be necessary
 835  * to process transmitted buffers.
 836  *
 837  * Transmitted buffers recycling implementation is a sytem-wide mechanism
 838  * and needs to be set prior any traffic is started. If this threshold
 839  * mechanism is not used, the user is responsible for polling the
 840  * transmitted buffers thanks to @a ixAtmdAccTxDoneDispatch() and
 841  * @a ixAtmdAccTxDoneLevelQuery() functions.
 842  *
 843  * This function should be called during system initialisation outside
 844  * an interrupt context
 845  *
 846  * @sa ixAtmdAccTxDoneDispatcherRegister
 847  * @sa ixAtmdAccTxDoneDispatch
 848  * @sa ixAtmdAccTxDoneLevelQuery
 849  *
 850  * @param numberOfPdus unsigned int [in] - The number of TxDone pdus which triggers the
 851  *        callback invocation This number has to be a power of 2, one of the
 852  *        values 0,1,2,4,8,16,32 ...
 853  *        The maximum value cannot be more than half of the txDone queue
 854  *        size (which can be retrieved using @a ixAtmdAccTxDoneQueueSizeQuery())
 855  * @param notificationCallback @ref IxAtmdAccTxDoneDispatcher [in] - The function to invoke. (This
 856  *        parameter can be @a ixAtmdAccTxDoneDispatch()).This
 857  *        parameter ust not be a null pointer.
 858  *
 859  * @return @li IX_SUCCESS Successful call to ixAtmdAccTxDoneDispatcherRegister
 860  * @return @li IX_FAIL error in the parameters:
 861  *
 862  * @note - The notificationCallback will be called exactly when the threshold level
 863  *         will increase from (numberOfPdus) to (numberOfPdus+1)
 864  *
 865  * @note - If there is no Tx traffic, there is no guarantee that TxDone Pdus will
 866  *       be released to the user (when txDone level is permanently under the threshold
 867  *       level. One of the preffered way to return resources to the user is to use
 868  *       a mix of txDone notifications, used together with a slow
 869  *       rate timer and an exclusion mechanism protecting from re-entrancy
 870  *
 871  * @note - The TxDone threshold will only hand back buffers when the threshold level is
 872  *      crossed. Setting this threshold to a great number reduce the interrupt rate
 873  *      and the cpu load, but also increase the number of outstanding mbufs and has
 874  *      a system wide impact when these mbufs are needed by other components.
 875  *
 876  */
 877 PUBLIC IX_STATUS ixAtmdAccTxDoneDispatcherRegister (unsigned int numberOfPdus,
 878    IxAtmdAccTxDoneDispatcher notificationCallback);
 879
 880 /* ------------------------------------------------------
 881    Part of the IxAtmdAcc interface related to Utopia config
 882    ------------------------------------------------------ */
 883
 884 /**
 885  *
 886  * @ingroup IxAtmdAccCtrlAPI
 887  *
 888  * @defgroup IxAtmdAccUtopiaCtrlAPI IXP400 ATM Driver Access (IxAtmdAcc) Utopia Control API
 889  *
 890  * @brief The public API for the IXP400 Atm Driver Control component
 891  *
 892  * IxAtmdAcc is the low level interface by which AAL PDU get
 893  * transmitted to,and received from the Utopia bus
 894  *
 895  * This part is related to the UTOPIA configuration.
 896  *
 897  * @{
 898  */
 899
 900 /**
 901  *
 902  * @brief Utopia configuration
 903  *
 904  * This structure is used to set the Utopia parameters
 905  * @li contains the values of Utopia registers, to be set during initialisation
 906  * @li contains debug commands for NPE, to be used during development steps
 907  *
 908  * @note - the exact description of all parameters is done in the Utopia reference
 909  *   documents.
 910  *
 911  */
 912 typedef struct
 913 {
 914     /**
 915     * @ingroup IxAtmdAccUtopiaCtrlAPI
 916     * @struct UtTxConfig_
 917     * @brief Utopia Tx Config Register
 918     */
 919     struct UtTxConfig_
 920     {
 921
 922     unsigned int reserved_1:1;  /**< [31] These bits are always 0.*/
 923     unsigned int txInterface:1;     /**< [30] Utopia Transmit Interface. The following encoding
 924                                    * is used to set the Utopia Transmit interface as ATM master
 925                                    * or PHY slave:
 926                                    * @li 1 - PHY
 927                                    * @li 0 - ATM
 928                                    */
 929     unsigned int txMode:1;      /**< [29] Utopia Transmit Mode. The following encoding is used
 930     *  to set the Utopia Transmit mode to SPHY or MPHY:
 931     *  @li 1 - SPHY
 932     *  @li 0 - MPHY
 933     */
 934     unsigned int txOctet:1;  /**< [28] Utopia Transmit cell transfer protocol. Used to set
 935     * the Utopia cell transfer protocol to Octet-level handshaking.
 936     * Note this is only applicable in SPHY mode.
 937     * @li 1 - Octet-handshaking enabled
 938     * @li 0 - Cell-handshaking enabled
 939     */
 940     unsigned int txParity:1;    /**< [27] Utopia Transmit parity enabled when set. TxEvenParity
 941     * defines the parity format odd/even.
 942     * @li 1 - Enable Parity generation.
 943     * @li 0 - ut_op_prty held low.
 944     */
 945     unsigned int txEvenParity:1; /**< [26] Utopia Transmit Parity Mode
 946     * @li 1 - Even Parity Generated.
 947     * @li 0 - Odd Parity Generated.
 948     */
 949     unsigned int txHEC:1; /**< [25] Header Error Check Insertion Mode. Specifies if the transmit
 950     * cell header check byte is calculated and inserted when set.
 951     * @li 1 - Generate HEC.
 952     * @li 0 - Disable HEC generation.
 953     */
 954     unsigned int txCOSET:1;    /**< [24] If enabled the HEC is Exclusive-OR'ed with the value 0x55 before
 955   * being presented on the Utopia bus.
 956   * @li 1 - Enable HEC ExOR with value 0x55
 957   * @li 0 - Use generated HEC value.
 958   */
 959
 960     unsigned int reserved_2:1;    /**< [23] These bits are always 0
 961     */
 962     unsigned int txCellSize:7;    /**< [22:16] Transmit expected cell size. Configures the cell size
 963     * for the transmit module: Values between 52-64 are valid.
 964     */
 965     unsigned int reserved_3:3;  /**< [15:13] These bits are always 0 */
 966     unsigned int txAddrRange:5;       /**< [12:8] When configured as an ATM master in MPHY mode this
 967     * register specifies the upper limit of the PHY polling logical
 968     * range. The number of active PHYs are TxAddrRange + 1.
 969     */
 970     unsigned int reserved_4:3;      /**< [7:5] These bits are always 0 */
 971     unsigned int txPHYAddr:5;     /**< [4:0] When configured as a slave in an MPHY system this register
 972     * specifies the physical address of the PHY.
 973     */
 974     }
 975
 976     utTxConfig;       /**< Tx config Utopia register */
 977
 978    /**
 979     * @ingroup IxAtmdAccUtopiaCtrlAPI
 980    * @struct UtTxStatsConfig_
 981    * @brief Utopia Tx stats Register
 982     */
 983     struct UtTxStatsConfig_
 984     {
 985
 986     unsigned int vpi:12;  /**< [31:20] ATM VPI [11:0] OR GFC [3:0] and VPI [7:0]
 987     @li Note: if VCStatsTxGFC is set to 0 the GFC field is ignored in test. */
 988
 989     unsigned int vci:16;  /**< [19:4] ATM VCI [15:0] or PHY Address[4] */
 990
 991     unsigned int pti:3;  /**< [3:1] ATM PTI [2:0] or PHY Address[3:1]
 992   @li Note: if VCStatsTxPTI is set to 0 the PTI field is ignored in test.
 993   @li Note: if VCStatsTxEnb is set to 0 only the transmit PHY port
 994   address as defined by this register is used for ATM statistics [4:0]. */
 995
 996     unsigned int clp:1;  /**< [0] ATM CLP or PHY Address [0]
 997   @li Note: if VCStatsTxCLP is set to 0 the CLP field is ignored in test.
 998   @li Note: if VCStatsTxEnb is set to 0 only the transmit PHY port
 999   address as defined by this register is used for ATM statistics [4:0]. */
1000     }
1001
1002     utTxStatsConfig;       /**< Tx stats config Utopia register */
1003
1004        /**
1005     * @ingroup IxAtmdAccUtopiaCtrlAPI
1006        * @struct UtTxDefineIdle_
1007        * @brief Utopia Tx idle cells Register
1008     */
1009     struct UtTxDefineIdle_
1010     {
1011
1012     unsigned int vpi:12;  /**< [31:20] ATM VPI [11:0] OR GFC [3:0] and VPI [7:0]
1013     @li Note: if VCIdleTxGFC is set to 0 the GFC field is ignored in test. */
1014
1015     unsigned int vci:16;  /**< [19:4] ATM VCI [15:0] */
1016
1017     unsigned int pti:3;  /**< [3:1] ATM PTI PTI [2:0]
1018   @li Note: if VCIdleTxPTI is set to 0 the PTI field is ignored in test.*/
1019
1020     unsigned int clp:1;  /**< [0] ATM CLP [0]
1021   @li Note: if VCIdleTxCLP is set to 0 the CLP field is ignored in test.*/
1022     }
1023
1024     utTxDefineIdle;      /**< Tx idle cell config Utopia register */
1025
1026       /**
1027     * @ingroup IxAtmdAccUtopiaCtrlAPI
1028       * @struct UtTxEnableFields_
1029       * @brief Utopia Tx ienable fields Register
1030     */
1031     struct UtTxEnableFields_
1032     {
1033
1034     unsigned int defineTxIdleGFC:1;    /**< [31] This register is used to include or exclude the GFC
1035     field of the ATM header when testing for Idle cells.
1036     @li 1 - GFC field is valid.
1037     @li 0 - GFC field ignored.*/
1038
1039     unsigned int defineTxIdlePTI:1;    /**< [30] This register is used to include or exclude the PTI
1040     field of the ATM header when testing for Idle cells.
1041     @li 1 - PTI field is valid
1042     @li    0 - PTI field ignored.*/
1043
1044     unsigned int defineTxIdleCLP:1;    /**< [29] This register is used to include or
1045     exclude the CLP field of the ATM header when testing for Idle cells.
1046     @li 1 - CLP field is valid.
1047     @li 0 - CLP field ignored. */
1048
1049     unsigned int phyStatsTxEnb:1;    /**< [28] This register is used to enable or disable ATM
1050   statistics gathering based on the specified PHY address as defined
1051   in TxStatsConfig register.
1052   @li 1 - Enable statistics for specified transmit PHY address.
1053     @li 0 - Disable statistics for specified transmit PHY address. */
1054
1055     unsigned int vcStatsTxEnb:1;  /**< [27] This register is used to change the ATM
1056       statistics-gathering mode from the specified logical PHY address
1057       to a specific VPI/VCI address.
1058       @li 1 - Enable statistics for specified VPI/VCI address.
1059       @li 0 - Disable statistics for specified VPI/VCI address */
1060
1061     unsigned int vcStatsTxGFC:1;  /**< [26] This register is used to include or exclude the GFC
1062       field of the ATM header when ATM VPI/VCI statistics are enabled.
1063       GFC is only available at the UNI and uses the first 4-bits of
1064       the VPI field.
1065       @li 1 - GFC field is valid
1066       @li 0 - GFC field ignored.*/
1067
1068     unsigned int vcStatsTxPTI:1;  /**< [25] This register is used to include or exclude the PTI
1069       field of the ATM header when ATM VPI/VCI statistics are enabled.
1070       @li 1 - PTI field is valid
1071       @li 0 - PTI field ignored.*/
1072
1073     unsigned int vcStatsTxCLP:1;  /**< [24] This register is used to include or exclude the CLP
1074       field of the ATM header when ATM VPI/VCI statistics are enabled.
1075       @li 1 - CLP field is valid
1076       @li 0 - CLP field ignored. */
1077
1078     unsigned int reserved_1:3;  /**< [23-21] These bits are always 0 */
1079
1080     unsigned int txPollStsInt:1;    /**< [20] Enable the assertion of the ucp_tx_poll_sts condition
1081   where there is a change in polling status.
1082   @li 1 - ucp_tx_poll_sts asserted whenever there is a change in status
1083   @li    0 - ucp_tx_poll_sts asserted if ANY transmit PHY is available
1084   */
1085     unsigned int txCellOvrInt:1;    /**< [19] Enable TxCellCount overflow CBI Transmit Status condition
1086       assertion.
1087       @li 1 - If TxCellCountOvr is set assert the Transmit Status Condition.
1088       @li 0 - No CBI Transmit Status condition assertion */
1089
1090     unsigned int txIdleCellOvrInt:1;  /**< [18] Enable TxIdleCellCount overflow Transmit Status Condition
1091     @li 1 - If TxIdleCellCountOvr is set assert the Transmit Status Condition
1092       @li 0 - No CBI Transmit Status condition assertion..*/
1093
1094     unsigned int enbIdleCellCnt:1;    /**< [17] Enable Transmit Idle Cell Count.
1095     @li 1 - Enable count of Idle cells transmitted.
1096       @li 0 - No count is maintained. */
1097
1098     unsigned int enbTxCellCnt:1;    /**< [16] Enable Transmit Valid Cell Count of non-idle/non-error cells
1099       @li 1 - Enable count of valid cells transmitted- non-idle/non-error
1100       @li 0 - No count is maintained.*/
1101
1102     unsigned int reserved_2:16;   /**< [15:0] These bits are always 0 */
1103     } utTxEnableFields;  /**< Tx enable Utopia register */
1104
1105     /**
1106     * @ingroup IxAtmdAccUtopiaCtrlAPI
1107     * @struct UtTxTransTable0_
1108     * @brief Utopia Tx translation table Register
1109     */
1110     struct UtTxTransTable0_
1111     {
1112
1113     unsigned int phy0:5;  /**< [31-27] Tx Mapping value of logical phy 0 */
1114
1115     unsigned int phy1:5;  /**< [26-22] Tx Mapping value of logical phy 1 */
1116
1117     unsigned int phy2:5;  /**< [21-17] Tx Mapping value of logical phy 2 */
1118
1119     unsigned int reserved_1:1;  /**< [16] These bits are always 0.*/
1120
1121     unsigned int phy3:5;  /**< [15-11] Tx Mapping value of logical phy 3 */
1122
1123     unsigned int phy4:5;  /**< [10-6] Tx Mapping value of logical phy 4 */
1124
1125     unsigned int phy5:5;  /**< [5-1] Tx Mapping value of logical phy 5 */
1126
1127     unsigned int reserved_2:1;  /**< [0] These bits are always 0 */
1128     } utTxTransTable0;  /**< Tx translation table */
1129
1130   /**
1131     * @ingroup IxAtmdAccUtopiaCtrlAPI
1132   * @struct UtTxTransTable1_
1133   * @brief Utopia Tx translation table Register
1134     */
1135     struct UtTxTransTable1_
1136     {
1137
1138     unsigned int phy6:5;  /**< [31-27] Tx Mapping value of logical phy 6 */
1139
1140     unsigned int phy7:5;  /**< [26-22] Tx Mapping value of logical phy 7 */
1141
1142     unsigned int phy8:5;  /**< [21-17] Tx Mapping value of logical phy 8 */
1143
1144     unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */
1145
1146     unsigned int phy9:5;  /**< [15-11] Tx Mapping value of logical phy 3 */
1147
1148     unsigned int phy10:5;   /**< [10-6] Tx Mapping value of logical phy 4 */
1149
1150     unsigned int phy11:5;   /**< [5-1] Tx Mapping value of logical phy 5 */
1151
1152     unsigned int reserved_2:1;  /**< [0] These bits are always 0 */
1153     } utTxTransTable1;  /**< Tx translation table */
1154
1155     /**
1156     * @ingroup IxAtmdAccUtopiaCtrlAPI
1157     * @struct UtTxTransTable2_
1158     * @brief Utopia Tx translation table Register
1159     */
1160     struct UtTxTransTable2_
1161     {
1162
1163     unsigned int phy12:5;   /**< [31-27] Tx Mapping value of logical phy 6 */
1164
1165     unsigned int phy13:5;   /**< [26-22] Tx Mapping value of logical phy 7 */
1166
1167     unsigned int phy14:5;   /**< [21-17] Tx Mapping value of logical phy 8 */
1168
1169     unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */
1170
1171     unsigned int phy15:5;   /**< [15-11] Tx Mapping value of logical phy 3 */
1172
1173     unsigned int phy16:5;   /**< [10-6] Tx Mapping value of logical phy 4 */
1174
1175     unsigned int phy17:5;   /**< [5-1] Tx Mapping value of logical phy 5 */
1176
1177     unsigned int reserved_2:1;  /**< [0] These bits are always 0 */
1178     } utTxTransTable2;    /**< Tx translation table */
1179
1180     /**
1181     * @ingroup IxAtmdAccUtopiaCtrlAPI
1182     * @struct UtTxTransTable3_
1183     * @brief Utopia Tx translation table Register
1184     */
1185     struct UtTxTransTable3_
1186     {
1187
1188     unsigned int phy18:5;   /**< [31-27] Tx Mapping value of logical phy 6 */
1189
1190     unsigned int phy19:5;   /**< [26-22] Tx Mapping value of logical phy 7 */
1191
1192     unsigned int phy20:5;   /**< [21-17] Tx Mapping value of logical phy 8 */
1193
1194     unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */
1195
1196     unsigned int phy21:5;   /**< [15-11] Tx Mapping value of logical phy 3 */
1197
1198     unsigned int phy22:5;   /**< [10-6] Tx Mapping value of logical phy 4 */
1199
1200     unsigned int phy23:5;   /**< [5-1] Tx Mapping value of logical phy 5 */
1201
1202     unsigned int reserved_2:1;  /**< [0] These bits are always 0 */
1203     } utTxTransTable3;  /**< Tx translation table */
1204
1205     /**
1206     * @ingroup IxAtmdAccUtopiaCtrlAPI
1207     * @struct UtTxTransTable4_
1208     * @brief Utopia Tx translation table Register
1209     */
1210     struct UtTxTransTable4_
1211     {
1212
1213     unsigned int phy24:5;   /**< [31-27] Tx Mapping value of logical phy 6 */
1214
1215     unsigned int phy25:5;   /**< [26-22] Tx Mapping value of logical phy 7 */
1216
1217     unsigned int phy26:5;   /**< [21-17] Tx Mapping value of logical phy 8 */
1218
1219     unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */
1220
1221     unsigned int phy27:5;   /**< [15-11] Tx Mapping value of logical phy 3 */
1222
1223     unsigned int phy28:5;   /**< [10-6] Tx Mapping value of logical phy 4 */
1224
1225     unsigned int phy29:5;   /**< [5-1] Tx Mapping value of logical phy 5 */
1226
1227     unsigned int reserved_2:1;  /**< [0] These bits are always 0 */
1228     } utTxTransTable4;  /**< Tx translation table */
1229
1230     /**
1231     * @ingroup IxAtmdAccUtopiaCtrlAPI
1232     * @struct UtTxTransTable5_
1233     * @brief Utopia Tx translation table Register
1234     */
1235     struct UtTxTransTable5_
1236     {
1237
1238     unsigned int phy30:5;   /**< [31-27] Tx Mapping value of logical phy 6 */
1239
1240     unsigned int reserved_1:27;     /**< [26-0] These bits are always 0 */
1241
1242     } utTxTransTable5;  /**< Tx translation table */
1243
1244     /**
1245     * @ingroup IxAtmdAccUtopiaCtrlAPI
1246     * @struct UtRxConfig_
1247     * @brief Utopia Rx config Register
1248     */
1249     struct UtRxConfig_
1250     {
1251
1252     unsigned int rxInterface:1;    /**< [31] Utopia Receive Interface. The following encoding is used
1253  to set the Utopia Receive interface as ATM master or PHY slave:
1254  @li 1 - PHY
1255     @li 0 - ATM */
1256
1257     unsigned int rxMode:1;      /**< [30] Utopia Receive Mode. The following encoding is used to set
1258       the Utopia Receive mode to SPHY or MPHY:
1259       @li 1 - SPHY
1260     @li 0 - MPHY */
1261
1262     unsigned int rxOctet:1;  /**< [29] Utopia Receive cell transfer protocol. Used to set the Utopia
1263   cell transfer protocol to Octet-level handshaking. Note this is only
1264   applicable in SPHY mode.
1265   @li 1 - Octet-handshaking enabled
1266     @li 0 - Cell-handshaking enabled */
1267
1268     unsigned int rxParity:1;    /**< [28] Utopia Receive Parity Checking enable.
1269     @li 1 - Parity checking enabled
1270     @li 0 - Parity checking disabled */
1271
1272     unsigned int rxEvenParity:1;/**< [27] Utopia Receive Parity Mode
1273     @li 1 - Check for Even Parity
1274     @li 0 - Check for Odd Parity.*/
1275
1276     unsigned int rxHEC:1;    /**< [26] RxHEC    Header Error Check Mode. Enables/disables cell header
1277     error checking on the received cell header.
1278     @li 1 - HEC checking enabled
1279     @li 0 - HEC checking disabled */
1280
1281     unsigned int rxCOSET:1;  /**< [25] If enabled the HEC is Exclusive-OR'ed with the value 0x55
1282   before being tested with the received HEC.
1283   @li 1 - Enable HEC ExOR with value 0x55.
1284     @li 0 - Use generated HEC value.*/
1285
1286     unsigned int rxHECpass:1;    /**< [24] Specifies if the incoming cell HEC byte should be transferred
1287      after optional processing to the NPE2 Coprocessor Bus Interface or
1288      if it should be discarded.
1289      @li 1 - HEC maintained 53-byte/UDC cell sent to NPE2.
1290     @li 0 - HEC discarded 52-byte/UDC cell sent to NPE2 coprocessor.*/
1291
1292     unsigned int reserved_1:1;    /**< [23] These bits are always 0 */
1293
1294     unsigned int rxCellSize:7;    /**< [22:16] Receive cell size. Configures the receive cell size.
1295       Values between 52-64 are valid */
1296
1297     unsigned int rxHashEnbGFC:1;      /**< [15] Specifies if the VPI field [11:8]/GFC field should be
1298       included in the Hash data input or if the bits should be padded
1299       with 1'b0.
1300       @li 1 - VPI [11:8]/GFC field valid and used in Hash residue calculation.
1301       @li 0 - VPI [11:8]/GFC field padded with 1'b0 */
1302
1303     unsigned int rxPreHash:1; /**< [14] Enable Pre-hash value generation. Specifies if the
1304  incoming cell data should be pre-hashed to allow VPI/VCI header look-up
1305  in a hash table.
1306  @li 1 - Pre-hashing enabled
1307       @li 0 - Pre-hashing disabled */
1308
1309     unsigned int reserved_2:1;    /**< [13] These bits are always 0 */
1310
1311     unsigned int rxAddrRange:5;     /**< [12:8] In ATM master, MPHY mode,
1312      * this register specifies the upper
1313      * limit of the PHY polling logical range. The number of active PHYs are
1314      * RxAddrRange + 1.
1315      */
1316     unsigned int reserved_3:3;    /**< [7-5] These bits are always 0 .*/
1317     unsigned int rxPHYAddr:5;     /**< [4:0] When configured as a slave in an MPHY system this register
1318       * specifies the physical address of the PHY.
1319       */
1320     } utRxConfig;  /**< Rx config Utopia register */
1321
1322       /**
1323     * @ingroup IxAtmdAccUtopiaCtrlAPI
1324       * @struct UtRxStatsConfig_
1325       * @brief Utopia Rx stats config Register
1326     */
1327     struct UtRxStatsConfig_
1328     {
1329
1330     unsigned int vpi:12;  /**< [31:20] ATM VPI    VPI [11:0] OR GFC [3:0] and VPI [7:0]
1331     @li Note: if VCStatsRxGFC is set to 0 the GFC field is ignored in test. */
1332
1333     unsigned int vci:16;  /**< [19:4] VCI [15:0] or PHY Address [4] */
1334
1335     unsigned int pti:3;  /**< [3:1] PTI [2:0] or or PHY Address [3:1]
1336   @li Note: if VCStatsRxPTI is set to 0 the PTI field is ignored in test.
1337   @li Note: if VCStatsRxEnb is set to 0 only the PHY port address is used
1338   for statistics gathering.. */
1339
1340     unsigned int clp:1;  /**< [0] CLP [0] or PHY Address [0]
1341   @li Note: if VCStatsRxCLP is set to 0 the CLP field is ignored in test.
1342   @li Note: if VCStatsRxEnb is set to 0 only the PHY port address is used
1343   for statistics gathering.. */
1344     } utRxStatsConfig;  /**< Rx stats config Utopia register */
1345
1346   /**
1347     * @ingroup IxAtmdAccUtopiaCtrlAPI
1348   * @struct UtRxDefineIdle_
1349   * @brief Utopia Rx idle cells config Register
1350     */
1351     struct UtRxDefineIdle_
1352     {
1353
1354     unsigned int vpi:12;  /**< [31:20] ATM VPI [11:0] OR GFC [3:0] and VPI [7:0]
1355     @li Note: if VCIdleRxGFC is set to 0 the GFC field is ignored in test. */
1356
1357     unsigned int vci:16;  /**< [19:4] ATM VCI [15:0] */
1358
1359     unsigned int pti:3;  /**< [3:1] ATM PTI PTI [2:0]
1360   @li Note: if VCIdleRxPTI is set to 0 the PTI field is ignored in test.*/
1361
1362     unsigned int clp:1;  /**< [0] ATM CLP [0]
1363   @li Note: if VCIdleRxCLP is set to 0 the CLP field is ignored in test.*/
1364     } utRxDefineIdle;      /**< Rx idle cell config Utopia register */
1365
1366       /**
1367     * @ingroup IxAtmdAccUtopiaCtrlAPI
1368       * @struct UtRxEnableFields_
1369       * @brief Utopia Rx enable Register
1370     */
1371     struct UtRxEnableFields_
1372     {
1373
1374     unsigned int defineRxIdleGFC:1;/**< [31] This register is used to include or exclude the GFC
1375  field of the ATM header when testing for Idle cells.
1376  @li 1 - GFC field is valid.
1377     @li 0 - GFC field ignored.*/
1378
1379     unsigned int defineRxIdlePTI:1;/**< [30] This register is used to include or exclude the PTI
1380  field of the ATM header when testing for Idle cells.
1381  @li 1 - PTI field is valid.
1382     @li 0 - PTI field ignored.*/
1383
1384     unsigned int defineRxIdleCLP:1;/**< [29] This register is used to include or exclude the CLP
1385  field of the ATM header when testing for Idle cells.
1386  @li 1 - CLP field is valid.
1387     @li    0 - CLP field ignored.*/
1388
1389     unsigned int phyStatsRxEnb:1;/**< [28] This register is used to enable or disable ATM statistics
1390      gathering based on the specified PHY address as defined in RxStatsConfig
1391      register.
1392      @li 1 - Enable statistics for specified receive PHY address.
1393     @li 0 - Disable statistics for specified receive PHY address.*/
1394
1395     unsigned int vcStatsRxEnb:1;/**< [27] This register is used to enable or disable ATM statistics
1396     gathering based on a specific VPI/VCI address.
1397     @li 1 - Enable statistics for specified VPI/VCI address.
1398     @li 0 - Disable statistics for specified VPI/VCI address.*/
1399
1400     unsigned int vcStatsRxGFC:1;/**< [26] This register is used to include or exclude the GFC field
1401     of the ATM header when ATM VPI/VCI statistics are enabled. GFC is only
1402     available at the UNI and uses the first 4-bits of the VPI field.
1403     @li 1 - GFC field is valid.
1404     @li 0 - GFC field ignored. */
1405
1406     unsigned int vcStatsRxPTI:1;/**< [25] This register is used to include or exclude the PTI field
1407     of the ATM header when ATM VPI/VCI statistics are enabled.
1408     @li 1 - PTI field is valid.
1409     @li 0 - PTI field ignored.*/
1410
1411     unsigned int vcStatsRxCLP:1;/**< [24] This register is used to include or exclude the CLP field
1412     of the ATM header when ATM VPI/VCI statistics are enabled.
1413     @li 1 - CLP field is valid.
1414     @li 0 - CLP field ignored. */
1415
1416     unsigned int discardHecErr:1;/**< [23] Discard cells with an invalid HEC.
1417      @li 1 - Discard cells with HEC errors
1418     @li 0 - Cells with HEC errors are passed */
1419
1420     unsigned int discardParErr:1;/**< [22] Discard cells containing parity errors.
1421      @li 1 - Discard cells with parity errors
1422     @li 0 - Cells with parity errors are passed */
1423
1424     unsigned int discardIdle:1;    /**< [21] Discard Idle Cells based on DefineIdle register values
1425  @li    1 - Discard IDLE cells
1426     @li 0 - IDLE cells passed */
1427
1428     unsigned int enbHecErrCnt:1;/**< [20] Enable Receive HEC Error Count.
1429     @li 1 - Enable count of received cells containing HEC errors
1430     @li 0 - No count is maintained. */
1431
1432     unsigned int enbParErrCnt:1;/**< [19] Enable Parity Error Count
1433     @li    1 - Enable count of received cells containing Parity errors
1434     @li 0 - No count is maintained. */
1435
1436     unsigned int enbIdleCellCnt:1;/**< [18] Enable Receive Idle Cell Count.
1437       @li 1 - Enable count of Idle cells received.
1438     @li 0 - No count is maintained.*/
1439
1440     unsigned int enbSizeErrCnt:1;/**< [17] Enable Receive Size Error Count.
1441      @li 1 - Enable count of received cells of incorrect size
1442     @li    0 - No count is maintained. */
1443
1444     unsigned int enbRxCellCnt:1;/**< [16] Enable Receive Valid Cell Count of non-idle/non-error cells.
1445     @li    1 - Enable count of valid cells received - non-idle/non-error
1446     @li 0 - No count is maintained. */
1447
1448     unsigned int reserved_1:3;    /**< [15:13] These bits are always 0 */
1449
1450     unsigned int rxCellOvrInt:1;      /**< [12] Enable CBI Utopia Receive Status Condition if the RxCellCount
1451       register overflows.
1452       @li 1 - CBI Receive Status asserted.
1453       @li    0 - No CBI Receive Status asserted.*/
1454
1455     unsigned int invalidHecOvrInt:1;  /**< [11] Enable CBI Receive Status Condition if the InvalidHecCount
1456     register overflows.
1457     @li    1 - CBI Receive Condition asserted.
1458       @li 0 - No CBI Receive Condition asserted */
1459
1460     unsigned int invalidParOvrInt:1;  /**< [10] Enable CBI Receive Status Condition if the InvalidParCount
1461     register overflows
1462     @li    1 - CBI Receive Condition asserted.
1463       @li 0 - No CBI Receive Condition asserted */
1464
1465     unsigned int invalidSizeOvrInt:1;   /**< [9] Enable CBI Receive Status Condition if the InvalidSizeCount
1466      register overflows.
1467      @li 1 - CBI Receive Status Condition asserted.
1468      @li 0 - No CBI Receive Status asserted */
1469
1470     unsigned int rxIdleOvrInt:1;      /**< [8] Enable CBI Receive Status Condition if the RxIdleCount overflows.
1471       @li 1 - CBI Receive Condition asserted.
1472       @li 0 - No CBI Receive Condition asserted */
1473
1474     unsigned int reserved_2:3;    /**< [7:5] These bits are always 0 */
1475
1476     unsigned int rxAddrMask:5;    /**< [4:0] This register is used as a mask to allow the user to increase
1477     the PHY receive address range. The register should be programmed with
1478     the address-range limit, i.e. if set to 0x3 the address range increases
1479   to a maximum of 4 addresses. */
1480     } utRxEnableFields;      /**< Rx enable Utopia register */
1481
1482       /**
1483     * @ingroup IxAtmdAccUtopiaCtrlAPI
1484       * @struct UtRxTransTable0_
1485       * @brief Utopia Rx translation table Register
1486     */
1487     struct UtRxTransTable0_
1488     {
1489
1490     unsigned int phy0:5;  /**< [31-27] Rx Mapping value of logical phy 0 */
1491
1492     unsigned int phy1:5;  /**< [26-22] Rx Mapping value of logical phy 1 */
1493
1494     unsigned int phy2:5;  /**< [21-17] Rx Mapping value of logical phy 2 */
1495
1496     unsigned int reserved_1:1;  /**< [16] These bits are always 0 */
1497
1498     unsigned int phy3:5;  /**< [15-11] Rx Mapping value of logical phy 3 */
1499
1500     unsigned int phy4:5;  /**< [10-6] Rx Mapping value of logical phy 4 */
1501
1502     unsigned int phy5:5;  /**< [5-1] Rx Mapping value of logical phy 5 */
1503
1504     unsigned int reserved_2:1;  /**< [0] These bits are always 0 */
1505     }
1506
1507     utRxTransTable0;  /**< Rx translation table */
1508
1509   /**
1510     * @ingroup IxAtmdAccUtopiaCtrlAPI
1511   * @struct UtRxTransTable1_
1512   * @brief Utopia Rx translation table Register
1513     */
1514     struct UtRxTransTable1_
1515     {
1516
1517     unsigned int phy6:5;  /**< [31-27] Rx Mapping value of logical phy 6 */
1518
1519     unsigned int phy7:5;  /**< [26-22] Rx Mapping value of logical phy 7 */
1520
1521     unsigned int phy8:5;  /**< [21-17] Rx Mapping value of logical phy 8 */
1522
1523     unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */
1524
1525     unsigned int phy9:5;  /**< [15-11] Rx Mapping value of logical phy 3 */
1526
1527     unsigned int phy10:5;   /**< [10-6] Rx Mapping value of logical phy 4 */
1528
1529     unsigned int phy11:5;   /**< [5-1] Rx Mapping value of logical phy 5 */
1530
1531     unsigned int reserved_2:1;  /**< [0] These bits are always 0 */
1532     }
1533
1534     utRxTransTable1;  /**< Rx translation table */
1535
1536     /**
1537     * @ingroup IxAtmdAccUtopiaCtrlAPI
1538     * @struct UtRxTransTable2_
1539     * @brief Utopia Rx translation table Register
1540     */
1541     struct UtRxTransTable2_
1542     {
1543
1544     unsigned int phy12:5;   /**< [31-27] Rx Mapping value of logical phy 6 */
1545
1546     unsigned int phy13:5;   /**< [26-22] Rx Mapping value of logical phy 7 */
1547
1548     unsigned int phy14:5;   /**< [21-17] Rx Mapping value of logical phy 8 */
1549
1550     unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */
1551
1552     unsigned int phy15:5;   /**< [15-11] Rx Mapping value of logical phy 3 */
1553
1554     unsigned int phy16:5;   /**< [10-6] Rx Mapping value of logical phy 4 */
1555
1556     unsigned int phy17:5;   /**< [5-1] Rx Mapping value of logical phy 5 */
1557
1558     unsigned int reserved_2:1;  /**< [0] These bits are always 0 */
1559     } utRxTransTable2;    /**< Rx translation table */
1560
1561     /**
1562     * @ingroup IxAtmdAccUtopiaCtrlAPI
1563     * @struct UtRxTransTable3_
1564     * @brief Utopia Rx translation table Register
1565     */
1566     struct UtRxTransTable3_
1567     {
1568
1569     unsigned int phy18:5;   /**< [31-27] Rx Mapping value of logical phy 6 */
1570
1571     unsigned int phy19:5;   /**< [26-22] Rx Mapping value of logical phy 7 */
1572
1573     unsigned int phy20:5;   /**< [21-17] Rx Mapping value of logical phy 8 */
1574
1575     unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */
1576
1577     unsigned int phy21:5;   /**< [15-11] Rx Mapping value of logical phy 3 */
1578
1579     unsigned int phy22:5;   /**< [10-6] Rx Mapping value of logical phy 4 */
1580
1581     unsigned int phy23:5;   /**< [5-1] Rx Mapping value of logical phy 5 */
1582
1583     unsigned int reserved_2:1;  /**< [0] These bits are always 0 */
1584     } utRxTransTable3;  /**< Rx translation table */
1585
1586     /**
1587     * @ingroup IxAtmdAccUtopiaCtrlAPI
1588     * @struct UtRxTransTable4_
1589     * @brief Utopia Rx translation table Register
1590     */
1591     struct UtRxTransTable4_
1592     {
1593
1594     unsigned int phy24:5;   /**< [31-27] Rx Mapping value of logical phy 6 */
1595
1596     unsigned int phy25:5;   /**< [26-22] Rx Mapping value of logical phy 7 */
1597
1598     unsigned int phy26:5;   /**< [21-17] Rx Mapping value of logical phy 8 */
1599
1600     unsigned int reserved_1:1; /**< [16-0] These bits are always 0 */
1601
1602     unsigned int phy27:5;   /**< [15-11] Rx Mapping value of logical phy 3 */
1603
1604     unsigned int phy28:5;   /**< [10-6] Rx Mapping value of logical phy 4 */
1605
1606     unsigned int phy29:5;   /**< [5-1] Rx Mapping value of logical phy 5 */
1607
1608     unsigned int reserved_2:1;  /**< [0] These bits are always 0 */
1609     } utRxTransTable4;  /**< Rx translation table */
1610
1611     /**
1612     * @ingroup IxAtmdAccUtopiaCtrlAPI
1613     * @struct UtRxTransTable5_
1614     * @brief Utopia Rx translation table Register
1615     */
1616     struct UtRxTransTable5_
1617     {
1618
1619     unsigned int phy30:5;   /**< [31-27] Rx Mapping value of logical phy 6 */
1620
1621     unsigned int reserved_1:27;     /**< [26-0] These bits are always 0 */
1622
1623     } utRxTransTable5;  /**< Rx translation table */
1624
1625     /**
1626     * @ingroup IxAtmdAccUtopiaCtrlAPI
1627     * @struct UtSysConfig_
1628     * @brief NPE setup Register
1629     */
1630     struct UtSysConfig_
1631     {
1632
1633     unsigned int reserved_1:2;     /**< [31-30] These bits are always 0 */
1634     unsigned int txEnbFSM:1;    /**< [29] Enables the operation ofthe Utopia Transmit FSM
1635    * @li 1 - FSM enabled
1636    * @li 0 - FSM inactive
1637    */
1638     unsigned int rxEnbFSM:1;    /**< [28] Enables the operation ofthe Utopia Revieve FSM
1639    * @li 1 - FSM enabled
1640    * @li 0 - FSM inactive
1641    */
1642     unsigned int disablePins:1;    /**< [27] Disable Utopia interface I/O pins forcing the signals to an
1643    * inactive state.  Note that this bit is set on reset and must be
1644    * de-asserted
1645    * @li 0 - Normal data transfer
1646    * @li    1 - Utopia interface pins are forced inactive
1647     */
1648     unsigned int tstLoop:1;    /**< [26] Test Loop Back Enable.
1649     * @li Note: For loop back to function RxMode and Tx Mode must both be set
1650     * to single PHY mode.
1651     * @li 0 - Loop back
1652     * @li 1 - Normal operating mode
1653     */
1654
1655     unsigned int txReset:1;   /**< [25] Resets the Utopia Coprocessor transmit module to a known state.
1656     * @li Note: All transmit configuration and status registers will be reset
1657     * to their reset values.
1658     * @li 0 - Normal operating mode
1659     * @li 1 - Reset transmit modules
1660     */
1661
1662     unsigned int rxReset:1;   /**< [24] Resets the Utopia Coprocessor receive module to a known state.
1663     * @li Note: All receive configuration and status registers will be reset
1664     * to their reset values.
1665     * @li    0 - Normal operating mode
1666     * @li 1 - Reset receive modules
1667     */
1668
1669     unsigned int reserved_2:24;     /**< [23-0] These bits are always 0 */
1670     } utSysConfig;  /**< NPE debug config */
1671
1672 }
1673 IxAtmdAccUtopiaConfig;
1674
1675 /**
1676 *
1677 * @brief Utopia status
1678 *
1679 * This structure is used to set/get the Utopia status parameters
1680 * @li contains debug cell counters, to be accessed during a read operation
1681 *
1682 * @note - the exact description of all parameters is done in the Utopia reference
1683 *   documents.
1684 *
1685 */
1686 typedef struct
1687 {
1688
1689     unsigned int utTxCellCount;  /**< count of cells transmitted */
1690
1691     unsigned int utTxIdleCellCount;    /**< count of idle cells transmitted */
1692
1693     /**
1694     * @ingroup IxAtmdAccUtopiaCtrlAPI
1695     * @struct UtTxCellConditionStatus_
1696     * @brief Utopia Tx Status Register
1697     */
1698     struct UtTxCellConditionStatus_
1699     {
1700
1701     unsigned int reserved_1:2;   /**< [31:30] These bits are always 0 */
1702     unsigned int txFIFO2Underflow:1; /**< [29] This bit is set if 64-byte
1703                                      * Transmit FIFO2 indicates a FIFO underflow
1704                                      * error condition.
1705                                      */
1706     unsigned int txFIFO1Underflow:1; /**< [28] This bit is set if
1707                                      * 64-byte Transmit FIFO1 indicates a FIFO
1708                                      * underflow error condition.
1709                                      */
1710     unsigned int txFIFO2Overflow:1;  /**< [27] This bit is set if 64-byte
1711                                      * Transmit FIFO2 indicates a FIFO overflow
1712                                      * error condition.
1713                                      */
1714     unsigned int txFIFO1Overflow:1; /**< [26] This bit is set if 64-byte
1715                                     * Transmit FIFO1 indicates a FIFO overflow
1716                                     * error condition.
1717                                     */
1718     unsigned int txIdleCellCountOvr:1; /**< [25] This bit is set if the
1719                                        * TxIdleCellCount register overflows.
1720                                        */
1721     unsigned int txCellCountOvr:1; /**< [24] This bit is set if the
1722                                    * TxCellCount register overflows
1723                                    */
1724     unsigned int reserved_2:24;    /**< [23:0] These bits are always 0 */
1725     } utTxCellConditionStatus;    /**< Tx cells condition status */
1726
1727     unsigned int utRxCellCount; /**< count of cell received */
1728     unsigned int utRxIdleCellCount;    /**< count of idle cell received */
1729     unsigned int utRxInvalidHECount;     /**< count of invalid cell
1730                                         * received because of HEC errors
1731                                         */
1732     unsigned int utRxInvalidParCount;  /**< count of invalid cell received
1733                                         * because of parity errors
1734                                         */
1735     unsigned int utRxInvalidSizeCount;  /**< count of invalid cell
1736                                         * received because of cell
1737                                         * size errors
1738                                         */
1739
1740     /**
1741     * @ingroup IxAtmdAccUtopiaCtrlAPI
1742     * @struct UtRxCellConditionStatus_
1743     * @brief Utopia Rx Status Register
1744     */
1745     struct UtRxCellConditionStatus_
1746     {
1747
1748     unsigned int reserved_1:3;  /**< [31:29] These bits are always 0.*/
1749     unsigned int rxCellCountOvr:1;      /**< [28] This bit is set if the RxCellCount register overflows. */
1750     unsigned int invalidHecCountOvr:1;    /**< [27] This bit is set if the InvalidHecCount register overflows.*/
1751     unsigned int invalidParCountOvr:1;    /**< [26] This bit is set if the InvalidParCount register overflows.*/
1752     unsigned int invalidSizeCountOvr:1;    /**< [25] This bit is set if the InvalidSizeCount register overflows.*/
1753     unsigned int rxIdleCountOvr:1;      /**< [24] This bit is set if the RxIdleCount register overflows.*/
1754     unsigned int reserved_2:4;  /**< [23:20] These bits are always 0 */
1755     unsigned int rxFIFO2Underflow:1;  /**< [19] This bit is set if 64-byte Receive FIFO2
1756                                       * indicates a FIFO underflow error condition.
1757                                       */
1758     unsigned int rxFIFO1Underflow:1;  /**< [18] This bit is set if 64-byte Receive
1759                                       * FIFO1 indicates a FIFO underflow error condition
1760                                     . */
1761     unsigned int rxFIFO2Overflow:1;    /**< [17] This bit is set if 64-byte Receive FIFO2
1762                                        * indicates a FIFO overflow error condition.
1763                                         */
1764     unsigned int rxFIFO1Overflow:1;    /**< [16] This bit is set if 64-byte Receive FIFO1
1765                                     * indicates a FIFO overflow error condition.
1766                                     */
1767     unsigned int reserved_3:16;      /**< [15:0] These bits are always 0. */
1768     } utRxCellConditionStatus;    /**< Rx cells condition status */
1769
1770 } IxAtmdAccUtopiaStatus;
1771
1772 /**
1773  * @} defgroup IxAtmdAccUtopiaCtrlAPI
1774  */
1775
1776  /**
1777  *
1778  * @ingroup IxAtmdAccCtrlAPI
1779  *
1780  * @fn ixAtmdAccUtopiaConfigSet (const IxAtmdAccUtopiaConfig *
1781                         ixAtmdAccUtopiaConfigPtr)
1782  *
1783  * @brief Send the configuration structure to the Utopia interface
1784  *
1785  * This function downloads the @a IxAtmdAccUtopiaConfig structure to
1786  * the Utopia and has the following effects
1787  *  @li setup the Utopia interface
1788  *  @li initialise the NPE
1789  *  @li reset the Utopia cell counters and status registers to known values
1790  *
1791  * This action has to be done once at initialisation. A lock is preventing
1792  * the concurrent use of @a ixAtmdAccUtopiaStatusGet() and
1793  * @A ixAtmdAccUtopiaConfigSet()
1794  *
1795  * @param *ixAtmdAccNPEConfigPtr @ref IxAtmdAccUtopiaConfig [in] - pointer to a structure to download to
1796  *  Utopia. This parameter cannot be a null pointer.
1797  *
1798  * @return @li IX_SUCCESS successful download
1799  * @return @li IX_FAIL error in the parameters, or configuration is not
1800  *         complete or failed
1801  *
1802  * @sa ixAtmdAccUtopiaStatusGet
1803  *
1804  */
1805 PUBLIC IX_STATUS ixAtmdAccUtopiaConfigSet (const IxAtmdAccUtopiaConfig *
1806                         ixAtmdAccUtopiaConfigPtr);
1807
1808 /**
1809  *
1810  * @ingroup IxAtmdAccCtrlAPI
1811  *
1812  * @fn ixAtmdAccUtopiaStatusGet (IxAtmdAccUtopiaStatus *
1813                         ixAtmdAccUtopiaStatus)
1814  *
1815  * @brief Get the Utopia interface configuration.
1816  *
1817  * This function reads the Utopia registers and the Cell counts
1818  * and fills the @a IxAtmdAccUtopiaStatus structure
1819  *
1820  * A lock is preventing the concurrent
1821  * use of @a ixAtmdAccUtopiaStatusGet() and @A ixAtmdAccUtopiaConfigSet()
1822  *
1823  * @param ixAtmdAccUtopiaStatus @ref IxAtmdAccUtopiaStatus [out] - pointer to structure to be updated from internal
1824  *        hardware counters. This parameter cannot be a NULL pointer.
1825  *
1826  * @return @li IX_SUCCESS successful read
1827  * @return @li IX_FAIL error in the parameters null pointer, or
1828  *          configuration read is not complete or failed
1829  *
1830  * @sa ixAtmdAccUtopiaConfigSet
1831  *
1832  */
1833 PUBLIC IX_STATUS ixAtmdAccUtopiaStatusGet (IxAtmdAccUtopiaStatus *
1834                         ixAtmdAccUtopiaStatus);
1835
1836 /**
1837  *
1838  * @ingroup IxAtmdAcc
1839  *
1840  * @fn ixAtmdAccPortEnable (IxAtmLogicalPort port)
1841  *
1842  * @brief enable a PHY logical port
1843  *
1844  * This function enables the transmission over one port. It should be
1845  * called before accessing any resource from this port and before the
1846  * establishment of a VC.
1847  *
1848  * When a port is enabled, the cell transmission to the Utopia interface
1849  * is started. If there is no traffic already running, idle cells are
1850  * sent over the interface.
1851  *
1852  * This function can be called multiple times.
1853  *
1854  * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
1855  *
1856  * @return @li IX_SUCCESS enable is complete
1857  * @return @li IX_ATMDACC_WARNING port already enabled
1858  * @return @li IX_FAIL enable failed, wrong parameter, or cannot
1859  *         initialise this port (the port is maybe already in use,
1860  *         or there is a hardware issue)
1861  *
1862  * @note - This function needs internal locks and should not be
1863  *         called from an interrupt context
1864  *
1865  * @sa ixAtmdAccPortDisable
1866  *
1867  */
1868 PUBLIC IX_STATUS ixAtmdAccPortEnable (IxAtmLogicalPort port);
1869
1870 /**
1871  *
1872  * @ingroup IxAtmdAccCtrlAPI
1873  *
1874  * @fn ixAtmdAccPortDisable (IxAtmLogicalPort port)
1875  *
1876  * @brief disable a PHY logical port
1877  *
1878  * This function disable the transmission over one port.
1879  *
1880  * When a port is disabled, the cell transmission to the Utopia interface
1881  * is stopped.
1882  *
1883  * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
1884  *
1885  * @return @li IX_SUCCESS disable is complete
1886  * @return @li IX_ATMDACC_WARNING port already disabled
1887  * @return @li IX_FAIL disable failed, wrong parameter .
1888  *
1889  * @note - This function needs internal locks and should not be called
1890  *         from an interrupt context
1891  *
1892  * @note - The response from hardware is done through the txDone mechanism
1893  *         to ensure the synchrnisation with tx resources. Therefore, the
1894  *         txDone mechanism needs to be serviced to make a PortDisable complete.
1895  *
1896  * @sa ixAtmdAccPortEnable
1897  * @sa ixAtmdAccPortDisableComplete
1898  * @sa ixAtmdAccTxDoneDispatch
1899  *
1900  */
1901 PUBLIC IX_STATUS ixAtmdAccPortDisable (IxAtmLogicalPort port);
1902
1903 /**
1904 *
1905 * @ingroup IxAtmdAccCtrlAPI
1906 *
1907 * @fn ixAtmdAccPortDisableComplete (IxAtmLogicalPort port)
1908 *
1909 * @brief disable a PHY logical port
1910 *
1911 * This function indicates if the port disable for a port has completed. This
1912 * function will return true if the port has never been enabled.
1913 *
1914 * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
1915 *
1916 * @return @li true disable is complete
1917 * @return @li false disable failed, wrong parameter .
1918 *
1919 * @note - This function needs internal locks and should not be called
1920 *         from an interrupt context
1921 *
1922 * @sa ixAtmdAccPortEnable
1923 * @sa ixAtmdAccPortDisable
1924 *
1925 */
1926 PUBLIC BOOL ixAtmdAccPortDisableComplete (IxAtmLogicalPort port);
1927
1928 #endif /* IXATMDACCCTRL_H */
1929
1930 /**
1931  * @} defgroup IxAtmdAccCtrlAPI
1932  */
1933
1934