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