/**
* @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 */
/** @} */