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

/** @} */