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