ixatmsch.h

AMCC POWERPC 44X系列的U-BOOT文件

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

/** @} */