drivers/net/npe/include/IxAtmdAcc.h

   1
   2 /**
   3  * @file    IxAtmdAcc.h
   4  *
   5  * @date    07-Nov-2001
   6  *
   7  * @brief IxAtmdAcc Public API
   8  *
   9  * This file contains the public API of IxAtmdAcc, related to the
  10  * data functions of the component
  11  *
  12  *
  13  * @par
  14  * IXP400 SW Release version 2.0
  15  *
  16  * -- Copyright Notice --
  17  *
  18  * @par
  19  * Copyright 2001-2005, Intel Corporation.
  20  * All rights reserved.
  21  *
  22  * @par
  23  * SPDX-License-Identifier:     BSD-3-Clause
  24  * @par
  25  * -- End of Copyright Notice --
  26  */
  27
  28 /* ------------------------------------------------------
  29    Doxygen group definitions
  30    ------------------------------------------------------ */
  31
  32 /**
  33  *
  34  * @defgroup IxAtmdAccAPI IXP400 ATM Driver Access (IxAtmdAcc) API
  35  *
  36  * @brief The public API for the IXP400 Atm Driver Data component
  37  *
  38  * IxAtmdAcc is the low level interface by which AAL0/AAL5 and
  39  * OAM data gets transmitted to,and received from the Utopia bus.
  40  *
  41  * For AAL0/AAL5 services transmit and receive connections may
  42  * be established independantly for unique combinations of
  43  * port,VPI,and VCI.
  44  *
  45  * Two AAL0 services supporting 48 or 52 byte cell data are provided.
  46  * Submitted AAL0 PDUs must be a multiple of the cell data size (48/52).
  47  * AAL0_52 is a raw cell service the client must format
  48  * the PDU with an ATM cell header (excluding HEC) at the start of
  49  * each cell, note that AtmdAcc does not validate the cell headers in
  50  * a submitted PDU.
  51  *
  52  * OAM cells cannot be received over the AAL0 service but instead
  53  * are received over a dedicated OAM service.
  54  *
  55  * For the OAM service an "OAM Tx channel" may be enabled for a port
  56  * by establishing a single dedicated OAM Tx connection on that port.
  57  * A single "OAM Rx channel" for all ports may be  enabled by
  58  * establishing a dedicated OAM Rx connection.
  59  *
  60  * The OAM service allows buffers containing 52 byte OAM F4/F5 cells
  61  * to be transmitted and received over the dedicated OAM channels.
  62  * HEC is appended/removed, and CRC-10 performed by the NPE. The OAM
  63  * service offered by AtmdAcc is a raw cell transport service.
  64  * It is assumed that ITU I.610 procedures that make use of this
  65  * service are implemented above AtmdAcc.
  66  *
  67  * Note that the dedicated OAM connections are established on
  68  * reserved VPI,VCI, and (in the case of Rx) port values defined below.
  69  * These values are used purely to descriminate the dedicated OAM channels
  70  * and do not identify a particular OAM F4/F5 flow. F4/F5 flows may be
  71  * realised for particluar VPI/VCIs by manipulating the VPI,VCI
  72  * fields of the ATM cell headers of cells in the buffers passed
  73  * to AtmdAcc. Note that AtmdAcc does not validate the cell headers
  74  * in a submitted OAM PDU.
  75  *
  76  *
  77  *
  78  * This part is related to the User datapath processing
  79  *
  80  * @{
  81  */
  82
  83 #ifndef IXATMDACC_H
  84 #define IXATMDACC_H
  85
  86 #include "IxAtmTypes.h"
  87
  88 /* ------------------------------------------------------
  89    AtmdAcc Data Types definition
  90    ------------------------------------------------------ */
  91
  92 /**
  93  *
  94  * @ingroup IxAtmdAccAPI
  95  *
  96  * @def IX_ATMDACC_WARNING
  97  *
  98  * @brief Warning return code
  99  *
 100  * This constant is used to tell IxAtmDAcc user about a special case.
 101  *
 102  */
 103 #define IX_ATMDACC_WARNING 2
 104
 105 /**
 106  *
 107  * @ingroup IxAtmdAccAPI
 108  *
 109  * @def IX_ATMDACC_BUSY
 110  *
 111  * @brief Busy return code
 112  *
 113  * This constant is used to tell IxAtmDAcc user that the request
 114  * is correct, but cannot be processed because the IxAtmAcc resources
 115  * are already used. The user has to retry its request later
 116  *
 117  */
 118 #define IX_ATMDACC_BUSY 3
 119
 120 /**
 121  *
 122  * @ingroup IxAtmdAccAPI
 123  *
 124  * @def IX_ATMDACC_RESOURCES_STILL_ALLOCATED
 125  *
 126  * @brief Disconnect return code
 127  *
 128  * This constant is used to tell IxAtmDAcc user that the disconnect
 129  * functions are not complete because the resources used by the driver
 130  * are not yet released. The user has to retry the disconnect call
 131  * later.
 132  *
 133  */
 134 #define IX_ATMDACC_RESOURCES_STILL_ALLOCATED 4
 135
 136 /**
 137  *
 138  * @ingroup IxAtmdAccAPI
 139  *
 140  * @def IX_ATMDACC_DEFAULT_REPLENISH_COUNT
 141  *
 142  * @brief Default resources usage for RxVcFree replenish mechanism
 143  *
 144  * This constant is used to tell IxAtmDAcc to allocate and use
 145  * the minimum of resources for rx free replenish.
 146  *
 147  * @sa ixAtmdAccRxVcConnect
 148  */
 149 #define IX_ATMDACC_DEFAULT_REPLENISH_COUNT 0
 150
 151
 152 /**
 153  * @ingroup IxAtmdAccAPI
 154  *
 155  * @def IX_ATMDACC_OAM_TX_VPI
 156  *
 157  * @brief The reserved value used for the dedicated OAM
 158  * Tx connection. This "well known" value is used by atmdAcc and
 159  * its clients to dsicriminate the OAM channel, and should be chosen so
 160  * that it does not coencide with the VPI value used in an AAL0/AAL5 connection.
 161  * Any attempt to connect a service type other than OAM on this VPI will fail.
 162  *
 163  *
 164  */
 165 #define IX_ATMDACC_OAM_TX_VPI 0
 166
 167 /**
 168  * @ingroup IxAtmdAccAPI
 169  *
 170  * @def IX_ATMDACC_OAM_TX_VCI
 171  *
 172  * @brief The reserved value used for the dedicated OAM
 173  * Tx connection. This "well known" value is used by atmdAcc and
 174  * its clients to dsicriminate the OAM channel, and should be chosen so
 175  * that it does not coencide with the VCI value used in an AAL0/AAL5 connection.
 176  * Any attempt to connect a service type other than OAM on this VCI will fail.
 177  */
 178 #define IX_ATMDACC_OAM_TX_VCI 0
 179
 180
 181  /**
 182  * @ingroup IxAtmdAccAPI
 183  *
 184  * @def IX_ATMDACC_OAM_RX_PORT
 185  *
 186  * @brief The reserved dummy PORT used for all dedicated OAM
 187  * Rx connections. Note that this is not a real port but must
 188  * have a value that lies within the valid range of port values.
 189  */
 190 #define IX_ATMDACC_OAM_RX_PORT IX_UTOPIA_PORT_0
 191
 192  /**
 193  * @ingroup IxAtmdAccAPI
 194  *
 195  * @def IX_ATMDACC_OAM_RX_VPI
 196  *
 197  * @brief The reserved value value used for the dedicated OAM
 198  * Rx connection. This value should be chosen so that it does not
 199  * coencide with the VPI value used in an AAL0/AAL5 connection.
 200  * Any attempt to connect a service type other than OAM on this VPI will fail.
 201  */
 202 #define IX_ATMDACC_OAM_RX_VPI 0
 203
 204 /**
 205  * @ingroup IxAtmdAccAPI
 206  *
 207  * @def IX_ATMDACC_OAM_RX_VCI
 208  *
 209  * @brief The reserved value value used for the dedicated OAM
 210  * Rx connection. This value should be chosen so that it does not
 211  * coencide with the VCI value used in an AAL0/AAL5 connection.
 212  * Any attempt to connect a service type other than OAM on this VCI will fail.
 213  */
 214 #define IX_ATMDACC_OAM_RX_VCI 0
 215
 216
 217 /**
 218  * @enum IxAtmdAccPduStatus
 219  *
 220  * @ingroup IxAtmdAccAPI
 221  *
 222  * @brief IxAtmdAcc Pdu status :
 223  *
 224  * IxAtmdAccPduStatus is used during a RX operation to indicate
 225  * the status of the received PDU
 226  *
 227  */
 228
 229 typedef enum
 230 {
 231     IX_ATMDACC_AAL0_VALID = 0,    /**< aal0 pdu */
 232     IX_ATMDACC_OAM_VALID,         /**< OAM pdu */
 233     IX_ATMDACC_AAL2_VALID,        /**< aal2 pdu @b reserved for future use */
 234     IX_ATMDACC_AAL5_VALID,        /**< aal5 pdu complete and trailer is valid */
 235     IX_ATMDACC_AAL5_PARTIAL,      /**< aal5 pdu not complete, trailer is missing */
 236     IX_ATMDACC_AAL5_CRC_ERROR,    /**< aal5 pdu not complete, crc error/length error */
 237     IX_ATMDACC_MBUF_RETURN        /**< empty buffer returned to the user */
 238 } IxAtmdAccPduStatus;
 239
 240
 241 /**
 242  *
 243  * @enum IxAtmdAccAalType
 244  *
 245  * @ingroup IxAtmdAccAPI
 246  *
 247  * @brief IxAtmdAcc AAL Service Type :
 248  *
 249  * IxAtmdAccAalType defines the type of traffic to run on this VC
 250  *
 251  */
 252 typedef enum
 253 {
 254     IX_ATMDACC_AAL5,                /**< ITU-T AAL5 */
 255     IX_ATMDACC_AAL2,                /**< ITU-T AAL2 @b reserved for future use */
 256     IX_ATMDACC_AAL0_48,             /**< AAL0 48 byte payloads (cell header is added by NPE)*/
 257     IX_ATMDACC_AAL0_52,             /**< AAL0 52 byte cell data (HEC is added by NPE) */
 258     IX_ATMDACC_OAM,                 /**< OAM cell transport service (HEC is added by NPE)*/
 259     IX_ATMDACC_MAX_SERVICE_TYPE     /**< not a service, used for parameter validation */
 260 } IxAtmdAccAalType;
 261
 262 /**
 263  *
 264  * @enum IxAtmdAccClpStatus
 265  *
 266  * @ingroup IxAtmdAccAPI
 267  *
 268  * @brief IxAtmdAcc CLP indication
 269  *
 270  * IxAtmdAccClpStatus defines the CLP status of the current PDU
 271  *
 272  */
 273 typedef enum
 274 {
 275     IX_ATMDACC_CLP_NOT_SET = 0,     /**< CLP indication is not set */
 276     IX_ATMDACC_CLP_SET = 1     /**< CLP indication is set */
 277 } IxAtmdAccClpStatus;
 278
 279 /**
 280  * @typedef IxAtmdAccUserId
 281  *
 282  * @ingroup IxAtmdAccAPI
 283  *
 284  * @brief User-supplied Id
 285  *
 286  * IxAtmdAccUserId is passed through callbacks and allows the
 287  * IxAtmdAcc user to identify the source of a call back. The range of
 288  * this user-owned Id is [0...2^32-1)].
 289  *
 290  * The user provides this own Ids on a per-channel basis as a parameter
 291  * in a call to @a ixAtmdAccRxVcConnect() or @a ixAtmdAccRxVcConnect()
 292  *
 293  * @sa ixAtmdAccRxVcConnect
 294  * @sa ixAtmdAccTxVcConnect
 295  *
 296  */
 297 typedef unsigned int IxAtmdAccUserId;
 298
 299 /* ------------------------------------------------------
 300    Part of the IxAtmdAcc interface related to RX traffic
 301    ------------------------------------------------------ */
 302
 303 /**
 304  *
 305  * @ingroup IxAtmdAccAPI
 306  *
 307  * @brief  Rx callback prototype
 308  *
 309  * IxAtmdAccRxVcRxCallback is the prototype of the Rx callback user
 310  * function called once per PDU to pass a receive Pdu to a user on a
 311  * partilcular connection. The callback is likely to push the mbufs
 312  * to a protocol layer, and recycle the mbufs for a further use.
 313  *
 314  * @note -This function is called ONLY in the context of
 315  *        the @a ixAtmdAccRxDispatch() function
 316  *
 317  * @sa ixAtmdAccRxDispatch
 318  * @sa ixAtmdAccRxVcConnect
 319  *
 320  * @param port @ref IxAtmLogicalPort [in] - the port on which this PDU was received
 321  *        a logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 322  * @param userId @ref IxAtmdAccUserId [in] - user Id provided in the call
 323  *        to @a ixAtmdAccRxVcConnect()
 324  * @param status @ref IxAtmdAccPduStatus [in] - an indication about the PDU validity.
 325  *        In the case of AAL0 the only possibile value is
 326  *        AAL0_VALID, in this case the client may optionally determine
 327  *        that an rx timeout occured by checking if the mbuf is
 328  *        compleletly or only partially filled, the later case
 329  *        indicating a timeout.
 330  *        In the case of OAM the only possible value is OAM valid.
 331  *        The status is set to @a IX_ATMDACC_MBUF_RETURN when
 332  *        the mbuf is released during a disconnect process.
 333  * @param clp @ref IxAtmdAccClpStatus [in] - clp indication for this PDU.
 334  *        For AAL5/AAL0_48 this information
 335  *        is set if the clp bit of any rx cell is set
 336  *        For AAL0-52/OAM the client may inspect the CLP in individual
 337  *        cell headers in the PDU, and this parameter is set to 0.
 338  * @param *mbufPtr @ref IX_OSAL_MBUF [in] - depending on the servive type a pointer to
 339  *        an mbuf (AAL5/AAL0/OAM) or mbuf chain (AAL5 only),
 340  *        that comprises the complete PDU data.
 341  *
 342  *        This parameter is guaranteed not to be a null pointer.
 343  *
 344  */
 345 typedef void (*IxAtmdAccRxVcRxCallback) (IxAtmLogicalPort port,
 346                        IxAtmdAccUserId userId,
 347                        IxAtmdAccPduStatus status,
 348                        IxAtmdAccClpStatus clp,
 349                        IX_OSAL_MBUF * mbufPtr);
 350
 351 /**
 352  *
 353  * @ingroup IxAtmdAccAPI
 354  *
 355  * @brief Callback prototype for free buffer level is low.
 356  *
 357  * IxAtmdAccRxVcFreeLowCallback is the prototype of the user function
 358  * which get called on a per-VC basis, when more  mbufs are needed to
 359  * continue the ATM data reception. This function is likely to supply
 360  * more available mbufs by one or many calls to the replenish function
 361  * @a ixAtmdAccRxVcFreeReplenish()
 362  *
 363  * This function is called when the number of available buffers for
 364  * reception is going under the threshold level as defined
 365  * in @a ixAtmdAccRxVcFreeLowCallbackRegister()
 366  *
 367  * This function is called inside an Qmgr dispatch context. No system
 368  * resource or interrupt-unsafe feature should be used inside this
 369  * callback.
 370  *
 371  * @sa ixAtmdAccRxVcFreeLowCallbackRegister
 372  * @sa IxAtmdAccRxVcFreeLowCallback
 373  * @sa ixAtmdAccRxVcFreeReplenish
 374  * @sa ixAtmdAccRxVcFreeEntriesQuery
 375  * @sa ixAtmdAccRxVcConnect
 376  *
 377  * @param userId @ref IxAtmdAccUserId [in] - user Id provided in the call
 378  * to @a ixAtmdAccRxVcConnect()
 379  *
 380  * @return None
 381  *
 382  */
 383 typedef void (*IxAtmdAccRxVcFreeLowCallback) (IxAtmdAccUserId userId);
 384
 385 /* ------------------------------------------------------
 386    Part of the IxAtmdAcc interface related to TX traffic
 387    ------------------------------------------------------ */
 388
 389 /**
 390  *
 391  * @ingroup IxAtmdAccAPI
 392  *
 393  * @brief  Buffer callback prototype.
 394  *
 395  * This function is called to relinguish ownership of a transmitted
 396  * buffer chain to the user.
 397  *
 398  * @note -In the case of a chained mbuf the AmtdAcc component can
 399  * chain many user buffers together and pass ownership to the user in
 400  * one function call.
 401  *
 402  * @param userId @ref IxAtmdAccUserId [in] - user If provided at registration of this
 403  *        callback.
 404  * @param mbufPtr @ref IX_OSAL_MBUF [in] - a pointer to mbufs or chain of mbufs and is
 405  *        guaranteed not to be a null pointer.
 406  *
 407  */
 408 typedef void (*IxAtmdAccTxVcBufferReturnCallback) (IxAtmdAccUserId userId,
 409                         IX_OSAL_MBUF * mbufPtr);
 410
 411 /* ------------------------------------------------------
 412    Part of the IxAtmdAcc interface related to Initialisation
 413    ------------------------------------------------------ */
 414
 415 /**
 416  *
 417  * @ingroup IxAtmdAccAPI
 418  *
 419  * @fn ixAtmdAccInit (void)
 420  *
 421  * @brief Initialise the IxAtmdAcc Component
 422  *
 423  * This function initialise the IxAtmdAcc component. This function shall
 424  * be called before any other function of the API. Its role is to
 425  * initialise all internal resources of the IxAtmdAcc component.
 426  *
 427  * The ixQmgr component needs to be initialized prior the use of
 428  * @a ixAtmdAccInit()
 429  *
 430  * @param none
 431  *
 432  * Failing to initilialize the IxAtmdAcc API before any use of it will
 433  * result in a failed status.
 434  * If the specified component is not present, a success status will still be
 435  * returned, however, a warning indicating the NPE to download to is not
 436  * present will be issued.
 437  *
 438  * @return @li IX_SUCCESS initialisation is complete (in case of component not
 439  *             being present, a warning is clearly indicated)
 440  * @return @li IX_FAIL unable to process this request either
 441  *             because this IxAtmdAcc is already initialised
 442  *             or some unspecified error has occrred.
 443  */
 444 PUBLIC IX_STATUS ixAtmdAccInit (void);
 445
 446 /**
 447  *
 448  * @ingroup IxAtmdAccAPI
 449  *
 450  * @fn ixAtmdAccShow (void)
 451  *
 452  * @brief Show IxAtmdAcc configuration on a per port basis
 453  *
 454  * @param none
 455  *
 456  * @return none
 457  *
 458  * @note - Display use printf() and are redirected to stdout
 459  */
 460 PUBLIC void
 461 ixAtmdAccShow (void);
 462
 463 /**
 464  *
 465  * @ingroup IxAtmdAccAPI
 466  *
 467  * @fn ixAtmdAccStatsShow (void)
 468  *
 469  * @brief Show all IxAtmdAcc stats
 470  *
 471  * @param none
 472  *
 473  * @return none
 474  *
 475  * @note - Stats display use printf() and are redirected to stdout
 476  */
 477 PUBLIC void
 478 ixAtmdAccStatsShow (void);
 479
 480 /**
 481  *
 482  * @ingroup IxAtmdAccAPI
 483  *
 484  * @fn ixAtmdAccStatsReset (void)
 485  *
 486  * @brief Reset all IxAtmdAcc stats
 487  *
 488  * @param none
 489  *
 490  * @return none
 491  *
 492  */
 493 PUBLIC void
 494 ixAtmdAccStatsReset (void);
 495
 496 /* ------------------------------------------------------
 497    Part of the IxAtmdAcc interface related to RX traffic
 498    ------------------------------------------------------ */
 499
 500 /**
 501  *
 502  * @ingroup IxAtmdAccAPI
 503  *
 504  * @fn ixAtmdAccRxVcConnect (IxAtmLogicalPort port,
 505                       unsigned int vpi,
 506                       unsigned int vci,
 507                       IxAtmdAccAalType aalServiceType,
 508                       IxAtmRxQueueId rxQueueId,
 509                       IxAtmdAccUserId userCallbackId,
 510                       IxAtmdAccRxVcRxCallback rxCallback,
 511                       unsigned int minimumReplenishCount,
 512                       IxAtmConnId * connIdPtr,
 513                       IxAtmNpeRxVcId * npeVcIdPtr )
 514  *
 515  * @brief Connect to a Aal Pdu receive service for a particular
 516  *        port/vpi/vci, and service type.
 517  *
 518  * This function allows a user to connect to an Aal5/Aal0/OAM Pdu receive service
 519  * for a particular port/vpi/vci. It registers the callback and allocates
 520  * internal resources and a Connection Id to be used in further API calls
 521  * related to this VCC.
 522  *
 523  * The function will setup VC receive service on the specified rx queue.
 524  *
 525  * This function is blocking and makes use internal locks, and hence
 526  * should not be called from an interrupt context.
 527  *
 528  * On return from @a ixAtmdAccRxVcConnect() with a failure status, the
 529  * connection Id parameter is unspecified. Its value cannot be used.
 530  * A connId is the reference by which IxAtmdAcc refers to a
 531  * connected VC. This identifier is the result of a succesful call
 532  * to a connect function. This identifier is invalid after a
 533  * sucessful call to a disconnect function.
 534  *
 535  * Calling this function for the same combination of Vpi, Vci and more
 536  * than once without calling @a ixAtmdAccRxVcTryDisconnect() will result in a
 537  * failure status.
 538  *
 539  * If this function returns success the user should supply receive
 540  * buffers by calling @a ixAtmdAccRxVcFreeReplenish() and then call
 541  * @a ixAtmdAccRxVcEnable() to begin receiving pdus.
 542  *
 543  * There is a choice of two receive Qs on which the VC pdus could be
 544  * receive. The user must associate the VC with one of these. Essentially
 545  * having two qs allows more flexible system configuration such as have
 546  * high prioriy traffic on one q (e.g. voice) and low priority traffic on
 547  * the other (e.g. data). The high priority Q could be serviced in
 548  * preference to the low priority Q. One queue may be configured to be
 549  * serviced as soon as there is traffic, the other queue may be configured
 550  * to be serviced by a polling mechanism running at idle time.
 551  *
 552  * Two AAL0 services supporting 48 or 52 byte cell data are provided.
 553  * Received AAL0 PDUs will be be a multiple of the cell data size (48/52).
 554  * AAL0_52 is a raw cell service and includes an ATM cell header
 555  * (excluding HEC) at the start of each cell.
 556  *
 557  * A single "OAM Rx channel" for all ports may be  enabled by
 558  * establishing a dedicated OAM Rx connection.
 559  *
 560  * The OAM service allows buffers containing 52 byte OAM F4/F5 cells
 561  * to be transmitted and received over the dedicated OAM channels.
 562  * HEC is appended/removed, and CRC-10 performed by the NPE. The OAM
 563  * service offered by AtmdAcc is a raw cell transport service.
 564  * It is assumed that ITU I.610 procedures that make use of this
 565  * service are implemented above AtmdAcc.
 566  *
 567  * Note that the dedicated OAM connections are established on
 568  * reserved VPI,VCI, and (in the case of Rx) port values.
 569  * These values are used purely to descriminate the dedicated OAM channels
 570  * and do not identify a particular OAM F4/F5 flow. F4/F5 flows may be
 571  * realised for particluar VPI/VCIs by manipulating the VPI,VCI
 572  * fields of the ATM cell headers of cells in the buffers passed
 573  * to AtmdAcc.
 574  *
 575  * Calling this function prior to enable the port will fail.
 576  *
 577  * @sa ixAtmdAccRxDispatch
 578  * @sa ixAtmdAccRxVcEnable
 579  * @sa ixAtmdAccRxVcDisable
 580  * @sa ixAtmdAccRxVcTryDisconnect
 581  * @sa ixAtmdAccPortEnable
 582  *
 583  * @param port @ref IxAtmLogicalPort [in] - VC identification : logical PHY port
 584  *                  [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 585  * @param vpi unsigned int [in] - VC identification : ATM Vpi [0..255] or IX_ATMDACC_OAM_VPI
 586  * @param vci unsigned int [in] - VC identification : ATM Vci [0..65535] or IX_ATMDACC_OAM_VCI
 587  * @param aalServiceType @ref IxAtmdAccAalType [in] - type of service: AAL5, AAL0_48, AAL0_52, or OAM
 588  * @param rxQueueId @ref IxAtmRxQueueId [in] - this identifieds which of two Qs the VC
 589  *     should use.when icoming traffic is processed
 590  * @param userCallbackId @ref IxAtmdAccUserId [in] - user Id used later as a parameter to
 591  *     the supplied rxCallback.
 592  * @param rxCallback [in] @ref IxAtmdAccRxVxRxCallback - function called when mbufs are received.
 593  *     This parameter cannot be a null pointer.
 594  * @param bufferFreeCallback [in] - function to be called to return
 595  *     ownership of buffers to IxAtmdAcc user.
 596  * @param minimumReplenishCount unsigned int [in] -  For AAL5/AAL0 the number of free mbufs
 597  *     to be used with this channel. Use a high number when the expected traffic
 598  *     rate on this channel is high, or when the user's mbufs are small, or when
 599  *     the RxVcFreeLow Notification has to be invoked less often. When this
 600  *     value is IX_ATMDACC_DEFAULT_REPLENISH_COUNT, the minimum of
 601  *     resources  will be used. Depending on traffic rate, pdu
 602  *     size and mbuf size, rxfree queue size, polling/interrupt rate, this value may
 603  *     require to be replaced by a different value in the range 1-128
 604  *     For OAM the rxFree queue size is fixed by atmdAcc and this parameter is ignored.
 605  * @param connIdPtr @ref IxAtmConnId [out] - pointer to a connection Id
 606  *     This parameter cannot be a null pointer.
 607  * @param npeVcIdPtr @ref IxAtmNpeRxVcId [out] - pointer to an npe Vc Id
 608  *     This parameter cannot be a null pointer.
 609  *
 610  * @return @li IX_SUCCESS successful call to IxAtmdAccRxVcConnect
 611  * @return @li IX_ATMDACC_BUSY cannot process this request :
 612  *         no VC is available
 613  * @return @li IX_FAIL
 614  *             parameter error,
 615  *             VC already in use,
 616  *             attempt to connect AAL service on reserved OAM VPI/VCI,
 617  *             attempt to connect OAM service on VPI/VCI other than the reserved OAM VPI/VCI,
 618  *             port is not initialised,
 619  *             or some other error occurs during processing.
 620  *
 621  */
 622 PUBLIC IX_STATUS ixAtmdAccRxVcConnect (IxAtmLogicalPort port,
 623                       unsigned int vpi,
 624                       unsigned int vci,
 625                       IxAtmdAccAalType aalServiceType,
 626                       IxAtmRxQueueId rxQueueId,
 627                       IxAtmdAccUserId userCallbackId,
 628                       IxAtmdAccRxVcRxCallback rxCallback,
 629                       unsigned int minimumReplenishCount,
 630                       IxAtmConnId * connIdPtr,
 631                       IxAtmNpeRxVcId * npeVcIdPtr );
 632
 633 /**
 634  *
 635  * @ingroup IxAtmdAccAPI
 636  *
 637  * @fn ixAtmdAccRxVcFreeReplenish (IxAtmConnId connId,
 638                         IX_OSAL_MBUF * mbufPtr)
 639  *
 640  * @brief Provide free mbufs for data reception on a connection.
 641  *
 642  * This function provides mbufs for data reception by the hardware. This
 643  * function needs to be called by the user on a regular basis to ensure
 644  * no packet loss. Providing free buffers is a connection-based feature;
 645  * each connection can have different requirements in terms of buffer size
 646  * number of buffers, recycling rate. This function could be invoked from
 647  * within the context of a @a IxAtmdAccRxVcFreeLowCallback() callback
 648  * for a particular VC
 649  *
 650  * Mbufs provided through this function call can be chained. They will be
 651  * unchained internally. A call to this function with chained mbufs or
 652  * multiple calls with unchained mbufs are equivalent, but calls with
 653  * unchained mbufs are more efficients.
 654  *
 655  * Mbufs provided to this interface need to be able to hold at least one
 656  * full cell payload (48/52 bytes, depending on service type).
 657  * Chained buffers with a size less than the size supported by the hardware
 658  * will be returned through the rx callback provided during the connect step.
 659  *
 660  * Failing to invoke this function prior to enabling the RX traffic
 661  * can result in packet loss.
 662  *
 663  * This function is not reentrant for the same connId.
 664  *
 665  * This function does not use system resources and can be
 666  * invoked from an interrupt context.
 667  *
 668  * @note - Over replenish is detected, and extra mbufs are returned through
 669  *         the rx callback provided during the connect step.
 670  *
 671  * @note - Mbuf provided to the replenish function should have a length greater or
 672  *         equal to 48/52 bytes according to service type.
 673  *
 674  * @note - The memory cache of mMbuf payload should be invalidated prior to Mbuf
 675  *         submission. Flushing the Mbuf headers is handled by IxAtmdAcc.
 676  *
 677  * @note - When a chained mbuf is provided, this function process the mbufs
 678  *         up to the hardware limit and invokes the user-supplied callback
 679  *         to release extra buffers.
 680  *
 681  * @sa ixAtmdAccRxVcFreeLowCallbackRegister
 682  * @sa IxAtmdAccRxVcFreeLowCallback
 683  * @sa ixAtmdAccRxVcConnect
 684  *
 685  * @param connId @ref IxAtmConnId [in] - connection Id as returned from a succesfull call to
 686  *        @a IxAtmdAccRxVcConnect()
 687  * @param mbufPtr @ref IX_OSAL_MBUF [in] - pointer to a mbuf structure to be used for data
 688  *        reception. The mbuf pointed to by this parameter can be chained
 689  *        to an other mbuf.
 690  *
 691  * @return @li IX_SUCCESS successful call to @a ixAtmdAccRxVcFreeReplenish()
 692  *          and the mbuf is now ready to use for incoming traffic.
 693  * @return @li IX_ATMDACC_BUSY cannot process this request because
 694  *         the max number of outstanding free buffers has been reached
 695  *         or the internal resources have exhausted for this VC.
 696  *         The user is responsible for retrying this request later.
 697  * @return @li IX_FAIL cannot process this request because of parameter
 698  *         errors or some unspecified internal error has occurred.
 699  *
 700  * @note - It is not always guaranteed the replenish step to be as fast as the
 701  *   hardware is consuming Rx Free mbufs. There is nothing in IxAtmdAcc to
 702  *   guarantee that replenish reaches the rxFree threshold level. If the
 703  *   threshold level is not reached, the next rxFree low notification for
 704  *   this channel will not be triggered.
 705  *   The preferred ways to replenish can be as follows (depending on
 706  *   applications and implementations) :
 707  *   @li Replenish in a rxFree low notification until the function
 708  *       ixAtmdAccRxVcFreeReplenish() returns IX_ATMDACC_BUSY
 709  *   @li Query the queue level using @sa ixAtmdAccRxVcFreeEntriesQuery, then
 710  *     , replenish using @a ixAtmdAccRxVcFreeReplenish(), then query the queue
 711  *       level again, and replenish if the threshold is still not reached.
 712  *   @li Trigger replenish from an other event source and use rxFree starvation
 713  *       to throttle the Rx traffic.
 714  *
 715  */
 716 PUBLIC IX_STATUS ixAtmdAccRxVcFreeReplenish (IxAtmConnId connId,
 717                         IX_OSAL_MBUF * mbufPtr);
 718
 719 /**
 720  *
 721  * @ingroup IxAtmdAccAPI
 722  *
 723  * @fn ixAtmdAccRxVcFreeLowCallbackRegister (IxAtmConnId connId,
 724                                     unsigned int numberOfMbufs,
 725                                     IxAtmdAccRxVcFreeLowCallback callback)
 726  *
 727  * @brief Configure the RX Free threshold value and register a callback
 728  * to handle threshold notifications.
 729  *
 730  * The function ixAtmdAccRxVcFreeLowCallbackRegister sets the threshold value for
 731  * a particular RX VC. When the number of buffers reaches this threshold
 732  * the callback is invoked.
 733  *
 734  * This function should be called once per VC before RX traffic is
 735  * enabled.This function will fail if the curent level of the free buffers
 736  * is equal or less than the threshold value.
 737  *
 738  * @sa ixAtmdAccRxVcFreeLowCallbackRegister
 739  * @sa IxAtmdAccRxVcFreeLowCallback
 740  * @sa ixAtmdAccRxVcFreeReplenish
 741  * @sa ixAtmdAccRxVcFreeEntriesQuery
 742  * @sa ixAtmdAccRxVcConnect
 743  *
 744  * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call
 745  *        to @a IxAtmdAccRxVcConnect()
 746  * @param numberOfMbufs unsigned int [in] - threshold number of buffers. This number
 747  *        has to be a power of 2, one of the values 0,1,2,4,8,16,32....
 748  *        The maximum value cannot be more than half of the rxFree queue
 749  *        size (which can be retrieved using @a ixAtmdAccRxVcFreeEntriesQuery()
 750  *        before any use of the @a ixAtmdAccRxVcFreeReplenish() function)
 751  * @param callback @ref IxAtmdAccRxVcFreeLowCallback [in] - function telling the user that the number of
 752  *        free buffers has reduced to the threshold value.
 753  *
 754  * @return @li IX_SUCCESS Threshold set successfully.
 755  * @return @li IX_FAIL parameter error or the current number of free buffers
 756  *              is less than or equal to the threshold supplied or some
 757  *              unspecified error has occrred.
 758  *
 759  * @note - the callback will be called when the threshold level will drop from
 760  *        exactly (numberOfMbufs + 1) to (numberOfMbufs).
 761  *
 762  */
 763 PUBLIC IX_STATUS ixAtmdAccRxVcFreeLowCallbackRegister (IxAtmConnId connId,
 764     unsigned int numberOfMbufs,
 765     IxAtmdAccRxVcFreeLowCallback callback);
 766
 767 /**
 768  *
 769  * @ingroup IxAtmdAccAPI
 770  *
 771  * @fn ixAtmdAccRxVcFreeEntriesQuery (IxAtmConnId connId,
 772                          unsigned int *numberOfMbufsPtr)
 773  *
 774  * @brief Get the number of rx mbufs the system can accept to replenish the
 775  *       the rx reception mechanism on a particular channel
 776  *
 777  * The ixAtmdAccRxVcFreeEntriesQuery function is used to retrieve the current
 778  * number of available mbuf entries for reception, on a per-VC basis. This
 779  * function can be used to know the number of mbufs which can be provided
 780  * using @a ixAtmdAccRxVcFreeReplenish().
 781  *
 782  * This function can be used from a timer context, or can be associated
 783  * with a threshold event, or can be used inside an active polling
 784  * mechanism which is under user control.
 785  *
 786  * This function is reentrant and does not use system resources and can
 787  * be invoked from an interrupt context.
 788  *
 789  * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call
 790  *        to @a IxAtmdAccRxVcConnect()
 791  * @param numberOfMbufsPtr unsigned int [out] - Pointer to the number of available entries.
 792  *      . This parameter cannot be a null pointer.
 793  *
 794  * @return @li IX_SUCCESS the current number of mbufs not yet used for incoming traffic
 795  * @return @li IX_FAIL invalid parameter
 796  *
 797  * @sa ixAtmdAccRxVcFreeReplenish
 798  *
 799  */
 800 PUBLIC IX_STATUS ixAtmdAccRxVcFreeEntriesQuery (IxAtmConnId connId,
 801                          unsigned int *numberOfMbufsPtr);
 802
 803 /**
 804  *
 805  * @ingroup IxAtmdAccAPI
 806  *
 807  * @fn ixAtmdAccRxVcEnable (IxAtmConnId connId)
 808  *
 809  * @brief Start the RX service on a VC.
 810  *
 811  * This functions kicks-off the traffic reception for a particular VC.
 812  * Once invoked, incoming PDUs will be made available by the hardware
 813  * and are eventually directed to the @a IxAtmdAccRxVcRxCallback() callback
 814  * registered for the connection.
 815  *
 816  * If the traffic is already running, this function returns IX_SUCCESS.
 817  * This function can be invoked many times.
 818  *
 819  * IxAtmdAccRxVcFreeLowCallback event will occur only after
 820  * @a ixAtmdAccRxVcEnable() function is invoked.
 821  *
 822  * Before using this function, the @a ixAtmdAccRxVcFreeReplenish() function
 823  * has to be used to replenish the RX Free queue. If not, incoming traffic
 824  * may be discarded.and in the case of interrupt driven reception the
 825  * @a IxAtmdAccRxVcFreeLowCallback() callback may be invoked as a side effect
 826  * during a replenish action.
 827  *
 828  * This function is not reentrant and should not be used inside an
 829  * interrupt context.
 830  *
 831  * For an VC connection this function can be called after a call to
 832  * @a ixAtmdAccRxVcDisable() and should not be called after
 833  * @a ixAtmdAccRxVcTryDisconnect()
 834  *
 835  * @sa ixAtmdAccRxVcDisable
 836  * @sa ixAtmdAccRxVcConnect
 837  * @sa ixAtmdAccRxVcFreeReplenish
 838  *
 839  * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call
 840  * to @a IxAtmdAccRxVcConnect()
 841  *
 842  * @return @li IX_SUCCESS successful call to ixAtmdAccRxVcEnable
 843  * @return @li IX_ATMDACC_WARNING the channel is already enabled
 844  * @return @li IX_FAIL invalid parameters or some unspecified internal
 845  *         error occured.
 846  *
 847  */
 848 PUBLIC IX_STATUS ixAtmdAccRxVcEnable (IxAtmConnId connId);
 849
 850 /**
 851  *
 852  * @ingroup IxAtmdAccAPI
 853  *
 854  * @fn ixAtmdAccRxVcDisable (IxAtmConnId connId)
 855  *
 856  * @brief Stop the RX service on a VC.
 857  *
 858  * This functions stops the traffic reception for a particular VC connection.
 859  *
 860  * Once invoked, incoming Pdus are discarded by the hardware. Any Pdus
 861  * pending will be freed to the user
 862  *
 863  * Hence once this function returns no more receive callbacks will be
 864  * called for that VC. However, buffer free callbacks will be invoked
 865  * until such time as all buffers supplied by the user have been freed
 866  * back to the user
 867  *
 868  * Calling this function doe not invalidate the connId.
 869  * @a ixAtmdAccRxVcEnable() can be invoked to enable Pdu reception again.
 870  *
 871  * If the traffic is already stopped, this function returns IX_SUCCESS.
 872  *
 873  * This function is not reentrant and should not be used inside an
 874  * interrupt context.
 875  *
 876  * @sa ixAtmdAccRxVcConnect
 877  * @sa ixAtmdAccRxVcEnable
 878  * @sa ixAtmdAccRxVcDisable
 879  *
 880  * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call to @a
 881  *     IxAtmdAccRxVcConnect()
 882  *
 883  * @return @li IX_SUCCESS successful call to @a ixAtmdAccRxVcDisable().
 884  * @return @li IX_ATMDACC_WARNING the channel is already disabled
 885  * @return @li IX_FAIL invalid parameters or some unspecified internal error occured
 886  *
 887  */
 888 PUBLIC IX_STATUS ixAtmdAccRxVcDisable (IxAtmConnId connId);
 889
 890 /**
 891  *
 892  * @ingroup IxAtmdAccAPI
 893  *
 894  * @fn ixAtmdAccRxVcTryDisconnect (IxAtmConnId connId)
 895  *
 896  * @brief Disconnect a VC from the RX service.
 897  *
 898  * This function deregisters the VC and guarantees that all resources
 899  * associated with this VC are free. After its execution, the connection
 900  * Id is not available.
 901  *
 902  * This function will fail until such time as all resources allocated to
 903  * the VC connection have been freed. The user is responsible to delay and
 904  * call again this function many times until a success status is returned.
 905  *
 906  * This function needs internal locks and should not be called from an
 907  * interrupt context
 908  *
 909  * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call to
 910  * @a IxAtmdAccRxVcConnect()
 911  *
 912  * @return @li IX_SUCCESS successful call to ixAtmdAccRxVcDisable
 913  * @return @li IX_ATMDACC_RESOURCES_STILL_ALLOCATED not all resources
 914  *         associated with the connection have been freed.
 915  * @return @li IX_FAIL cannot process this request because of a parameter
 916  *         error
 917  *
 918  */
 919 PUBLIC IX_STATUS ixAtmdAccRxVcTryDisconnect (IxAtmConnId connId);
 920
 921 /* ------------------------------------------------------
 922    Part of the IxAtmdAcc interface related to TX traffic
 923    ------------------------------------------------------ */
 924
 925 /**
 926  *
 927  * @ingroup IxAtmdAccAPI
 928  *
 929  * @fn ixAtmdAccTxVcConnect (IxAtmLogicalPort port,
 930                       unsigned int vpi,
 931                       unsigned int vci,
 932                       IxAtmdAccAalType aalServiceType,
 933                       IxAtmdAccUserId userId,
 934                       IxAtmdAccTxVcBufferReturnCallback bufferFreeCallback,
 935                       IxAtmConnId * connIdPtr)
 936  *
 937  * @brief Connect to a Aal Pdu transmit service for a particular
 938  *        port/vpi/vci and service type.
 939  *
 940  * This function allows a user to connect to an Aal5/Aal0/OAM Pdu transmit service
 941  * for a particular port/vpi/vci. It registers the callback and allocates
 942  * internal resources and a Connection Id to be used in further API calls
 943  * related to this VC.
 944  *
 945  * The function will setup VC transmit service on the specified on the
 946  * specified port. A connId is the reference by which IxAtmdAcc refers to a
 947  * connected VC. This identifier is the result of a succesful call
 948  * to a connect function. This identifier is invalid after a
 949  * sucessful call to a disconnect function.
 950  *
 951  * This function needs internal locks, and hence  should not be called
 952  * from an interrupt context.
 953  *
 954  * On return from @a ixAtmdAccTxVcConnect() with a failure status, the
 955  * connection Id parameter is unspecified. Its value cannot be used.
 956  *
 957  * Calling this function for the same combination of port, Vpi, Vci and
 958  * more than once without calling @a ixAtmdAccTxVcTryDisconnect() will result
 959  * in a failure status.
 960  *
 961  * Two AAL0 services supporting 48 or 52 byte cell data are provided.
 962  * Submitted AAL0 PDUs must be a multiple of the cell data size (48/52).
 963  * AAL0_52 is a raw cell service the client must format
 964  * the PDU with an ATM cell header (excluding HEC) at the start of
 965  * each cell, note that AtmdAcc does not validate the cell headers in
 966  * a submitted PDU.
 967  *
 968  * For the OAM service an "OAM Tx channel" may be enabled for a port
 969  * by establishing a single dedicated OAM Tx connection on that port.
 970  *
 971  * The OAM service allows buffers containing 52 byte OAM F4/F5 cells
 972  * to be transmitted and received over the dedicated OAM channels.
 973  * HEC is appended/removed, and CRC-10 performed by the NPE. The OAM
 974  * service offered by AtmdAcc is a raw cell transport service.
 975  * It is assumed that ITU I.610 procedures that make use of this
 976  * service are implemented above AtmdAcc.
 977  *
 978  * Note that the dedicated OAM connections are established on
 979  * reserved VPI,VCI, and (in the case of Rx) port values.
 980  * These values are used purely to descriminate the dedicated OAM channels
 981  * and do not identify a particular OAM F4/F5 flow. F4/F5 flows may be
 982  * realised for particluar VPI/VCIs by manipulating the VPI,VCI
 983  * fields of the ATM cell headers of cells in the buffers passed
 984  * to AtmdAcc.
 985  *
 986  * Calling this function before enabling the port will fail.
 987  *
 988  * @sa ixAtmdAccTxVcTryDisconnect
 989  * @sa ixAtmdAccPortTxScheduledModeEnable
 990  * @sa ixAtmdAccPortEnable
 991  *
 992  * @param port @ref IxAtmLogicalPort [in] - VC identification : logical PHY port
 993  *                  [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 994  * @param vpi unsigned int  [in] - VC identification : ATM Vpi [0..255] or IX_ATMDACC_OAM_VPI
 995  * @param vci unsigned int [in] - VC identification : ATM Vci [0..65535] or IX_ATMDACC_OAM_VCI
 996  * @param aalServiceType @ref IxAtmdAccAalType [in] - type of service AAL5, AAL0_48, AAL0_52, or OAM
 997  * @param userId @ref IxAtmdAccUserId [in] - user id to be used later during callbacks related
 998  *        to this channel
 999  * @param bufferFreeCallback @ref IxAtmdAccTxVcBufferReturnCallback [in] - function called when mbufs
1000  *        transmission is complete. This parameter cannot be a null
1001  *        pointer.
1002  * @param connIdPtr @ref IxAtmConnId [out] - Pointer to a connection Id.
1003  *        This parameter cannot be a null pointer.
1004  *
1005  * @return @li IX_SUCCESS successful call to @a IxAtmdAccRxVcConnect().
1006  * @return @li IX_ATMDACC_BUSY cannot process this request
1007  *         because no VC is available
1008  * @return @li IX_FAIL
1009  *             parameter error,
1010  *             VC already in use,
1011  *             attempt to connect AAL service on reserved OAM VPI/VCI,
1012  *             attempt to connect OAM service on VPI/VCI other than the reserved OAM VPI/VCI,
1013  *             port is not initialised,
1014  *             or some other error occurs during processing.
1015  *
1016  * @note - Unscheduled mode is not supported in ixp425 1.0. Therefore, the
1017  *       function @a ixAtmdAccPortTxScheduledModeEnable() need to be called
1018  *       for this port before any establishing a Tx Connection
1019  */
1020 PUBLIC IX_STATUS ixAtmdAccTxVcConnect (IxAtmLogicalPort port,
1021                       unsigned int vpi,
1022                       unsigned int vci,
1023                       IxAtmdAccAalType aalServiceType,
1024                       IxAtmdAccUserId userId,
1025                       IxAtmdAccTxVcBufferReturnCallback bufferFreeCallback,
1026                       IxAtmConnId * connIdPtr);
1027
1028 /**
1029  *
1030  * @ingroup IxAtmdAccAPI
1031  *
1032  * @fn ixAtmdAccTxVcPduSubmit (IxAtmConnId connId,
1033                     IX_OSAL_MBUF * mbufPtr,
1034                     IxAtmdAccClpStatus clp,
1035                     unsigned int numberOfCells)
1036  *
1037  * @brief Submit a Pdu for transmission on connection.
1038  *
1039  * A data user calls this function to submit an mbufs containing a Pdu
1040  * to be transmitted. The buffer supplied can be chained and the Pdu it
1041  * contains must be complete.
1042  *
1043  * The transmission behavior of this call depends on the operational mode
1044  * of the port on which the connection is made.
1045  *
1046  * In unscheduled mode the mbuf will be submitted to the hardware
1047  * immediately if sufficent resource is available. Otherwise the function
1048  * will return failure.
1049  *
1050  * In scheduled mode the buffer is queued internally in IxAtmdAcc. The cell
1051  * demand is made known to the traffic shaping entity. Cells from the
1052  * buffers are MUXed onto the port some time later as dictated by the
1053  * traffic shaping entity. The traffic shaping entity does this by sending
1054  * transmit schedules to IxAtmdAcc via @a ixAtmdAccPortTxProcess() function call.
1055  *
1056  * Note that the dedicated OAM channel is scheduled just like any
1057  * other channel. This means that any OAM traffic relating to an
1058  * active AAL0/AAL5 connection will be scheduled independantly of the
1059  * AAL0/AAL5 traffic for that connection.
1060  *
1061  * When transmission is complete, the TX Done mechanism will give the
1062  * owmnership of these buffers back to the customer. The tx done mechanism
1063  * must be in operation before transmission is attempted.
1064  *
1065  * For AAL0/OAM submitted AAL0 PDUs must be a multiple of the cell data
1066  * size (48/52). AAL0_52 and OAM are raw cell services, and the client
1067  * must format the PDU with an ATM cell header (excluding HEC) at the
1068  * start of each cell, note that AtmdAcc does not validate the cell headers in
1069  * a submitted PDU.
1070  *
1071  *
1072  * @sa IxAtmdAccTxVcBufferReturnCallback
1073  * @sa ixAtmdAccTxDoneDispatch
1074  *
1075  * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call to
1076  *        @a ixAtmdAccTxVcConnect()
1077  * @param mbufPtr @ref IX_OSAL_MBUF [in] - pointer to a chained structure of mbufs to transmit.
1078  *       This parameter cannot be a null pointer.
1079  * @param clp @ref IxAtmdAccClpStatus [in] - clp indication for this PDU. All cells of this pdu
1080  *       will be sent with the clp bit set
1081  * @param numberOfCells unsigned int [in] - number of cells in the PDU.
1082  *
1083  * @return @li IX_SUCCESS successful call to @a ixAtmdAccTxVcPduSubmit()
1084  *             The pdu pointed by the mbufPtr parameter will be
1085  *             transmitted
1086  * @return @li IX_ATMDACC_BUSY unable to process this request because
1087  *             internal resources are all used. The caller is responsible
1088  *             for retrying this request later.
1089  * @return @li IX_FAIL unable to process this request because of error
1090  *             in the parameters (wrong connId supplied,
1091  *             or wrong mbuf pointer supplied), the total length of all buffers
1092  *             in the chain should be a multiple of the cell size
1093  *             ( 48/52 depending on the service type ),
1094  *             or unspecified error during processing
1095  *
1096  * @note - This function in not re-entrant for the same VC (e.g. : two
1097  *         thread cannot send PDUs for the same VC). But two threads can
1098  *         safely call this function with a different connection Id
1099  *
1100  * @note - In unscheduled mode, this function is not re-entrant on a per
1101  *         port basis. The size of pdus is limited to 8Kb.
1102  *
1103  * @note - 0-length mbufs should be removed from the chain before submission.
1104  *         The total length of the pdu (sdu + padding +trailer) has to be
1105  *         updated in the header of the first mbuf of a chain of mbufs.
1106  *
1107  * @note - Aal5 trailer information (UUI, CPI, SDU length) has to be supplied
1108  *         before submission.
1109  *
1110  * @note - The payload memory cache should be flushed, if needed, prior to
1111  *         transmission. Mbuf headers are flushed by IxAtmdAcc
1112  *
1113  * @note - This function does not use system resources and can be used
1114  *         inside an interrupt context
1115  */
1116 PUBLIC IX_STATUS ixAtmdAccTxVcPduSubmit (IxAtmConnId connId,
1117                     IX_OSAL_MBUF * mbufPtr,
1118                     IxAtmdAccClpStatus clp,
1119                     unsigned int numberOfCells);
1120
1121 /**
1122  *
1123  * @ingroup IxAtmdAccAPI
1124  *
1125  * @fn ixAtmdAccTxVcTryDisconnect (IxAtmConnId connId)
1126  *
1127  * @brief Disconnect from a Aal Pdu transmit service for a particular
1128  *        port/vpi/vci.
1129  *
1130  * This function deregisters the VC and guarantees that all resources
1131  * associated with this VC are free. After its execution, the connection
1132  * Id is not available.
1133  *
1134  * This function will fail until such time as all resources allocated to
1135  * the VC connection have been freed. The user is responsible to delay
1136  * and call again this function many times until a success status is
1137  * returned.
1138  *
1139  * After its execution, the connection Id is not available.
1140  *
1141  * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call to
1142  *        @a ixAtmdAccTxVcConnect()
1143  *
1144  * @return @li IX_SUCCESS successful call to @a ixAtmdAccTxVcTryDisconnect()
1145  * @return @li IX_ATMDACC_RESOURCES_STILL_ALLOCATED not all resources
1146  *     associated with the connection have been freed. This condition will
1147  *     disappear after Tx and TxDone is complete for this channel.
1148  * @return @li IX_FAIL unable to process this request because of errors
1149  *                     in the parameters (wrong connId supplied)
1150  *
1151  * @note - This function needs internal locks and should not be called
1152  *         from an interrupt context
1153  *
1154  * @note - If the @a IX_ATMDACC_RESOURCES_STILL_ALLOCATED error does not
1155  *     clear after a while, this may be linked to a previous problem
1156  *     of cell overscheduling. Diabling the port and retry a disconnect
1157  *     will free the resources associated with this channel.
1158  *
1159  * @sa ixAtmdAccPortTxProcess
1160  *
1161  */
1162 PUBLIC IX_STATUS ixAtmdAccTxVcTryDisconnect (IxAtmConnId connId);
1163
1164 #endif /* IXATMDACC_H */
1165
1166 /**
1167  * @} defgroup IxAtmdAccAPI
1168  */
1169
1170