ixethdb.h

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

 * If no match is found the function returns IX_ETH_DB_NO_SUCH_ADDR. 
 * The portID is only valid if the function finds a match.
 *
 * - Reentrant      - yes
 * - ISR Callable   - no
 *
 * @retval IX_ETH_DB_SUCCESS the MAC address was found
 * @retval IX_ETH_DB_NO_SUCH_ADDR the MAC address was not found
 * @retval IX_ETH_DB_INVALID_ARG invalid macAddr or portID pointer argument(s)
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBFilteringPortUpdatingSearch(IxEthDBPortId *portID, IxEthDBMacAddr *macAddr);

/**
 * @ingroup IxEthDB
 *
 * @def IX_ETH_DB_MAINTENANCE_TIME
 *
 * @brief The @ref ixEthDBDatabaseMaintenance must be called by the user at a frequency of 
 * IX_ETH_DB_MAINTENANCE_TIME
 *
 */
#define IX_ETH_DB_MAINTENANCE_TIME (1 * 60) /* 1 Minute */

/**
 * @ingroup IxEthDB
 *
 * @def IX_ETH_DB_LEARNING_ENTRY_AGE_TIME
 *
 * @brief The define specifies the filtering database age entry time. Static entries older than
 * IX_ETH_DB_LEARNING_ENTRY_AGE_TIME +/- IX_ETH_DB_MAINTENANCE_TIME shall be removed.
 *
 */
#define IX_ETH_DB_LEARNING_ENTRY_AGE_TIME (15 * 60 ) /* 15 Mins */

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPortAgingDisable(IxEthDBPortId portID)
 *
 * @brief Disable the aging function for a specific port
 *
 * @param portID @ref IxEthDBPortId [in] - port ID to disable aging on
 *
 * - Reentrant    - yes
 * - ISR Callable - no
 *
 * @retval IX_ETH_DB_SUCCESS aging disabled successfully
 * @retval IX_ETH_DB_INVALID_PORT portID is invalid
 * @retval IX_ETH_DB_PORT_UNINITIALIZED port ID is not initialized
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE learning feature is disabled
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBPortAgingDisable(IxEthDBPortId portID);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPortAgingEnable(IxEthDBPortId portID)
 *
 * @brief Enable the aging function for a specific port
 * 
 * Enables the aging of dynamic MAC address entries stored in the learning/filtering database
 * 
 * @note The aging function relies on the @ref ixEthDBDatabaseMaintenance being called with a period of 
 * @ref IX_ETH_DB_MAINTENANCE_TIME seconds.
 *
 * - Reentrant    - yes
 * - ISR Callable - no
 *
 * @param portID @ref IxEthDBPortId [in] - port ID to enable aging on
 *
 * @retval IX_ETH_DB_SUCCESS aging enabled successfully
 * @retval IX_ETH_DB_INVALID_PORT portID is invalid
 * @retval IX_ETH_DB_PORT_UNINITIALIZED port ID is not initialized
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE learning feature is disabled
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBPortAgingEnable(IxEthDBPortId portID);

/**
 * @ingroup IxEthDB
 *
 * @fn void ixEthDBDatabaseMaintenance(void)
 *
 * @brief Performs a maintenance operation on the Ethernet learning/filtering database
 * 
 * In order to perform a database maintenance this function must be called every
 * @ref IX_ETH_DB_MAINTENANCE_TIME seconds. It should be called regardless of whether learning is
 * enabled or not.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 * 
 * @note this function call will be ignored if the learning feature is disabled
 */
IX_ETH_DB_PUBLIC 
void ixEthDBDatabaseMaintenance(void);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBFilteringDatabaseShow(IxEthDBPortId  portID)
 *
 * @brief This function displays the Mac Ethernet MAC address filtering tables.
 *
 * It displays the MAC address, port ID, entry type (dynamic/static),and age for 
 * the given port ID.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID @ref IxEthDBPortId [in] - port ID to display the MAC address entries
 *
 * @retval IX_ETH_DB_SUCCESS operation completed successfully
 * @retval IX_ETH_DB_INVALID_PORT portID is invalid
 * @retval IX_ETH_DB_PORT_UNINITIALIZED port ID is not initialized
 * @retval IX_ETH_DB_FAIL record browser failed due to an internal busy or lock condition
 *
 * @note this function is deprecated and kept for compatibility reasons; use @ref ixEthDBFilteringDatabaseShowRecords instead
 * 
 * @see ixEthDBFilteringDatabaseShowRecords
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBFilteringDatabaseShow(IxEthDBPortId portID);

/** 
 * @ingroup IxEthDB
 *
 * @fn void ixEthDBFilteringDatabaseShowAll(void)
 *
 * @brief Displays the MAC address recorded in the filtering database for all registered
 * ports (see IxEthDBPortDefs.h), grouped by port ID.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @retval void
 *
 * @note this function is deprecated and kept for compatibility reasons; use @ref ixEthDBFilteringDatabaseShowRecords instead
 * 
 * @see ixEthDBFilteringDatabaseShowRecords
 */
IX_ETH_DB_PUBLIC 
void ixEthDBFilteringDatabaseShowAll(void);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBFilteringDatabaseShowRecords(IxEthDBPortId portID, IxEthDBRecordType recordFilter)
 *
 * @brief This function displays per port database records, given a record type filter
 *
 * The supported record type filters are:
 * 
 * - IX_ETH_DB_FILTERING_RECORD - displays the non-VLAN filtering records (MAC address, age, static/dynamic)
 * - IX_ETH_DB_FILTERING_VLAN_RECORD - displays the VLAN filtering records (MAC address, age, static/dynamic, VLAN ID, CFI, QoS class)
 * - IX_ETH_DB_FILTERING_RECORD | IX_ETH_DB_FILTERING_VLAN_RECORD - displays the previous two types of records
 * - IX_ETH_DB_WIFI_RECORD - displays the WiFi header conversion records (MAC address, optional gateway MAC address) and WiFi header conversion parameters (BBSID, Duration/ID)
 * - IX_ETH_DB_FIREWALL_RECORD - displays the firewall MAC address table and firewall operating mode (white list/black list)
 * - IX_ETH_DB_ALL_RECORD_TYPES - displays all the record types
 * - IX_ETH_DB_NO_RECORD_TYPE - displays only the port status (no records are displayed)
 * 
 * Additionally, the status of each port will be displayed, containg the following information: type, capabilities, enabled status, 
 * aging enabled status, group membership and maximum frame size.
 *
 * The port ID can either be an actual port or IX_ETH_DB_ALL_PORTS, in which case the requested information
 * will be displayed for all the ports (grouped by port)
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID ID of the port to display information on (use IX_ETH_DB_ALL_PORTS for all the ports)
 * @param recordFilter record type filter
 *
 * @retval IX_ETH_DB_SUCCESS operation completed successfully
 * @retval IX_ETH_DB_INVALID_PORT portID is invalid
 * @retval IX_ETH_DB_PORT_UNINITIALIZED port ID is not initialized
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBFilteringDatabaseShowRecords(IxEthDBPortId portID, IxEthDBRecordType recordFilter);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPortDependencyMapSet(IxEthDBPortId portID, IxEthDBPortMap dependencyPortMap)
 *
 * @brief Sets the dependency port map for a port
 *
 * @param portID ID of the port to set the dependency map to
 * @param dependencyPortMap new dependency map (as bitmap, each bit set indicates a port being included)
 *
 * This function is used to share filtering information between ports.
 * By adding a port into another port's dependency map the target port
 * filtering data will import the filtering data from the port it depends on.
 * Any changes to filtering data for a port - such as adding, updating or removing records -
 * will trigger updates in the filtering information for all the ports depending on
 * on the updated port.
 *
 * For example, if ports 2 and 3 are set in the port 0 dependency map the filtering
 * information for port 0 will also include the filtering information from ports 2 and 3.
 * Adding a record to port 2 will also trigger an update not only on port 2 but also on
 * port 0.
 *
 * The dependency map is a 256 bit array where each bit corresponds to a port corresponding to the
 * bit offset (bit 0 - port 0, bit 1 - port 1 etc). Setting a bit to 1 indicates that the corresponding
 * port is the port map. For example, a dependency port map of 0x14 consists in the ports with IDs 2 and 4.
 * Note that the last bit (offset 255) is reserved and should never be set (it will be automatically
 * cleared by the function).
 *
 * By default, each port has a dependency port map consisting only of itself, i.e. 
 *
 * @verbatim
    IxEthDBPortMap portMap;
    
    // clear all ports from port map
    memset(portMap, 0, sizeof (portMap)); 
    
    // include portID in port map 
    portMap[portID / 8] = 1 << (portID % 8);
   @endverbatim
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @note Setting dependency maps is useful for NPE ports, which benefit from automatic updates
 * of filtering information. Setting dependency maps for user-defined ports is not an error
 * but will have no actual effect.
 * 
 * @note Including a port in its own dependency map is not compulsory, however note that
 * in this case updating the port will not trigger an update on the port itself, which 
 * might not be the intended behavior
 *
 * @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>dependencyPortMap</i> pointer
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE Filtering is not available or not enabled for the port
 */
IX_ETH_DB_PUBLIC
IxEthDBStatus ixEthDBPortDependencyMapSet(IxEthDBPortId portID, IxEthDBPortMap dependencyPortMap);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPortDependencyMapGet(IxEthDBPortId portID, IxEthDBPortMap dependencyPortMap)
 *
 * @brief Retrieves the dependency port map for a port
 *
 * @param portID ID of the port to set the dependency map to
 * @param dependencyPortMap location where the port dependency map is to be copied
 *
 * This function will copy the port dependency map to a user specified location.
 *
 * - 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 <i>dependencyPortMap</i> pointer
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE Filtering is not available or not enabled for the port
 */
IX_ETH_DB_PUBLIC
IxEthDBStatus ixEthDBPortDependencyMapGet(IxEthDBPortId portID, IxEthDBPortMap dependencyPortMap);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPortVlanTagSet(IxEthDBPortId portID, IxEthDBVlanTag vlanTag)
 *
 * @brief Sets the default 802.1Q VLAN tag for a given port
 *
 * @param portID @ref IxEthDBPortId [in] - ID of the port to set the default VLAN tag to
 * @param vlanTag @ref IxEthDBVlanTag [in] - default 802.1Q VLAN tag
 *
 * The tag format has 16 bits and it is defined in the IEEE802.1Q specification.
 * This tag will be used for tagging untagged frames (if enabled) and classifying
 * unexpedited traffic into an internal traffic class (using the user priority field).
 *
 * <table border="1"> <caption> 802.1Q tag format </caption>
 *    <tr> <td>  <b> 3 bits   <td> <b> 1 bit <td> <b> 12 bits </b>
 *    <tr> <td> user priority <td>  CFI  <td>   VID
 * </table>
 *
 * User Priority : Defines user priority, giving eight (2^3) priority levels. IEEE 802.1P defines 
 * the operation for these 3 user priority bits
 * 
 * CFI : Canonical Format Indicator is always set to zero for Ethernet switches. CFI is used for 
 * compatibility reason between Ethernet type network and Token Ring type network. If a frame received 
 * at an Ethernet port has a CFI set to 1, then that frame should not be forwarded as it is to an untagged port. 
 *
 * VID : VLAN ID is the identification of the VLAN, which is basically used by the standard 802.1Q.