ixatmdacc.h

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

 * interrupt context.
 *
 * @sa ixAtmdAccRxVcConnect
 * @sa ixAtmdAccRxVcEnable
 * @sa ixAtmdAccRxVcDisable
 *
 * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call to @a
 *     IxAtmdAccRxVcConnect()
 *
 * @return @li IX_SUCCESS successful call to @a ixAtmdAccRxVcDisable().
 * @return @li IX_ATMDACC_WARNING the channel is already disabled
 * @return @li IX_FAIL invalid parameters or some unspecified internal error occured
 *
 */
PUBLIC IX_STATUS ixAtmdAccRxVcDisable (IxAtmConnId connId);

/**
 *
 * @ingroup IxAtmdAccAPI
 * 
 * @fn ixAtmdAccRxVcTryDisconnect (IxAtmConnId connId)
 *
 * @brief Disconnect a VC from the RX service.
 *
 * This function deregisters the VC and guarantees that all resources
 * associated with this VC are free. After its execution, the connection
 * Id is not available.
 *
 * This function will fail until such time as all resources allocated to
 * the VC connection have been freed. The user is responsible to delay and
 * call again this function many times until a success status is returned.
 *
 * This function needs internal locks and should not be called from an
 * interrupt context
 *
 * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call to
 * @a IxAtmdAccRxVcConnect()
 *
 * @return @li IX_SUCCESS successful call to ixAtmdAccRxVcDisable
 * @return @li IX_ATMDACC_RESOURCES_STILL_ALLOCATED not all resources
 *         associated with the connection have been freed.
 * @return @li IX_FAIL cannot process this request because of a parameter
 *         error
 *
 */
PUBLIC IX_STATUS ixAtmdAccRxVcTryDisconnect (IxAtmConnId connId);

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

/**
 *
 * @ingroup IxAtmdAccAPI
 * 
 * @fn ixAtmdAccTxVcConnect (IxAtmLogicalPort port,
                      unsigned int vpi,
                      unsigned int vci,
                      IxAtmdAccAalType aalServiceType,
                      IxAtmdAccUserId userId,
                      IxAtmdAccTxVcBufferReturnCallback bufferFreeCallback,
                      IxAtmConnId * connIdPtr)
 *
 * @brief Connect to a Aal Pdu transmit service for a particular
 *        port/vpi/vci and service type.
 *
 * This function allows a user to connect to an Aal5/Aal0/OAM Pdu transmit service
 * for a particular port/vpi/vci. It registers the callback and allocates
 * internal resources and a Connection Id to be used in further API calls
 * related to this VC.
 *
 * The function will setup VC transmit service on the specified on the
 * specified port. A connId is the reference by which IxAtmdAcc refers to a
 * connected VC. This identifier is the result of a succesful call
 * to a connect function. This identifier is invalid after a
 * sucessful call to a disconnect function.
 *
 * This function needs internal locks, and hence  should not be called
 * from an interrupt context.
 *
 * On return from @a ixAtmdAccTxVcConnect() with a failure status, the
 * connection Id parameter is unspecified. Its value cannot be used.
 *
 * Calling this function for the same combination of port, Vpi, Vci and
 * more than once without calling @a ixAtmdAccTxVcTryDisconnect() will result
 * in a failure status.
 *
 * Two AAL0 services supporting 48 or 52 byte cell data are provided.
 * Submitted AAL0 PDUs must be a multiple of the cell data size (48/52).
 * AAL0_52 is a raw cell service the client must format
 * the PDU with an ATM cell header (excluding HEC) at the start of
 * each cell, note that AtmdAcc does not validate the cell headers in
 * a submitted PDU.
 *
 * For the OAM service an "OAM Tx channel" may be enabled for a port
 * by establishing a single dedicated OAM Tx connection on that port.
 *
 * The OAM service allows buffers containing 52 byte OAM F4/F5 cells
 * to be transmitted and received over the dedicated OAM channels.
 * HEC is appended/removed, and CRC-10 performed by the NPE. The OAM
 * service offered by AtmdAcc is a raw cell transport service.
 * It is assumed that ITU I.610 procedures that make use of this
 * service are implemented above AtmdAcc.
 *
 * Note that the dedicated OAM connections are established on
 * reserved VPI,VCI, and (in the case of Rx) port values.
 * These values are used purely to descriminate the dedicated OAM channels
 * and do not identify a particular OAM F4/F5 flow. F4/F5 flows may be
 * realised for particluar VPI/VCIs by manipulating the VPI,VCI
 * fields of the ATM cell headers of cells in the buffers passed
 * to AtmdAcc.
 *
 * Calling this function before enabling the port will fail.
 *
 * @sa ixAtmdAccTxVcTryDisconnect
 * @sa ixAtmdAccPortTxScheduledModeEnable
 * @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 userId @ref IxAtmdAccUserId [in] - user id to be used later during callbacks related
 *        to this channel
 * @param bufferFreeCallback @ref IxAtmdAccTxVcBufferReturnCallback [in] - function called when mbufs
 *        transmission is complete. This parameter cannot be a null
 *        pointer.
 * @param connIdPtr @ref IxAtmConnId [out] - Pointer to a connection Id.
 *        This parameter cannot be a null pointer.
 *
 * @return @li IX_SUCCESS successful call to @a IxAtmdAccRxVcConnect().
 * @return @li IX_ATMDACC_BUSY cannot process this request
 *         because 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.
 *
 * @note - Unscheduled mode is not supported in ixp425 1.0. Therefore, the
 *       function @a ixAtmdAccPortTxScheduledModeEnable() need to be called
 *       for this port before any establishing a Tx Connection
 */
PUBLIC IX_STATUS ixAtmdAccTxVcConnect (IxAtmLogicalPort port,
                      unsigned int vpi,
                      unsigned int vci,
                      IxAtmdAccAalType aalServiceType,
                      IxAtmdAccUserId userId,
                      IxAtmdAccTxVcBufferReturnCallback bufferFreeCallback,
                      IxAtmConnId * connIdPtr);

/**
 *
 * @ingroup IxAtmdAccAPI
 *
 * @fn ixAtmdAccTxVcPduSubmit (IxAtmConnId connId,
                    IX_OSAL_MBUF * mbufPtr,
                    IxAtmdAccClpStatus clp,
                    unsigned int numberOfCells)
 *
 * @brief Submit a Pdu for transmission on connection.
 *
 * A data user calls this function to submit an mbufs containing a Pdu
 * to be transmitted. The buffer supplied can be chained and the Pdu it
 * contains must be complete.
 *
 * The transmission behavior of this call depends on the operational mode
 * of the port on which the connection is made.
 *
 * In unscheduled mode the mbuf will be submitted to the hardware
 * immediately if sufficent resource is available. Otherwise the function
 * will return failure.
 *
 * In scheduled mode the buffer is queued internally in IxAtmdAcc. The cell
 * demand is made known to the traffic shaping entity. Cells from the
 * buffers are MUXed onto the port some time later as dictated by the
 * traffic shaping entity. The traffic shaping entity does this by sending
 * transmit schedules to IxAtmdAcc via @a ixAtmdAccPortTxProcess() function call.
 *
 * Note that the dedicated OAM channel is scheduled just like any
 * other channel. This means that any OAM traffic relating to an
 * active AAL0/AAL5 connection will be scheduled independantly of the
 * AAL0/AAL5 traffic for that connection.
 *
 * When transmission is complete, the TX Done mechanism will give the
 * owmnership of these buffers back to the customer. The tx done mechanism
 * must be in operation before transmission is attempted.
 *
 * For AAL0/OAM submitted AAL0 PDUs must be a multiple of the cell data
 * size (48/52). AAL0_52 and OAM are raw cell services, and the client
 * must format the PDU with an ATM cell header (excluding HEC) at the
 * start of each cell, note that AtmdAcc does not validate the cell headers in
 * a submitted PDU.
 *
 *
 * @sa IxAtmdAccTxVcBufferReturnCallback
 * @sa ixAtmdAccTxDoneDispatch
 *
 * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call to
 *        @a ixAtmdAccTxVcConnect()
 * @param mbufPtr @ref IX_OSAL_MBUF [in] - pointer to a chained structure of mbufs to transmit.
 *       This parameter cannot be a null pointer.
 * @param clp @ref IxAtmdAccClpStatus [in] - clp indication for this PDU. All cells of this pdu
 *       will be sent with the clp bit set
 * @param numberOfCells unsigned int [in] - number of cells in the PDU.
 *
 * @return @li IX_SUCCESS successful call to @a ixAtmdAccTxVcPduSubmit()
 *             The pdu pointed by the mbufPtr parameter will be
 *             transmitted
 * @return @li IX_ATMDACC_BUSY unable to process this request because
 *             internal resources are all used. The caller is responsible
 *             for retrying this request later.
 * @return @li IX_FAIL unable to process this request because of error
 *             in the parameters (wrong connId supplied,
 *             or wrong mbuf pointer supplied), the total length of all buffers
 *             in the chain should be a multiple of the cell size
 *             ( 48/52 depending on the service type ),
 *             or unspecified error during processing
 *
 * @note - This function in not re-entrant for the same VC (e.g. : two
 *         thread cannot send PDUs for the same VC). But two threads can
 *         safely call this function with a different connection Id
 *
 * @note - In unscheduled mode, this function is not re-entrant on a per
 *         port basis. The size of pdus is limited to 8Kb.
 *
 * @note - 0-length mbufs should be removed from the chain before submission.
 *         The total length of the pdu (sdu + padding +trailer) has to be
 *         updated in the header of the first mbuf of a chain of mbufs.
 *
 * @note - Aal5 trailer information (UUI, CPI, SDU length) has to be supplied
 *         before submission.
 *
 * @note - The payload memory cache should be flushed, if needed, prior to
 *         transmission. Mbuf headers are flushed by IxAtmdAcc
 *
 * @note - This function does not use system resources and can be used
 *         inside an interrupt context
 */
PUBLIC IX_STATUS ixAtmdAccTxVcPduSubmit (IxAtmConnId connId,
                    IX_OSAL_MBUF * mbufPtr,
                    IxAtmdAccClpStatus clp,
                    unsigned int numberOfCells);

/**
 *
 * @ingroup IxAtmdAccAPI
 *
 * @fn ixAtmdAccTxVcTryDisconnect (IxAtmConnId connId)
 *
 * @brief Disconnect from a Aal Pdu transmit service for a particular
 *        port/vpi/vci.
 *
 * This function deregisters the VC and guarantees that all resources
 * associated with this VC are free. After its execution, the connection
 * Id is not available.
 *
 * This function will fail until such time as all resources allocated to
 * the VC connection have been freed. The user is responsible to delay
 * and call again this function many times until a success status is
 * returned.
 *
 * After its execution, the connection Id is not available.
 *
 * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call to
 *        @a ixAtmdAccTxVcConnect()
 *
 * @return @li IX_SUCCESS successful call to @a ixAtmdAccTxVcTryDisconnect()
 * @return @li IX_ATMDACC_RESOURCES_STILL_ALLOCATED not all resources
 *     associated with the connection have been freed. This condition will
 *     disappear after Tx and TxDone is complete for this channel.
 * @return @li IX_FAIL unable to process this request because of errors
 *                     in the parameters (wrong connId supplied)
 *
 * @note - This function needs internal locks and should not be called
 *         from an interrupt context
 *
 * @note - If the @a IX_ATMDACC_RESOURCES_STILL_ALLOCATED error does not
 *     clear after a while, this may be linked to a previous problem
 *     of cell overscheduling. Diabling the port and retry a disconnect
 *     will free the resources associated with this channel.
 *
 * @sa ixAtmdAccPortTxProcess
 *
 */
PUBLIC IX_STATUS ixAtmdAccTxVcTryDisconnect (IxAtmConnId connId);

#endif /* IXATMDACC_H */

/**
 * @} defgroup IxAtmdAccAPI
 */