summaryrefslogtreecommitdiff
path: root/cpu/ixp/npe/include/IxAtmSch.h
diff options
context:
space:
mode:
Diffstat (limited to 'cpu/ixp/npe/include/IxAtmSch.h')
-rw-r--r--cpu/ixp/npe/include/IxAtmSch.h504
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 */
+
+/** @} */