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 /** @} */ 796