mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-12-01 08:59:33 +00:00
504 lines
19 KiB
C
504 lines
19 KiB
C
/**
|
|
* @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)
|
|
*
|
|
* @brief A client calls this interface to set the vcUserConnId for a VC on
|
|
* the specified ATM port. This vcUserConnId will default to
|
|
* IX_ATM_IDLE_CELLS_CONNID if this function is not called for a VC.
|
|
* Hence if the client does not call this function for a VC then only idle
|
|
* cells will be scheduled for this VC.
|
|
*
|
|
* @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the upstream
|
|
* VC is has been established.
|
|
*
|
|
* @param vcId @ref IxAtmSchedulerVcId [in] - This is the unique identifier for this virtual
|
|
* connection. A valid identification is a non-negative number and is
|
|
* all ports.
|
|
*
|
|
* @param vcUserConnId @ref IxAtmConnId [in] - The connId is used to refer to a VC in schedule
|
|
* table entries. It is treated as the Id by which the scheduler client
|
|
* knows the VC. It is used in any communicatations from the Scheduler
|
|
* to the scheduler user e.g. schedule table entries.
|
|
*
|
|
* @return
|
|
* - <b>IX_SUCCESS :</b> The id has successfully been set.
|
|
* - <b>IX_FAIL :</b>Input data are invalid. connId id is not established.
|
|
*/
|
|
PUBLIC IX_STATUS
|
|
ixAtmSchVcConnIdSet( IxAtmLogicalPort port,
|
|
IxAtmSchedulerVcId vcId,
|
|
IxAtmConnId vcUserConnId);
|
|
|
|
/**
|
|
* @ingroup IxAtmSch
|
|
*
|
|
* @fn ixAtmSchVcModelRemove( IxAtmLogicalPort port,
|
|
IxAtmSchedulerVcId vcId)
|
|
*
|
|
* @brief Interface called by the client to remove a previously
|
|
* established VC on a particular port.
|
|
*
|
|
* @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
|
|
* removed is established.
|
|
*
|
|
* @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be removed. This is the
|
|
* value returned by the @ref ixAtmSchVcModelSetup call which
|
|
* established the relevant VC.
|
|
*
|
|
* @return
|
|
* - <b>IX_SUCCESS :</b> The VC has been successfully removed from
|
|
* this port. It is no longer modelled on this port.
|
|
* - <b>IX_FAIL :</b>Input data are invalid. The VC is still being modeled
|
|
* by the traffic shaper.
|
|
*
|
|
* @sa ixAtmSchVcModelSetup()
|
|
*/
|
|
PUBLIC IX_STATUS
|
|
ixAtmSchVcModelRemove( IxAtmLogicalPort port,
|
|
IxAtmSchedulerVcId vcId);
|
|
|
|
/**
|
|
* @ingroup IxAtmSch
|
|
*
|
|
* @fn ixAtmSchVcQueueUpdate( IxAtmLogicalPort port,
|
|
IxAtmSchedulerVcId vcId,
|
|
unsigned int numberOfCells)
|
|
*
|
|
* @brief The client calls this function to notify IxAtmSch that the
|
|
* user of a VC has submitted cells for transmission.
|
|
*
|
|
* This information is stored, aggregated from a number of calls to
|
|
* ixAtmSchVcQueueUpdate and eventually used in the call to
|
|
* ixAtmSchTableUpdate.
|
|
*
|
|
* Normally IxAtmSch will update the VC queue by adding the number of
|
|
* cells to the current queue length. However, if IxAtmSch
|
|
* determines that the user has over-submitted for the VC and
|
|
* exceeded its transmission quota the queue request can be rejected.
|
|
* The user should resubmit the request later when the queue has been
|
|
* depleted.
|
|
*
|
|
* This implementation of ixAtmSchVcQueueUpdate uses no operating
|
|
* system or external facilities, either directly or indirectly.
|
|
* This allows clients to call this function form within an interrupt handler.
|
|
*
|
|
* This interface is structurally compatible with the
|
|
* IxAtmdAccSchQueueUpdate callback type definition required for
|
|
* IXP400 ATM scheduler interoperability.
|
|
*
|
|
* @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
|
|
* updated is established.
|
|
*
|
|
* @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be updated. This is the
|
|
* value returned by the @ref ixAtmSchVcModelSetup call which
|
|
* established the relevant VC.
|
|
*
|
|
* @param numberOfCells unsigned int [in] - Indicates how many ATM cells should
|
|
* be added to the queue for this VC.
|
|
*
|
|
* @return
|
|
* - <b>IX_SUCCESS :</b> The VC queue has been successfully updated.
|
|
* - <b>IX_ATMSCH_RET_QUEUE_FULL :</b> The VC queue has reached a
|
|
* preset limit. This indicates the client has over-submitted
|
|
* and exceeded its transmission quota. The request is
|
|
* rejected. The VC queue is not updated. The VC user is
|
|
* advised to resubmit the request later.
|
|
* - <b>IX_FAIL :</b> The input are invalid. No VC queue is updated.
|
|
*
|
|
* @warning IxAtmSch assumes that the calling software ensures that
|
|
* calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
|
|
* ixAtmSchTableUpdate are both self and mutually exclusive
|
|
* for the same port.
|
|
*
|
|
* @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate(). */
|
|
PUBLIC IX_STATUS
|
|
ixAtmSchVcQueueUpdate( IxAtmLogicalPort port,
|
|
IxAtmSchedulerVcId vcId,
|
|
unsigned int numberOfCells);
|
|
|
|
/**
|
|
* @ingroup IxAtmSch
|
|
*
|
|
* @fn ixAtmSchVcQueueClear( IxAtmLogicalPort port,
|
|
IxAtmSchedulerVcId vcId)
|
|
*
|
|
* @brief The client calls this function to remove all currently
|
|
* queued cells from a registered VC. The pending cell count
|
|
* for the specified VC is reset to zero.
|
|
*
|
|
* This interface is structurally compatible with the
|
|
* IxAtmdAccSchQueueClear callback type definition required for
|
|
* IXP400 ATM scheduler interoperability.
|
|
*
|
|
* @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
|
|
* cleared is established.
|
|
*
|
|
* @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be cleared. This is the
|
|
* value returned by the @ref ixAtmSchVcModelSetup call which
|
|
* established the relevant VC.
|
|
*
|
|
* @return
|
|
* - <b>IX_SUCCESS :</b> The VC queue has been successfully cleared.
|
|
* - <b>IX_FAIL :</b> The input are invalid. No VC queue is modified.
|
|
*
|
|
* @warning IxAtmSch assumes that the calling software ensures that
|
|
* calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
|
|
* ixAtmSchTableUpdate are both self and mutually exclusive
|
|
* for the same port.
|
|
*
|
|
* @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate(). */
|
|
PUBLIC IX_STATUS
|
|
ixAtmSchVcQueueClear( IxAtmLogicalPort port,
|
|
IxAtmSchedulerVcId vcId);
|
|
|
|
/**
|
|
* @ingroup IxAtmSch
|
|
*
|
|
* @fn ixAtmSchTableUpdate( IxAtmLogicalPort port,
|
|
unsigned int maxCells,
|
|
IxAtmScheduleTable **rettable)
|
|
*
|
|
* @brief The client calls this function to request an update of the
|
|
* schedule table for a particular ATM port.
|
|
*
|
|
* This is called when the client decides it needs a new sequence of
|
|
* cells to send (probably because the transmit queue is near to
|
|
* empty for this ATM port). The scheduler will use its stored
|
|
* information on the cells submitted for transmit (i.e. data
|
|
* supplied via @ref ixAtmSchVcQueueUpdate function) with the traffic
|
|
* descriptor information of all established VCs on the ATM port to
|
|
* decide the sequence of cells to be sent and fill the schedule
|
|
* table for a period of time into the future.
|
|
*
|
|
* IxAtmSch will guarantee a minimum of minCellsToSchedule if there
|
|
* is at least one cell ready to send. If there are no cells then
|
|
* IX_ATMSCH_RET_QUEUE_EMPTY is returned.
|
|
*
|
|
* This implementation of ixAtmSchTableUpdate uses no operating
|
|
* system or external facilities, either directly or indirectly.
|
|
* This allows clients to call this function form within an FIQ
|
|
* interrupt handler.
|
|
*
|
|
* @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port for which requested
|
|
* schedule table is to be generated.
|
|
*
|
|
* @param maxCells unsigned [in] - Specifies the maximum number of cells
|
|
* that must be scheduled in the supplied table during any
|
|
* call to the interface.
|
|
*
|
|
* @param **table @ref IxAtmScheduleTable [out] - A pointer to an area of
|
|
* storage is returned which contains the generated
|
|
* schedule table. The client should not modify the
|
|
* contents of this table.
|
|
*
|
|
* @return
|
|
* - <b>IX_SUCCESS :</b> The schedule table has been published.
|
|
* Currently there is at least one VC queue that is nonempty.
|
|
* - <b>IX_ATMSCH_RET_QUEUE_EMPTY :</b> Currently all VC queues on
|
|
* this port are empty. The schedule table returned is set to
|
|
* NULL. The client is not expected to invoke this function
|
|
* again until more cells have been submitted on this port
|
|
* through the @ref ixAtmSchVcQueueUpdate function.
|
|
* - <b>IX_FAIL :</b> The input are invalid. No action is taken.
|
|
*
|
|
* @warning IxAtmSch assumes that the calling software ensures that
|
|
* calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
|
|
* ixAtmSchTableUpdate are both self and mutually exclusive
|
|
* for the same port.
|
|
*
|
|
* @warning Subsequent calls to this function for the same port will
|
|
* overwrite the contents of previously supplied schedule
|
|
* tables. The client must be completely finished with the
|
|
* previously supplied schedule table before calling this
|
|
* function again for the same port.
|
|
*
|
|
* @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate(). */
|
|
PUBLIC IX_STATUS
|
|
ixAtmSchTableUpdate( IxAtmLogicalPort port,
|
|
unsigned int maxCells,
|
|
IxAtmScheduleTable **rettable);
|
|
|
|
/**
|
|
* @ingroup IxAtmSch
|
|
*
|
|
* @fn ixAtmSchShow(void)
|
|
*
|
|
* @brief Utility function which will print statistics on the current
|
|
* and accumulated state of VCs and traffic in the ATM
|
|
* scheduler component. Output is sent to the default output
|
|
* device.
|
|
*
|
|
* @param none
|
|
* @return none
|
|
*/
|
|
PUBLIC void
|
|
ixAtmSchShow(void);
|
|
|
|
/**
|
|
* @ingroup IxAtmSch
|
|
*
|
|
* @fn ixAtmSchStatsClear(void)
|
|
*
|
|
* @brief Utility function which will reset all counter statistics in
|
|
* the ATM scheduler to zero.
|
|
*
|
|
* @param none
|
|
* @return none
|
|
*/
|
|
PUBLIC void
|
|
ixAtmSchStatsClear(void);
|
|
|
|
#endif
|
|
/* IXATMSCH_H */
|
|
|
|
/** @} */
|