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