ixethdb.h

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

 * It has 12 bits and allow the id entification of 4096 (2^12) VLANs. Of the 4096 possible VIDs, a VID of 0 
 * is used to identify priority frames and value 4095 (FFF) is reserved, so the maximum possible VLAN 
 * configurations are 4,094.
 * 
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @retval IX_ETH_DB_SUCCESS operation completed successfully
 * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
 * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 * @retval IX_ETH_DB_INVALID_VLAN <i>vlanTag</i> argument does not parse to a valid 802.1Q VLAN tag
 *
 * @note a VLAN ID value of 0 indicates that the port is not part of any VLAN
 * @note the value of the cannonical frame indicator (CFI) field is ignored, the 
 * field being used only in frame tagging operations
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBPortVlanTagSet(IxEthDBPortId portID, IxEthDBVlanTag vlanTag);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPortVlanTagGet(IxEthDBPortId portID, IxEthDBVlanTag *vlanTag)
 *
 * @brief Retrieves the default 802.1Q port VLAN tag for a given port (see also @ref ixEthDBPortVlanTagSet)
 *
 * @param portID @ref IxEthDBPortId [in] - ID of the port to retrieve the default VLAN tag from
 * @param vlanTag @ref IxEthDBVlanTag [out] - location to write the default port 802.1Q VLAN tag to
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @retval IX_ETH_DB_SUCCESS operation completed successfully
 * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
 * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 * @retval IX_ETH_DB_INVALID_ARG invalid vlanTag pointer
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBPortVlanTagGet(IxEthDBPortId portID, IxEthDBVlanTag *vlanTag);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBVlanTagSet(IxEthDBMacAddr *macAddr, IxEthDBVlanTag vlanTag)
 *
 * @brief Sets the 802.1Q VLAN tag for a database record
 *
 * @param macAddr MAC address
 * @param vlanTag 802.1Q VLAN tag
 *
 * This function is used together with @ref ixEthDBVlanTagGet to provide MAC-based VLAN classification support.
 * Please note that the bridging application must contain specific code to make use of this feature (see below).
 * 
 * VLAN tags can be set only in IX_ETH_DB_FILTERING_RECORD or IX_ETH_DB_FILTERING_VLAN_RECORD type records.
 * If to an IX_ETH_DB_FILTERING_RECORD type record is added a VLAN tag the record type is automatically
 * changed to IX_ETH_DB_FILTERING_VLAN_RECORD. Once this has occurred the record type will never
 * revert to a non-VLAN type (unless deleted and re-added).
 *
 * Record types used for different purposes (such as IX_ETH_DB_WIFI_RECORD) will be ignored by
 * this function.
 *
 * After using this function to associate a VLAN ID with a MAC address the VLAN ID can be extracted knowing the
 * MAC address using @ref ixEthDBVlanTagGet. This mechanism can be used to implement MAC-based VLAN classification
 * if a bridging application searches for the VLAN tag when receiving a frame based on the source MAC address 
 * (contained in the <i>ixp_ne_src_mac</i> field of the buffer header).
 * If found in the database, the application can instruct the NPE to tag the frame by writing the VLAN tag
 * in the <i>ixp_ne_vlan_tci</i> field of the buffer header. This way the NPE will inspect the Egress tagging
 * rule associated with the given VLAN ID on the Tx port and tag the frame if Egress tagging on the VLAN is
 * allowed. Additionally, Egress tagging can be forced by setting the <i>ixp_ne_tx_flags.tag_over</i> and 
 * <i>ixp_ne_tx_flags.tag_mode</i> flags in the buffer header.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @note this function will <b>not</b> add a filtering record, it can only be used to update an existing one
 * 
 * @retval IX_ETH_DB_SUCCESS operation completed successfully
 * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> pointer
 * @retval IX_ETH_DB_NO_SUCH_ADDR a filtering record with the specified MAC address was not found
 * @retval IX_ETH_DB_INVALID_VLAN <i>vlanTag</i> argument does not parse to a valid 802.1Q VLAN tag
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBVlanTagSet(IxEthDBMacAddr *macAddr, IxEthDBVlanTag vlanTag);

/**
 * @ingroup IxEthDB
 *
 * @fn ixEthDBVlanTagGet(IxEthDBMacAddr *macAddr, IxEthDBVlanTag *vlanTag)
 *
 * @brief Retrieves the 802.1Q VLAN tag from a database record given the record MAC address
 *
 * @param macAddr MAC address
 * @param vlanTag location to write the record 802.1Q VLAN tag to
 *
 * @note VLAN tags can be retrieved only from IX_ETH_DB_FILTERING_VLAN_RECORD type records
 * 
 * This function is used together with ixEthDBVlanTagSet to provide MAC-based VLAN classification support.
 * Please note that the bridging application must contain specific code to make use of this feature (see @ref ixEthDBVlanTagSet).
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @retval IX_ETH_DB_SUCCESS operation completed successfully
 * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> or <i>vlanTag</i> pointer
 * @retval IX_ETH_DB_NO_SUCH_ADDR a filtering record with the specified MAC address was not found
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBVlanTagGet(IxEthDBMacAddr *macAddr, IxEthDBVlanTag *vlanTag);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPortVlanMembershipAdd(IxEthDBPortId portID, IxEthDBVlanId vlanID)
 *
 * @brief Adds a VLAN ID to a port's VLAN membership table
 *
 * Adding a VLAN ID to a port's VLAN membership table will cause frames tagged with the specified 
 * VLAN ID to be accepted by the frame filter, if Ingress VLAN membership filtering is enabled.
 * 
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID @ref IxEthDBPortId [in] - ID of the port to add the VLAN ID membership to
 * @param vlanID @ref IxEthDBVlanId [in] - VLAN ID to be added to the port membership table
 *
 * @retval IX_ETH_DB_SUCCESS operation completed successfully
 * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
 * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 * @retval IX_ETH_DB_INVALID_VLAN vlanID is not a valid VLAN ID
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 * @retval IX_FAIL unknown OS or NPE communication error
 *
 * @note A port's default VLAN ID is always in its own membership table, hence there
 * is no need to explicitly add it using this function (although it is not an error
 * to do so)
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBPortVlanMembershipAdd(IxEthDBPortId portID, IxEthDBVlanId vlanID);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPortVlanMembershipRangeAdd(IxEthDBPortId portID, IxEthDBVlanId vlanIDMin, IxEthDBVlanId vlanIDMax)
 *
 * @brief Adds a VLAN ID range to a port's VLAN membership table
 *
 * All the VLAN IDs in the specified range will be added to the port VLAN
 * membership table, including the range start and end VLAN IDs. Tagged frames with
 * VLAN IDs in the specified range will be accepted by the frame filter, if Ingress VLAN
 * membership filtering is enabled.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID @ref IxEthDBPortId [in] - port ID to add the VLAN membership range into
 * @param vlanIDMin @ref IxEthDBVlanId [in] - start of the VLAN ID range
 * @param vlanIDMax @ref IxEthDBVlanId [in] - end of the VLAN ID range
 *
 * @retval IX_ETH_DB_SUCCESS operation completed successfully
 * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
 * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 * @retval IX_ETH_DB_INVALID_VLAN the specified VLAN IDs are invalid or do not constitute a range
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 * @retval IX_FAIL unknown OS or NPE communication error
 *
 * @note Is is valid to use the same VLAN ID for both vlanIDMin and vlanIDMax, in which case this
 * function will behave as @ref ixEthDBPortVlanMembershipAdd
 *
 * @note A port's default VLAN ID is always in its own membership table, hence there is no need
 * to explicitly add it using this function (although it is not an error to do so)
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBPortVlanMembershipRangeAdd(IxEthDBPortId portID, IxEthDBVlanId vlanIDMin, IxEthDBVlanId vlanIDMax);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPortVlanMembershipRemove(IxEthDBPortId portID, IxEthDBVlanId vlanID)
 *
 * @brief Removes a VLAN ID from a port's VLAN membership table
 *
 * Frames tagged with a VLAN ID which is not in a port's VLAN membership table
 * will be discarded by the frame filter, if Ingress membership filtering is enabled.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID @ref IxEthDBPortId [in] - ID of the port to remove the VLAN ID membership from
 * @param vlanID @ref IxEthDBVlanId [in] - VLAN ID to be removed from the port membership table
 *
 * @retval IX_ETH_DB_SUCCESS operation completed successfully
 * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
 * @retval IX_ETH_DB_INVALID_VLAN vlanID is not a valid VLAN ID
 * @retval IX_ETH_DB_NO_PERMISSION attempted to remove the default VLAN ID
 * from the port membership table (vlanID was set to the default port VLAN ID)
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 * @retval IX_FAIL unknown OS or NPE communication error
 *
 * @note A port's default VLAN ID cannot be removed from the port's membership
 * table; attempting it will return IX_ETH_DB_NO_PERMISSION
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBPortVlanMembershipRemove(IxEthDBPortId portID, IxEthDBVlanId vlanID);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPortVlanMembershipRangeRemove(IxEthDBPortId portID, IxEthDBVlanId vlanIDMin, IxEthDBVlanId vlanIDMax)
 *
 * @brief Removes a VLAN ID range from a port's VLAN membership table
 *
 * All the VLAN IDs in the specified range will be removed from the port VLAN
 * membership table, including the range start and end VLAN IDs. Tagged frames
 * with VLAN IDs in the range will be discarded by the frame filter, if Ingress
 * membership filtering is enabled.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID @ref IxEthDBPortId [in] - ID of the port to remove the VLAN membership range from
 * @param vlanIDMin @ref IxEthDBVlanId [in] - start of the VLAN ID range
 * @param vlanIDMax @ref IxEthDBVlanId [in] - end of the VLAN ID range
 *
 * @retval IX_ETH_DB_SUCCESS operation completed successfully
 * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
 * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 * @retval IX_ETH_DB_INVALID_VLAN the specified VLAN IDs are invalid or do not constitute a range
 * @retval IX_ETH_DB_NO_PERMISSION attempted to remove the default VLAN ID
 * from the port membership table (both vlanIDMin and vlanIDMax were set to the default port VLAN ID)
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 * @retval IX_FAIL unknown OS or NPE communication error
 *
 * @note Is is valid to use the same VLAN ID for both vlanIDMin and vlanIDMax, in which case
 * function will behave as @ref ixEthDBPortVlanMembershipRemove
 *
 * @note If the given range overlaps the default port VLAN ID this function
 * will remove all the VLAN IDs in the range except for the port VLAN ID from its 
 * own membership table. This situation will be silently dealt with (no error message
 * will be returned) as long as the range contains more than one value (i.e. at least 
 * one other value, apart from the default port VLAN ID). If the function is called 
 * with the vlanIDMin and vlanIDMax parameters both set to the port default VLAN ID, the 
 * function will infer that an attempt was specifically made to remove the default port 
 * VLAN ID from the port membership table, in which case the return value will be 
 * IX_ETH_DB_NO_PERMISSION.
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBPortVlanMembershipRangeRemove(IxEthDBPortId portID, IxEthDBVlanId vlanIDMin, IxEthDBVlanId vlanIDMax);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPortVlanMembershipSet(IxEthDBPortId portID, IxEthDBVlanSet vlanSet)
 *
 * @brief Sets a port's VLAN membership table
 *
 * Sets a port's VLAN membership table from a complete VLAN table containing all the possible
 * 4096 VLAN IDs. The table format is an array containing 4096 bits (512 bytes), where each bit
 * indicates whether the VLAN at that bit index is in the port's membership list (if set) or
 * not (unset).
 *
 * The bit at index 0, indicating VLAN ID 0, indicates no VLAN membership and therefore no
 * other bit must be set if bit 0 is set.
 *
 * The bit at index 4095 is reserved and should never be set (it will be ignored if set).
 *
 * The bit referencing the same VLAN ID as the default port VLAN ID should always be set, as 
 * the membership list must contain at least the default port VLAN ID.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID @ref IxEthDBPortId [in] - port ID to set the VLAN membership table to
 * @param vlanSet @ref IxEthDBVlanSet [in] - pointer to the VLAN membership table
 * 
 * @retval IX_ETH_DB_SUCCESS operation completed successfully
 * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
 * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 * @retval IX_ETH_DB_INVALID_ARG invalid <i>vlanSet</i> pointer
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 * @retval IX_FAIL unknown OS or NPE communication error
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBPortVlanMembershipSet(IxEthDBPortId portID, IxEthDBVlanSet vlanSet);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPortVlanMembershipGet(IxEthDBPortId portID, IxEthDBVlanSet vlanSet)
 *
 * @brief Retrieves a port's VLAN membership table
 *