cpu/ixp/npe/include/IxAtmm.h

   1 /**
   2  * @file    IxAtmm.h
   3  *
   4  * @date    3-DEC-2001
   5  *
   6  * @brief   Header file for the IXP400 ATM Manager component (IxAtmm)
   7  *
   8  *
   9  * @par
  10  * IXP400 SW Release version 2.0
  11  *
  12  * -- Copyright Notice --
  13  *
  14  * @par
  15  * Copyright 2001-2005, Intel Corporation.
  16  * All rights reserved.
  17  *
  18  * @par
  19  * Redistribution and use in source and binary forms, with or without
  20  * modification, are permitted provided that the following conditions
  21  * are met:
  22  * 1. Redistributions of source code must retain the above copyright
  23  *    notice, this list of conditions and the following disclaimer.
  24  * 2. Redistributions in binary form must reproduce the above copyright
  25  *    notice, this list of conditions and the following disclaimer in the
  26  *    documentation and/or other materials provided with the distribution.
  27  * 3. Neither the name of the Intel Corporation nor the names of its contributors
  28  *    may be used to endorse or promote products derived from this software
  29  *    without specific prior written permission.
  30  *
  31  * @par
  32  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
  33  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  34  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  35  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
  36  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  37  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  38  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  39  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  40  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  41  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  42  * SUCH DAMAGE.
  43  *
  44  * @par
  45  * -- End of Copyright Notice --
  46  */
  47
  48
  49 /**
  50  * @defgroup IxAtmm IXP400 ATM Manager (IxAtmm) API
  51  *
  52  * @brief IXP400 ATM Manager component Public API
  53  *
  54  * @{
  55  */
  56
  57 #ifndef IXATMM_H
  58 #define IXATMM_H
  59
  60 /*
  61  * Put the user defined include files required
  62  */
  63 #include "IxAtmSch.h"
  64 #include "IxOsalTypes.h"
  65
  66 /*
  67  * #defines and macros used in this file.
  68  */
  69
  70 /**
  71  * @def IX_ATMM_RET_ALREADY_INITIALIZED
  72  *
  73  * @brief Component has already been initialized
  74  */
  75 #define IX_ATMM_RET_ALREADY_INITIALIZED 2
  76
  77 /**
  78  * @def IX_ATMM_RET_INVALID_PORT
  79  *
  80  * @brief Specified port does not exist or is out of range */
  81 #define IX_ATMM_RET_INVALID_PORT 3
  82
  83 /**
  84  * @def IX_ATMM_RET_INVALID_VC_DESCRIPTOR
  85  *
  86  * @brief The VC description does not adhere to ATM standards */
  87 #define IX_ATMM_RET_INVALID_VC_DESCRIPTOR 4
  88
  89 /**
  90  * @def IX_ATMM_RET_VC_CONFLICT
  91  *
  92  * @brief The VPI/VCI values supplied are either reserved, or they
  93  *         conflict with a previously registered VC on this port */
  94 #define IX_ATMM_RET_VC_CONFLICT 5
  95
  96 /**
  97  * @def IX_ATMM_RET_PORT_CAPACITY_IS_FULL
  98  *
  99  * @brief The virtual connection cannot be established on the port
 100  *         because the remaining port capacity is not sufficient to
 101  *         support it */
 102 #define IX_ATMM_RET_PORT_CAPACITY_IS_FULL 6
 103
 104 /**
 105  * @def IX_ATMM_RET_NO_SUCH_VC
 106  *
 107  * @brief No registered VC, as described by the supplied VCI/VPI or
 108  *         VC identifier values, exists on this port */
 109 #define IX_ATMM_RET_NO_SUCH_VC 7
 110
 111 /**
 112  * @def IX_ATMM_RET_INVALID_VC_ID
 113  *
 114  * @brief The specified VC identifier is out of range. */
 115 #define IX_ATMM_RET_INVALID_VC_ID 8
 116
 117 /**
 118  * @def IX_ATMM_RET_INVALID_PARAM_PTR
 119  *
 120  * @brief A pointer parameter was NULL. */
 121 #define IX_ATMM_RET_INVALID_PARAM_PTR 9
 122
 123 /**
 124  * @def IX_ATMM_UTOPIA_SPHY_ADDR
 125  *
 126  * @brief The phy address when in SPHY mode */
 127 #define IX_ATMM_UTOPIA_SPHY_ADDR 31
 128
 129 /**
 130  * @def IX_ATMM_THREAD_PRI_HIGH
 131  *
 132  * @brief The value of high priority thread */
 133 #define IX_ATMM_THREAD_PRI_HIGH 90
 134
 135 /*
 136  * Typedefs whose scope is limited to this file.
 137  */
 138
 139 /** @brief Definition for use in the @ref IxAtmmVc structure.
 140  *         Indicates the direction of a VC */
 141 typedef enum
 142 {
 143     IX_ATMM_VC_DIRECTION_TX=0, /**< Atmm Vc direction transmit*/
 144     IX_ATMM_VC_DIRECTION_RX, /**< Atmm Vc direction receive*/
 145     IX_ATMM_VC_DIRECTION_INVALID /**< Atmm Vc direction invalid*/
 146 } IxAtmmVcDirection;
 147
 148 /** @brief Definition for use with @ref IxAtmmVcChangeCallback
 149  *         callback.  Indicates that the event type represented by the
 150  *         callback for this VC. */
 151 typedef enum
 152 {
 153     IX_ATMM_VC_CHANGE_EVENT_REGISTER=0, /**< Atmm Vc event register*/
 154     IX_ATMM_VC_CHANGE_EVENT_DEREGISTER, /**< Atmm Vc event de-register*/
 155     IX_ATMM_VC_CHANGE_EVENT_INVALID /**< Atmm Vc event invalid*/
 156 } IxAtmmVcChangeEvent;
 157
 158 /** @brief Definitions for use with @ref ixAtmmUTOPIAInit interface to
 159  *         indicate that UTOPIA loopback should be enabled or disabled
 160  *         on initialisation. */
 161 typedef enum
 162 {
 163     IX_ATMM_UTOPIA_LOOPBACK_DISABLED=0, /**< Atmm Utopia loopback mode disabled*/
 164     IX_ATMM_UTOPIA_LOOPBACK_ENABLED, /**< Atmm Utopia loopback mode enabled*/
 165     IX_ATMM_UTOPIA_LOOPBACK_INVALID /**< Atmm Utopia loopback mode invalid*/
 166 } IxAtmmUtopiaLoopbackMode;
 167
 168 /** @brief This structure describes the required attributes of a
 169  *         virtual connection.
 170 */
 171 typedef struct {
 172     unsigned vpi;  /**< VPI value of this virtual connection */
 173     unsigned vci;  /**< VCI value of this virtual connection. */
 174     IxAtmmVcDirection direction; /**< VC direction */
 175
 176     /** Traffic descriptor of this virtual connection.  This structure
 177      *  is defined by the @ref IxAtmSch component.  */
 178     IxAtmTrafficDescriptor trafficDesc;
 179 } IxAtmmVc;
 180
 181
 182 /** @brief Definitions for use with @ref ixAtmmUtopiaInit interface to
 183  *         indicate that UTOPIA multi-phy/single-phy mode is used.
 184  */
 185 typedef enum
 186 {
 187     IX_ATMM_MPHY_MODE = 0, /**< Atmm phy mode mphy*/
 188     IX_ATMM_SPHY_MODE, /**< Atmm phy mode sphy*/
 189     IX_ATMM_PHY_MODE_INVALID /**< Atmm phy mode invalid*/
 190 } IxAtmmPhyMode;
 191
 192
 193 /** @brief Structure contains port-specific information required to
 194  *         initialize IxAtmm, and specifically, the IXP400 UTOPIA
 195  *         Level-2 device. */
 196 typedef struct {
 197     unsigned reserved_1:11;     /**< [31:21] Should be zero */
 198     unsigned UtopiaTxPhyAddr:5; /**< [20:16] Address of the
 199      *   transmit (Tx) PHY for this
 200      *   port on the 5-bit UTOPIA
 201      *   Level-2 address bus */
 202     unsigned reserved_2:11;     /**< [15:5] Should be zero */
 203     unsigned UtopiaRxPhyAddr:5; /**< [4:0] Address of the receive
 204      *   (Rx) PHY for this port on the
 205      *   5-bit UTOPIA  Level-2
 206      *   address bus */
 207 } IxAtmmPortCfg;
 208
 209 /** @brief Callback type used with @ref ixAtmmVcChangeCallbackRegister interface
 210  *         Defines a callback type  which will be used to notify registered
 211  *         users of registration/deregistration events on a particular port
 212  *
 213  * @param eventType @ref IxAtmmVcChangeEvent [in] - Event indicating
 214  *                        whether the VC supplied has been added or
 215  *                        removed
 216  *
 217  * @param port @ref IxAtmLogicalPort [in] - Specifies the port on which the event has
 218  *                        occurred
 219  *
 220  * @param vcChanged @ref IxAtmmVc* [in] - Pointer to a structure which gives
 221  *                              details of the VC which has been added
 222  *                              or removed on the port
 223  */
 224 typedef void (*IxAtmmVcChangeCallback) (IxAtmmVcChangeEvent eventType,
 225                                         IxAtmLogicalPort port,
 226                                         const IxAtmmVc* vcChanged);
 227
 228 /*
 229  * Variable declarations global to this file only. Externs are followed by
 230  * static variables.
 231  */
 232
 233 /*
 234  * Extern function prototypes
 235  */
 236
 237 /*
 238  * Function declarations
 239  */
 240
 241
 242 /**
 243  * @ingroup IxAtmm
 244  *
 245  * @fn ixAtmmInit (void)
 246  *
 247  * @brief Interface to initialize the IxAtmm software component.  Can
 248  *         be called once only.
 249  *
 250  *  Must be called before any other IxAtmm API is called.
 251  *
 252  * @param "none"
 253  *
 254  *  @return @li  IX_SUCCESS : IxAtmm has been successfully initialized.
 255  *      Calls to other IxAtmm interfaces may now be performed.
 256  *  @return @li  IX_FAIL : IxAtmm has already been initialized.
 257  */
 258 PUBLIC IX_STATUS
 259 ixAtmmInit (void);
 260
 261 /**
 262  * @ingroup IxAtmm
 263  *
 264  * @fn ixAtmmUtopiaInit (unsigned numPorts,
 265                   IxAtmmPhyMode phyMode,
 266                   IxAtmmPortCfg portCfgs[],
 267                   IxAtmmUtopiaLoopbackMode loopbackMode)
 268  *
 269  * @brief Interface to initialize the UTOPIA Level-2 ATM coprocessor
 270  *         for the specified number of physical ports.  The function
 271  *         must be called before the ixAtmmPortInitialize interface
 272  *         can operate successfully.
 273  *
 274  * @param numPorts unsigned [in] - Indicates the total number of logical
 275  *          ports that are active on the device.  Up to 12 ports are
 276  *          supported.
 277  *
 278  * @param phyMode @ref IxAtmmPhyMode [in] - Put the Utopia coprocessor in SPHY
 279  *        or MPHY mode.
 280  *
 281  * @param portCfgs[] @ref IxAtmmPortCfg [in] - Pointer to an array of elements
 282  *          detailing the UTOPIA specific port characteristics.  The
 283  *          length of the array must be equal to the number of ports
 284  *          activated.  ATM ports are referred to by the relevant
 285  *          offset in this array in all subsequent IxAtmm interface
 286  *          calls.
 287  *
 288  * @param loopbackMode @ref IxAtmmUtopiaLoopbackMode [in] - Value must be one of
 289  *          @ref IX_ATMM_UTOPIA_LOOPBACK_ENABLED or @ref
 290  *          IX_ATMM_UTOPIA_LOOPBACK_DISABLED indicating whether
 291  *          loopback should be enabled on the device.  Loopback can
 292  *          only be supported on a single PHY, therefore the numPorts
 293  *          parameter must be 1 if loopback is enabled.
 294  *
 295  * @return @li IX_SUCCESS : Indicates that the  UTOPIA device has been
 296  *      successfully initialized for the supplied ports.
 297  * @return @li IX_ATMM_RET_ALREADY_INITIALIZED : The UTOPIA device has
 298  *      already been initialized.
 299  * @return @li IX_FAIL : The supplied parameters are invalid or have been
 300  *     rejected by the UTOPIA-NPE device.
 301  *
 302  * @warning
 303  * This interface may only be called once.
 304  * Port identifiers are assumed to range from 0 to (numPorts - 1) in all
 305  * instances.
 306  * In all subsequent calls to interfaces supplied by IxAtmm, the specified
 307  * port value is expected to represent the offset in the portCfgs array
 308  * specified in this interface.  i.e. The first port in this array will
 309  * subsequently be represented as port 0, the second port as port 1,
 310  * and so on.*/
 311 PUBLIC IX_STATUS
 312 ixAtmmUtopiaInit (unsigned numPorts,
 313                   IxAtmmPhyMode phyMode,
 314                   IxAtmmPortCfg portCfgs[],
 315                   IxAtmmUtopiaLoopbackMode loopbackMode);
 316
 317
 318 /**
 319  * @ingroup IxAtmm
 320  *
 321  * @fn ixAtmmPortInitialize (IxAtmLogicalPort port,
 322                       unsigned txPortRate,
 323                       unsigned rxPortRate)
 324  *
 325  * @brief The interface is called following @ref ixAtmmUtopiaInit ()
 326  *         and before calls to any other IxAtmm interface.  It serves
 327  *         to activate the registered ATM port with IxAtmm.
 328  *
 329  *  The transmit and receive port rates are specified in bits per
 330  *  second.  This translates to ATM cells per second according to the
 331  *  following formula: CellsPerSecond = portRate / (53*8)  The
 332  *  IXP400 device supports only 53 byte cells. The client shall make
 333  *  sure that the off-chip physical layer device has already been
 334  *  initialized.
 335  *
 336  *  IxAtmm will configure IxAtmdAcc and IxAtmSch to enable scheduling
 337  *  on the port.
 338  *
 339  *  This interface must be called once for each active port in the
 340  *  system.  The first time the interface is invoked, it will configure
 341  *  the mechanism by which the handling of transmit, transmit-done and
 342  *  receive are driven with the IxAtmdAcc component.
 343  *
 344  *  This function is reentrant.
 345  *
 346  *  @note The minimum tx rate that will be accepted is 424 bit/s which equates
 347  *        to 1 cell (53 bytes) per second.
 348  *
 349  * @param port @ref IxAtmLogicalPort [in] - Identifies the port which is to be
 350  *          initialized.
 351  *
 352  * @param txPortRate unsigned [in] - Value specifies the
 353  *          transmit port rate for this port in
 354  *          bits/second.  This value is used by the ATM Scheduler
 355  *          component is evaluating VC access requests for the port.
 356  *
 357  * @param rxPortRate unsigned [in] - Value specifies the
 358  *          receive port rate for this port in bits/second.
 359  *
 360  * @return @li IX_SUCCESS : The specificed ATM port has been successfully
 361  *       initialized. IxAtmm is ready to accept VC registrations on
 362  *       this port.
 363  *
 364  * @return @li IX_ATMM_RET_ALREADY_INITIALIZED : ixAtmmPortInitialize has
 365  *       already been called successfully on this port.  The current
 366  *       call is rejected.
 367  *
 368  * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
 369  *       input is not valid.  The request is rejected.
 370  *
 371  * @return @li IX_FAIL : IxAtmm could not initialize the port because the
 372  * inputs are not understood.
 373  *
 374  * @sa ixAtmmPortEnable, ixAtmmPortDisable
 375  *
 376  */
 377 PUBLIC IX_STATUS
 378 ixAtmmPortInitialize (IxAtmLogicalPort port,
 379                       unsigned txPortRate,
 380                       unsigned rxPortRate);
 381
 382 /**
 383  * @ingroup IxAtmm
 384  *
 385  * @fn ixAtmmPortModify (IxAtmLogicalPort port,
 386                   unsigned txPortRate,
 387                   unsigned rxPortRate)
 388  *
 389  * @brief A client may call this interface to change the existing
 390  *         port rate (expressed in bits/second) on an established ATM
 391  *         port.
 392  *
 393  * @param port @ref IxAtmLogicalPort [in] - Identifies the port which is to be
 394  *          initialized.
 395  *
 396  * @param txPortRate unsigned [in] -  Value specifies the``
 397  *          transmit port rate for this port in
 398  *          bits/second.  This value is used by the ATM Scheduler
 399  *          component is evaluating VC access requests for the port.
 400  *
 401  * @param rxPortRate unsigned [in] - Value specifies the
 402  *          receive port rate for this port in
 403  *          bits/second.
 404  *
 405  * @return @li IX_SUCCESS : The indicated ATM port rates have been
 406  *      successfully modified.
 407  *
 408  * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
 409  *       input is not valid.  The request is rejected.
 410  *
 411  * @return @li IX_FAIL : IxAtmm could not update the port because the
 412  *       inputs are not understood, or the interface was called before
 413  * the port was initialized.  */
 414 PUBLIC IX_STATUS
 415 ixAtmmPortModify (IxAtmLogicalPort port,
 416                   unsigned txPortRate,
 417                   unsigned rxPortRate);
 418
 419 /**
 420  * @ingroup IxAtmm
 421  *
 422  * @fn ixAtmmPortQuery (IxAtmLogicalPort port,
 423                  unsigned *txPortRate,
 424                  unsigned *rxPortRate);
 425
 426  *
 427  * @brief The client may call this interface to request details on
 428  *          currently registered transmit and receive rates for an ATM
 429  *          port.
 430  *
 431  * @param port @ref IxAtmLogicalPort [in] - Value identifies the port from which the
 432  *          rate details are requested.
 433  *
 434  * @param *txPortRate unsigned [out] - Pointer to a value
 435  *          which will be filled with the value of the transmit port
 436  *          rate specified in bits/second.
 437  *
 438  * @param *rxPortRate unsigned [out] - Pointer to a value
 439  *          which will be filled with the value of the receive port
 440  *          rate specified in bits/second.
 441  *
 442  * @return @li IX_SUCCESS : The information requested on the specified
 443  *       port has been successfully supplied in the output.
 444  *
 445  * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
 446  *       input is not valid.  The request is rejected.
 447  *
 448  * @return @li IX_ATMM_RET_INVALID_PARAM_PTR : A pointer parameter was
 449  *       NULL.
 450  *
 451  * @return @li IX_FAIL : IxAtmm could not update the port because the
 452  *       inputs are not understood, or the interface was called before
 453  *       the port was initialized.  */
 454 PUBLIC IX_STATUS
 455 ixAtmmPortQuery (IxAtmLogicalPort port,
 456                  unsigned *txPortRate,
 457                  unsigned *rxPortRate);
 458
 459 /**
 460  * @ingroup IxAtmm
 461  *
 462  * @fn ixAtmmPortEnable(IxAtmLogicalPort port)
 463  *
 464  * @brief The client call this interface to enable transmit for an ATM
 465  *          port. At initialisation, all the ports are disabled.
 466  *
 467  * @param port @ref IxAtmLogicalPort [in] - Value identifies the port
 468  *
 469  * @return @li IX_SUCCESS : Transmission over this port is started.
 470  *
 471  * @return @li IX_FAIL : The port parameter is not valid, or the
 472  *       port is already enabled
 473  *
 474  * @note - When a port is disabled, Rx and Tx VC Connect requests will fail
 475  *
 476  * @note - This function uses system resources and should not be used
 477  *        inside an interrupt context.
 478  *
 479  * @sa ixAtmmPortDisable  */
 480 PUBLIC IX_STATUS
 481 ixAtmmPortEnable(IxAtmLogicalPort port);
 482
 483 /**
 484  * @ingroup IxAtmm
 485  *
 486  * @fn ixAtmmPortDisable(IxAtmLogicalPort port)
 487  *
 488  * @brief The client call this interface to disable transmit for an ATM
 489  *          port. At initialisation, all the ports are disabled.
 490  *
 491  * @param port @ref IxAtmLogicalPort [in] - Value identifies the port
 492  *
 493  * @return @li IX_SUCCESS : Transmission over this port is stopped.
 494  *
 495  * @return @li IX_FAIL : The port parameter is not valid, or the
 496  *       port is already disabled
 497  *
 498  * @note - When a port is disabled, Rx and Tx VC Connect requests will fail
 499  *
 500  * @note - This function call does not stop RX traffic. It is supposed
 501  *        that this function is invoked when a serious problem
 502  *        is detected (e.g. physical layer broken). Then, the RX traffic
 503  *        is not passing.
 504  *
 505  * @note - This function is blocking until the hw acknowledge that the
 506  *        transmission is stopped.
 507  *
 508  * @note - This function uses system resources and should not be used
 509  *        inside an interrupt context.
 510  *
 511  * @sa ixAtmmPortEnable  */
 512 PUBLIC IX_STATUS
 513 ixAtmmPortDisable(IxAtmLogicalPort port);
 514
 515 /**
 516  * @ingroup IxAtmm
 517  *
 518  * @fn ixAtmmVcRegister (IxAtmLogicalPort port,
 519                   IxAtmmVc *vcToAdd,
 520                   IxAtmSchedulerVcId *vcId)
 521  *
 522  * @brief This interface is used to register an ATM Virtual
 523  *         Connection on the specified ATM port.
 524  *
 525  *  Each call to this interface registers a unidirectional virtual
 526  *  connection with the parameters specified.  If a bi-directional VC
 527  *  is needed, the function should be called twice (once for each
 528  *  direction, Tx & Rx) where the VPI and VCI and port parameters in
 529  *  each call are identical.
 530  *
 531  *  With the addition of each new VC to a port, a series of
 532  *  callback functions are invoked by the IxAtmm component to notify
 533  *  possible external components of the change.  The callback functions
 534  *  are registered using the @ref ixAtmmVcChangeCallbackRegister interface.
 535  *
 536  *  The IxAtmSch component is notified of the registration of transmit
 537  *  VCs.
 538  *
 539  * @param port @ref IxAtmLogicalPort [in] - Identifies port on which the specified VC is
 540  *          to be registered.
 541  *
 542  * @param *vcToAdd @ref IxAtmmVc [in] -  Pointer to an @ref IxAtmmVc structure
 543  *          containing a description of the VC to be registered. The
 544  *          client shall fill the vpi, vci and direction and relevant
 545  *          trafficDesc members of this structure before calling this
 546  *          function.
 547  *
 548  * @param *vcId @ref IxAtmSchedulerVcId [out] - Pointer to an integer value which is filled
 549  *              with the per-port unique identifier value for this VC.
 550  *              This identifier will be required when a request is
 551  *              made to deregister or change this VC.  VC identifiers
 552  *              for transmit VCs will have a value between 0-43,
 553  *              i.e. 32 data Tx VCs + 12 OAM Tx Port VCs.
 554  *              Receive VCs will have a value between 44-66,
 555  *              i.e. 32 data Rx VCs + 1 OAM Rx VC.
 556  *
 557  * @return @li IX_SUCCESS : The VC has been successfully registered on
 558  *       this port. The VC is ready for a client to configure IxAtmdAcc
 559  *       for receive and transmit operations on the VC.
 560  * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
 561  *       input is not valid or has not been initialized.  The request
 562  *       is rejected.
 563  * @return @li IX_ATMM_RET_INVALID_VC_DESCRIPTOR : The descriptor
 564  *       pointed to by vcToAdd is invalid.  The registration request
 565  *       is rejected.
 566  * @return @li IX_ATMM_RET_VC_CONFLICT : The VC requested conflicts with
 567  *      reserved VPI and/or VCI values or with another VC already activated
 568  *      on this port.
 569  * @return @li IX_ATMM_RET_PORT_CAPACITY_IS_FULL : The VC cannot be
 570  *       registered in the port becuase the port capacity is
 571  *       insufficient to support the requested ATM traffic contract.
 572  *       The registration request is rejected.
 573  * @return @li IX_ATMM_RET_INVALID_PARAM_PTR : A pointer parameter was
 574  *       NULL.
 575  *
 576  * @warning IxAtmm has no capability of signaling or negotiating a virtual
 577  *          connection. Negotiation of the admission of the VC to the network
 578  *          is beyond the scope of this function.  This is assumed to be
 579  *          performed by the calling client, if appropriate,
 580  *          before or after this function is called.
 581  */
 582 PUBLIC IX_STATUS
 583 ixAtmmVcRegister (IxAtmLogicalPort port,
 584                   IxAtmmVc *vcToAdd,
 585                   IxAtmSchedulerVcId *vcId);
 586
 587 /**
 588  * @ingroup IxAtmm
 589  *
 590  * @fn ixAtmmVcDeregister (IxAtmLogicalPort port, IxAtmSchedulerVcId vcId)
 591  *
 592  * @brief Function called by a client to deregister a VC from the
 593  *         system.
 594  *
 595  *  With the removal of each new VC from a port, a series of
 596  *  registered callback functions are invoked by the IxAtmm component
 597  *  to notify possible external components of the change.  The callback
 598  *  functions are registered using the @ref ixAtmmVcChangeCallbackRegister.
 599  *
 600  *  The IxAtmSch component is notified of the removal of transmit VCs.
 601  *
 602  * @param port @ref IxAtmLogicalPort [in] - Identifies port on which the VC to be
 603  *          removed is currently registered.
 604  *
 605  * @param vcId @ref IxAtmSchedulerVcId [in] - VC identifier value of the VC to
 606  *          be deregistered.  This value was supplied to the client when
 607             the VC was originally registered.  This value can also be
 608             queried from the IxAtmm component through the @ref ixAtmmVcQuery
 609  *          interface.
 610  *
 611  * @return @li IX_SUCCESS : The specified VC has been successfully
 612  *       removed from this port.
 613  * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
 614  *       input is not valid or has not been initialized.  The request
 615  *       is rejected.
 616  * @return @li IX_FAIL : There is no registered VC associated with the
 617  *       supplied identifier registered on this port. */
 618 PUBLIC IX_STATUS
 619 ixAtmmVcDeregister (IxAtmLogicalPort port, IxAtmSchedulerVcId vcId);
 620
 621 /**
 622  * @ingroup IxAtmm
 623  *
 624  * @fn ixAtmmVcQuery (IxAtmLogicalPort port,
 625                unsigned vpi,
 626                unsigned vci,
 627                IxAtmmVcDirection direction,
 628                IxAtmSchedulerVcId *vcId,
 629                IxAtmmVc *vcDesc)
 630  *
 631  * @brief This interface supplies information about an active VC on a
 632  *         particular port when supplied with the VPI, VCI and
 633  *         direction of that VC.
 634  *
 635  * @param port @ref IxAtmLogicalPort [in] - Identifies port on which the VC to be
 636  *          queried is currently registered.
 637  *
 638  * @param vpi unsigned [in] - ATM VPI value of the requested VC.
 639  *
 640  * @param vci unsigned [in] - ATM VCI value of the requested VC.
 641  *
 642  * @param direction @ref IxAtmmVcDirection [in] - One of @ref
 643  *          IX_ATMM_VC_DIRECTION_TX or @ref IX_ATMM_VC_DIRECTION_RX
 644  *          indicating the direction (Tx or Rx) of the requested VC.
 645  *
 646  * @param *vcId @ref IxAtmSchedulerVcId [out] - Pointer to an integer value which will be
 647  *              filled with the VC identifier value for the requested
 648  *              VC (as returned by @ref ixAtmmVcRegister), if it
 649  *              exists on this port.
 650  *
 651  * @param *vcDesc @ref IxAtmmVc [out] - Pointer to an @ref IxAtmmVc structure
 652  *              which will be filled with the specific details of the
 653  *              requested VC, if it exists on this port.
 654  *
 655  * @return @li IX_SUCCESS : The specified VC has been found on this port
 656  *       and the requested details have been returned.
 657  * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
 658  *       input is not valid or has not been initialized.  The request
 659  *       is rejected.
 660  * @return @li IX_ATMM_RET_NO_SUCH_VC : No VC exists on the specified
 661  *       port which matches the search criteria (VPI, VCI, direction)
 662  *       given.  No data is returned.
 663  * @return @li IX_ATMM_RET_INVALID_PARAM_PTR : A pointer parameter was
 664  *       NULL.
 665  *
 666  */
 667 PUBLIC IX_STATUS
 668 ixAtmmVcQuery (IxAtmLogicalPort port,
 669                unsigned vpi,
 670                unsigned vci,
 671                IxAtmmVcDirection direction,
 672                IxAtmSchedulerVcId *vcId,
 673                IxAtmmVc *vcDesc);
 674
 675
 676 /**
 677  * @ingroup IxAtmm
 678  *
 679  * @fn ixAtmmVcIdQuery (IxAtmLogicalPort port, IxAtmSchedulerVcId vcId, IxAtmmVc *vcDesc)
 680  *
 681  * @brief This interface supplies information about an active VC on a
 682  *         particular port when supplied with a vcId for that VC.
 683  *
 684  * @param port @ref IxAtmLogicalPort [in] - Identifies port on which the VC to be
 685  *          queried is currently registered.
 686  *
 687  * @param vcId @ref IxAtmSchedulerVcId [in] - Value returned by @ref ixAtmmVcRegister which
 688  *          uniquely identifies the requested VC on this port.
 689  *
 690  * @param *vcDesc @ref IxAtmmVc [out] - Pointer to an @ref IxAtmmVc structure
 691  *              which will be filled with the specific details of the
 692  *              requested VC, if it exists on this port.
 693  *
 694  * @return @li IX_SUCCESS : The specified VC has been found on this port
 695  *       and the requested details have been returned.
 696  * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
 697  *       input is not valid or has not been initialized.  The request
 698  *       is rejected.
 699  * @return @li IX_ATMM_RET_NO_SUCH_VC : No VC exists on the specified
 700  *       port which matches the supplied identifier.  No data is
 701  *       returned.
 702  * @return @li IX_ATMM_RET_INVALID_PARAM_PTR : A pointer parameter was
 703  *       NULL.
 704  */
 705 PUBLIC IX_STATUS
 706 ixAtmmVcIdQuery (IxAtmLogicalPort port, IxAtmSchedulerVcId vcId, IxAtmmVc *vcDesc);
 707
 708 /**
 709  * @ingroup IxAtmm
 710  *
 711  * @fn ixAtmmVcChangeCallbackRegister (IxAtmmVcChangeCallback callback)
 712  *
 713  * @brief This interface is invoked to supply a function to IxAtmm
 714  *         which will be called to notify the client if a new VC is
 715  *         registered with IxAtmm or an existing VC is removed.
 716  *
 717  * The callback, when invoked, will run within the context of the call
 718  * to @ref ixAtmmVcRegister or @ref ixAtmmVcDeregister which caused
 719  * the change of state.
 720  *
 721  * A maximum of 32 calbacks may be registered in with IxAtmm.
 722  *
 723  * @param callback @ref IxAtmmVcChangeCallback [in] - Callback which complies
 724  *          with the @ref IxAtmmVcChangeCallback definition.  This
 725  *          function will be invoked by IxAtmm with the appropiate
 726  *          parameters for the relevant VC when any VC has been
 727  *          registered or deregistered with IxAtmm.
 728  *
 729  * @return @li IX_SUCCESS : The specified callback has been registered
 730  *      successfully with IxAtmm and will be invoked when appropriate.
 731  * @return @li IX_FAIL : Either the supplied callback is invalid, or
 732  *      IxAtmm has already registered 32 and connot accommodate
 733  *      any further registrations of this type.  The request is
 734  *      rejected.
 735  *
 736  * @warning The client must not call either the @ref
 737  *          ixAtmmVcRegister or @ref ixAtmmVcDeregister interfaces
 738  *          from within the supplied callback function.  */
 739 PUBLIC IX_STATUS ixAtmmVcChangeCallbackRegister (IxAtmmVcChangeCallback callback);
 740
 741
 742 /**
 743  * @ingroup IxAtmm
 744  *
 745  * @fn ixAtmmVcChangeCallbackDeregister (IxAtmmVcChangeCallback callback)
 746  *
 747  * @brief This interface is invoked to deregister a previously supplied
 748  *         callback function.
 749  *
 750  * @param callback @ref IxAtmmVcChangeCallback [in] - Callback which complies
 751  *          with the @ref IxAtmmVcChangeCallback definition.  This
 752  *          function will removed from the table of callbacks.
 753  *
 754  * @return @li IX_SUCCESS : The specified callback has been deregistered
 755  *      successfully from IxAtmm.
 756  * @return @li IX_FAIL : Either the supplied callback is invalid, or
 757  *      is not currently registered with IxAtmm.
 758  */
 759 PUBLIC IX_STATUS
 760 ixAtmmVcChangeCallbackDeregister (IxAtmmVcChangeCallback callback);
 761
 762 /**
 763  * @ingroup IxAtmm
 764  *
 765  * @fn ixAtmmUtopiaStatusShow (void)
 766  *
 767  *  @brief Display utopia status counters
 768  *
 769  * @param "none"
 770  *
 771  * @return @li IX_SUCCESS : Show function was successful
 772  * @return @li IX_FAIL : Internal failure
 773  */
 774 PUBLIC IX_STATUS
 775 ixAtmmUtopiaStatusShow (void);
 776
 777 /**
 778  * @ingroup IxAtmm
 779  *
 780  * @fn ixAtmmUtopiaCfgShow (void)
 781  *
 782  * @brief Display utopia information(config registers and status registers)
 783  *
 784  * @param "none"
 785  *
 786  * @return @li IX_SUCCESS : Show function was successful
 787  * @return @li IX_FAIL : Internal failure
 788  */
 789 PUBLIC IX_STATUS
 790 ixAtmmUtopiaCfgShow (void);
 791
 792 #endif
 793 /* IXATMM_H */
 794
 795 /** @} */