ixethdb.h

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

 * Retrieves the complete VLAN membership table from a port, 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 will be set if bit 0 is set.
 *
 * The bit at index 4095 is reserved and will not be set (it will be ignored if set).
 *
 * The bit referencing the same VLAN ID as the default port VLAN ID will 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 retrieve the VLAN membership table from
 * @param vlanSet @ref IxEthDBVlanSet [out] - pointer a location where the VLAN membership table will be
 *                written to 
 * 
 * @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
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBPortVlanMembershipGet(IxEthDBPortId portID, IxEthDBVlanSet vlanSet);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBAcceptableFrameTypeSet(IxEthDBPortId portID, IxEthDBFrameFilter frameFilter)
 *
 * @brief Sets a port's acceptable frame type filter
 *
 * The acceptable frame type is one (or a combination) of the following values:
 *    - IX_ETH_DB_ACCEPT_ALL_FRAMES       - accepts all the frames
 *    - IX_ETH_DB_UNTAGGED_FRAMES         - accepts untagged frames
 *    - IX_ETH_DB_VLAN_TAGGED_FRAMES      - accepts tagged frames
 *    - IX_ETH_DB_PRIORITY_TAGGED_FRAMES  - accepts tagged frames with VLAN ID set to 0 (no VLAN membership)
 *
 * Except for using the exact values given above only the following combinations are valid:
 *    - IX_ETH_DB_UNTAGGED_FRAMES | IX_ETH_DB_VLAN_TAGGED_FRAMES
 *    - IX_ETH_DB_UNTAGGED_FRAMES | IX_ETH_DB_PRIORITY_TAGGED_FRAMES
 *
 * Please note that IX_ETH_DB_UNTAGGED_FRAMES | IX_ETH_DB_VLAN_TAGGED_FRAMES is equivalent
 * to IX_ETH_DB_ACCEPT_ALL_FRAMES.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @note by default the acceptable frame type filter is set to IX_ETH_DB_ACCEPT_ALL_FRAMES
 *
 * @note setting the acceptable frame type to PRIORITY_TAGGED_FRAMES is internally
 * accomplished by changing the frame filter to VLAN_TAGGED_FRAMES and setting the
 * VLAN membership list to include only VLAN ID 0; the membership list will need
 * to be restored manually to an appropriate value if the acceptable frame type
 * filter is changed back to ACCEPT_ALL_FRAMES or VLAN_TAGGED_FRAMES; failure to do so
 * will filter all VLAN traffic bar frames tagged with VLAN ID 0
 *
 * @param portID @ref IxEthDBPortId [in] - port ID to set the acceptable frame type filter to
 * @param frameFilter @ref IxEthDBFrameFilter [in] - acceptable frame type filter
 * 
 * @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 frame type filter
 * @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 ixEthDBAcceptableFrameTypeSet(IxEthDBPortId portID, IxEthDBFrameFilter frameFilter);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBAcceptableFrameTypeGet(IxEthDBPortId portID, IxEthDBFrameFilter *frameFilter)
 *
 * @brief Retrieves a port's acceptable frame type filter 
 *
 * For a description of the acceptable frame types see @ref ixEthDBAcceptableFrameTypeSet
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID @ref IxEthDBPortId [in] - port ID to retrieve the acceptable frame type filter from
 * @param frameFilter @ref IxEthDBFrameFilter [out] - location to store the acceptable frame type filter
 * 
 * @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>frameFilter</i> pointer argument
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBAcceptableFrameTypeGet(IxEthDBPortId portID, IxEthDBFrameFilter *frameFilter);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPriorityMappingTableSet(IxEthDBPortId portID, IxEthDBPriorityTable priorityTable)
 *
 * @brief Sets a port's priority mapping table
 *
 * The priority mapping table is an 8x2 table mapping a QoS (user) priority into an internal
 * traffic class. There are 8 valid QoS priorities (0..7, 0 being the lowest) which can be
 * mapped into one of the 4 available traffic classes (0..3, 0 being the lowest).
 * If a custom priority mapping table is not specified using this function the following
 * default priority table will be used (as per IEEE 802.1Q and IEEE 802.1D):
 * 
 * <table border="1"> <caption> QoS traffic classes  </caption>
 *    <tr> <td> <b> QoS priority <td> <b> Default traffic class <td> <b> Traffic type </b>
 *    <tr> <td>      0       <td>           1           <td> Best effort, default class for unexpedited traffic
 *    <tr> <td>      1       <td>           0           <td> Background traffic
 *    <tr> <td>      2       <td>           0           <td> Spare bandwidth
 *    <tr> <td>      3       <td>           1           <td> Excellent effort
 *    <tr> <td>      4       <td>           2           <td> Controlled load
 *    <tr> <td>      5       <td>           2           <td> Video traffic
 *    <tr> <td>      6       <td>           3           <td> Voice traffic
 *    <tr> <td>      7       <td>           3           <td> Network control
 * </table>
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID @ref IxEthDBPortId [in] - port ID of the port to set the priority mapping table to
 * @param priorityTable @ref IxEthDBPriorityTable [in] - location of the user priority table
 *
 * @note The provided table will be copied into internal data structures in EthDB and 
 * can be deallocated by the called after this function has completed its execution, if
 * so desired
 *
 * @warning The number of available traffic classes differs depending on the NPE images
 * and queue configuration. Check IxEthDBQoS.h for up-to-date information on the availability of
 * traffic classes. Note that specifiying a traffic class in the priority map which exceeds
 * the system availability will produce an IX_ETH_DB_INVALID_PRIORITY return error code and no
 * priority will be remapped.
 * 
 * @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>priorityTable</i> pointer
 * @retval IX_ETH_DB_INVALID_PRIORITY at least one priority value exceeds
 * the current number of available traffic classes
 * @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 ixEthDBPriorityMappingTableSet(IxEthDBPortId portID, IxEthDBPriorityTable priorityTable);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPriorityMappingTableGet(IxEthDBPortId portID, IxEthDBPriorityTable priorityTable)
 *
 * @brief Retrieves a port's priority mapping table
 *
 * The priority mapping table for the given port will be copied in the location
 * specified by the caller using "priorityTable"
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID ID @ref IxEthDBPortId [in] - of the port to retrieve the priority mapping table from
 * @param priorityTable @ref IxEthDBPriorityTable [out] - pointer to a user specified location where the table will be copied to
 *
 * @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 priorityTable pointer
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBPriorityMappingTableGet(IxEthDBPortId portID, IxEthDBPriorityTable priorityTable);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPriorityMappingClassSet(IxEthDBPortId portID, IxEthDBPriority userPriority, IxEthDBPriority trafficClass)
 *
 * @brief Sets one QoS/user priority => traffic class mapping in a port's priority mapping table
 *
 * This function establishes a mapping between a user (QoS) priority and an internal traffic class.
 * The mapping will be saved in the port's priority mapping table. Use this function when not all
 * the QoS priorities need remapping (see also @ref ixEthDBPriorityMappingTableSet)
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID @ref IxEthDBPortId [in] - ID of the port to set the mapping to
 * @param userPriority @ref IxEthDBPriority [in] - user (QoS) priority, between 0 and 7 (0 being the lowest)
 * @param trafficClass @ref IxEthDBPriority [in] - internal traffic class, between 0 and 3 (0 being the lowest)
 *
 * @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_PRIORITY <i>userPriority</i> out of range or
 * <i>trafficClass</i> is beyond the number of currently available traffic classes
 * @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 ixEthDBPriorityMappingClassSet(IxEthDBPortId portID, IxEthDBPriority userPriority, IxEthDBPriority trafficClass);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBPriorityMappingClassGet(IxEthDBPortId portID, IxEthDBPriority userPriority, IxEthDBPriority *trafficClass)
 *
 * @brief Retrieves one QoS/user priority => traffic class mapping in a port's priority mapping table
 *
 * This function retrieves the internal traffic class associated with a QoS (user) priority from a given
 * port's priority mapping table. Use this function when not all the QoS priority mappings are 
 * required (see also @ref ixEthDBPriorityMappingTableGet)
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID @ref IxEthDBPortId [in] - ID of the port to set the mapping to
 * @param userPriority @ref IxEthDBPriority [in] - user (QoS) priority, between 0 and 7 (0 being the lowest)
 * @param trafficClass @ref IxEthDBPriority [out] - location to write the corresponding internal traffic class to
 *
 * @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_PRIORITY invalid userPriority value (out of range)
 * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 * @retval IX_ETH_DB_INVALID_ARG invalid <i>trafficClass</i> pointer argument
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBPriorityMappingClassGet(IxEthDBPortId portID, IxEthDBPriority userPriority, IxEthDBPriority *trafficClass);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBEgressVlanEntryTaggingEnabledSet(IxEthDBPortId portID, IxEthDBVlanId vlanID, BOOL enabled)
 *
 * @brief Enables or disables Egress VLAN tagging for a port and a given VLAN
 *
 * This function enables or disables Egress VLAN tagging for the given port and VLAN ID.
 * If the VLAN tagging for a certain VLAN ID is enabled then all the frames to be
 * transmitted on the given port tagged with the same VLAN ID will be transmitted in a tagged format.
 * If tagging is not enabled for the given VLAN ID, the VLAN tag from the frames matching
 * this VLAN ID will be removed (the frames will be untagged).
 *
 * VLAN ID 4095 is reserved and should never be used with this function.
 * VLAN ID 0 has the special meaning of "No VLAN membership" and it is used in this
 * context to allow the port to send priority-tagged frames or not.
 *
 * By default, no Egress VLAN tagging is enabled on any port.
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @param portID @ref IxEthDBPortId [in] - ID of the port to enable or disable the VLAN ID Egress tagging on
 * @param vlanID @ref IxEthDBVlanId [in] - VLAN ID to be matched against outgoing frames
 * @param enabled BOOL [in] - TRUE to enable Egress VLAN tagging on the port and given VLAN, and
 *                FALSE to disable Egress VLAN tagging
 *
 * @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 invalid VLAN ID (out of 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
 */
IX_ETH_DB_PUBLIC 
IxEthDBStatus ixEthDBEgressVlanEntryTaggingEnabledSet(IxEthDBPortId portID, IxEthDBVlanId vlanID, BOOL enabled);

/**
 * @ingroup IxEthDB
 *
 * @fn IxEthDBStatus ixEthDBEgressVlanEntryTaggingEnabledGet(IxEthDBPortId portID, IxEthDBVlanId vlanID, BOOL *enabled)
 *
 * @brief Retrieves the Egress VLAN tagging enabling status for a port and VLAN ID
 *
 * @param portID [in] - ID of the port to extract the Egress VLAN ID tagging status from
 * @param vlanID VLAN [in] - ID whose tagging status is to be extracted
 * @param enabled [in] - user-specifed location where the status is copied to; following
 * the successfull execution of this function the value will be TRUE if Egress VLAN 
 * tagging is enabled for the given port and VLAN ID, and FALSE otherwise                                                 
 *
 * - Reentrant    - no
 * - ISR Callable - no
 *
 * @see ixEthDBEgressVlanEntryTaggingEnabledGet
 *
 * @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 invalid VLAN ID (o