ixatmsch.h

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

/**
 * @file    IxAtmSch.h
 *
 * @date    23-NOV-2001
 *
 * @brief   Header file for the IXP400 ATM Traffic Shaper
 *
 * This component demonstrates an ATM Traffic Shaper implementation. It
 * will perform shaping on upto 12 ports and total of 44 VCs accross all ports,
 * 32 are intended for AAL0/5 and 12 for OAM (1 per port).
 * The supported traffic types are;1 rt-VBR VC where PCR = SCR.
 * (Effectively CBR) and Up-to 44 VBR VCs.
 *
 * This component models the ATM ports and VCs and is capable of producing
 * a schedule of ATM cells per port which can be supplied to IxAtmdAcc
 * for execution on the data path.
 * 
 * @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 --
 *
 * @sa IxAtmm.h
 *
 */

/**
 * @defgroup IxAtmSch IXP400 ATM Transmit Scheduler (IxAtmSch) API
 *
 * @brief IXP400 ATM scheduler component Public API
 *
 * @{
 */

#ifndef IXATMSCH_H
#define IXATMSCH_H

#include "IxOsalTypes.h"
#include "IxAtmTypes.h"

/*
 * #defines and macros used in this file.
 */

/* Return codes */

/** 
 * @ingroup IxAtmSch
 *
 * @def IX_ATMSCH_RET_NOT_ADMITTED
 * @brief Indicates that CAC function has rejected VC registration due
 *         to insufficient line capacity.
*/
#define IX_ATMSCH_RET_NOT_ADMITTED 2

/**  
 * @ingroup IxAtmSch
 *
 * @def IX_ATMSCH_RET_QUEUE_FULL
 *  @brief Indicates that the VC queue is full, no more demand can be
 *         queued at this time.
 */
#define IX_ATMSCH_RET_QUEUE_FULL 3

/**  
 * @ingroup IxAtmSch
 *
 *  @def IX_ATMSCH_RET_QUEUE_EMPTY
 *  @brief Indicates that all VC queues on this port are empty and
 *         therefore there are no cells to be scheduled at this time.
 */
#define IX_ATMSCH_RET_QUEUE_EMPTY 4

/*
 * Function declarations
 */

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchInit(void)
 *
 *  @brief This function is used to initialize the ixAtmSch component. It
 *         should be called before any other IxAtmSch API function.
 *
 * @param None
 *
 * @return
 * - <b>IX_SUCCESS :</b> indicates that
 *          -# The ATM scheduler component has been successfully initialized.
 *          -# The scheduler is ready to accept Port modelling requests.
 * - <b>IX_FAIL :</b> Some internal error has prevented the scheduler component
 *          from initialising.
 */
PUBLIC IX_STATUS
ixAtmSchInit(void);

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchPortModelInitialize( IxAtmLogicalPort port,
                                       unsigned int portRate,
                                       unsigned int minCellsToSchedule)
 *
 * @brief This function shall be called first to initialize an ATM port before
 *         any other ixAtmSch API calls may be made for that port.
 *
 * @param port @ref IxAtmLogicalPort [in] - The specific port to initialize.  Valid
 *          values range from 0 to IX_UTOPIA_MAX_PORTS - 1, representing a 
 *          maximum of IX_UTOPIA_MAX_PORTS possible ports.
 *
 * @param portRate unsigned int [in] - Value indicating the upstream capacity
 *          of the indicated port.  The value should be supplied in
 *          units of ATM (53 bytes) cells per second.
 *          A port rate of 800Kbits/s is the equivalent 
 *          of 1886 cells per second
 *
 * @param minCellsToSchedule unsigned int [in] - This parameter specifies the minimum
 *          number of cells which the scheduler will put in a schedule
 *          table for this port. This value sets the worst case CDVT for VCs
 *          on this port i.e. CDVT = 1*minCellsToSchedule/portRate.
 * @return
 *    - <b>IX_SUCCESS :</b> indicates that
 *          -# The ATM scheduler has been successfully initialized.
 *          -# The requested port model has been established.
 *          -# The scheduler is ready to accept VC modelling requests
 *            on the ATM port.
 *    - <b>IX_FAIL :</b> indicates the requested port could not be
 * initialized.  */
PUBLIC IX_STATUS
ixAtmSchPortModelInitialize( IxAtmLogicalPort port,
                                       unsigned int portRate,
                                       unsigned int minCellsToSchedule);

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchPortRateModify( IxAtmLogicalPort port,
                        unsigned int portRate)
 *
 *  @brief This function is called to modify the portRate on a
 *         previously initialized port, typically in the event that
 *         the line condition of the port changes.
 *
 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port which is to be
 *          modified.
 *
 * @param portRate unsigned int [in] - Value indicating the new upstream
 *          capacity for this port in cells/second.
 *          A port rate of 800Kbits/s is the equivalent 
 *          of 1886 cells per second
 *
 * @return
 * - <b>IX_SUCCESS :</b> The port rate has been successfully modified.<br>
 * - <b>IX_FAIL :</b> The port rate could not be modified, either
 *      because the input data was invalid, or the new port rate is
 *      insufficient to support established ATM VC contracts on this
 *      port.
 *
 * @warning The IxAtmSch component will validate the supplied port
 *          rate is sufficient to support all established VC
 *          contracts on the port.  If the new port rate is
 *          insufficient to support all established contracts then
 *          the request to modify the port rate will be rejected.
 *          In this event, the user is expected to remove
 *          established contracts using the ixAtmSchVcModelRemove
 *          interface and then retry this interface.
 *
 * @sa ixAtmSchVcModelRemove() */
PUBLIC IX_STATUS
ixAtmSchPortRateModify( IxAtmLogicalPort port,
                        unsigned int portRate);


/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchVcModelSetup( IxAtmLogicalPort port,
                      IxAtmTrafficDescriptor *trafficDesc,
                      IxAtmSchedulerVcId *vcId)
 *
 *  @brief A client calls this interface to set up an upstream
 *         (transmitting) virtual connection model (VC) on the
 *         specified ATM port.  This function also provides the
 *         virtual * connection admission control (CAC) service to the
 *         client.
 *
 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the upstream
 *          VC is to be established.
 *
 * @param *trafficDesc @ref IxAtmTrafficDescriptor [in] - Pointer to a structure
 *          describing the requested traffic contract of the VC to be
 *          established.  This structure contains the typical ATM
 *          traffic descriptor values (e.g. PCR, SCR, MBS, CDVT, etc.)
 *          defined by the ATM standard.
 *
 * @param *vcId @ref IxAtmSchedulerVcId [out] - This value will be filled with the
 *              port-unique identifier for this virtual connection.  A
 *              valid identification is a non-negative number.
 *
 * @return
 * - <b>IX_SUCCESS :</b> The VC has been successfully established on
 *      this port.  The client may begin to submit demand on this VC.
 * - <b>IX_ATMSCH_RET_NOT_ADMITTED :</b> The VC cannot be established
 *      on this port because there is insufficient upstream capacity
 *      available to support the requested traffic contract descriptor
 * - <b>IX_FAIL :</b>Input data are invalid.  VC has not been
 *      established.
 */
PUBLIC IX_STATUS
ixAtmSchVcModelSetup( IxAtmLogicalPort port,
                      IxAtmTrafficDescriptor *trafficDesc,
                      IxAtmSchedulerVcId *vcId);

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchVcConnIdSet( IxAtmLogicalPort port,
                     IxAtmSchedulerVcId vcId,
                     IxAtmConnId vcUserConnId)