ixatmdaccctrl.h

AMCC POWERPC 44X系列的U-BOOT文件

/**
 * @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);