drivers/net/npe/include/IxAtmSch.h

   1 /**
   2  * @file    IxAtmSch.h
   3  *
   4  * @date    23-NOV-2001
   5  *
   6  * @brief   Header file for the IXP400 ATM Traffic Shaper
   7  *
   8  * This component demonstrates an ATM Traffic Shaper implementation. It
   9  * will perform shaping on upto 12 ports and total of 44 VCs accross all ports,
  10  * 32 are intended for AAL0/5 and 12 for OAM (1 per port).
  11  * The supported traffic types are;1 rt-VBR VC where PCR = SCR.
  12  * (Effectively CBR) and Up-to 44 VBR VCs.
  13  *
  14  * This component models the ATM ports and VCs and is capable of producing
  15  * a schedule of ATM cells per port which can be supplied to IxAtmdAcc
  16  * for execution on the data path.
  17  *
  18  * @par
  19  * IXP400 SW Release version 2.0
  20  *
  21  * -- Copyright Notice --
  22  *
  23  * @par
  24  * Copyright 2001-2005, Intel Corporation.
  25  * All rights reserved.
  26  *
  27  * @par
  28  * SPDX-License-Identifier:     BSD-3-Clause
  29  * @par
  30  * -- End of Copyright Notice --
  31  *
  32  * @sa IxAtmm.h
  33  *
  34  */
  35
  36 /**
  37  * @defgroup IxAtmSch IXP400 ATM Transmit Scheduler (IxAtmSch) API
  38  *
  39  * @brief IXP400 ATM scheduler component Public API
  40  *
  41  * @{
  42  */
  43
  44 #ifndef IXATMSCH_H
  45 #define IXATMSCH_H
  46
  47 #include "IxOsalTypes.h"
  48 #include "IxAtmTypes.h"
  49
  50 /*
  51  * #defines and macros used in this file.
  52  */
  53
  54 /* Return codes */
  55
  56 /**
  57  * @ingroup IxAtmSch
  58  *
  59  * @def IX_ATMSCH_RET_NOT_ADMITTED
  60  * @brief Indicates that CAC function has rejected VC registration due
  61  *         to insufficient line capacity.
  62 */
  63 #define IX_ATMSCH_RET_NOT_ADMITTED 2
  64
  65 /**
  66  * @ingroup IxAtmSch
  67  *
  68  * @def IX_ATMSCH_RET_QUEUE_FULL
  69  *  @brief Indicates that the VC queue is full, no more demand can be
  70  *         queued at this time.
  71  */
  72 #define IX_ATMSCH_RET_QUEUE_FULL 3
  73
  74 /**
  75  * @ingroup IxAtmSch
  76  *
  77  *  @def IX_ATMSCH_RET_QUEUE_EMPTY
  78  *  @brief Indicates that all VC queues on this port are empty and
  79  *         therefore there are no cells to be scheduled at this time.
  80  */
  81 #define IX_ATMSCH_RET_QUEUE_EMPTY 4
  82
  83 /*
  84  * Function declarations
  85  */
  86
  87 /**
  88  * @ingroup IxAtmSch
  89  *
  90  * @fn ixAtmSchInit(void)
  91  *
  92  *  @brief This function is used to initialize the ixAtmSch component. It
  93  *         should be called before any other IxAtmSch API function.
  94  *
  95  * @param None
  96  *
  97  * @return
  98  * - <b>IX_SUCCESS :</b> indicates that
  99  *          -# The ATM scheduler component has been successfully initialized.
 100  *          -# The scheduler is ready to accept Port modelling requests.
 101  * - <b>IX_FAIL :</b> Some internal error has prevented the scheduler component
 102  *          from initialising.
 103  */
 104 PUBLIC IX_STATUS
 105 ixAtmSchInit(void);
 106
 107 /**
 108  * @ingroup IxAtmSch
 109  *
 110  * @fn ixAtmSchPortModelInitialize( IxAtmLogicalPort port,
 111                                        unsigned int portRate,
 112                                        unsigned int minCellsToSchedule)
 113  *
 114  * @brief This function shall be called first to initialize an ATM port before
 115  *         any other ixAtmSch API calls may be made for that port.
 116  *
 117  * @param port @ref IxAtmLogicalPort [in] - The specific port to initialize.  Valid
 118  *          values range from 0 to IX_UTOPIA_MAX_PORTS - 1, representing a
 119  *          maximum of IX_UTOPIA_MAX_PORTS possible ports.
 120  *
 121  * @param portRate unsigned int [in] - Value indicating the upstream capacity
 122  *          of the indicated port.  The value should be supplied in
 123  *          units of ATM (53 bytes) cells per second.
 124  *          A port rate of 800Kbits/s is the equivalent
 125  *          of 1886 cells per second
 126  *
 127  * @param minCellsToSchedule unsigned int [in] - This parameter specifies the minimum
 128  *          number of cells which the scheduler will put in a schedule
 129  *          table for this port. This value sets the worst case CDVT for VCs
 130  *          on this port i.e. CDVT = 1*minCellsToSchedule/portRate.
 131  * @return
 132  *    - <b>IX_SUCCESS :</b> indicates that
 133  *          -# The ATM scheduler has been successfully initialized.
 134  *          -# The requested port model has been established.
 135  *          -# The scheduler is ready to accept VC modelling requests
 136  *            on the ATM port.
 137  *    - <b>IX_FAIL :</b> indicates the requested port could not be
 138  * initialized.  */
 139 PUBLIC IX_STATUS
 140 ixAtmSchPortModelInitialize( IxAtmLogicalPort port,
 141                                        unsigned int portRate,
 142                                        unsigned int minCellsToSchedule);
 143
 144 /**
 145  * @ingroup IxAtmSch
 146  *
 147  * @fn ixAtmSchPortRateModify( IxAtmLogicalPort port,
 148                         unsigned int portRate)
 149  *
 150  *  @brief This function is called to modify the portRate on a
 151  *         previously initialized port, typically in the event that
 152  *         the line condition of the port changes.
 153  *
 154  * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port which is to be
 155  *          modified.
 156  *
 157  * @param portRate unsigned int [in] - Value indicating the new upstream
 158  *          capacity for this port in cells/second.
 159  *          A port rate of 800Kbits/s is the equivalent
 160  *          of 1886 cells per second
 161  *
 162  * @return
 163  * - <b>IX_SUCCESS :</b> The port rate has been successfully modified.<br>
 164  * - <b>IX_FAIL :</b> The port rate could not be modified, either
 165  *      because the input data was invalid, or the new port rate is
 166  *      insufficient to support established ATM VC contracts on this
 167  *      port.
 168  *
 169  * @warning The IxAtmSch component will validate the supplied port
 170  *          rate is sufficient to support all established VC
 171  *          contracts on the port.  If the new port rate is
 172  *          insufficient to support all established contracts then
 173  *          the request to modify the port rate will be rejected.
 174  *          In this event, the user is expected to remove
 175  *          established contracts using the ixAtmSchVcModelRemove
 176  *          interface and then retry this interface.
 177  *
 178  * @sa ixAtmSchVcModelRemove() */
 179 PUBLIC IX_STATUS
 180 ixAtmSchPortRateModify( IxAtmLogicalPort port,
 181                         unsigned int portRate);
 182
 183
 184 /**
 185  * @ingroup IxAtmSch
 186  *
 187  * @fn ixAtmSchVcModelSetup( IxAtmLogicalPort port,
 188                       IxAtmTrafficDescriptor *trafficDesc,
 189                       IxAtmSchedulerVcId *vcId)
 190  *
 191  *  @brief A client calls this interface to set up an upstream
 192  *         (transmitting) virtual connection model (VC) on the
 193  *         specified ATM port.  This function also provides the
 194  *         virtual * connection admission control (CAC) service to the
 195  *         client.
 196  *
 197  * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the upstream
 198  *          VC is to be established.
 199  *
 200  * @param *trafficDesc @ref IxAtmTrafficDescriptor [in] - Pointer to a structure
 201  *          describing the requested traffic contract of the VC to be
 202  *          established.  This structure contains the typical ATM
 203  *          traffic descriptor values (e.g. PCR, SCR, MBS, CDVT, etc.)
 204  *          defined by the ATM standard.
 205  *
 206  * @param *vcId @ref IxAtmSchedulerVcId [out] - This value will be filled with the
 207  *              port-unique identifier for this virtual connection.  A
 208  *              valid identification is a non-negative number.
 209  *
 210  * @return
 211  * - <b>IX_SUCCESS :</b> The VC has been successfully established on
 212  *      this port.  The client may begin to submit demand on this VC.
 213  * - <b>IX_ATMSCH_RET_NOT_ADMITTED :</b> The VC cannot be established
 214  *      on this port because there is insufficient upstream capacity
 215  *      available to support the requested traffic contract descriptor
 216  * - <b>IX_FAIL :</b>Input data are invalid.  VC has not been
 217  *      established.
 218  */
 219 PUBLIC IX_STATUS
 220 ixAtmSchVcModelSetup( IxAtmLogicalPort port,
 221                       IxAtmTrafficDescriptor *trafficDesc,
 222                       IxAtmSchedulerVcId *vcId);
 223
 224 /**
 225  * @ingroup IxAtmSch
 226  *
 227  * @fn ixAtmSchVcConnIdSet( IxAtmLogicalPort port,
 228                      IxAtmSchedulerVcId vcId,
 229                      IxAtmConnId vcUserConnId)
 230  *
 231  *  @brief A client calls this interface to set the vcUserConnId for a VC on
 232  *         the specified ATM port. This vcUserConnId will default to
 233  *         IX_ATM_IDLE_CELLS_CONNID if this function is not called for a VC.
 234  *         Hence if the client does not call this function for a VC then only idle
 235  *         cells will be scheduled for this VC.
 236  *
 237  * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the upstream
 238  *        VC is has been established.
 239  *
 240  * @param vcId @ref IxAtmSchedulerVcId [in] - This is the unique identifier for this virtual
 241  *        connection. A valid identification is a non-negative number and is
 242  *        all ports.
 243  *
 244  * @param vcUserConnId @ref IxAtmConnId [in] - The connId is used to refer to a VC in schedule
 245  *        table entries. It is treated as the Id by which the scheduler client
 246  *        knows the VC. It is used in any communicatations from the Scheduler
 247  *        to the scheduler user e.g. schedule table entries.
 248  *
 249  * @return
 250  * - <b>IX_SUCCESS :</b> The id has successfully been set.
 251  * - <b>IX_FAIL :</b>Input data are invalid. connId id is not established.
 252  */
 253 PUBLIC IX_STATUS
 254 ixAtmSchVcConnIdSet( IxAtmLogicalPort port,
 255                      IxAtmSchedulerVcId vcId,
 256                      IxAtmConnId vcUserConnId);
 257
 258 /**
 259  * @ingroup IxAtmSch
 260  *
 261  * @fn ixAtmSchVcModelRemove( IxAtmLogicalPort port,
 262                        IxAtmSchedulerVcId vcId)
 263  *
 264  *  @brief Interface called by the client to remove a previously
 265  *         established VC on a particular port.
 266  *
 267  * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
 268  *          removed is established.
 269  *
 270  * @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be removed.  This is the
 271  *          value returned by the @ref ixAtmSchVcModelSetup call which
 272  *          established the relevant VC.
 273  *
 274  * @return
 275  * - <b>IX_SUCCESS :</b> The VC has been successfully removed from
 276  *      this port. It is no longer modelled on this port.
 277  * - <b>IX_FAIL :</b>Input data are invalid. The VC is still being modeled
 278  *      by the traffic shaper.
 279  *
 280  * @sa ixAtmSchVcModelSetup()
 281  */
 282 PUBLIC IX_STATUS
 283 ixAtmSchVcModelRemove( IxAtmLogicalPort port,
 284                        IxAtmSchedulerVcId vcId);
 285
 286 /**
 287  * @ingroup IxAtmSch
 288  *
 289  * @fn ixAtmSchVcQueueUpdate( IxAtmLogicalPort port,
 290                        IxAtmSchedulerVcId vcId,
 291                        unsigned int numberOfCells)
 292  *
 293  *  @brief The client calls this function to notify IxAtmSch that the
 294  *         user of a VC has submitted cells for transmission.
 295  *
 296  *  This information is stored, aggregated from a number of calls to
 297  *  ixAtmSchVcQueueUpdate and eventually used in the call to
 298  *  ixAtmSchTableUpdate.
 299  *
 300  *  Normally IxAtmSch will update the VC queue by adding the number of
 301  *  cells to the current queue length.  However, if IxAtmSch
 302  *  determines that the user has over-submitted for the VC and
 303  *  exceeded its transmission quota the queue request can be rejected.
 304  *  The user should resubmit the request later when the queue has been
 305  *  depleted.
 306  *
 307  *  This implementation of ixAtmSchVcQueueUpdate uses no operating
 308  *  system or external facilities, either directly or indirectly.
 309  *  This allows clients to call this function form within an interrupt handler.
 310  *
 311  *  This interface is structurally compatible with the
 312  *  IxAtmdAccSchQueueUpdate callback type definition required for
 313  *  IXP400 ATM scheduler interoperability.
 314  *
 315  * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
 316  *          updated is established.
 317  *
 318  * @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be updated.  This is the
 319  *          value returned by the @ref ixAtmSchVcModelSetup call which
 320  *          established the relevant VC.
 321  *
 322  * @param numberOfCells unsigned int [in] - Indicates how many ATM cells should
 323  *          be added to the queue for this VC.
 324  *
 325  * @return
 326  *  - <b>IX_SUCCESS :</b> The VC queue has been successfully updated.
 327  *  - <b>IX_ATMSCH_RET_QUEUE_FULL :</b> The VC queue has reached a
 328  *       preset limit.  This indicates the client has over-submitted
 329  *       and exceeded its transmission quota.  The request is
 330  *       rejected.  The VC queue is not updated.  The VC user is
 331  *       advised to resubmit the request later.
 332  *  - <b>IX_FAIL :</b> The input are invalid.  No VC queue is updated.
 333  *
 334  * @warning IxAtmSch assumes that the calling software ensures that
 335  *          calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
 336  *          ixAtmSchTableUpdate are both self and mutually exclusive
 337  *          for the same port.
 338  *
 339  * @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate().  */
 340 PUBLIC IX_STATUS
 341 ixAtmSchVcQueueUpdate( IxAtmLogicalPort port,
 342                        IxAtmSchedulerVcId vcId,
 343                        unsigned int numberOfCells);
 344
 345 /**
 346  * @ingroup IxAtmSch
 347  *
 348  * @fn ixAtmSchVcQueueClear( IxAtmLogicalPort port,
 349                       IxAtmSchedulerVcId vcId)
 350  *
 351  *  @brief The client calls this function to remove all currently
 352  *         queued cells from a registered VC.  The pending cell count
 353  *         for the specified VC is reset to zero.
 354  *
 355  *  This interface is structurally compatible with the
 356  *  IxAtmdAccSchQueueClear callback type definition required for
 357  *  IXP400 ATM scheduler interoperability.
 358  *
 359  * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
 360  *          cleared is established.
 361  *
 362  * @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be cleared.  This is the
 363  *          value returned by the @ref ixAtmSchVcModelSetup call which
 364  *          established the relevant VC.
 365  *
 366  * @return
 367  *  - <b>IX_SUCCESS :</b> The VC queue has been successfully cleared.
 368  *  - <b>IX_FAIL :</b> The input are invalid.  No VC queue is modified.
 369  *
 370  * @warning IxAtmSch assumes that the calling software ensures that
 371  *          calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
 372  *          ixAtmSchTableUpdate are both self and mutually exclusive
 373  *          for the same port.
 374  *
 375  * @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate().  */
 376 PUBLIC IX_STATUS
 377 ixAtmSchVcQueueClear( IxAtmLogicalPort port,
 378                       IxAtmSchedulerVcId vcId);
 379
 380 /**
 381  * @ingroup IxAtmSch
 382  *
 383  * @fn ixAtmSchTableUpdate( IxAtmLogicalPort port,
 384                      unsigned int maxCells,
 385                      IxAtmScheduleTable **rettable)
 386  *
 387  *  @brief The client calls this function to request an update of the
 388  *         schedule table for a particular ATM port.
 389  *
 390  *  This is called when the client decides it needs a new sequence of
 391  *  cells to send (probably because the transmit queue is near to
 392  *  empty for this ATM port).  The scheduler will use its stored
 393  *  information on the cells submitted for transmit (i.e. data
 394  *  supplied via @ref ixAtmSchVcQueueUpdate function) with the traffic
 395  *  descriptor information of all established VCs on the ATM port to
 396  *  decide the sequence of cells to be sent and fill the schedule
 397  *  table for a period of time into the future.
 398  *
 399  *  IxAtmSch will guarantee a minimum of minCellsToSchedule if there
 400  *  is at least one cell ready to send. If there are no cells then
 401  *  IX_ATMSCH_RET_QUEUE_EMPTY is returned.
 402  *
 403  *  This implementation of ixAtmSchTableUpdate uses no operating
 404  *  system or external facilities, either directly or indirectly.
 405  *  This allows clients to call this function form within an FIQ
 406  *  interrupt handler.
 407  *
 408  * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port for which requested
 409  *          schedule table is to be generated.
 410  *
 411  * @param maxCells unsigned [in] - Specifies the maximum number of cells
 412  *          that must be scheduled in the supplied table during any
 413  *          call to the interface.
 414  *
 415  * @param **table @ref IxAtmScheduleTable [out] - A pointer to an area of
 416  *              storage is returned which contains the generated
 417  *              schedule table.  The client should not modify the
 418  *              contents of this table.
 419  *
 420  * @return
 421  *  - <b>IX_SUCCESS :</b> The schedule table has been published.
 422  *       Currently there is at least one VC queue that is nonempty.
 423  *  - <b>IX_ATMSCH_RET_QUEUE_EMPTY :</b> Currently all VC queues on
 424  *       this port are empty.  The schedule table returned is set to
 425  *       NULL.  The client is not expected to invoke this function
 426  *       again until more cells have been submitted on this port
 427  *       through the @ref ixAtmSchVcQueueUpdate function.
 428  *  - <b>IX_FAIL :</b> The input are invalid.  No action is taken.
 429  *
 430  * @warning IxAtmSch assumes that the calling software ensures that
 431  *          calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
 432  *          ixAtmSchTableUpdate are both self and mutually exclusive
 433  *          for the same port.
 434  *
 435  * @warning Subsequent calls to this function for the same port will
 436  *          overwrite the contents of previously supplied schedule
 437  *          tables.  The client must be completely finished with the
 438  *          previously supplied schedule table before calling this
 439  *          function again for the same port.
 440  *
 441  * @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate().  */
 442 PUBLIC IX_STATUS
 443 ixAtmSchTableUpdate( IxAtmLogicalPort port,
 444                      unsigned int maxCells,
 445                      IxAtmScheduleTable **rettable);
 446
 447 /**
 448  * @ingroup IxAtmSch
 449  *
 450  * @fn ixAtmSchShow(void)
 451  *
 452  *  @brief Utility function which will print statistics on the current
 453  *         and accumulated state of VCs and traffic in the ATM
 454  *         scheduler component.  Output is sent to the default output
 455  *         device.
 456  *
 457  * @param none
 458  * @return none
 459  */
 460 PUBLIC void
 461 ixAtmSchShow(void);
 462
 463 /**
 464  * @ingroup IxAtmSch
 465  *
 466  * @fn ixAtmSchStatsClear(void)
 467  *
 468  *  @brief Utility function which will reset all counter statistics in
 469  *         the ATM scheduler to zero.
 470  *
 471  * @param none
 472  * @return none
 473  */
 474 PUBLIC void
 475 ixAtmSchStatsClear(void);
 476
 477 #endif
 478 /* IXATMSCH_H */
 479
 480 /** @} */