ixethacc.h

u-boot 源代码

 *   within the @ref IxQMgrAPI component. The calling context may be from interrupt or high priority thread. 
 *   The decision is system specific.
 *
 *
 * @param callbackTag UINT32 [in] - This tag is that provided when the callback was registered for a particular MAC 
 * via @a ixEthAccPortRxCallbackRegister. It allows the same callback to be used for multiple MACs.
 * @param mbuf @ref IX_OSAL_MBUF [in] - Pointer to the Rx mbuf header. Mbufs may be chained if 
 *               the frame length is greater than the supplied mbuf length.
 * @param reserved [in] - deprecated parameter The information is passed 
 *      thru the IxEthAccNe header destination port ID field 
 *      (@sa IX_ETHACC_NE_DESTPORTID). For backward 
 *      compatibility,the value is equal to IX_ETH_DB_UNKNOWN_PORT (0xff). 
 * 
 * @return void
 *
 * @note
 * Buffers may not be filled up to the length supplied in 
 * @a ixEthAccPortRxFreeReplenish(). The firmware fills
 * them to the previous 64 bytes boundary. The user has to be aware 
 * that the length of the received mbufs may be smaller than the length
 * of the supplied mbufs. 
 * The mbuf header contains the following modified field
 * @li @a IX_OSAL_MBUF_PKT_LEN is set in the header of the first mbuf and indicates
 *  the total frame size
 * @li @a IX_OSAL_MBUF_MLEN is set each mbuf header and indicates the payload length
 * @li @a IX_OSAL_MBUF_NEXT_BUFFER_IN_PKT_PTR contains a pointer to the next 
 *     mbuf, or NULL at the end of a chain.
 * @li @a IX_OSAL_MBUF_NEXT_PKT_IN_CHAIN_PTR is modified. Its value is reset to NULL
 * @li @a IX_OSAL_MBUF_FLAGS contains the bit 4 set for a broadcast packet and the bit 5
 *     set for a multicast packet. Other bits are unmodified.
 *
 * <hr>
 */
typedef void (*IxEthAccPortRxCallback) (UINT32 callbackTag, IX_OSAL_MBUF *buffer, UINT32 reserved);

/**
 * @ingroup IxEthAcc
 *
 * @brief Function prototype for Ethernet Frame Rx callback. Registered via @a ixEthAccPortMultiBufferRxCallbackRegister 
 * 
 * It is the responsibility of the user function to free any MBUF's which it receives.
 *  
 * @li Reentrant    - yes , The user provided function should be reentrant.
 * @li ISR Callable - yes , The user provided function must be callable from an ISR.
 * @par
 *
 * This function dispatches many frames to the user level
 * via the provided function. The invocation shall be made for multiple frames
 * dequeued from the Ethernet QM queue. The user is required to free any MBUF's 
 * supplied via this callback. In addition the registered callback must free up MBUF's
 * from the receive free queue when the port is disabled 
 * 
 * If called several times the latest callback shall be registered for a particular port.
 *
 * <b>Calling Context </b>: 
 * @par
 *   This callback is called in the context of the queue manager dispatch loop @a ixQmgrDispatcherLoopRun
 *   within the @ref IxQMgrAPI component. The calling context may be from interrupt or high priority thread. 
 *   The decision is system specific.
 *
 *
 * @param callbackTag - This tag is that provided when the callback was registered for a particular MAC 
 * via @a ixEthAccPortMultiBufferRxCallbackRegister. It allows the same callback to be used for multiple MACs.
 * @param mbuf - Pointer to an array of Rx mbuf headers. Mbufs 
 *               may be chained if 
 *               the frame length is greater than the supplied mbuf length.
 *               The end of the array contains a zeroed entry (NULL pointer).
 *
 * @return void
 *
 * @note The mbufs passed to this callback have the same structure than the
 *  buffers passed to @a IxEthAccPortRxCallback interfac. 
 *
 * @note The usage of this callback is exclusive with the usage of
 *  @a ixEthAccPortRxCallbackRegister and @a IxEthAccPortRxCallback 
 *
 * @sa ixEthAccPortMultiBufferRxCallbackRegister
 * @sa IxEthAccPortMultiBufferRxCallback
 * @sa ixEthAccPortRxCallbackRegister
 * @sa IxEthAccPortRxCallback
 * <hr>
 */

typedef void (*IxEthAccPortMultiBufferRxCallback) (UINT32 callbackTag, IX_OSAL_MBUF **buffer);




/**
 * @ingroup IxEthAcc
 *
 * @fn ixEthAccPortRxCallbackRegister( IxEthAccPortId portId, IxEthAccPortRxCallback rxCallbackFn, UINT32 callbackTag)
 *
 * @brief Register a callback function to allow 
 * the reception of frames.
 *
 * The registered callback function is called once a frame is received  by this service.
 *
 * If called several times the latest callback shall be registered for a particular port.
 *
 *
 * @li Reentrant    - yes
 * @li ISR Callable - yes
 *
 *
 * @param portId @ref IxEthAccPortId [in] - Register callback for a particular MAC device.
 * @param rxCallbackFn @ref IxEthAccPortRxCallback [in] - Function to be called when Ethernet frames are availble.
 * @param callbackTag UINT32 [in] -  This tag shall be provided to the callback function.
 *
 * @return IxEthAccStatus
 * @li @a IX_ETH_ACC_SUCCESS 
 * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
 * @li @a IX_ETH_ACC_INVALID_ARG : An argument other than portId is invalid.
 *
 * <hr>
 */
PUBLIC IxEthAccStatus
ixEthAccPortRxCallbackRegister(IxEthAccPortId portId,
							   IxEthAccPortRxCallback rxCallbackFn,
							   UINT32 callbackTag);


/**
 * @ingroup IxEthAcc
 *
 * @fn ixEthAccPortMultiBufferRxCallbackRegister( IxEthAccPortId portId, IxEthAccPortMultiBufferRxCallback rxCallbackFn, UINT32 callbackTag)
 *
 * @brief Register a callback function to allow 
 * the reception of frames.
 * 
 * The registered callback function is called once a frame is 
 * received  by this service. If many frames are already received, 
 * the function is called once.
 *
 * If called several times the latest callback shall be registered for a particular port.
 *
 * @li Reentrant    - yes
 * @li ISR Callable - yes
 *
 *
 * @param portId - Register callback for a particular MAC device.
 * @param rxCallbackFn - @a IxEthAccMultiBufferRxCallbackFn - Function to be called when Ethernet frames are availble.
 * @param callbackTag -  This tag shall be provided to the callback function.
 *
 * @return IxEthAccStatus
 * @li @a IX_ETH_ACC_SUCCESS 
 * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
 * @li @a IX_ETH_ACC_INVALID_ARG : An argument other than portId is invalid.
 *
 * @sa ixEthAccPortMultiBufferRxCallbackRegister
 * @sa IxEthAccPortMultiBufferRxCallback
 * @sa ixEthAccPortRxCallbackRegister
 * @sa IxEthAccPortRxCallback
 * <hr>
 */
PUBLIC IxEthAccStatus
ixEthAccPortMultiBufferRxCallbackRegister(IxEthAccPortId portId,
										  IxEthAccPortMultiBufferRxCallback rxCallbackFn,
										  UINT32 callbackTag);

/**
 * @ingroup IxEthAcc
 *
 * @fn ixEthAccPortRxFreeReplenish( IxEthAccPortId portId, IX_OSAL_MBUF *buffer)
 *
 * @brief This function provides buffers for the Ethernet receive path. 
 *
 * This component does not have a buffer management mechanisms built in. All Rx buffers must be supplied to it
 * via this interface. 
 *
 * @li Reentrant    - yes
 * @li ISR Callable - yes
 *
 * @param portId @ref IxEthAccPortId [in] - Provide buffers only to specific Rx MAC. 
 * @param buffer @ref IX_OSAL_MBUF [in] - Provide an MBUF to the Ethernet receive mechanism. 
 *                 Buffers size smaller than IX_ETHACC_RX_MBUF_MIN_SIZE may result in poor
 *                 performances and excessive buffer chaining. Buffers
 *                 larger than this size may be suitable for jumbo frames.
 *                 Chained packets are not supported and the field IX_OSAL_MBUF_NEXT_PKT_IN_CHAIN_PTR must be NULL. 
 *
 * @return IxEthAccStatus
 * @li @a IX_ETH_ACC_SUCCESS
 * @li @a IX_ETH_ACC_FAIL : Buffer has was not able to queue the 
 *                     buffer in the receive service.
 * @li @a IX_ETH_ACC_FAIL : Buffer size is less than IX_ETHACC_RX_MBUF_MIN_SIZE
 * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
 *
 * @note
 * If the buffer replenish operation fails it is the responsibility 
 * of the user to free the buffer.
 *
 * @note
 * Sufficient buffers must be supplied to the component to maintain
 * receive throughput and avoid rx buffer underflow conditions.
 * To meet this goal, It is expected that the user preload the 
 * component with a sufficent number of buffers prior to enabling the
 * NPE Ethernet receive path. The recommended minimum number of 
 * buffers is 8.
 *
 * @note
 * For maximum performances, the mbuf size should be greater 
 * than the maximum frame size (Ethernet header, payload and FCS) + 64. 
 * Supplying smaller mbufs to the service results in mbuf
 * chaining and degraded performances. The recommended size
 * is @a IX_ETHACC_RX_MBUF_MIN_SIZE, which is
 * enough to take care of 802.3 frames and "baby jumbo" frames without
 * chaining, and "jumbo" frame within chaining.
 *
 * @note
 * Buffers may not be filled up to their length. The firware fills
 * them up to the previous 64 bytes boundary. The user has to be aware 
 * that the length of the received mbufs may be smaller than the length
 * of the supplied mbufs.
 *
 * @warning This function checks the parameters if the NDEBUG 
 * flag is not defined. Turning on the argument checking (disabled by 
 * default) results in a lower EthAcc performance as this function
 * is part of the data path.
 *
 * <hr>
 */
PUBLIC IxEthAccStatus
ixEthAccPortRxFreeReplenish( IxEthAccPortId portId, IX_OSAL_MBUF *buffer);



/***************************************************************

  ####    ####   #    #   #####  #####    ####   #
 #    #  #    #  ##   #     #    #    #  #    #  #
 #       #    #  # #  #     #    #    #  #    #  #
 #       #    #  #  # #     #    #####   #    #  #
 #    #  #    #  #   ##     #    #   #   #    #  #
  ####    ####   #    #     #    #    #   ####   ######


         #####   #         ##    #    #  ######
         #    #  #        #  #   ##   #  #
         #    #  #       #    #  # #  #  #####
         #####   #       ######  #  # #  #
         #       #       #    #  #   ##  #
         #       ######  #    #  #    #  ######

***************************************************************/

/**
 * @ingroup IxEthAcc
 *
 * @fn ixEthAccPortEnable(IxEthAccPortId portId)
 *
 * @brief This enables an Ethernet port for both Tx and Rx. 
 *
 * @li Reentrant    - yes
 * @li ISR Callable - no
 *
 * @pre The port must first be initialized via @a ixEthAccPortInit and the MAC address 
 * must be set using @a ixEthAccUnicastMacAddressSet before enabling it
 * The rx and Tx Done callbacks registration via @a
 * ixEthAccPortTxDoneCallbackRegister amd @a  ixEthAccPortRxCallbackRegister
 * has to be done before enabling the traffic.
 * 
 * @param  portId @ref IxEthAccPortId [in] - Port id to act upon.
 * 
 * @return IxEthAccStatus
 * @li @a IX_ETH_ACC_SUCCESS 
 * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is not initialized
 * @li @a IX_ETH_ACC_MAC_UNINITIALIZED : port MAC address is not initialized
 *
 * <hr>
 */
PUBLIC IxEthAccStatus ixEthAccPortEnable(IxEthAccPortId portId);

/**
 * @ingroup IxEthAcc
 *
 * @fn ixEthAccPortDisable(IxEthAccPortId portId)
 *
 * @brief This disables an Ethernet port for both Tx and Rx. 
 *
 * Free MBufs are returned to the user via the registered callback when the port is disabled 
 *
 * @li Reentrant    - yes
 * @li ISR Callable - no
 *
 * @pre The port must be enabled with @a ixEthAccPortEnable, otherwise this
 * function has no effect
 *
 * @param  portId @ref IxEthAccPortId [in] - Port id to act upon.
 * 
 * @return IxEthAccStatus
 * @li @a IX_ETH_ACC_SUCCESS 
 * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is not initialized
 * @li @a IX_ETH_ACC_MAC_UNINITIALIZED : port MAC address is not initialized
 *
 * <hr>
 */
PUBLIC IxEthAccStatus ixEthAccPortDisable(IxEthAccPortId portId);

/**
 * @ingroup IxEthAcc
 *
 * @fn ixEthAccPortEnabledQuery(IxEthAccPortId portId, BOOL *enabled)
 *
 * @brief Get the enabled state of a port.
 *
 * @li Reentrant    - yes
 * @li ISR Callable - yes
 *
 * @pre The port must first be initialized via @a ixEthAccPortInit
 *
 * @param  portId @ref IxEthAccPortId [in] - Port id to act upon.
 * @param  enabled BOOL [out] - location to store the state of the port
 *
 * @return IxEthAccStatus
 * @li @a IX_ETH_ACC_SUCCESS
 * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid
 *
 * <hr>
 */
PUBLIC IxEthAccStatus
ixEthAccPortEnabledQuery(IxEthAccPortId portId, BOOL *enabled);

/**
 * @ingroup IxEthAcc
 *
 * @fn ixEthAccPortPromiscuousModeClear(IxEthAccPortId portId)
 *
 * @brief Put the Ethernet MAC device in non-promiscuous mode.
 * 
 * In non-promiscuous mode the MAC filters all frames other than 
 * destination MAC address which matches the following criteria:
 * @li Unicast address provisioned via @a ixEthAccUnicastMacAddressSet
 * @li All broadcast frames.
 * @li Multicast addresses provisioned via @a ixEthAccMulticastAddressJoin
 *
 * Other functions modify the MAC filtering
 *
 * @li @a ixEthAccPortMulticastAddressJoinAll() - all multicast
 *     frames are forwarded to the application
 * @li @a ixEthAccPortMulticastAddressLeaveAll() - rollback the
 *     effects of @a ixEthAccPortMulticastAddressJoinAll()
 * @li @a ixEthAccPortMulticastAddressLeave() - unprovision a new 
 *     filtering address
 * @li @a ixEthAccPortMulticastAddressJoin() - provision a new 
 *     filtering address
 * @li @a ixEthAccPortPromiscuousModeSet() - all frames are 
 *     forwarded to the application regardless of the multicast 
 *     address provisioned
 * @li @a ixEthAccPortPromiscuousModeClear() - frames are forwarded 
 *     to the application following the multicast address provisioned
 *
 * In all cases, unicast and broadcast addresses are forwarded to 
 * the application.
 *
 * @li Reentrant    - yes
 * @li ISR Callable - no
 * 
 * @sa ixEthAccPortPromiscuousModeSet
 * 
 * @param portId @ref IxEthAccPortId [in] - Ethernet port id.
 * 
 * @return IxEthAccStatus 
 * @li @a IX_ETH_ACC_SUCCESS
 * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
 *
 * <hr>
 */
PUBLIC IxEthAccStatus ixEthAccPortPromiscuousModeClear(IxEthAccPortId portId);


/**
 * @ingroup IxEthAcc
 *
 * @fn  ixEthAccPortPromiscuousModeSet(IxEthAccPortId portId)
 *
 * @brief Put the MAC device in promiscuous mode.
 * 
 * If the device is in promiscuous mode then all all received frames shall be forwared
 * to the NPE for processing.
 *
 * Other functions modify the MAC filtering
 *
 * @li @a ixEthAccPortMulticastAddressJoinAll() - all multicast
 *     frames are forwarded to the application
 * @li @a ixEthAccPortMulticastAddressLeaveAll() - rollback the
 *     effects of @a ixEthAccPortMulticastAddressJoinAll()
 * @li @a ixEthAccPortMulticastAddressLeave() - unprovision a new 
 *     filtering address
 * @li @a ixEthAccPortMulticastAddressJoin() - provision a new 
 *     filtering address
 * @li @a ixEthAccPortPromiscuousModeSet() - all frames are 
 *     forwarded to the application regardless of the multicast 
 *     address provisioned
 * @li @a ixEthAccPortPromiscuousModeClear() - frames are forwarded 
 *     to the application following the multicast address provisioned
 *
 * In all cases, unicast and broadcast addresses are forwarded to 
 * the application.