diff options
Diffstat (limited to 'cpu/ixp/npe/include/IxAtmSch.h')
| -rw-r--r-- | cpu/ixp/npe/include/IxAtmSch.h | 504 |
1 files changed, 504 insertions, 0 deletions
diff --git a/cpu/ixp/npe/include/IxAtmSch.h b/cpu/ixp/npe/include/IxAtmSch.h new file mode 100644 index 0000000000..73c3be29ab --- /dev/null +++ b/cpu/ixp/npe/include/IxAtmSch.h @@ -0,0 +1,504 @@ +/** + * @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 */ + +/** @} */ |