ixethacc.h

u-boot 源代码

 *      @li 0x01 - IEEE802.3 - Ethernet (Rx) / IEEE802.3 - Ethernet (Tx)
 *      @li 0x02 - IEEE802.11 AP -> STA (Rx) / IEEE802.11 STA -> AP (Tx)
 *      @li 0x03 - IEEE802.11 AP -> AP (Rx) / IEEE802.11 AP->AP (Tx)
 *
 * @sa IX_ETHACC_NE_FLAGS
 *
 */
#define IX_ETHACC_NE_LINKMASK       (0x3 << 4)

/**
 * @ingroup IxEthAcc
 *
 * @def IX_ETHACC_NE_STMASK
 *
 * @brief This mask defines if a received frame is a Spanning Tree frame.
 *
 * This mask applies to @a IX_ETHACC_NE_FLAGS.
 * On rx direction, it defines if a received if frame is a Spanning Tree frame.
 * Setting this fkag on transmit direction overrides the port settings 
 * regarding the VLAN options and 
 *
 * @sa IX_ETHACC_NE_FLAGS
 *
 */
#define IX_ETHACC_NE_STMASK         (0x1 << 6)

/**
 * @ingroup IxEthAcc
 *
 * @def IX_ETHACC_NE_FILTERMASK
 *
 * @brief This bit indicates whether a frame has been filtered by the Rx service.
 *
 * This mask applies to @a IX_ETHACC_NE_FLAGS.
 * Certain frames, which should normally be fully filtered by the NPE to due
 * the destination MAC address being on the same segment as the Rx port are
 * still forwarded to the XScale (although the payload is invalid) in order
 * to learn the MAC address of the transmitting station, if this is unknown.
 * Normally EthAcc will filter and recycle these framess internally and no
 * frames with the FILTER bit set will be received by the client.
 *
 * @sa IX_ETHACC_NE_FLAGS
 *
 */
#define IX_ETHACC_NE_FILTERMASK     (0x1 << 7)

/**
 * @ingroup IxEthAcc
 *
 * @def IX_ETHACC_NE_PORTMASK
 *
 * @brief This mask defines the rule to transmit a frame
 *
 * This mask defines the rule to transmit a frame. When set, a frame
 * is transmitted to the destination port as set by the macro
 * @a IX_ETHACC_NE_DESTPORTID. If not set, the destination port 
 * is searched using the destination MAC address.
 *
 * @note This flag is meaningful only for multiport Network Engines.
 * 
 * @sa IX_ETHACC_NE_FLAGS 
 * @sa IX_ETHACC_NE_DESTPORTID
 *
 */
#define IX_ETHACC_NE_PORTOVERMASK   (0x1 << 8)

/**
 * @ingroup IxEthAcc
 *
 * @def IX_ETHACC_NE_TAGMODEMASK
 *
 * @brief This mask defines the tagging rules to apply to a transmit frame.
 *
 * This mask defines the tagging rules to apply to a transmit frame
 * regardless of the default setting for a port. When used together 
 * with @a IX_ETHACC_NE_TAGOVERMASK and when set, the 
 * frame will be tagged prior to transmission. When not set,
 * the frame will be untagged prior to transmission. This is accomplished
 * irrespective of the Egress tagging rules, constituting a per-frame override.
 *
 * @sa IX_ETHACC_NE_FLAGS
 * @sa IX_ETHACC_NE_TAGOVERMASK 
 *
 */
#define IX_ETHACC_NE_TAGMODEMASK    (0x1 << 9)

/**
 * @ingroup IxEthAcc
 *
 * @def IX_ETHACC_NE_TAGOVERMASK
 *
 * @brief This mask defines the rule to transmit a frame
 *
 * This mask defines the rule to transmit a frame. When set, the
 * default transmit rules of a port are overriden.
 * When not set, the default rules as set by @ref IxEthDB should apply.
 *
 * @sa IX_ETHACC_NE_FLAGS
 * @sa IX_ETHACC_NE_TAGMODEMASK
 *
 */
#define IX_ETHACC_NE_TAGOVERMASK    (0x1 << 10)

/**
 * @ingroup IxEthAcc
 *
 * @def IX_ETHACC_NE_VLANENABLEMASK
 *
 * @brief This mask defines if a frame is a VLAN frame or not
 *
 * When set, frames undergo normal VLAN processing on the Tx path
 * (membership filtering, tagging, tag removal etc). If this flag is
 * not set, the frame is considered to be a regular non-VLAN frame
 * and no VLAN processing will be performed.
 *
 * Note that VLAN-enabled NPE images will always set this flag in all
 * Rx frames, and images which are not VLAN enabled will clear this
 * flag for all received frames.
 *
 * @sa IX_ETHACC_NE_FLAGS
 *
 */
#define IX_ETHACC_NE_VLANENABLEMASK (0x1 << 14)

/**
 * @ingroup IxEthAcc
 *
 * @def IX_ETHACC_NE_NEWSRCMASK
 *
 * @brief This mask defines if a received frame has been learned.
 *
 * This mask defines if the source MAC address of a frame is 
 * already known. If the bit is set, the source MAC address was
 * unknown to the NPE at the time the frame was received.
 *
 * @sa IX_ETHACC_NE_FLAGS 
 *
 */
#define IX_ETHACC_NE_NEWSRCMASK     (0x1 << 15)

/**
 * @ingroup IxEthAcc
 *
 * @brief This defines the recommanded minimum size of MBUF's submitted
 * to the frame receive service.
 *
 */
#define IX_ETHACC_RX_MBUF_MIN_SIZE (2048)

/**
 * @ingroup IxEthAcc
 *
 * @brief This defines the highest MII address of any attached PHYs 
 * 
 * The maximum number for PHY address is 31, add on for range checking.
 *
 */
#define IXP425_ETH_ACC_MII_MAX_ADDR   32

/**
 * @ingroup IxEthAcc
 *
 * @fn ixEthAccInit(void)
 * 
 * @brief Initializes the IXP400 Ethernet Access Service.
 * 
 * @li Reentrant    - no
 * @li ISR Callable - no
 * 
 * This should be called once per module initialization.
 * @pre
 *   The NPE must first be downloaded with the required microcode which supports all
 *   required features.
 *
 * @return IxEthAccStatus
 * @li @a IX_ETH_ACC_SUCCESS
 * @li @a IX_ETH_ACC_FAIL	:  Service has failed to initialize.
 *
 * <hr>
 */
PUBLIC IxEthAccStatus ixEthAccInit(void);


/**
 * @ingroup IxEthAcc
 *
 * @fn ixEthAccUnload(void)
 * 
 * @brief Unload the Ethernet Access Service.
 * 
 * @li Reentrant    - no
 * @li ISR Callable - no
 *
 * @return void 
 *
 * <hr>
 */
PUBLIC void ixEthAccUnload(void);

/**
 * @ingroup IxEthAcc
 *
 * @fn ixEthAccPortInit( IxEthAccPortId portId)
 *
 * @brief Initializes an NPE/Ethernet MAC Port.
 *
 * The NPE/Ethernet port initialisation includes the following steps
 * @li Initialize the NPE/Ethernet MAC hardware.
 * @li Verify NPE downloaded and operational.
 * @li The NPE shall be available for usage once this API returns.
 * @li Verify that the Ethernet port is present before initializing
 *
 * @li Reentrant    - no
 * @li ISR Callable - no
 *
 * This should be called once per mac device.
 * The NPE/MAC shall be in disabled state after init.
 *
 * @pre
 *   The component must be initialized via @a ixEthAccInit
 *   The NPE must first be downloaded with the required microcode which supports all
 *   required features.
 *
 * Dependant on Services: (Must be initialized before using this service may be initialized)
 * 	ixNPEmh - NPE Message handling service.
 * 	ixQmgr	- Queue Manager component.
 *
 * @param portId  @ref IxEthAccPortId [in]
 *
 * @return IxEthAccStatus
 * @li @a IX_ETH_ACC_SUCCESS: if the ethernet port is not present, a warning is issued.
 * @li @a IX_ETH_ACC_FAIL : The NPE processor has failed to initialize.
 * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 *
 * <hr>
 */
PUBLIC IxEthAccStatus ixEthAccPortInit(IxEthAccPortId portId);


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

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

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


/**
 * @ingroup IxEthAcc
 *
 * @fn ixEthAccPortTxFrameSubmit( 
    IxEthAccPortId portId,
    IX_OSAL_MBUF *buffer, 
    IxEthAccTxPriority priority)
 * 
 * @brief This function shall be used to submit MBUFs buffers for transmission on a particular MAC device. 
 *
 * When the frame is transmitted, the buffer shall be returned thru the 
 * callback @a IxEthAccPortTxDoneCallback.
 *
 * In case of over-submitting, the order of the frames on the 
 * network may be modified.
 *
 * Buffers shall be not queued for transmission if the port is disabled.
 * The port can be enabled using @a ixEthAccPortEnable
 *
 * 
 * @li Reentrant    - yes
 * @li ISR Callable - yes
 *
 *
 * @pre 
 *  @a ixEthAccPortTxDoneCallbackRegister must be called to register a function to allow this service to
 *   return the buffer to the calling service. 
 * 
 * @note 
 *  If the buffer submit fails for any reason the user has retained ownership of the buffer.
 *
 * @param portId @ref IxEthAccPortId [in] - MAC port ID to transmit Ethernet frame on.
 * @param buffer @ref IX_OSAL_MBUF [in] - pointer to an MBUF formatted buffer. Chained buffers are supported for transmission.
 *             Chained packets are not supported and the field IX_OSAL_MBUF_NEXT_PKT_IN_CHAIN_PTR is ignored. 
 * @param priority @ref IxEthAccTxPriority [in]
 *
 * @return IxEthAccStatus
 * @li @a IX_ETH_ACC_SUCCESS
 * @li @a IX_ETH_ACC_FAIL  : Failed to queue frame for transmission. 
 * @li @a IX_ETH_ACC_INVALID_PORT : portId is invalid.
 * @li @a IX_ETH_ACC_PORT_UNINITIALIZED : portId is un-initialized
 *
 * <hr>
 */

PUBLIC IxEthAccStatus ixEthAccPortTxFrameSubmit( 
    IxEthAccPortId portId,
    IX_OSAL_MBUF *buffer, 
    IxEthAccTxPriority priority);

/**
 * @ingroup IxEthAcc
 *
 * @brief Function prototype for Ethernet Tx Buffer Done callback. Registered 
 *  via @a ixEthAccTxBufferDoneCallbackRegister 
 * 
 * This function is called once the previously submitted buffer is no longer required by this service.
 * It may be returned upon successful transmission of the frame or during the shutdown of 
 * the port prior to the transmission of a queued frame.
 * The calling of this registered function is not a guarantee of successful transmission of the buffer.
 *
 *  
 * @li Reentrant    - yes , The user provided function should be reentrant.
 * @li ISR Callable - yes , The user provided function must be callable from an ISR.
 *
 *
 * <b>Calling Context </b>: 
 * @par
 *   This callback is called in the context of the queue manager dispatch loop @a ixQmgrgrDispatcherLoopRun
 *   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 ixEthAccPortTxDoneCallbackRegister. It allows the same callback to be used for multiple MACs.
 * @param mbuf @ref IX_OSAL_MBUF [in] - Pointer to the Tx mbuf descriptor. 
 * 
 * @return void
 *
 * @note
 * The field IX_OSAL_MBUF_NEXT_PKT_IN_CHAIN_PTR is modified by the access layer and reset to NULL.
 *
 * <hr>
 */
typedef void (*IxEthAccPortTxDoneCallback) ( UINT32 callbackTag, IX_OSAL_MBUF *buffer );



/**
 * @ingroup IxEthAcc
 *
 * @fn ixEthAccPortTxDoneCallbackRegister( IxEthAccPortId portId, 
					   IxEthAccPortTxDoneCallback txCallbackFn, 
 					   UINT32 callbackTag)
 *
 * @brief Register a callback function to allow 
 * the transmitted buffers to return to the user.
 * 
 * This function registers the transmit buffer done function callback for a particular port.
 *
 * The registered callback function is called once the previously submitted buffer is no longer required by this service.
 * It may be returned upon successful transmission of the frame or  shutdown of port prior to submission.
 * The calling of this registered function is not a guarantee of successful transmission of the buffer.
 *
 * If called several times the latest callback shall be registered for a particular port.
 *
 * @li Reentrant    - yes
 * @li ISR Callable - yes
 *
 * @pre
 *	The port must be initialized via @a ixEthAccPortInit
 *
 *
 * @param portId @ref IxEthAccPortId [in] - Register callback for a particular MAC device.
 * @param txCallbackFn @ref IxEthAccPortTxDoneCallback [in] - Function to be called to return transmit buffers to the user.
 * @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
ixEthAccPortTxDoneCallbackRegister(IxEthAccPortId portId,
								   IxEthAccPortTxDoneCallback txCallbackFn,
								   UINT32 callbackTag);



/**
 * @ingroup IxEthAcc
 *
 * @brief Function prototype for Ethernet Frame Rx callback. Registered via @a ixEthAccPortRxCallbackRegister 
 * 
 * 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 frames to the user level
 * via the provided function. The invocation shall be made for each
 * frame 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 ixQmgrgrDispatcherLoopRun