ixatmdacc.h

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

 * Calling this function prior to enable the port will fail.
 *
 * @sa ixAtmdAccRxDispatch
 * @sa ixAtmdAccRxVcEnable
 * @sa ixAtmdAccRxVcDisable
 * @sa ixAtmdAccRxVcTryDisconnect
 * @sa ixAtmdAccPortEnable
 *
 * @param port @ref IxAtmLogicalPort [in] - VC identification : logical PHY port
 *                  [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
 * @param vpi unsigned int [in] - VC identification : ATM Vpi [0..255] or IX_ATMDACC_OAM_VPI
 * @param vci unsigned int [in] - VC identification : ATM Vci [0..65535] or IX_ATMDACC_OAM_VCI
 * @param aalServiceType @ref IxAtmdAccAalType [in] - type of service: AAL5, AAL0_48, AAL0_52, or OAM
 * @param rxQueueId @ref IxAtmRxQueueId [in] - this identifieds which of two Qs the VC
 *     should use.when icoming traffic is processed
 * @param userCallbackId @ref IxAtmdAccUserId [in] - user Id used later as a parameter to
 *     the supplied rxCallback.
 * @param rxCallback [in] @ref IxAtmdAccRxVxRxCallback - function called when mbufs are received.
 *     This parameter cannot be a null pointer.
 * @param bufferFreeCallback [in] - function to be called to return
 *     ownership of buffers to IxAtmdAcc user.
 * @param minimumReplenishCount unsigned int [in] -  For AAL5/AAL0 the number of free mbufs
 *     to be used with this channel. Use a high number when the expected traffic
 *     rate on this channel is high, or when the user's mbufs are small, or when
 *     the RxVcFreeLow Notification has to be invoked less often. When this
 *     value is IX_ATMDACC_DEFAULT_REPLENISH_COUNT, the minimum of
 *     resources  will be used. Depending on traffic rate, pdu
 *     size and mbuf size, rxfree queue size, polling/interrupt rate, this value may
 *     require to be replaced by a different value in the range 1-128
 *     For OAM the rxFree queue size is fixed by atmdAcc and this parameter is ignored.
 * @param connIdPtr @ref IxAtmConnId [out] - pointer to a connection Id
 *     This parameter cannot be a null pointer.
 * @param npeVcIdPtr @ref IxAtmNpeRxVcId [out] - pointer to an npe Vc Id
 *     This parameter cannot be a null pointer.
 *
 * @return @li IX_SUCCESS successful call to IxAtmdAccRxVcConnect
 * @return @li IX_ATMDACC_BUSY cannot process this request :
 *         no VC is available
 * @return @li IX_FAIL
 *             parameter error,
 *             VC already in use,
 *             attempt to connect AAL service on reserved OAM VPI/VCI,
 *             attempt to connect OAM service on VPI/VCI other than the reserved OAM VPI/VCI,
 *             port is not initialised,
 *             or some other error occurs during processing.
 *
 */
PUBLIC IX_STATUS ixAtmdAccRxVcConnect (IxAtmLogicalPort port,
                      unsigned int vpi,
                      unsigned int vci,
                      IxAtmdAccAalType aalServiceType,
                      IxAtmRxQueueId rxQueueId,
                      IxAtmdAccUserId userCallbackId,
                      IxAtmdAccRxVcRxCallback rxCallback,
                      unsigned int minimumReplenishCount,
                      IxAtmConnId * connIdPtr,
                      IxAtmNpeRxVcId * npeVcIdPtr );

/**
 *
 * @ingroup IxAtmdAccAPI
 * 
 * @fn ixAtmdAccRxVcFreeReplenish (IxAtmConnId connId,
                        IX_OSAL_MBUF * mbufPtr)
 *
 * @brief Provide free mbufs for data reception on a connection.
 *
 * This function provides mbufs for data reception by the hardware. This
 * function needs to be called by the user on a regular basis to ensure
 * no packet loss. Providing free buffers is a connection-based feature;
 * each connection can have different requirements in terms of buffer size
 * number of buffers, recycling rate. This function could be invoked from
 * within the context of a @a IxAtmdAccRxVcFreeLowCallback() callback
 * for a particular VC
 *
 * Mbufs provided through this function call can be chained. They will be
 * unchained internally. A call to this function with chained mbufs or
 * multiple calls with unchained mbufs are equivalent, but calls with
 * unchained mbufs are more efficients.
 *
 * Mbufs provided to this interface need to be able to hold at least one
 * full cell payload (48/52 bytes, depending on service type).
 * Chained buffers with a size less than the size supported by the hardware
 * will be returned through the rx callback provided during the connect step.
 *
 * Failing to invoke this function prior to enabling the RX traffic
 * can result in packet loss.
 *
 * This function is not reentrant for the same connId.
 *
 * This function does not use system resources and can be
 * invoked from an interrupt context.
 *
 * @note - Over replenish is detected, and extra mbufs are returned through
 *         the rx callback provided during the connect step.
 *
 * @note - Mbuf provided to the replenish function should have a length greater or
 *         equal to 48/52 bytes according to service type.
 *
 * @note - The memory cache of mMbuf payload should be invalidated prior to Mbuf
 *         submission. Flushing the Mbuf headers is handled by IxAtmdAcc.
 *
 * @note - When a chained mbuf is provided, this function process the mbufs
 *         up to the hardware limit and invokes the user-supplied callback
 *         to release extra buffers.
 *
 * @sa ixAtmdAccRxVcFreeLowCallbackRegister
 * @sa IxAtmdAccRxVcFreeLowCallback
 * @sa ixAtmdAccRxVcConnect
 *
 * @param connId @ref IxAtmConnId [in] - connection Id as returned from a succesfull call to
 *        @a IxAtmdAccRxVcConnect()
 * @param mbufPtr @ref IX_OSAL_MBUF [in] - pointer to a mbuf structure to be used for data
 *        reception. The mbuf pointed to by this parameter can be chained
 *        to an other mbuf.
 *
 * @return @li IX_SUCCESS successful call to @a ixAtmdAccRxVcFreeReplenish()
 *          and the mbuf is now ready to use for incoming traffic.
 * @return @li IX_ATMDACC_BUSY cannot process this request because
 *         the max number of outstanding free buffers has been reached
 *         or the internal resources have exhausted for this VC.
 *         The user is responsible for retrying this request later.
 * @return @li IX_FAIL cannot process this request because of parameter
 *         errors or some unspecified internal error has occurred.
 *
 * @note - It is not always guaranteed the replenish step to be as fast as the
 *   hardware is consuming Rx Free mbufs. There is nothing in IxAtmdAcc to
 *   guarantee that replenish reaches the rxFree threshold level. If the
 *   threshold level is not reached, the next rxFree low notification for
 *   this channel will not be triggered.
 *   The preferred ways to replenish can be as follows (depending on
 *   applications and implementations) :
 *   @li Replenish in a rxFree low notification until the function
 *       ixAtmdAccRxVcFreeReplenish() returns IX_ATMDACC_BUSY
 *   @li Query the queue level using @sa ixAtmdAccRxVcFreeEntriesQuery, then
 *     , replenish using @a ixAtmdAccRxVcFreeReplenish(), then query the queue
 *       level again, and replenish if the threshold is still not reached.
 *   @li Trigger replenish from an other event source and use rxFree starvation
 *       to throttle the Rx traffic.
 *
 */
PUBLIC IX_STATUS ixAtmdAccRxVcFreeReplenish (IxAtmConnId connId,
                        IX_OSAL_MBUF * mbufPtr);

/**
 *
 * @ingroup IxAtmdAccAPI
 * 
 * @fn ixAtmdAccRxVcFreeLowCallbackRegister (IxAtmConnId connId,
                                    unsigned int numberOfMbufs,
                                    IxAtmdAccRxVcFreeLowCallback callback)
 *
 * @brief Configure the RX Free threshold value and register a callback
 * to handle threshold notifications.
 *
 * The function ixAtmdAccRxVcFreeLowCallbackRegister sets the threshold value for
 * a particular RX VC. When the number of buffers reaches this threshold
 * the callback is invoked.
 *
 * This function should be called once per VC before RX traffic is
 * enabled.This function will fail if the curent level of the free buffers
 * is equal or less than the threshold value.
 *
 * @sa ixAtmdAccRxVcFreeLowCallbackRegister
 * @sa IxAtmdAccRxVcFreeLowCallback
 * @sa ixAtmdAccRxVcFreeReplenish
 * @sa ixAtmdAccRxVcFreeEntriesQuery
 * @sa ixAtmdAccRxVcConnect
 *
 * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call
 *        to @a IxAtmdAccRxVcConnect()
 * @param numberOfMbufs unsigned int [in] - threshold number of buffers. This number
 *        has to be a power of 2, one of the values 0,1,2,4,8,16,32....
 *        The maximum value cannot be more than half of the rxFree queue
 *        size (which can be retrieved using @a ixAtmdAccRxVcFreeEntriesQuery()
 *        before any use of the @a ixAtmdAccRxVcFreeReplenish() function)
 * @param callback @ref IxAtmdAccRxVcFreeLowCallback [in] - function telling the user that the number of
 *        free buffers has reduced to the threshold value.
 *
 * @return @li IX_SUCCESS Threshold set successfully.
 * @return @li IX_FAIL parameter error or the current number of free buffers
 *              is less than or equal to the threshold supplied or some
 *              unspecified error has occrred.
 *
 * @note - the callback will be called when the threshold level will drop from
 *        exactly (numberOfMbufs + 1) to (numberOfMbufs).
 *
 */
PUBLIC IX_STATUS ixAtmdAccRxVcFreeLowCallbackRegister (IxAtmConnId connId,
    unsigned int numberOfMbufs,
    IxAtmdAccRxVcFreeLowCallback callback);

/**
 *
 * @ingroup IxAtmdAccAPI
 *
 * @fn ixAtmdAccRxVcFreeEntriesQuery (IxAtmConnId connId,
                         unsigned int *numberOfMbufsPtr)
 *
 * @brief Get the number of rx mbufs the system can accept to replenish the
 *       the rx reception mechanism on a particular channel
 *
 * The ixAtmdAccRxVcFreeEntriesQuery function is used to retrieve the current
 * number of available mbuf entries for reception, on a per-VC basis. This
 * function can be used to know the number of mbufs which can be provided
 * using @a ixAtmdAccRxVcFreeReplenish().
 *
 * This function can be used from a timer context, or can be associated
 * with a threshold event, or can be used inside an active polling
 * mechanism which is under user control.
 *
 * This function is reentrant and does not use system resources and can
 * be invoked from an interrupt context.
 *
 * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call
 *        to @a IxAtmdAccRxVcConnect()
 * @param numberOfMbufsPtr unsigned int [out] - Pointer to the number of available entries.
 *      . This parameter cannot be a null pointer.
 *
 * @return @li IX_SUCCESS the current number of mbufs not yet used for incoming traffic
 * @return @li IX_FAIL invalid parameter
 *
 * @sa ixAtmdAccRxVcFreeReplenish
 *
 */
PUBLIC IX_STATUS ixAtmdAccRxVcFreeEntriesQuery (IxAtmConnId connId,
                         unsigned int *numberOfMbufsPtr);

/**
 *
 * @ingroup IxAtmdAccAPI
 *
 * @fn ixAtmdAccRxVcEnable (IxAtmConnId connId)
 *
 * @brief Start the RX service on a VC.
 *
 * This functions kicks-off the traffic reception for a particular VC.
 * Once invoked, incoming PDUs will be made available by the hardware
 * and are eventually directed to the @a IxAtmdAccRxVcRxCallback() callback
 * registered for the connection.
 *
 * If the traffic is already running, this function returns IX_SUCCESS.
 * This function can be invoked many times.
 *
 * IxAtmdAccRxVcFreeLowCallback event will occur only after
 * @a ixAtmdAccRxVcEnable() function is invoked.
 *
 * Before using this function, the @a ixAtmdAccRxVcFreeReplenish() function
 * has to be used to replenish the RX Free queue. If not, incoming traffic
 * may be discarded.and in the case of interrupt driven reception the
 * @a IxAtmdAccRxVcFreeLowCallback() callback may be invoked as a side effect
 * during a replenish action.
 *
 * This function is not reentrant and should not be used inside an
 * interrupt context.
 *
 * For an VC connection this function can be called after a call to
 * @a ixAtmdAccRxVcDisable() and should not be called after
 * @a ixAtmdAccRxVcTryDisconnect()
 *
 * @sa ixAtmdAccRxVcDisable
 * @sa ixAtmdAccRxVcConnect
 * @sa ixAtmdAccRxVcFreeReplenish
 *
 * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call
 * to @a IxAtmdAccRxVcConnect()
 *
 * @return @li IX_SUCCESS successful call to ixAtmdAccRxVcEnable
 * @return @li IX_ATMDACC_WARNING the channel is already enabled
 * @return @li IX_FAIL invalid parameters or some unspecified internal
 *         error occured.
 *
 */
PUBLIC IX_STATUS ixAtmdAccRxVcEnable (IxAtmConnId connId);

/**
 *
 * @ingroup IxAtmdAccAPI
 * 
 * @fn ixAtmdAccRxVcDisable (IxAtmConnId connId)
 *
 * @brief Stop the RX service on a VC.
 *
 * This functions stops the traffic reception for a particular VC connection.
 *
 * Once invoked, incoming Pdus are discarded by the hardware. Any Pdus
 * pending will be freed to the user
 *
 * Hence once this function returns no more receive callbacks will be
 * called for that VC. However, buffer free callbacks will be invoked
 * until such time as all buffers supplied by the user have been freed
 * back to the user
 *
 * Calling this function doe not invalidate the connId.
 * @a ixAtmdAccRxVcEnable() can be invoked to enable Pdu reception again.
 *
 * If the traffic is already stopped, this function returns IX_SUCCESS.
 *
 * This function is not reentrant and should not be used inside an