ixatmdaccctrl.h

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

/**
 *
 * @ingroup IxAtmdAccCtrlAPI
 *
 * @fn ixAtmdAccRxDispatch (IxAtmRxQueueId rxQueueId,
    unsigned int numberOfPdusToProcess,
    unsigned int *numberOfPdusProcessedPtr)
 *
 *
 * @brief Control function which executes Rx processing for a particular
 * Rx stream.
 *
 * The @a IxAtmdAccRxDispatch() function is used to process received Pdus
 * available from one of the two incoming RX streams. When this function
 * is invoked, the incoming traffic (up to the number of PDUs passed as
 * a parameter) will be transferred to the IxAtmdAcc users through the
 * callback @a IxAtmdAccRxVcRxCallback(), as registered during the
 * @a ixAtmdAccRxVcConnect() call.
 *
 * The user receive callbacks will be executed in the context of this
 * function.
 *
 * Failing to use this function on a regular basis when there is traffic
 * will block incoming traffic and can result in Pdus being dropped by
 * the hardware.
 *
 * This should be used to control when received pdus are handed off from
 * the hardware to Aal users from a particluar stream. The function can
 * be used from a timer context, or can be registered as a callback in
 * response to an rx stream threshold event, or can be used inside an
 * active polling mechanism which is under user control.
 *
 * @note - The signature of this function is directly compatible with the
 * callback prototype which can be register with @a ixAtmdAccRxDispatcherRegister().
 *
 * @sa ixAtmdAccRxDispatcherRegister
 * @sa IxAtmdAccRxVcRxCallback
 * @sa ixAtmdAccRxVcFreeEntriesQuery
 *
 * @param rxQueueId @ref IxAtmRxQueueId [in] - indicates which RX queue to process.
 * @param numberOfPdusToProcess unsigned int [in] - indicates the maxiumum number of PDU to
 *     remove from the RX queue. A value of IX_ATMDACC_ALLPDUS indicates
 *     to process all PDUs from the queue. This includes at least the PDUs
 *     in the queue when the fuction is invoked. Because of real-time
 *     constraints, there is no guarantee thatthe queue will be empty
 *     when the function exits. If this parameter is greater than the
 *     number of entries of the queues, the function will succeed
 *     and the parameter numberOfPdusProcessedPtr will reflect the exact
 *     number of PDUs processed.
 * @param *numberOfPdusProcessedPtr unsigned int [out] - indicates the actual number of PDU
 *     processed during this call. This parameter cannot be a null
 *     pointer.
 *
 * @return @li IX_SUCCESS the number of PDUs as indicated in
 *     numberOfPdusProcessedPtr are removed from the RX queue and the VC callback
 *     are called.
 * @return @li IX_FAIL invalid parameters or some unspecified internal
 *     error occured.
 *
 */
PUBLIC IX_STATUS ixAtmdAccRxDispatch (IxAtmRxQueueId rxQueueId,
    unsigned int numberOfPdusToProcess,
    unsigned int *numberOfPdusProcessedPtr);

/**
 *
 * @ingroup IxAtmdAccCtrlAPI
 * 
 * @fn ixAtmdAccRxLevelQuery (IxAtmRxQueueId rxQueueId,
                     unsigned int *numberOfPdusPtr)
 *
 * @brief Query the number of entries in a particular RX queue.
 *
 * This function is used to retrieve the number of pdus received by
 * the hardware and ready for distribution to users.
 *
 * @param rxQueueId @ref IxAtmRxQueueId [in] - indicates which of two RX queues to query.
 * @param numberOfPdusPtr unsigned int* [out] - Pointer to store the number of available
 *        PDUs in the RX queue. This parameter cannot be a null pointer.
 *
 * @return @li IX_SUCCESS the value in numberOfPdusPtr specifies the
 *         number of incoming pdus waiting in this queue
 * @return @li IX_FAIL an error occurs during processing.
 *         The value in numberOfPdusPtr is unspecified.
 *
 * @note - This function is reentrant, doesn't use system resources
 *         and can be used from an interrupt context.
 *
 */
PUBLIC IX_STATUS ixAtmdAccRxLevelQuery (IxAtmRxQueueId rxQueueId,
                     unsigned int *numberOfPdusPtr);

/**
 *
 * @ingroup IxAtmdAccCtrlAPI
 *
 * @fn ixAtmdAccRxQueueSizeQuery (IxAtmRxQueueId rxQueueId,
                     unsigned int *numberOfPdusPtr)
 *
 * @brief Query the size of a particular RX queue.
 *
 * This function is used to retrieve the number of pdus the system is
 * able to queue when reception is complete.
 *
 * @param rxQueueId @ref IxAtmRxQueueId [in] - indicates which of two RX queues to query.
 * @param numberOfPdusPtr unsigned int* [out] - Pointer to store the number of pdus
 *         the system is able to queue in the RX queue. This parameter
 *         cannot be a null pointer.
 *
 * @return @li IX_SUCCESS the value in numberOfPdusPtr specifies the
 *         number of pdus the system is able to queue.
 * @return @li IX_FAIL an error occurs during processing.
 *         The value in numberOfPdusPtr is unspecified.
 *
 * @note - This function is reentrant, doesn't use system resources
 *         and can be used from an interrupt context.
 *
 */
PUBLIC IX_STATUS ixAtmdAccRxQueueSizeQuery (IxAtmRxQueueId rxQueueId,
                     unsigned int *numberOfPdusPtr);

/* ------------------------------------------------------
   Part of the IxAtmdAcc interface related to TX traffic
   ------------------------------------------------------ */

/**
 *
 * @ingroup IxAtmdAccCtrlAPI
 *
 * @fn ixAtmdAccPortTxFreeEntriesQuery (IxAtmLogicalPort port,
                         unsigned int *numberOfCellsPtr)
 *
 * @brief Get the number of available cells the system can accept for
 *       transmission.
 *
 * The function is used to retrieve the number of cells that can be
 * queued for transmission to the hardware.
 *
 * This number is based on the worst schedule table where one cell
 * is stored in one schedule table entry, depending on the pdus size
 * and mbuf size and fragmentation.
 *
 * This function doesn't use system resources and can be used from a
 * timer context, or can be associated with a threshold event, or can
 * be used inside an active polling mechanism
 *
 * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 * @param numberOfCellsPtr unsigned int* [out] - number of available cells.
 *                   This parameter cannot be a null pointer.
 *
 * @sa ixAtmdAccPortTxProcess
 *
 * @return @li IX_SUCCESS numberOfCellsPtr contains the number of cells that can be scheduled
 *         for this port.
 * @return @li IX_FAIL error in the parameters, or some processing error
 *         occured.
 *
 */
PUBLIC IX_STATUS ixAtmdAccPortTxFreeEntriesQuery (IxAtmLogicalPort port,
                         unsigned int *numberOfCellsPtr);

/**
 *
 * @ingroup IxAtmdAccCtrlAPI
 * 
 * @fn ixAtmdAccPortTxCallbackRegister (IxAtmLogicalPort port,
                       unsigned int numberOfCells,
                       IxAtmdAccPortTxLowCallback callback)
 *
 * @brief Configure the Tx port threshold value and register a callback to handle
 * threshold notifications.
 *
 * This function sets the threshold in cells
 *
 * @sa ixAtmdAccPortTxCallbackRegister
 * @sa ixAtmdAccPortTxProcess
 * @sa ixAtmdAccPortTxFreeEntriesQuery
 *
 * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 * @param numberOfCells unsigned int [in] - threshold value which triggers the callback
 *        invocation, This number has to be one of the
 *        values 0,1,2,4,8,16,32 ....
 *        The maximum value cannot be more than half of the txVc queue
 *        size (which can be retrieved using @a ixAtmdAccPortTxFreeEntriesQuery()
 *        before any Tx traffic is sent for this port)
 * @param callback @ref IxAtmdAccPortTxLowCallback [in] - callback function to invoke when the threshold
 *                 level is reached.
 *                 This parameter cannot be a null pointer.
 *
 * @return @li IX_SUCCESS Successful call to @a ixAtmdAccPortTxCallbackRegister()
 * @return @li IX_FAIL error in the parameters, Tx channel already set for this port
 *             threshold level is not correct or within the range regarding the
 *             queue size:or unspecified error during processing:
 *
 * @note - This callback function get called when the threshold level drops from
 *         (numberOfCells+1) cells to (numberOfCells) cells
 *
 * @note - This function should be called during system initialisation,
 *         outside an interrupt context
 *
 */
PUBLIC IX_STATUS ixAtmdAccPortTxCallbackRegister (IxAtmLogicalPort port,
                       unsigned int numberOfCells,
                       IxAtmdAccPortTxLowCallback callback);

/**
 *
 * @ingroup IxAtmdAccCtrlAPI
 *
 * @fn ixAtmdAccPortTxScheduledModeEnable (IxAtmLogicalPort port,
    IxAtmdAccTxVcDemandUpdateCallback vcDemandUpdateCallback,
    IxAtmdAccTxVcDemandClearCallback vcDemandClearCallback,
    IxAtmdAccTxSchVcIdGetCallback vcIdGetCallback)
 *
 * @brief Put the port into Scheduled Mode
 *
 * This function puts the specified port into scheduled mode of
 * transmission which means an external s/w entity controls the
 * transmission of cells on this port. This faciltates traffic shaping on
 * the port.
 *
 * Any buffers submitted on a VC for this port will be queued in IxAtmdAcc.
 * The transmission of these buffers to and by the hardware will be driven
 * by a transmit schedule submitted regulary in calls to
 * @a ixAtmdAccPortTxProcess() by traffic shaping entity.
 *
 * The transmit schedule is expected to be dynamic in nature based on
 * the demand in cells for each VC on the port. Hence the callback
 * parameters provided to this function allow IxAtmdAcc to inform the
 * shaping entity of demand changes for each VC on the port.
 *
 * By default a port is in Unscheduled Mode so if this function is not
 * called, transmission of data is done without sheduling rules, on a
 * first-come, first-out basis.
 *
 * Once a port is put in scheduled mode it cannot be reverted to
 * un-scheduled mode. Note that unscheduled mode is not supported
 * in ixp425 1.0
 *
 * @note - This function should be called before any VCs have be
 * connected on a port. Otherwise this function call will return failure.
 *
 * @note - This function uses internal locks and should not be called from
 * an interrupt context
 *
 * @sa IxAtmdAccTxVcDemandUpdateCallback
 * @sa IxAtmdAccTxVcDemandClearCallback
 * @sa IxAtmdAccTxSchVcIdGetCallback
 * @sa ixAtmdAccPortTxProcess
 *
 * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 * @param vcDemandUpdateCallback @ref IxAtmdAccTxVcDemandUpdateCallback [in] - callback function used to update
 *     the number of outstanding cells for transmission. This parameter
 *     cannot be a null pointer.
 * @param vcDemandClearCallback @ref IxAtmdAccTxVcDemandClearCallback [in] - callback function used to remove all
 *     clear the number of outstanding cells for a VC. This parameter
 *     cannot be a null pointer.
 * @param vcIdGetCallback @ref IxAtmdAccTxSchVcIdGetCallback [in] - callback function used to exchange vc
 *     Identifiers between IxAtmdAcc and the entity supplying the
 *     transmit schedule. This parameter cannot be a null pointer.
 *
 * @return @li IX_SUCCESS scheduler registration is complete and the port
 *         is now in scheduled mode.
 * @return @li IX_FAIL failed (wrong parameters, or traffic is already
 *         enabled on this port, possibly without ATM shaping)
 *
 */
PUBLIC IX_STATUS ixAtmdAccPortTxScheduledModeEnable (IxAtmLogicalPort port,
    IxAtmdAccTxVcDemandUpdateCallback vcDemandUpdateCallback,
    IxAtmdAccTxVcDemandClearCallback vcDemandClearCallback,
    IxAtmdAccTxSchVcIdGetCallback vcIdGetCallback);

/**
 *
 * @ingroup IxAtmdAccCtrlAPI
 *
 * @fn ixAtmdAccPortTxProcess (IxAtmLogicalPort port,
    IxAtmScheduleTable* scheduleTablePtr)
 *
 * @brief Transmit queue cells to the H/W based on the supplied schedule
 *        table.
 *
 * This function @a ixAtmdAccPortTxProcess() process the schedule
 * table provided as a parameter to the function. As a result cells are
 * sent to the underlaying hardware for transmission.
 *
 * The schedule table is executed in its entirety or not at all. So the
 * onus is on the caller not to submit a table containing more cells than
 * can be transmitted at that point. The maximum numbers that can be
 * transmitted is guaranteed to be the number of cells as returned by the
 * function @a ixAtmdAccPortTxFreeEntriesQuery().
 *
 * When the scheduler is invoked on a threshold level, IxAtmdAcc gives the
 * minimum number of cells (to ensure the callback will fire again later)
 * and the maximum number of cells that @a ixAtmdAccPortTxProcess()
 * will be able to process (assuming the ATM scheduler is able
 * to produce the worst-case schedule table, i.e. one entry per cell).
 *
 * When invoked ouside a threshold level, the overall number of cells of
 * the schedule table should be less than the number of cells returned
 * by the @a ixAtmdAccPortTxFreeEntriesQuery() function.
 *
 * After invoking the @a ixAtmdAccPortTxProcess() function, it is the
 * user choice to query again the queue level with the function
 * @a ixAtmdAccPortTxFreeEntriesQuery() and, depending on a new cell
 * number, submit an other schedule table.
 *
 * IxAtmdAcc will check that the number of cells in the schedule table
 * is compatible with the current transmit level. If the
 *
 * Obsolete or invalid connection Id will be silently discarded.
 *
 * This function is not reentrant for the same port.
 *
 * This functions doesn't use system resources and can be used inside an
 * interrupt context.
 *
 * This function is used as a response to the hardware requesting more
 * cells to transmit.
 *
 * @sa ixAtmdAccPortTxScheduledModeEnable
 * @sa ixAtmdAccPortTxFreeEntriesQuery
 * @sa ixAtmdAccPortTxCallbackRegister
 * @sa ixAtmdAccPortEnable
 *
 * @param port @ref IxAtmLogicalPort [in] - logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 * @param scheduleTablePtr @ref IxAtmScheduleTable* [in] - pointer to a scheduler update table. The
 *     content of this table is not modified by this function. This
 *     parameter cannot be a null pointer.
 *
 * @return @li IX_SUCCESS the schedule table process is complete
 *             and cells are transmitted to the hardware
 * @return @li IX_ATMDACC_WARNING : Traffic will be dropped: the schedule table exceed
 *     the hardware capacity  If this error is ignored, further traffic
 *     and schedule will work correctly.
 *     Overscheduling does not occur when the schedule table does
 *     not contain more entries that the number of free entries returned
 *     by @a ixAtmdAccPortTxFreeEntriesQuery().
 *     However, Disconnect attempts just after this error will fail permanently
 *     with the error code @a IX_ATMDACC_RESOURCES_STILL_ALLOCATED, and it is
 *     necessary to disable the port to make @a ixAtmdAccTxVcTryDisconnect()
 *     successful.
 * @return @li IX_FAIL a wrong parameter is supplied, or the format of
 *     the schedule table is invalid, or the port is not Enabled, or
 *     an internal severe error occured. No cells is transmitted to the hardware
 *
 * @note - If the failure is linked to an overschedule of data cells
 *     the result is an inconsistency in the output traffic (one or many
 *     cells may be missing and the traffic contract is not respected).
 *
 */
PUBLIC IX_STATUS ixAtmdAccPortTxProcess (IxAtmLogicalPort port,
    IxAtmScheduleTable* scheduleTablePtr);

/**
 *
 * @ingroup IxAtmdAccCtrlAPI
 *
 * @fn ixAtmdAccTxDoneDispatch (unsigned int numberOfPdusToProcess,
                unsigned int *numberOfPdusProcessedPtr)
 *
 * @brief Process a number of pending transmit done pdus from the hardware.
 *
 * As a by-product of Atm transmit operation buffers which transmission
 * is complete need to be recycled to users. This function is invoked
 * to service the oustanding list of transmitted buffers and pass them
 * to VC users.
 *
 * Users are handed back pdus by invoking the free callback registered
 * during the @a ixAtmdAccTxVcConnect() call.
 *
 * There is a single Tx done stream servicing all active Atm Tx ports
 * which can contain a maximum of 64 entries. If this stream fills port