/** * @file    IxAtmdAccCtrl.h * * @date    20-Mar-2002 * * @brief IxAtmdAcc Public API * * This file contains the public API of IxAtmdAcc, related to the * control functions of the component. * *  * @par * IXP400 SW Release version 2.0 *  * -- Copyright Notice -- *  * @par * Copyright 2001-2005, Intel Corporation. * All rights reserved. *  * @par * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright *    notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright *    notice, this list of conditions and the following disclaimer in the *    documentation and/or other materials provided with the distribution. * 3. Neither the name of the Intel Corporation nor the names of its contributors *    may be used to endorse or promote products derived from this software *    without specific prior written permission. *  * @par * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. *  * @par * -- End of Copyright Notice -- *//* ------------------------------------------------------   Doxygen group definitions   ------------------------------------------------------ *//** * * @defgroup IxAtmdAccCtrlAPI IXP400 ATM Driver Access (IxAtmdAcc) Control API * * @brief The public API for the IXP400 Atm Driver Control component * * IxAtmdAcc is the low level interface by which AAL PDU get transmitted * to,and received from the Utopia bus * * This part is related to the Control configuration * * @{ */#ifndef IXATMDACCCTRL_H#define IXATMDACCCTRL_H#include "IxAtmdAcc.h"/* ------------------------------------------------------   AtmdAccCtrl Data Types definition   ------------------------------------------------------ *//**** @ingroup IxAtmdAccCtrlAPI** @def IX_ATMDACC_PORT_DISABLE_IN_PROGRESS** @brief Port enable return code** This constant is used to tell IxAtmDAcc user that the port disable* functions are not complete. The user can call ixAtmdAccPortDisableComplete()* to find out when the disable has finished. The port enable can then proceed.**/#define IX_ATMDACC_PORT_DISABLE_IN_PROGRESS 5/**** @ingroup IxAtmdAccCtrlAPI** @def IX_ATMDACC_ALLPDUS** @brief All PDUs** This constant is used to tell IxAtmDAcc to process all PDUs from* the RX queue or the TX Done** @sa IxAtmdAccRxDispatcher* @sa IxAtmdAccTxDoneDispatcher**/#define IX_ATMDACC_ALLPDUS 0xffffffff/* ------------------------------------------------------   Part of the IxAtmdAcc interface related to RX traffic   ------------------------------------------------------ *//** * * @ingroup IxAtmdAccCtrlAPI * * @brief Callback prototype for notification of available PDUs for * an Rx Q. * * This a protoype for a function which is called when there is at * least one Pdu available for processing on a particular Rx Q. * * This function should call @a ixAtmdAccRxDispatch() with * the aprropriate number of parameters to read and process the Rx Q. * * @sa ixAtmdAccRxDispatch * @sa ixAtmdAccRxVcConnect * @sa ixAtmdAccRxDispatcherRegister * * @param rxQueueId @ref IxAtmRxQueueId [in] indicates which RX queue to has Pdus to process. * @param numberOfPdusToProcess unsigned int [in] indicates the minimum number of *        PDUs available to process all PDUs from the queue. * @param reservedPtr unsigned int* [out] pointer to a int location which can *        be written to, but does not retain written values. This is *        provided to make this prototype compatible *        with @a ixAtmdAccRxDispatch() * * @return @li int - ignored. * */typedef IX_STATUS (*IxAtmdAccRxDispatcher) (IxAtmRxQueueId rxQueueId,                         unsigned int numberOfPdusToProcess,                         unsigned int *reservedPtr);/* ------------------------------------------------------   Part of the IxAtmdAcc interface related to TX traffic   ------------------------------------------------------ *//** * * @ingroup IxAtmdAccCtrlAPI * * @brief Callback prototype for transmitted mbuf when threshold level is *        crossed. * * IxAtmdAccTxDoneDispatcher is the prototype of the user function * which get called when pdus are completely transmitted. This function * is likely to call the @a ixAtmdAccTxDoneDispatch() function. * * This function is called when the number of available pdus for * reception is crossing the threshold level as defined * in @a ixAtmdAccTxDoneDispatcherRegister() * * This function is called inside an Qmgr dispatch context. No system * resource or interrupt-unsafe feature should be used inside this * callback. * * Transmitted buffers recycling implementation is a sytem-wide mechanism * and needs to be set before any traffic is started. If this threshold * mechanism is not used, the user is responsible for polling the * transmitted buffers with @a ixAtmdAccTxDoneDispatch() * and @a ixAtmdAccTxDoneLevelQuery() functions. * * @sa ixAtmdAccTxDoneDispatcherRegister * @sa ixAtmdAccTxDoneDispatch * @sa ixAtmdAccTxDoneLevelQuery * * @param numberOfPdusToProcess unsigned int [in] - The current number of pdus currently *        available for recycling * @param *reservedPtr unsigned int [out] - pointer to a int location which can be *        written to but does not retain written values. This is provided *        to make this prototype compatible *        with @a ixAtmdAccTxDoneDispatch() * * @return @li IX_SUCCESS This is provided to make *    this prototype compatible with @a ixAtmdAccTxDoneDispatch() * @return @li IX_FAIL invalid parameters or some unspecified internal *    error occured. This is provided to make *    this prototype compatible with @a ixAtmdAccTxDoneDispatch() * */typedef IX_STATUS (*IxAtmdAccTxDoneDispatcher) (unsigned int numberOfPdusToProcess,                                                unsigned int *reservedPtr);/**** @ingroup IxAtmdAccCtrlAPI** @brief Notification that the threshold number of scheduled cells* remains in a port's transmit Q.** The is the prototype for of the user notification function which* gets called on a per-port basis, when the number of remaining* scheduled cells to be transmitted decreases to the threshold level.* The number of cells passed as a parameter can be used for scheduling* purposes as the maximum number of cells that can be passed in a* schedule table to the @a ixAtmdAccPortTxProcess() function.** @sa ixAtmdAccPortTxCallbackRegister* @sa ixAtmdAccPortTxProcess* @sa ixAtmdAccPortTxFreeEntriesQuery** @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]* @param numberOfAvailableCells unsigned int [in] - number of available*        cell entries.for the port** @note - This functions shall not use system resources when used*         inside an interrupt context.**/typedef void (*IxAtmdAccPortTxLowCallback) (IxAtmLogicalPort port,                           unsigned int numberOfAvailableCells);/**** @ingroup IxAtmdAccCtrlAPI** @brief  Prototype to submit cells for transmission** IxAtmdAccTxVcDemandUpdateCallback is the prototype of the callback* function used by AtmD to notify an ATM Scheduler that the user of* a VC has submitted cells for transmission.** @sa IxAtmdAccTxVcDemandUpdateCallback* @sa IxAtmdAccTxVcDemandClearCallback* @sa IxAtmdAccTxSchVcIdGetCallback* @sa ixAtmdAccPortTxScheduledModeEnable** @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be updated*        is established* @param vcId int [in] - Identifies the VC to be updated. This is the value*        returned by the @a IxAtmdAccTxSchVcIdGetCallback() call .* @param numberOfCells unsigned int [in] - Indicates how many ATM cells should be added*        to the queue for this VC.** @return @li IX_SUCCESS the function is registering the cell demand for*        this VC.* @return @li IX_FAIL the function cannot register cell for this VC : the*         scheduler maybe overloaded or misconfigured**/typedef IX_STATUS (*IxAtmdAccTxVcDemandUpdateCallback) (IxAtmLogicalPort port,                        int vcId,                        unsigned int numberOfCells);/**** @ingroup IxAtmdAccCtrlAPI** @brief  prototype to  remove all currently queued cells from a* registered VC** IxAtmdAccTxVcDemandClearCallback is the prototype of the function* to remove all currently queued cells from a registered VC. The* pending cell count for the specified VC is reset to zero. After the* use of this callback, the scheduler shall not schedule more cells* for this VC.** This callback function is called during a VC disconnection* @a ixAtmdAccTxVcTryDisconnect()** @sa IxAtmdAccTxVcDemandUpdateCallback* @sa IxAtmdAccTxVcDemandClearCallback* @sa IxAtmdAccTxSchVcIdGetCallback* @sa ixAtmdAccPortTxScheduledModeEnable* @sa ixAtmdAccTxVcTryDisconnect** @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be cleared*        is established* @param vcId int [in] - Identifies the VC to be cleared. This is the value*        returned by the @a IxAtmdAccTxSchVcIdGetCallback() call .** @return none**/typedef void (*IxAtmdAccTxVcDemandClearCallback) (IxAtmLogicalPort port,                             int vcId);/**** @ingroup IxAtmdAccCtrlAPI** @brief  prototype to get a scheduler vc id** IxAtmdAccTxSchVcIdGetCallback is the prototype of the function to get* a scheduler vcId** @sa IxAtmdAccTxVcDemandUpdateCallback* @sa IxAtmdAccTxVcDemandClearCallback* @sa IxAtmdAccTxSchVcIdGetCallback* @sa ixAtmdAccPortTxScheduledModeEnable** @param port @ref IxAtmLogicalPort [in] - Specifies the ATM logical port on which the VC is*        established* @param vpi unsigned int [in] - For AAL0/AAL5 specifies the ATM vpi on which the *                 VC is established.*                 For OAM specifies the dedicated "OAM Tx channel" VPI.* @param vci unsigned int [in] - For AAL0/AAL5 specifies the ATM vci on which the *                 VC is established.*                 For OAM specifies the dedicated "OAM Tx channel" VCI.* @param connId @ref IxAtmConnId [in] - specifies the IxAtmdAcc connection Id already*        associated with this VC* @param vcId int* [out] - pointer to a vcId** @return @li IX_SUCCESS the function is returning a Scheduler vcId for this*         VC* @return @li IX_FAIL the function cannot process scheduling for this VC.*                 the contents of vcId is unspecified**/typedef IX_STATUS (*IxAtmdAccTxSchVcIdGetCallback) (IxAtmLogicalPort port,                               unsigned int vpi,                               unsigned int vci,                               IxAtmConnId connId,                               int *vcId);/* ------------------------------------------------------   Part of the IxAtmdAcc interface related to RX traffic   ------------------------------------------------------ *//** * * @ingroup IxAtmdAccCtrlAPI * * @fn ixAtmdAccRxDispatcherRegister (                          IxAtmRxQueueId queueId,                          IxAtmdAccRxDispatcher callback) * * @brief Register a notification callback to be invoked when there is * at least one entry on a particular Rx queue. * * This function registers a callback to be invoked when there is at * least one entry in a particular queue. The registered callback is * called every time when the hardware adds one or more pdus to the * specified Rx queue. * * This function cannot be used when a Rx Vc using this queue is * already existing. * * @note -The callback function can be the API function *       @a ixAtmdAccRxDispatch() : every time the threhold level *       of the queue is reached, the ixAtmdAccRxDispatch() is *       invoked to remove all entries from the queue. * * @sa ixAtmdAccRxDispatch * @sa IxAtmdAccRxDispatcher * * @param queueId @ref IxAtmRxQueueId [in] RX queue identification * @param callback @ref IxAtmdAccRxDispatcher [in] function triggering the delivery of incoming *        traffic. This parameter cannot be a null pointer. * * @return @li IX_SUCCESS Successful call to @a ixAtmdAccRxDispatcherRegister() * @return @li IX_FAIL error in the parameters, or there is an *             already active RX VC for this queue or some unspecified *             internal error occurred. * */PUBLIC IX_STATUS ixAtmdAccRxDispatcherRegister (                          IxAtmRxQueueId queueId,                          IxAtmdAccRxDispatcher callback);