drivers/net/npe/include/IxEthDB.h

   1 /** @file IxEthDB.h
   2  *
   3  * @brief this file contains the public API of @ref IxEthDB component
   4  *
   5  *
   6  * @par
   7  * IXP400 SW Release version 2.0
   8  *
   9  * -- Copyright Notice --
  10  *
  11  * @par
  12  * Copyright 2001-2005, Intel Corporation.
  13  * All rights reserved.
  14  *
  15  * @par
  16  * SPDX-License-Identifier:     BSD-3-Clause
  17  * @par
  18  * -- End of Copyright Notice --
  19  *
  20  */
  21
  22 #ifndef IxEthDB_H
  23 #define IxEthDB_H
  24
  25 #include <IxOsBuffMgt.h>
  26 #include <IxTypes.h>
  27
  28 /**
  29  * @defgroup IxEthDB IXP400 Ethernet Database (IxEthDB) API
  30  *
  31  * @brief ethDB is a library that does provides a MAC address database learning/filtering capability
  32  *
  33  *@{
  34  */
  35
  36 #define INLINE __inline__
  37
  38 #define IX_ETH_DB_PRIVATE PRIVATE /* imported from IxTypes.h */
  39
  40 #define IX_ETH_DB_PUBLIC PUBLIC
  41
  42 /**
  43  * @brief port ID => message handler NPE id conversion (0 => NPE_B, 1 => NPE_C)
  44  */
  45 #define IX_ETH_DB_PORT_ID_TO_NPE(id) (id == 0 ? 1 : (id == 1 ? 2 : (id == 2 ? 0 : -1)))
  46
  47 /**
  48  * @def IX_ETH_DB_NPE_TO_PORT_ID(npe)
  49  * @brief message handler NPE id => port ID conversion (NPE_B => 0, NPE_C => 1)
  50  */
  51 #define IX_ETH_DB_NPE_TO_PORT_ID(npe) (npe == 0 ? 2 : (npe == 1 ? 0 : (npe == 2 ? 1 : -1)))
  52
  53 /* temporary define - won't work for Azusa */
  54 #define IX_ETH_DB_PORT_ID_TO_NPE_LOGICAL_ID(id) (IX_ETH_DB_PORT_ID_TO_NPE(id) << 4)
  55 #define IX_ETH_DB_NPE_LOGICAL_ID_TO_PORT_ID(id) (IX_ETH_DB_NPE_TO_PORT_ID(id >> 4))
  56
  57 /**
  58  * @def IX_IEEE803_MAC_ADDRESS_SIZE
  59  * @brief The size of the MAC address
  60  */
  61 #define IX_IEEE803_MAC_ADDRESS_SIZE (6)
  62
  63 /**
  64  * @def IX_IEEE802_1Q_QOS_PRIORITY_COUNT
  65  * @brief Number of QoS priorities defined by IEEE802.1Q
  66  */
  67 #define IX_IEEE802_1Q_QOS_PRIORITY_COUNT (8)
  68
  69 /**
  70  * @enum IxEthDBStatus
  71  * @brief Ethernet Database API return values
  72  */
  73 typedef enum /* IxEthDBStatus */
  74 {
  75   IX_ETH_DB_SUCCESS = IX_SUCCESS,   /**< Success */
  76   IX_ETH_DB_FAIL = IX_FAIL,         /**< Failure */
  77   IX_ETH_DB_INVALID_PORT,           /**< Invalid port */
  78   IX_ETH_DB_PORT_UNINITIALIZED,     /**< Port not initialized */
  79   IX_ETH_DB_MAC_UNINITIALIZED,      /**< MAC not initialized */
  80   IX_ETH_DB_INVALID_ARG,            /**< Invalid argument */
  81   IX_ETH_DB_NO_SUCH_ADDR,           /**< Address not found for search or delete operations */
  82   IX_ETH_DB_NOMEM,                  /**< Learning database memory full */
  83   IX_ETH_DB_BUSY,                   /**< Learning database cannot complete operation, access temporarily blocked */
  84   IX_ETH_DB_END,                    /**< Database browser passed the end of the record set */
  85   IX_ETH_DB_INVALID_VLAN,           /**< Invalid VLAN ID (valid range is 0..4094, 0 signifies no VLAN membership, used for priority tagged frames) */
  86   IX_ETH_DB_INVALID_PRIORITY,       /**< Invalid QoS priority/traffic class (valid range for QoS priority is 0..7, valid range for traffic class depends on run-time configuration) */
  87   IX_ETH_DB_NO_PERMISSION,          /**< No permission for attempted operation */
  88   IX_ETH_DB_FEATURE_UNAVAILABLE,    /**< Feature not available (or not enabled) */
  89   IX_ETH_DB_INVALID_KEY,            /**< Invalid search key */
  90   IX_ETH_DB_INVALID_RECORD_TYPE     /**< Invalid record type */
  91 } IxEthDBStatus;
  92
  93 /** @brief VLAN ID type, valid range is 0..4094, 0 signifying no VLAN membership */
  94 typedef UINT32 IxEthDBVlanId;
  95
  96 /** @brief 802.1Q VLAN tag, contains 3 bits user priority, 1 bit CFI, 12 bits VLAN ID */
  97 typedef UINT32 IxEthDBVlanTag;
  98
  99 /** @brief QoS priority/traffic class type, valid range is 0..7, 0 being the lowest */
 100 typedef UINT32 IxEthDBPriority;
 101
 102 /** @brief Priority mapping table; 0..7 QoS priorities used to index, table contains traffic classes */
 103 typedef UINT8 IxEthDBPriorityTable[8];
 104
 105 /** @brief A 4096 bit array used to map the complete VLAN ID range */
 106 typedef UINT8 IxEthDBVlanSet[512];
 107
 108 #define IX_ETH_DB_802_1Q_VLAN_MASK (0xFFF)
 109 #define IX_ETH_DB_802_1Q_QOS_MASK  (0x7)
 110
 111 #define IX_ETH_DB_802_1Q_MAX_VLAN_ID (0xFFE)
 112
 113 /**
 114  * @def IX_ETH_DB_SET_VLAN_ID
 115  * @brief returns the given 802.1Q tag with the VLAN ID field substituted with the given VLAN ID
 116  *
 117  * This macro is used to change the VLAN ID in a 802.1Q tag.
 118  *
 119  * Example:
 120  *
 121  *  tag = IX_ETH_DB_SET_VLAN_ID(tag, 32)
 122  *
 123  * inserts the VLAN ID "32" in the given tag.
 124  */
 125 #define IX_ETH_DB_SET_VLAN_ID(vlanTag, vlanID) (((vlanTag) & 0xF000) | ((vlanID) & IX_ETH_DB_802_1Q_VLAN_MASK))
 126
 127 /**
 128 * @def IX_ETH_DB_GET_VLAN_ID
 129 * @brief returns the VLAN ID from the given 802.1Q tag
 130 */
 131 #define IX_ETH_DB_GET_VLAN_ID(vlanTag) ((vlanTag) & IX_ETH_DB_802_1Q_VLAN_MASK)
 132
 133 #define IX_ETH_DB_GET_QOS_PRIORITY(vlanTag) (((vlanTag) >> 13) & IX_ETH_DB_802_1Q_QOS_MASK)
 134
 135 #define IX_ETH_DB_SET_QOS_PRIORITY(vlanTag, priority) (((vlanTag) & 0x1FFF) | (((priority) & IX_ETH_DB_802_1Q_QOS_MASK) << 13))
 136
 137 #define IX_ETH_DB_CHECK_VLAN_TAG(vlanTag) { if(((vlanTag & 0xFFFF0000) != 0) || (IX_ETH_DB_GET_VLAN_ID(vlanTag) > 4094)) return IX_ETH_DB_INVALID_VLAN; }
 138
 139 #define IX_ETH_DB_CHECK_VLAN_ID(vlanId) { if (vlanId > IX_ETH_DB_802_1Q_MAX_VLAN_ID) return IX_ETH_DB_INVALID_VLAN; }
 140
 141 #define IX_IEEE802_1Q_VLAN_TPID (0x8100)
 142
 143 typedef enum
 144 {
 145   IX_ETH_DB_UNTAGGED_FRAMES        = 0x1, /**< Accepts untagged frames */
 146   IX_ETH_DB_VLAN_TAGGED_FRAMES     = 0x2, /**< Accepts tagged frames */
 147   IX_ETH_DB_PRIORITY_TAGGED_FRAMES = 0x4, /**< Accepts tagged frames with VLAN ID set to 0 (no VLAN membership) */
 148   IX_ETH_DB_ACCEPT_ALL_FRAMES      =
 149       IX_ETH_DB_UNTAGGED_FRAMES | IX_ETH_DB_VLAN_TAGGED_FRAMES /**< Accepts all the frames */
 150 } IxEthDBFrameFilter;
 151
 152 typedef enum
 153 {
 154   IX_ETH_DB_PASS_THROUGH = 0x1, /**< Leave frame as-is */
 155   IX_ETH_DB_ADD_TAG      = 0x2, /**< Add default port VLAN tag */
 156   IX_ETH_DB_REMOVE_TAG   = 0x3  /**< Remove VLAN tag from frame */
 157 } IxEthDBTaggingAction;
 158
 159 typedef enum
 160 {
 161   IX_ETH_DB_FIREWALL_WHITE_LIST = 0x1,  /**< Firewall operates in white-list mode (MAC address based admission) */
 162   IX_ETH_DB_FIREWALL_BLACK_LIST = 0x2   /**< Firewall operates in black-list mode (MAC address based blocking) */
 163 } IxEthDBFirewallMode;
 164
 165 typedef enum
 166 {
 167   IX_ETH_DB_FILTERING_RECORD        = 0x01, /**< <table><caption> Filtering record </caption>
 168                                              *      <tr><td> MAC address <td> static/dynamic type <td> age
 169                                              *   </table>
 170                                              */
 171   IX_ETH_DB_FILTERING_VLAN_RECORD   = 0x02, /**< <table><caption> VLAN-enabled filtering record </caption>
 172                                              *      <tr><td> MAC address <td> static/dynamic type <td> age <td> 802.1Q tag
 173                                              *   </table>
 174                                              */
 175   IX_ETH_DB_WIFI_RECORD             = 0x04, /**< <table><caption> WiFi header conversion record </caption>
 176                                              *      <tr><td> MAC address <td> optional gateway MAC address <td>
 177                                              *   </table>
 178                                              */
 179   IX_ETH_DB_FIREWALL_RECORD         = 0x08, /**< <table><caption> Firewall record </caption>
 180                                              *      <tr><td> MAC address
 181                                              *   </table>
 182                                              */
 183   IX_ETH_DB_GATEWAY_RECORD          = 0x10, /**< <i>For internal use only</i> */
 184   IX_ETH_DB_MAX_RECORD_TYPE_INDEX   = 0x10, /**< <i>For internal use only</i> */
 185   IX_ETH_DB_NO_RECORD_TYPE          = 0,    /**< None of the registered record types */
 186   IX_ETH_DB_ALL_FILTERING_RECORDS   = IX_ETH_DB_FILTERING_RECORD | IX_ETH_DB_FILTERING_VLAN_RECORD, /**< All the filtering records */
 187   IX_ETH_DB_ALL_RECORD_TYPES        = IX_ETH_DB_FILTERING_RECORD | IX_ETH_DB_FILTERING_VLAN_RECORD |
 188       IX_ETH_DB_WIFI_RECORD | IX_ETH_DB_FIREWALL_RECORD /**< All the record types registered within EthDB */
 189 } IxEthDBRecordType;
 190
 191 typedef enum
 192 {
 193   IX_ETH_DB_LEARNING                = 0x01, /**< Learning feature; enables EthDB to learn MAC address (filtering) records, including 802.1Q enabled records */
 194   IX_ETH_DB_FILTERING               = 0x02, /**< Filtering feature; enables EthDB to communicate with the NPEs for downloading filtering information in the NPEs; depends on the learning feature */
 195   IX_ETH_DB_VLAN_QOS                = 0x04, /**< VLAN/QoS feature; enables EthDB to configure NPEs to operate in VLAN/QoS aware modes */
 196   IX_ETH_DB_FIREWALL                = 0x08, /**< Firewall feature; enables EthDB to configure NPEs to operate in firewall mode, using white/black address lists */
 197   IX_ETH_DB_SPANNING_TREE_PROTOCOL  = 0x10, /**< Spanning tree protocol feature; enables EthDB to configure the NPEs as STP nodes */
 198   IX_ETH_DB_WIFI_HEADER_CONVERSION  = 0x20  /**< WiFi 802.3 to 802.11 header conversion feature; enables EthDB to handle WiFi conversion data */
 199 } IxEthDBFeature;
 200
 201 typedef UINT32 IxEthDBProperty;  /**< Property ID type */
 202
 203 typedef enum
 204 {
 205   IX_ETH_DB_INTEGER_PROPERTY  = 0x1, /**< 4 byte unsigned integer type */
 206   IX_ETH_DB_STRING_PROPERTY   = 0x2, /**< NULL-terminated string type of maximum 255 characters (including the terminator) */
 207   IX_ETH_DB_MAC_ADDR_PROPERTY = 0x3, /**< 6 byte MAC address type */
 208   IX_ETH_DB_BOOL_PROPERTY     = 0x4  /**< 4 byte boolean type; can contain only true and false values */
 209 } IxEthDBPropertyType;
 210
 211 /* list of supported properties for the IX_ETH_DB_VLAN_QOS feature */
 212 #define IX_ETH_DB_QOS_TRAFFIC_CLASS_COUNT_PROPERTY   (0x01)     /**< Property identifying number the supported number of traffic classes */
 213 #define IX_ETH_DB_QOS_TRAFFIC_CLASS_0_RX_QUEUE_PROPERTY (0x10)  /**< Rx queue assigned to traffic class 0 */
 214 #define IX_ETH_DB_QOS_TRAFFIC_CLASS_1_RX_QUEUE_PROPERTY (0x11)  /**< Rx queue assigned to traffic class 1 */
 215 #define IX_ETH_DB_QOS_TRAFFIC_CLASS_2_RX_QUEUE_PROPERTY (0x12)  /**< Rx queue assigned to traffic class 2 */
 216 #define IX_ETH_DB_QOS_TRAFFIC_CLASS_3_RX_QUEUE_PROPERTY (0x13)  /**< Rx queue assigned to traffic class 3 */
 217 #define IX_ETH_DB_QOS_TRAFFIC_CLASS_4_RX_QUEUE_PROPERTY (0x14)  /**< Rx queue assigned to traffic class 4 */
 218 #define IX_ETH_DB_QOS_TRAFFIC_CLASS_5_RX_QUEUE_PROPERTY (0x15)  /**< Rx queue assigned to traffic class 5 */
 219 #define IX_ETH_DB_QOS_TRAFFIC_CLASS_6_RX_QUEUE_PROPERTY (0x16)  /**< Rx queue assigned to traffic class 6 */
 220 #define IX_ETH_DB_QOS_TRAFFIC_CLASS_7_RX_QUEUE_PROPERTY (0x17)  /**< Rx queue assigned to traffic class 7 */
 221
 222 /* private property used by EthAcc to indicate queue configuration complete */
 223 #define IX_ETH_DB_QOS_QUEUE_CONFIGURATION_COMPLETE (0x18)
 224
 225 /**
 226  *
 227  * @brief The IEEE 802.3 Ethernet MAC address structure.
 228  *
 229  * The data should be packed with bytes xx:xx:xx:xx:xx:xx
 230  *
 231  * @note The data must be packed in network byte order.
 232  */
 233 typedef struct
 234 {
 235    UINT8 macAddress[IX_IEEE803_MAC_ADDRESS_SIZE];
 236 } IxEthDBMacAddr;
 237
 238 /**
 239  * @ingroup IxEthDB
 240  *
 241  * @brief Definition of an IXP400 port.
 242  */
 243 typedef UINT32 IxEthDBPortId;
 244
 245 /**
 246  * @ingroup IxEthDB
 247  *
 248  * @brief Port dependency map definition
 249  */
 250 typedef UINT8 IxEthDBPortMap[32];
 251
 252 /**
 253  * @ingroup IxEthDB
 254  *
 255  * @fn IxEthDBStatus ixEthDBInit(void)
 256  *
 257  * @brief Initializes the Ethernet learning/filtering database
 258  *
 259  * @note calling this function multiple times does not constitute an error;
 260  * redundant calls will be ignored, returning IX_ETH_DB_SUCCESS
 261  *
 262  * @retval IX_ETH_DB_SUCCESS initialization was successful
 263  * @retval IX_ETH_DB_FAIL initialization failed (OS error)
 264  */
 265 IX_ETH_DB_PUBLIC
 266 IxEthDBStatus ixEthDBInit(void);
 267
 268 /**
 269  * @ingroup IxEthDB
 270  *
 271  * @fn IxEthDBStatus ixEthDBUnload(void)
 272  *
 273  * @brief Stops and prepares the EthDB component for unloading.
 274  *
 275  * @retval IX_ETH_DB_SUCCESS de-initialization was successful
 276  * @retval IX_ETH_DB_BUSY de-initialization failed, ports must be disabled first
 277  * @retval IX_ETH_DB_FAIL de-initialization failed (OS error)
 278  */
 279 IX_ETH_DB_PUBLIC
 280 IxEthDBStatus ixEthDBUnload(void);
 281
 282 /**
 283  * @ingroup IxEthDB
 284  *
 285  * @fn void ixEthDBPortInit(IxEthDBPortId portID)
 286  *
 287  * @brief Initializes a port
 288  *
 289  * This function is called automatically by the Ethernet Access
 290  * ixEthAccPortInit() routine for Ethernet NPE ports and should be manually
 291  * called for any user-defined port (any port that is not one of
 292  * the two Ethernet NPEs).
 293  *
 294  * @param portID @ref IxEthDBPortId [in] - ID of the port to be initialized
 295  *
 296  * @see IxEthDBPortDefs.h for port definitions
 297  *
 298  * @note calling this function multiple times does not constitute an error;
 299  * redundant calls will be ignored
 300  */
 301 IX_ETH_DB_PUBLIC
 302 void ixEthDBPortInit(IxEthDBPortId portID);
 303
 304 /**
 305  * @ingroup IxEthDB
 306  *
 307  * @fn IxEthDBStatus ixEthDBPortEnable(IxEthDBPortId portID)
 308  *
 309  * @brief Enables a port
 310  *
 311  * This function is called automatically from the Ethernet Access component
 312  * ixEthAccPortEnable() routine for Ethernet NPE ports and should be manually
 313  * called for any user-defined port (any port that is not one of
 314  * the Ethernet NPEs).
 315  *
 316  * @param portID @ref IxEthDBPortId [in] - ID of the port to enable processing on
 317  *
 318  * @retval IX_ETH_DB_SUCCESS if enabling is successful
 319  * @retval IX_ETH_DB_FAIL if the enabling was not successful due to
 320  * a message handler error
 321  * @retval IX_ETH_DB_MAC_UNINITIALIZED the MAC address of this port was
 322  * not initialized (only for Ethernet NPEs)
 323  * @retval IX_ETH_DB_INVALID_PORT if portID is invalid
 324  *
 325  * @pre ixEthDBPortAddressSet needs to be called prior to enabling the port events
 326  * for Ethernet NPEs
 327  *
 328  * @see ixEthDBPortAddressSet
 329  *
 330  * @see IxEthDBPortDefs.h for port definitions
 331  *
 332  * @note calling this function multiple times does not constitute an error;
 333  * redundant calls will be ignored
 334  */
 335 IX_ETH_DB_PUBLIC
 336 IxEthDBStatus ixEthDBPortEnable(IxEthDBPortId portID);
 337
 338 /**
 339  * @ingroup IxEthDB
 340  *
 341  * @fn IxEthDBStatus ixEthDBPortDisable(IxEthDBPortId portID)
 342  *
 343  * @brief Disables processing on a port
 344  *
 345  * This function is called automatically from the Ethernet Access component
 346  * ixEthAccPortDisable() routine for Ethernet NPE ports and should be manually
 347  * called for any user-defined port (any port that is not one of
 348  * the Ethernet NPEs).
 349  *
 350  * @note Calling ixEthAccPortDisable() will disable the respective Ethernet NPE.
 351  * After Ethernet NPEs are disabled they are stopped therefore
 352  * when re-enabled they need to be reset, downloaded with microcode and started.
 353  * For learning to restart working the user needs to call again
 354  * ixEthAccPortUnicastMacAddressSet or ixEthDBUnicastAddressSet
 355  * with the respective port MAC address.
 356  * Residual MAC addresses learnt before the port was disabled are deleted as soon
 357  * as the port is disabled. This only applies to dynamic (learnt) entries, static
 358  * entries do not dissapear when the port is disabled.
 359  *
 360  * @param portID @ref IxEthDBPortId [in] - ID of the port to disable processing on
 361  *
 362  * @retval IX_ETH_DB_SUCCESS if disabling is successful
 363  * @retval IX_ETH_DB_FAIL if the disabling was not successful due to
 364  * a message handler error
 365  * @retval IX_ETH_DB_INVALID_PORT if portID is invalid
 366  *
 367  * @note calling this function multiple times after the first time completed successfully
 368  * does not constitute an error; redundant calls will be ignored and return IX_ETH_DB_SUCCESS
 369 */
 370 IX_ETH_DB_PUBLIC
 371 IxEthDBStatus ixEthDBPortDisable(IxEthDBPortId portID);
 372
 373 /**
 374  * @ingroup IxEthDB
 375  *
 376  * @fn IxEthDBStatus ixEthDBPortAddressSet(IxEthDBPortId portID, IxEthDBMacAddr *macAddr)
 377  *
 378  * @brief Sets the port MAC address
 379  *
 380  * This function is to be called from the Ethernet Access component top-level
 381  * ixEthDBUnicastAddressSet(). Event processing cannot be enabled for a port
 382  * until its MAC address has been set.
 383  *
 384  * @param portID @ref IxEthDBPortId [in] - ID of the port whose MAC address is set
 385  * @param macAddr @ref IxEthDBMacAddr [in] - port MAC address
 386  *
 387  * @retval IX_ETH_DB_SUCCESS MAC address was set successfully
 388  * @retval IX_ETH_DB_FAIL MAC address was not set due to a message handler failure
 389  * @retval IX_ETH_DB_INVALID_PORT if the port is not an Ethernet NPE
 390  *
 391  * @see IxEthDBPortDefs.h for port definitions
 392  */
 393 IX_ETH_DB_PUBLIC
 394 IxEthDBStatus ixEthDBPortAddressSet(IxEthDBPortId portID, IxEthDBMacAddr *macAddr);
 395
 396 /**
 397  * @ingroup IxEthDB
 398  *
 399  * @fn IxEthDBStatus ixEthDBFilteringPortMaximumFrameSizeSet(IxEthDBPortId portID, UINT32 maximumFrameSize)
 400  *
 401  * @brief Set the maximum frame size supported on the given port ID
 402  *
 403  * This functions set the maximum frame size supported on a specific port ID
 404  *
 405  * - Reentrant    - yes
 406  * - ISR Callable - no
 407  *
 408  * @param portID @ref IxEthDBPortId [in] - port ID to configure
 409  * @param maximumFrameSize UINT32 [in] - maximum frame size to configure
 410  *
 411  * @retval IX_ETH_DB_SUCCESS the port is configured
 412  * @retval IX_ETH_DB_PORT_UNINITIALIZED the port has not been initialized
 413  * @retval IX_ETH_DB_INVALID_PORT portID is invalid
 414  * @retval IX_ETH_DB_INVALID_ARG size parameter is out of range
 415  * @retval IX_ETH_DB_NO_PERMISSION selected port is not an Ethernet NPE
 416  * @retval IX_FAIL unknown OS or NPE communication error
 417  *
 418  * @note
 419  * This maximum frame size is used to filter the frames based on their
 420  * destination addresses and the capabilities of the destination port.
 421  * The mximum value that can be set for a NPE port is 16320.
 422  * (IX_ETHNPE_ACC_FRAME_LENGTH_MAX)
 423  */
 424 IX_ETH_DB_PUBLIC
 425 IxEthDBStatus ixEthDBFilteringPortMaximumFrameSizeSet(IxEthDBPortId portID, UINT32 maximumFrameSize);
 426
 427 /**
 428  * @ingroup IxEthDB
 429  *
 430  * @fn IxEthDBStatus ixEthDBFilteringStaticEntryProvision(IxEthDBPortId portID, IxEthDBMacAddr *macAddr)
 431  *
 432  * @brief Populate the Ethernet learning/filtering database with a static MAC address
 433  *
 434  * Populates the Ethernet learning/filtering database with a static MAC address. The entry will not be subject to aging.
 435  * If there is an entry (static or dynamic) with the corresponding MAC address on any port this entry will take precedence.
 436  * Any other entry with the same MAC address will be removed.
 437  *
 438  * - Reentrant    - yes
 439  * - ISR Callable - yes
 440  *
 441  * @param portID @ref IxEthDBPortId [in] - port ID to add the static address to
 442  * @param macAddr @ref IxEthDBMacAddr [in] - static MAC address to add
 443  *
 444  * @retval IX_ETH_DB_SUCCESS the add was successful
 445  * @retval IX_ETH_DB_FAIL failed to populate the database entry
 446  * @retval IX_ETH_DB_BUSY failed due to a temporary busy condition (i.e. lack of CPU cycles), try again later
 447  * @retval IX_ETH_DB_INVALID_PORT portID is invalid
 448  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 449  * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> pointer argument
 450  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE learning feature is disabled
 451  */
 452 IX_ETH_DB_PUBLIC
 453 IxEthDBStatus ixEthDBFilteringStaticEntryProvision(IxEthDBPortId portID, IxEthDBMacAddr *macAddr);
 454
 455 /**
 456  * @ingroup IxEthDB
 457  *
 458  * @fn IxEthDBStatus ixEthDBFilteringDynamicEntryProvision(IxEthDBPortId portID, IxEthDBMacAddr *macAddr)
 459  *
 460  * @brief Populate the Ethernet learning/filtering database with a dynamic MAC address
 461  *
 462  * Populates the Ethernet learning/filtering database with a dynamic MAC address. This entry will be subject to normal
 463  * aging function, if aging is enabled on its port.
 464  * If there is an entry (static or dynamic) with the same MAC address on any port this entry will take precedence.
 465  * Any other entry with the same MAC address will be removed.
 466  *
 467  * - Reentrant    - yes
 468  * - ISR Callable - yes
 469  *
 470  * @param portID @ref IxEthDBPortId [in] - port ID to add the dynamic address to
 471  * @param macAddr @ref IxEthDBMacAddr [in] - static MAC address to add
 472  *
 473  * @retval IX_ETH_DB_SUCCESS the add was successful
 474  * @retval IX_ETH_DB_FAIL failed to populate the database entry
 475  * @retval IX_ETH_DB_BUSY failed due to a temporary busy condition (i.e. lack of CPU cycles), try again later
 476  * @retval IX_ETH_DB_INVALID_PORT portID is invalid
 477  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 478  * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> pointer argument
 479  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE learning feature is disabled
 480  */
 481 IX_ETH_DB_PUBLIC
 482 IxEthDBStatus ixEthDBFilteringDynamicEntryProvision(IxEthDBPortId portID, IxEthDBMacAddr *macAddr);
 483
 484 /**
 485  * @ingroup IxEthDB
 486  *
 487  * @fn IxEthDBStatus ixEthDBFilteringEntryDelete(IxEthDBMacAddr *macAddr)
 488  *
 489  * @brief Removes a MAC address entry from the Ethernet learning/filtering database
 490  *
 491  * @param macAddr IxEthDBMacAddr [in] - MAC address to remove
 492  *
 493  * - Reentrant    - yes
 494  * - ISR Callable - no
 495  *
 496  * @retval IX_ETH_DB_SUCCESS the removal was successful
 497  * @retval IX_ETH_DB_NO_SUCH_ADDR failed to remove the address (not in the database)
 498  * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> pointer argument
 499  * @retval IX_ETH_DB_BUSY failed due to a temporary busy condition (i.e. lack of CPU cycles), try again later
 500  */
 501 IX_ETH_DB_PUBLIC
 502 IxEthDBStatus ixEthDBFilteringEntryDelete(IxEthDBMacAddr *macAddr);
 503
 504 /**
 505  * @ingroup IxEthDB
 506  *
 507  * @fn IxEthDBStatus ixEthDBFilteringPortSearch(IxEthDBPortId portID, IxEthDBMacAddr *macAddr)
 508  *
 509  * @brief Search the Ethernet learning/filtering database for the given MAC address and port ID
 510  *
 511  * This functions searches the database for a specific port ID and MAC address. Both the port ID
 512  * and the MAC address have to match in order for the record to be reported as found.
 513  *
 514  * - Reentrant    - yes
 515  * - ISR Callable - no
 516  *
 517  * @param portID @ref IxEthDBPortId [in] - port ID to search for
 518  * @param macAddr @ref IxEthDBMacAddr [in] - MAC address to search for
 519  *
 520  * @retval IX_ETH_DB_SUCCESS the record exists in the database
 521  * @retval IX_ETH_DB_INVALID_ARG invalid macAddr pointer argument
 522  * @retval IX_ETH_DB_NO_SUCH_ADDR the record was not found in the database
 523  * @retval IX_ETH_DB_INVALID_PORT portID is invalid
 524  * @retval IX_ETH_DB_PORT_UNINITIALIZED port ID is not initialized
 525  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE learning feature is disabled
 526  */
 527 IX_ETH_DB_PUBLIC
 528 IxEthDBStatus ixEthDBFilteringPortSearch(IxEthDBPortId portID, IxEthDBMacAddr *macAddr);
 529
 530 /**
 531  * @ingroup IxEthDB
 532  *
 533  * @fn IxEthDBStatus ixEthDBFilteringDatabaseSearch(IxEthDBPortId *portID, IxEthDBMacAddr *macAddr)
 534  *
 535  * @brief Search the Ethernet learning/filtering database for a MAC address and return the port ID
 536  *
 537  * Searches the database for a MAC address. The function returns the portID for the
 538  * MAC address record, if found. If no match is found the function returns IX_ETH_DB_NO_SUCH_ADDR.
 539  * The portID is only valid if the function finds a match.
 540  *
 541  * - Reentrant    - yes
 542  * - ISR Callable - no
 543  *
 544  * @param portID @ref IxEthDBPortId [in] - port ID the address belongs to (populated only on a successful search)
 545  * @param macAddr @ref IxEthDBMacAddr [in] - MAC address to search for
 546  *
 547  * @retval IX_ETH_DB_SUCCESS the record exists in the database
 548  * @retval IX_ETH_DB_NO_SUCH_ADDR the record was not found in the database
 549  * @retval IX_ETH_DB_INVALID_ARG invalid macAddr or portID pointer argument(s)
 550  */
 551 IX_ETH_DB_PUBLIC
 552 IxEthDBStatus ixEthDBFilteringDatabaseSearch(IxEthDBPortId *portID, IxEthDBMacAddr *macAddr);
 553
 554 /**
 555  * @ingroup IxEthDB
 556  *
 557  * @fn IxEthDBStatus ixEthDBFilteringPortUpdatingSearch(IxEthDBPortId *portID, IxEthDBMacAddr *macAddr)
 558  *
 559  * @brief Search the filtering database for a MAC address, return the port ID and reset the record age
 560  *
 561  * Searches the database for a MAC address. The function returns the portID for the
 562  * MAC address record and resets the entry age to 0, if found.
 563  * If no match is found the function returns IX_ETH_DB_NO_SUCH_ADDR.
 564  * The portID is only valid if the function finds a match.
 565  *
 566  * - Reentrant      - yes
 567  * - ISR Callable   - no
 568  *
 569  * @retval IX_ETH_DB_SUCCESS the MAC address was found
 570  * @retval IX_ETH_DB_NO_SUCH_ADDR the MAC address was not found
 571  * @retval IX_ETH_DB_INVALID_ARG invalid macAddr or portID pointer argument(s)
 572  */
 573 IX_ETH_DB_PUBLIC
 574 IxEthDBStatus ixEthDBFilteringPortUpdatingSearch(IxEthDBPortId *portID, IxEthDBMacAddr *macAddr);
 575
 576 /**
 577  * @ingroup IxEthDB
 578  *
 579  * @def IX_ETH_DB_MAINTENANCE_TIME
 580  *
 581  * @brief The @ref ixEthDBDatabaseMaintenance must be called by the user at a frequency of
 582  * IX_ETH_DB_MAINTENANCE_TIME
 583  *
 584  */
 585 #define IX_ETH_DB_MAINTENANCE_TIME (1 * 60) /* 1 Minute */
 586
 587 /**
 588  * @ingroup IxEthDB
 589  *
 590  * @def IX_ETH_DB_LEARNING_ENTRY_AGE_TIME
 591  *
 592  * @brief The define specifies the filtering database age entry time. Static entries older than
 593  * IX_ETH_DB_LEARNING_ENTRY_AGE_TIME +/- IX_ETH_DB_MAINTENANCE_TIME shall be removed.
 594  *
 595  */
 596 #define IX_ETH_DB_LEARNING_ENTRY_AGE_TIME (15 * 60 ) /* 15 Mins */
 597
 598 /**
 599  * @ingroup IxEthDB
 600  *
 601  * @fn IxEthDBStatus ixEthDBPortAgingDisable(IxEthDBPortId portID)
 602  *
 603  * @brief Disable the aging function for a specific port
 604  *
 605  * @param portID @ref IxEthDBPortId [in] - port ID to disable aging on
 606  *
 607  * - Reentrant    - yes
 608  * - ISR Callable - no
 609  *
 610  * @retval IX_ETH_DB_SUCCESS aging disabled successfully
 611  * @retval IX_ETH_DB_INVALID_PORT portID is invalid
 612  * @retval IX_ETH_DB_PORT_UNINITIALIZED port ID is not initialized
 613  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE learning feature is disabled
 614  */
 615 IX_ETH_DB_PUBLIC
 616 IxEthDBStatus ixEthDBPortAgingDisable(IxEthDBPortId portID);
 617
 618 /**
 619  * @ingroup IxEthDB
 620  *
 621  * @fn IxEthDBStatus ixEthDBPortAgingEnable(IxEthDBPortId portID)
 622  *
 623  * @brief Enable the aging function for a specific port
 624  *
 625  * Enables the aging of dynamic MAC address entries stored in the learning/filtering database
 626  *
 627  * @note The aging function relies on the @ref ixEthDBDatabaseMaintenance being called with a period of
 628  * @ref IX_ETH_DB_MAINTENANCE_TIME seconds.
 629  *
 630  * - Reentrant    - yes
 631  * - ISR Callable - no
 632  *
 633  * @param portID @ref IxEthDBPortId [in] - port ID to enable aging on
 634  *
 635  * @retval IX_ETH_DB_SUCCESS aging enabled successfully
 636  * @retval IX_ETH_DB_INVALID_PORT portID is invalid
 637  * @retval IX_ETH_DB_PORT_UNINITIALIZED port ID is not initialized
 638  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE learning feature is disabled
 639  */
 640 IX_ETH_DB_PUBLIC
 641 IxEthDBStatus ixEthDBPortAgingEnable(IxEthDBPortId portID);
 642
 643 /**
 644  * @ingroup IxEthDB
 645  *
 646  * @fn void ixEthDBDatabaseMaintenance(void)
 647  *
 648  * @brief Performs a maintenance operation on the Ethernet learning/filtering database
 649  *
 650  * In order to perform a database maintenance this function must be called every
 651  * @ref IX_ETH_DB_MAINTENANCE_TIME seconds. It should be called regardless of whether learning is
 652  * enabled or not.
 653  *
 654  * - Reentrant    - no
 655  * - ISR Callable - no
 656  *
 657  * @note this function call will be ignored if the learning feature is disabled
 658  */
 659 IX_ETH_DB_PUBLIC
 660 void ixEthDBDatabaseMaintenance(void);
 661
 662 /**
 663  * @ingroup IxEthDB
 664  *
 665  * @fn IxEthDBStatus ixEthDBFilteringDatabaseShow(IxEthDBPortId  portID)
 666  *
 667  * @brief This function displays the Mac Ethernet MAC address filtering tables.
 668  *
 669  * It displays the MAC address, port ID, entry type (dynamic/static),and age for
 670  * the given port ID.
 671  *
 672  * - Reentrant    - no
 673  * - ISR Callable - no
 674  *
 675  * @param portID @ref IxEthDBPortId [in] - port ID to display the MAC address entries
 676  *
 677  * @retval IX_ETH_DB_SUCCESS operation completed successfully
 678  * @retval IX_ETH_DB_INVALID_PORT portID is invalid
 679  * @retval IX_ETH_DB_PORT_UNINITIALIZED port ID is not initialized
 680  * @retval IX_ETH_DB_FAIL record browser failed due to an internal busy or lock condition
 681  *
 682  * @note this function is deprecated and kept for compatibility reasons; use @ref ixEthDBFilteringDatabaseShowRecords instead
 683  *
 684  * @see ixEthDBFilteringDatabaseShowRecords
 685  */
 686 IX_ETH_DB_PUBLIC
 687 IxEthDBStatus ixEthDBFilteringDatabaseShow(IxEthDBPortId portID);
 688
 689 /**
 690  * @ingroup IxEthDB
 691  *
 692  * @fn void ixEthDBFilteringDatabaseShowAll(void)
 693  *
 694  * @brief Displays the MAC address recorded in the filtering database for all registered
 695  * ports (see IxEthDBPortDefs.h), grouped by port ID.
 696  *
 697  * - Reentrant    - no
 698  * - ISR Callable - no
 699  *
 700  * @retval void
 701  *
 702  * @note this function is deprecated and kept for compatibility reasons; use @ref ixEthDBFilteringDatabaseShowRecords instead
 703  *
 704  * @see ixEthDBFilteringDatabaseShowRecords
 705  */
 706 IX_ETH_DB_PUBLIC
 707 void ixEthDBFilteringDatabaseShowAll(void);
 708
 709 /**
 710  * @ingroup IxEthDB
 711  *
 712  * @fn IxEthDBStatus ixEthDBFilteringDatabaseShowRecords(IxEthDBPortId portID, IxEthDBRecordType recordFilter)
 713  *
 714  * @brief This function displays per port database records, given a record type filter
 715  *
 716  * The supported record type filters are:
 717  *
 718  * - IX_ETH_DB_FILTERING_RECORD - displays the non-VLAN filtering records (MAC address, age, static/dynamic)
 719  * - IX_ETH_DB_FILTERING_VLAN_RECORD - displays the VLAN filtering records (MAC address, age, static/dynamic, VLAN ID, CFI, QoS class)
 720  * - IX_ETH_DB_FILTERING_RECORD | IX_ETH_DB_FILTERING_VLAN_RECORD - displays the previous two types of records
 721  * - 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)
 722  * - IX_ETH_DB_FIREWALL_RECORD - displays the firewall MAC address table and firewall operating mode (white list/black list)
 723  * - IX_ETH_DB_ALL_RECORD_TYPES - displays all the record types
 724  * - IX_ETH_DB_NO_RECORD_TYPE - displays only the port status (no records are displayed)
 725  *
 726  * Additionally, the status of each port will be displayed, containg the following information: type, capabilities, enabled status,
 727  * aging enabled status, group membership and maximum frame size.
 728  *
 729  * The port ID can either be an actual port or IX_ETH_DB_ALL_PORTS, in which case the requested information
 730  * will be displayed for all the ports (grouped by port)
 731  *
 732  * - Reentrant    - no
 733  * - ISR Callable - no
 734  *
 735  * @param portID ID of the port to display information on (use IX_ETH_DB_ALL_PORTS for all the ports)
 736  * @param recordFilter record type filter
 737  *
 738  * @retval IX_ETH_DB_SUCCESS operation completed successfully
 739  * @retval IX_ETH_DB_INVALID_PORT portID is invalid
 740  * @retval IX_ETH_DB_PORT_UNINITIALIZED port ID is not initialized
 741  */
 742 IX_ETH_DB_PUBLIC
 743 IxEthDBStatus ixEthDBFilteringDatabaseShowRecords(IxEthDBPortId portID, IxEthDBRecordType recordFilter);
 744
 745 /**
 746  * @ingroup IxEthDB
 747  *
 748  * @fn IxEthDBStatus ixEthDBPortDependencyMapSet(IxEthDBPortId portID, IxEthDBPortMap dependencyPortMap)
 749  *
 750  * @brief Sets the dependency port map for a port
 751  *
 752  * @param portID ID of the port to set the dependency map to
 753  * @param dependencyPortMap new dependency map (as bitmap, each bit set indicates a port being included)
 754  *
 755  * This function is used to share filtering information between ports.
 756  * By adding a port into another port's dependency map the target port
 757  * filtering data will import the filtering data from the port it depends on.
 758  * Any changes to filtering data for a port - such as adding, updating or removing records -
 759  * will trigger updates in the filtering information for all the ports depending on
 760  * on the updated port.
 761  *
 762  * For example, if ports 2 and 3 are set in the port 0 dependency map the filtering
 763  * information for port 0 will also include the filtering information from ports 2 and 3.
 764  * Adding a record to port 2 will also trigger an update not only on port 2 but also on
 765  * port 0.
 766  *
 767  * The dependency map is a 256 bit array where each bit corresponds to a port corresponding to the
 768  * bit offset (bit 0 - port 0, bit 1 - port 1 etc). Setting a bit to 1 indicates that the corresponding
 769  * port is the port map. For example, a dependency port map of 0x14 consists in the ports with IDs 2 and 4.
 770  * Note that the last bit (offset 255) is reserved and should never be set (it will be automatically
 771  * cleared by the function).
 772  *
 773  * By default, each port has a dependency port map consisting only of itself, i.e.
 774  *
 775  * @verbatim
 776     IxEthDBPortMap portMap;
 777
 778     // clear all ports from port map
 779     memset(portMap, 0, sizeof (portMap));
 780
 781     // include portID in port map
 782     portMap[portID / 8] = 1 << (portID % 8);
 783    @endverbatim
 784  *
 785  * - Reentrant    - no
 786  * - ISR Callable - no
 787  *
 788  * @note Setting dependency maps is useful for NPE ports, which benefit from automatic updates
 789  * of filtering information. Setting dependency maps for user-defined ports is not an error
 790  * but will have no actual effect.
 791  *
 792  * @note Including a port in its own dependency map is not compulsory, however note that
 793  * in this case updating the port will not trigger an update on the port itself, which
 794  * might not be the intended behavior
 795  *
 796  * @retval IX_ETH_DB_SUCCESS operation completed successfully
 797  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
 798  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 799  * @retval IX_ETH_DB_INVALID_ARG invalid <i>dependencyPortMap</i> pointer
 800  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE Filtering is not available or not enabled for the port
 801  */
 802 IX_ETH_DB_PUBLIC
 803 IxEthDBStatus ixEthDBPortDependencyMapSet(IxEthDBPortId portID, IxEthDBPortMap dependencyPortMap);
 804
 805 /**
 806  * @ingroup IxEthDB
 807  *
 808  * @fn IxEthDBStatus ixEthDBPortDependencyMapGet(IxEthDBPortId portID, IxEthDBPortMap dependencyPortMap)
 809  *
 810  * @brief Retrieves the dependency port map for a port
 811  *
 812  * @param portID ID of the port to set the dependency map to
 813  * @param dependencyPortMap location where the port dependency map is to be copied
 814  *
 815  * This function will copy the port dependency map to a user specified location.
 816  *
 817  * - Reentrant    - no
 818  * - ISR Callable - no
 819  *
 820  * @retval IX_ETH_DB_SUCCESS operation completed successfully
 821  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
 822  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 823  * @retval IX_ETH_DB_INVALID_ARG invalid <i>dependencyPortMap</i> pointer
 824  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE Filtering is not available or not enabled for the port
 825  */
 826 IX_ETH_DB_PUBLIC
 827 IxEthDBStatus ixEthDBPortDependencyMapGet(IxEthDBPortId portID, IxEthDBPortMap dependencyPortMap);
 828
 829 /**
 830  * @ingroup IxEthDB
 831  *
 832  * @fn IxEthDBStatus ixEthDBPortVlanTagSet(IxEthDBPortId portID, IxEthDBVlanTag vlanTag)
 833  *
 834  * @brief Sets the default 802.1Q VLAN tag for a given port
 835  *
 836  * @param portID @ref IxEthDBPortId [in] - ID of the port to set the default VLAN tag to
 837  * @param vlanTag @ref IxEthDBVlanTag [in] - default 802.1Q VLAN tag
 838  *
 839  * The tag format has 16 bits and it is defined in the IEEE802.1Q specification.
 840  * This tag will be used for tagging untagged frames (if enabled) and classifying
 841  * unexpedited traffic into an internal traffic class (using the user priority field).
 842  *
 843  * <table border="1"> <caption> 802.1Q tag format </caption>
 844  *    <tr> <td>  <b> 3 bits   <td> <b> 1 bit <td> <b> 12 bits </b>
 845  *    <tr> <td> user priority <td>  CFI  <td>   VID
 846  * </table>
 847  *
 848  * User Priority : Defines user priority, giving eight (2^3) priority levels. IEEE 802.1P defines
 849  * the operation for these 3 user priority bits
 850  *
 851  * CFI : Canonical Format Indicator is always set to zero for Ethernet switches. CFI is used for
 852  * compatibility reason between Ethernet type network and Token Ring type network. If a frame received
 853  * at an Ethernet port has a CFI set to 1, then that frame should not be forwarded as it is to an untagged port.
 854  *
 855  * VID : VLAN ID is the identification of the VLAN, which is basically used by the standard 802.1Q.
 856  * It has 12 bits and allow the id entification of 4096 (2^12) VLANs. Of the 4096 possible VIDs, a VID of 0
 857  * is used to identify priority frames and value 4095 (FFF) is reserved, so the maximum possible VLAN
 858  * configurations are 4,094.
 859  *
 860  * - Reentrant    - no
 861  * - ISR Callable - no
 862  *
 863  * @retval IX_ETH_DB_SUCCESS operation completed successfully
 864  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
 865  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 866  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 867  * @retval IX_ETH_DB_INVALID_VLAN <i>vlanTag</i> argument does not parse to a valid 802.1Q VLAN tag
 868  *
 869  * @note a VLAN ID value of 0 indicates that the port is not part of any VLAN
 870  * @note the value of the cannonical frame indicator (CFI) field is ignored, the
 871  * field being used only in frame tagging operations
 872  */
 873 IX_ETH_DB_PUBLIC
 874 IxEthDBStatus ixEthDBPortVlanTagSet(IxEthDBPortId portID, IxEthDBVlanTag vlanTag);
 875
 876 /**
 877  * @ingroup IxEthDB
 878  *
 879  * @fn IxEthDBStatus ixEthDBPortVlanTagGet(IxEthDBPortId portID, IxEthDBVlanTag *vlanTag)
 880  *
 881  * @brief Retrieves the default 802.1Q port VLAN tag for a given port (see also @ref ixEthDBPortVlanTagSet)
 882  *
 883  * @param portID @ref IxEthDBPortId [in] - ID of the port to retrieve the default VLAN tag from
 884  * @param vlanTag @ref IxEthDBVlanTag [out] - location to write the default port 802.1Q VLAN tag to
 885  *
 886  * - Reentrant    - no
 887  * - ISR Callable - no
 888  *
 889  * @retval IX_ETH_DB_SUCCESS operation completed successfully
 890  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
 891  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 892  * @retval IX_ETH_DB_INVALID_ARG invalid vlanTag pointer
 893  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 894  */
 895 IX_ETH_DB_PUBLIC
 896 IxEthDBStatus ixEthDBPortVlanTagGet(IxEthDBPortId portID, IxEthDBVlanTag *vlanTag);
 897
 898 /**
 899  * @ingroup IxEthDB
 900  *
 901  * @fn IxEthDBStatus ixEthDBVlanTagSet(IxEthDBMacAddr *macAddr, IxEthDBVlanTag vlanTag)
 902  *
 903  * @brief Sets the 802.1Q VLAN tag for a database record
 904  *
 905  * @param macAddr MAC address
 906  * @param vlanTag 802.1Q VLAN tag
 907  *
 908  * This function is used together with @ref ixEthDBVlanTagGet to provide MAC-based VLAN classification support.
 909  * Please note that the bridging application must contain specific code to make use of this feature (see below).
 910  *
 911  * VLAN tags can be set only in IX_ETH_DB_FILTERING_RECORD or IX_ETH_DB_FILTERING_VLAN_RECORD type records.
 912  * If to an IX_ETH_DB_FILTERING_RECORD type record is added a VLAN tag the record type is automatically
 913  * changed to IX_ETH_DB_FILTERING_VLAN_RECORD. Once this has occurred the record type will never
 914  * revert to a non-VLAN type (unless deleted and re-added).
 915  *
 916  * Record types used for different purposes (such as IX_ETH_DB_WIFI_RECORD) will be ignored by
 917  * this function.
 918  *
 919  * After using this function to associate a VLAN ID with a MAC address the VLAN ID can be extracted knowing the
 920  * MAC address using @ref ixEthDBVlanTagGet. This mechanism can be used to implement MAC-based VLAN classification
 921  * if a bridging application searches for the VLAN tag when receiving a frame based on the source MAC address
 922  * (contained in the <i>ixp_ne_src_mac</i> field of the buffer header).
 923  * If found in the database, the application can instruct the NPE to tag the frame by writing the VLAN tag
 924  * in the <i>ixp_ne_vlan_tci</i> field of the buffer header. This way the NPE will inspect the Egress tagging
 925  * rule associated with the given VLAN ID on the Tx port and tag the frame if Egress tagging on the VLAN is
 926  * allowed. Additionally, Egress tagging can be forced by setting the <i>ixp_ne_tx_flags.tag_over</i> and
 927  * <i>ixp_ne_tx_flags.tag_mode</i> flags in the buffer header.
 928  *
 929  * - Reentrant    - no
 930  * - ISR Callable - no
 931  *
 932  * @note this function will <b>not</b> add a filtering record, it can only be used to update an existing one
 933  *
 934  * @retval IX_ETH_DB_SUCCESS operation completed successfully
 935  * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> pointer
 936  * @retval IX_ETH_DB_NO_SUCH_ADDR a filtering record with the specified MAC address was not found
 937  * @retval IX_ETH_DB_INVALID_VLAN <i>vlanTag</i> argument does not parse to a valid 802.1Q VLAN tag
 938  */
 939 IX_ETH_DB_PUBLIC
 940 IxEthDBStatus ixEthDBVlanTagSet(IxEthDBMacAddr *macAddr, IxEthDBVlanTag vlanTag);
 941
 942 /**
 943  * @ingroup IxEthDB
 944  *
 945  * @fn ixEthDBVlanTagGet(IxEthDBMacAddr *macAddr, IxEthDBVlanTag *vlanTag)
 946  *
 947  * @brief Retrieves the 802.1Q VLAN tag from a database record given the record MAC address
 948  *
 949  * @param macAddr MAC address
 950  * @param vlanTag location to write the record 802.1Q VLAN tag to
 951  *
 952  * @note VLAN tags can be retrieved only from IX_ETH_DB_FILTERING_VLAN_RECORD type records
 953  *
 954  * This function is used together with ixEthDBVlanTagSet to provide MAC-based VLAN classification support.
 955  * Please note that the bridging application must contain specific code to make use of this feature (see @ref ixEthDBVlanTagSet).
 956  *
 957  * - Reentrant    - no
 958  * - ISR Callable - no
 959  *
 960  * @retval IX_ETH_DB_SUCCESS operation completed successfully
 961  * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> or <i>vlanTag</i> pointer
 962  * @retval IX_ETH_DB_NO_SUCH_ADDR a filtering record with the specified MAC address was not found
 963  */
 964 IX_ETH_DB_PUBLIC
 965 IxEthDBStatus ixEthDBVlanTagGet(IxEthDBMacAddr *macAddr, IxEthDBVlanTag *vlanTag);
 966
 967 /**
 968  * @ingroup IxEthDB
 969  *
 970  * @fn IxEthDBStatus ixEthDBPortVlanMembershipAdd(IxEthDBPortId portID, IxEthDBVlanId vlanID)
 971  *
 972  * @brief Adds a VLAN ID to a port's VLAN membership table
 973  *
 974  * Adding a VLAN ID to a port's VLAN membership table will cause frames tagged with the specified
 975  * VLAN ID to be accepted by the frame filter, if Ingress VLAN membership filtering is enabled.
 976  *
 977  * - Reentrant    - no
 978  * - ISR Callable - no
 979  *
 980  * @param portID @ref IxEthDBPortId [in] - ID of the port to add the VLAN ID membership to
 981  * @param vlanID @ref IxEthDBVlanId [in] - VLAN ID to be added to the port membership table
 982  *
 983  * @retval IX_ETH_DB_SUCCESS operation completed successfully
 984  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
 985  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
 986  * @retval IX_ETH_DB_INVALID_VLAN vlanID is not a valid VLAN ID
 987  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
 988  * @retval IX_FAIL unknown OS or NPE communication error
 989  *
 990  * @note A port's default VLAN ID is always in its own membership table, hence there
 991  * is no need to explicitly add it using this function (although it is not an error
 992  * to do so)
 993  */
 994 IX_ETH_DB_PUBLIC
 995 IxEthDBStatus ixEthDBPortVlanMembershipAdd(IxEthDBPortId portID, IxEthDBVlanId vlanID);
 996
 997 /**
 998  * @ingroup IxEthDB
 999  *
1000  * @fn IxEthDBStatus ixEthDBPortVlanMembershipRangeAdd(IxEthDBPortId portID, IxEthDBVlanId vlanIDMin, IxEthDBVlanId vlanIDMax)
1001  *
1002  * @brief Adds a VLAN ID range to a port's VLAN membership table
1003  *
1004  * All the VLAN IDs in the specified range will be added to the port VLAN
1005  * membership table, including the range start and end VLAN IDs. Tagged frames with
1006  * VLAN IDs in the specified range will be accepted by the frame filter, if Ingress VLAN
1007  * membership filtering is enabled.
1008  *
1009  * - Reentrant    - no
1010  * - ISR Callable - no
1011  *
1012  * @param portID @ref IxEthDBPortId [in] - port ID to add the VLAN membership range into
1013  * @param vlanIDMin @ref IxEthDBVlanId [in] - start of the VLAN ID range
1014  * @param vlanIDMax @ref IxEthDBVlanId [in] - end of the VLAN ID range
1015  *
1016  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1017  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1018  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1019  * @retval IX_ETH_DB_INVALID_VLAN the specified VLAN IDs are invalid or do not constitute a range
1020  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1021  * @retval IX_FAIL unknown OS or NPE communication error
1022  *
1023  * @note Is is valid to use the same VLAN ID for both vlanIDMin and vlanIDMax, in which case this
1024  * function will behave as @ref ixEthDBPortVlanMembershipAdd
1025  *
1026  * @note A port's default VLAN ID is always in its own membership table, hence there is no need
1027  * to explicitly add it using this function (although it is not an error to do so)
1028  */
1029 IX_ETH_DB_PUBLIC
1030 IxEthDBStatus ixEthDBPortVlanMembershipRangeAdd(IxEthDBPortId portID, IxEthDBVlanId vlanIDMin, IxEthDBVlanId vlanIDMax);
1031
1032 /**
1033  * @ingroup IxEthDB
1034  *
1035  * @fn IxEthDBStatus ixEthDBPortVlanMembershipRemove(IxEthDBPortId portID, IxEthDBVlanId vlanID)
1036  *
1037  * @brief Removes a VLAN ID from a port's VLAN membership table
1038  *
1039  * Frames tagged with a VLAN ID which is not in a port's VLAN membership table
1040  * will be discarded by the frame filter, if Ingress membership filtering is enabled.
1041  *
1042  * - Reentrant    - no
1043  * - ISR Callable - no
1044  *
1045  * @param portID @ref IxEthDBPortId [in] - ID of the port to remove the VLAN ID membership from
1046  * @param vlanID @ref IxEthDBVlanId [in] - VLAN ID to be removed from the port membership table
1047  *
1048  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1049  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1050  * @retval IX_ETH_DB_INVALID_VLAN vlanID is not a valid VLAN ID
1051  * @retval IX_ETH_DB_NO_PERMISSION attempted to remove the default VLAN ID
1052  * from the port membership table (vlanID was set to the default port VLAN ID)
1053  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1054  * @retval IX_FAIL unknown OS or NPE communication error
1055  *
1056  * @note A port's default VLAN ID cannot be removed from the port's membership
1057  * table; attempting it will return IX_ETH_DB_NO_PERMISSION
1058  */
1059 IX_ETH_DB_PUBLIC
1060 IxEthDBStatus ixEthDBPortVlanMembershipRemove(IxEthDBPortId portID, IxEthDBVlanId vlanID);
1061
1062 /**
1063  * @ingroup IxEthDB
1064  *
1065  * @fn IxEthDBStatus ixEthDBPortVlanMembershipRangeRemove(IxEthDBPortId portID, IxEthDBVlanId vlanIDMin, IxEthDBVlanId vlanIDMax)
1066  *
1067  * @brief Removes a VLAN ID range from a port's VLAN membership table
1068  *
1069  * All the VLAN IDs in the specified range will be removed from the port VLAN
1070  * membership table, including the range start and end VLAN IDs. Tagged frames
1071  * with VLAN IDs in the range will be discarded by the frame filter, if Ingress
1072  * membership filtering is enabled.
1073  *
1074  * - Reentrant    - no
1075  * - ISR Callable - no
1076  *
1077  * @param portID @ref IxEthDBPortId [in] - ID of the port to remove the VLAN membership range from
1078  * @param vlanIDMin @ref IxEthDBVlanId [in] - start of the VLAN ID range
1079  * @param vlanIDMax @ref IxEthDBVlanId [in] - end of the VLAN ID range
1080  *
1081  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1082  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1083  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1084  * @retval IX_ETH_DB_INVALID_VLAN the specified VLAN IDs are invalid or do not constitute a range
1085  * @retval IX_ETH_DB_NO_PERMISSION attempted to remove the default VLAN ID
1086  * from the port membership table (both vlanIDMin and vlanIDMax were set to the default port VLAN ID)
1087  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1088  * @retval IX_FAIL unknown OS or NPE communication error
1089  *
1090  * @note Is is valid to use the same VLAN ID for both vlanIDMin and vlanIDMax, in which case
1091  * function will behave as @ref ixEthDBPortVlanMembershipRemove
1092  *
1093  * @note If the given range overlaps the default port VLAN ID this function
1094  * will remove all the VLAN IDs in the range except for the port VLAN ID from its
1095  * own membership table. This situation will be silently dealt with (no error message
1096  * will be returned) as long as the range contains more than one value (i.e. at least
1097  * one other value, apart from the default port VLAN ID). If the function is called
1098  * with the vlanIDMin and vlanIDMax parameters both set to the port default VLAN ID, the
1099  * function will infer that an attempt was specifically made to remove the default port
1100  * VLAN ID from the port membership table, in which case the return value will be
1101  * IX_ETH_DB_NO_PERMISSION.
1102  */
1103 IX_ETH_DB_PUBLIC
1104 IxEthDBStatus ixEthDBPortVlanMembershipRangeRemove(IxEthDBPortId portID, IxEthDBVlanId vlanIDMin, IxEthDBVlanId vlanIDMax);
1105
1106 /**
1107  * @ingroup IxEthDB
1108  *
1109  * @fn IxEthDBStatus ixEthDBPortVlanMembershipSet(IxEthDBPortId portID, IxEthDBVlanSet vlanSet)
1110  *
1111  * @brief Sets a port's VLAN membership table
1112  *
1113  * Sets a port's VLAN membership table from a complete VLAN table containing all the possible
1114  * 4096 VLAN IDs. The table format is an array containing 4096 bits (512 bytes), where each bit
1115  * indicates whether the VLAN at that bit index is in the port's membership list (if set) or
1116  * not (unset).
1117  *
1118  * The bit at index 0, indicating VLAN ID 0, indicates no VLAN membership and therefore no
1119  * other bit must be set if bit 0 is set.
1120  *
1121  * The bit at index 4095 is reserved and should never be set (it will be ignored if set).
1122  *
1123  * The bit referencing the same VLAN ID as the default port VLAN ID should always be set, as
1124  * the membership list must contain at least the default port VLAN ID.
1125  *
1126  * - Reentrant    - no
1127  * - ISR Callable - no
1128  *
1129  * @param portID @ref IxEthDBPortId [in] - port ID to set the VLAN membership table to
1130  * @param vlanSet @ref IxEthDBVlanSet [in] - pointer to the VLAN membership table
1131  *
1132  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1133  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1134  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1135  * @retval IX_ETH_DB_INVALID_ARG invalid <i>vlanSet</i> pointer
1136  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1137  * @retval IX_FAIL unknown OS or NPE communication error
1138  */
1139 IX_ETH_DB_PUBLIC
1140 IxEthDBStatus ixEthDBPortVlanMembershipSet(IxEthDBPortId portID, IxEthDBVlanSet vlanSet);
1141
1142 /**
1143  * @ingroup IxEthDB
1144  *
1145  * @fn IxEthDBStatus ixEthDBPortVlanMembershipGet(IxEthDBPortId portID, IxEthDBVlanSet vlanSet)
1146  *
1147  * @brief Retrieves a port's VLAN membership table
1148  *
1149  * Retrieves the complete VLAN membership table from a port, containing all the possible
1150  * 4096 VLAN IDs. The table format is an array containing 4096 bits (512 bytes), where each bit
1151  * indicates whether the VLAN at that bit index is in the port's membership list (if set) or
1152  * not (unset).
1153  *
1154  * The bit at index 0, indicating VLAN ID 0, indicates no VLAN membership and therefore no
1155  * other bit will be set if bit 0 is set.
1156  *
1157  * The bit at index 4095 is reserved and will not be set (it will be ignored if set).
1158  *
1159  * The bit referencing the same VLAN ID as the default port VLAN ID will always be set, as
1160  * the membership list must contain at least the default port VLAN ID.
1161  *
1162  * - Reentrant    - no
1163  * - ISR Callable - no
1164  *
1165  * @param portID @ref IxEthDBPortId [in] - port ID to retrieve the VLAN membership table from
1166  * @param vlanSet @ref IxEthDBVlanSet [out] - pointer a location where the VLAN membership table will be
1167  *                written to
1168  *
1169  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1170  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1171  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1172  * @retval IX_ETH_DB_INVALID_ARG invalid <i>vlanSet</i> pointer
1173  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1174  */
1175 IX_ETH_DB_PUBLIC
1176 IxEthDBStatus ixEthDBPortVlanMembershipGet(IxEthDBPortId portID, IxEthDBVlanSet vlanSet);
1177
1178 /**
1179  * @ingroup IxEthDB
1180  *
1181  * @fn IxEthDBStatus ixEthDBAcceptableFrameTypeSet(IxEthDBPortId portID, IxEthDBFrameFilter frameFilter)
1182  *
1183  * @brief Sets a port's acceptable frame type filter
1184  *
1185  * The acceptable frame type is one (or a combination) of the following values:
1186  *    - IX_ETH_DB_ACCEPT_ALL_FRAMES       - accepts all the frames
1187  *    - IX_ETH_DB_UNTAGGED_FRAMES         - accepts untagged frames
1188  *    - IX_ETH_DB_VLAN_TAGGED_FRAMES      - accepts tagged frames
1189  *    - IX_ETH_DB_PRIORITY_TAGGED_FRAMES  - accepts tagged frames with VLAN ID set to 0 (no VLAN membership)
1190  *
1191  * Except for using the exact values given above only the following combinations are valid:
1192  *    - IX_ETH_DB_UNTAGGED_FRAMES | IX_ETH_DB_VLAN_TAGGED_FRAMES
1193  *    - IX_ETH_DB_UNTAGGED_FRAMES | IX_ETH_DB_PRIORITY_TAGGED_FRAMES
1194  *
1195  * Please note that IX_ETH_DB_UNTAGGED_FRAMES | IX_ETH_DB_VLAN_TAGGED_FRAMES is equivalent
1196  * to IX_ETH_DB_ACCEPT_ALL_FRAMES.
1197  *
1198  * - Reentrant    - no
1199  * - ISR Callable - no
1200  *
1201  * @note by default the acceptable frame type filter is set to IX_ETH_DB_ACCEPT_ALL_FRAMES
1202  *
1203  * @note setting the acceptable frame type to PRIORITY_TAGGED_FRAMES is internally
1204  * accomplished by changing the frame filter to VLAN_TAGGED_FRAMES and setting the
1205  * VLAN membership list to include only VLAN ID 0; the membership list will need
1206  * to be restored manually to an appropriate value if the acceptable frame type
1207  * filter is changed back to ACCEPT_ALL_FRAMES or VLAN_TAGGED_FRAMES; failure to do so
1208  * will filter all VLAN traffic bar frames tagged with VLAN ID 0
1209  *
1210  * @param portID @ref IxEthDBPortId [in] - port ID to set the acceptable frame type filter to
1211  * @param frameFilter @ref IxEthDBFrameFilter [in] - acceptable frame type filter
1212  *
1213  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1214  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1215  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1216  * @retval IX_ETH_DB_INVALID_ARG invalid frame type filter
1217  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1218  * @retval IX_FAIL unknown OS or NPE communication error
1219  */
1220 IX_ETH_DB_PUBLIC
1221 IxEthDBStatus ixEthDBAcceptableFrameTypeSet(IxEthDBPortId portID, IxEthDBFrameFilter frameFilter);
1222
1223 /**
1224  * @ingroup IxEthDB
1225  *
1226  * @fn IxEthDBStatus ixEthDBAcceptableFrameTypeGet(IxEthDBPortId portID, IxEthDBFrameFilter *frameFilter)
1227  *
1228  * @brief Retrieves a port's acceptable frame type filter
1229  *
1230  * For a description of the acceptable frame types see @ref ixEthDBAcceptableFrameTypeSet
1231  *
1232  * - Reentrant    - no
1233  * - ISR Callable - no
1234  *
1235  * @param portID @ref IxEthDBPortId [in] - port ID to retrieve the acceptable frame type filter from
1236  * @param frameFilter @ref IxEthDBFrameFilter [out] - location to store the acceptable frame type filter
1237  *
1238  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1239  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1240  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1241  * @retval IX_ETH_DB_INVALID_ARG invalid <i>frameFilter</i> pointer argument
1242  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1243  */
1244 IX_ETH_DB_PUBLIC
1245 IxEthDBStatus ixEthDBAcceptableFrameTypeGet(IxEthDBPortId portID, IxEthDBFrameFilter *frameFilter);
1246
1247 /**
1248  * @ingroup IxEthDB
1249  *
1250  * @fn IxEthDBStatus ixEthDBPriorityMappingTableSet(IxEthDBPortId portID, IxEthDBPriorityTable priorityTable)
1251  *
1252  * @brief Sets a port's priority mapping table
1253  *
1254  * The priority mapping table is an 8x2 table mapping a QoS (user) priority into an internal
1255  * traffic class. There are 8 valid QoS priorities (0..7, 0 being the lowest) which can be
1256  * mapped into one of the 4 available traffic classes (0..3, 0 being the lowest).
1257  * If a custom priority mapping table is not specified using this function the following
1258  * default priority table will be used (as per IEEE 802.1Q and IEEE 802.1D):
1259  *
1260  * <table border="1"> <caption> QoS traffic classes  </caption>
1261  *    <tr> <td> <b> QoS priority <td> <b> Default traffic class <td> <b> Traffic type </b>
1262  *    <tr> <td>      0       <td>           1           <td> Best effort, default class for unexpedited traffic
1263  *    <tr> <td>      1       <td>           0           <td> Background traffic
1264  *    <tr> <td>      2       <td>           0           <td> Spare bandwidth
1265  *    <tr> <td>      3       <td>           1           <td> Excellent effort
1266  *    <tr> <td>      4       <td>           2           <td> Controlled load
1267  *    <tr> <td>      5       <td>           2           <td> Video traffic
1268  *    <tr> <td>      6       <td>           3           <td> Voice traffic
1269  *    <tr> <td>      7       <td>           3           <td> Network control
1270  * </table>
1271  *
1272  * - Reentrant    - no
1273  * - ISR Callable - no
1274  *
1275  * @param portID @ref IxEthDBPortId [in] - port ID of the port to set the priority mapping table to
1276  * @param priorityTable @ref IxEthDBPriorityTable [in] - location of the user priority table
1277  *
1278  * @note The provided table will be copied into internal data structures in EthDB and
1279  * can be deallocated by the called after this function has completed its execution, if
1280  * so desired
1281  *
1282  * @warning The number of available traffic classes differs depending on the NPE images
1283  * and queue configuration. Check IxEthDBQoS.h for up-to-date information on the availability of
1284  * traffic classes. Note that specifiying a traffic class in the priority map which exceeds
1285  * the system availability will produce an IX_ETH_DB_INVALID_PRIORITY return error code and no
1286  * priority will be remapped.
1287  *
1288  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1289  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1290  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1291  * @retval IX_ETH_DB_INVALID_ARG invalid <i>priorityTable</i> pointer
1292  * @retval IX_ETH_DB_INVALID_PRIORITY at least one priority value exceeds
1293  * the current number of available traffic classes
1294  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1295  * @retval IX_FAIL unknown OS or NPE communication error
1296  */
1297 IX_ETH_DB_PUBLIC
1298 IxEthDBStatus ixEthDBPriorityMappingTableSet(IxEthDBPortId portID, IxEthDBPriorityTable priorityTable);
1299
1300 /**
1301  * @ingroup IxEthDB
1302  *
1303  * @fn IxEthDBStatus ixEthDBPriorityMappingTableGet(IxEthDBPortId portID, IxEthDBPriorityTable priorityTable)
1304  *
1305  * @brief Retrieves a port's priority mapping table
1306  *
1307  * The priority mapping table for the given port will be copied in the location
1308  * specified by the caller using "priorityTable"
1309  *
1310  * - Reentrant    - no
1311  * - ISR Callable - no
1312  *
1313  * @param portID ID @ref IxEthDBPortId [in] - of the port to retrieve the priority mapping table from
1314  * @param priorityTable @ref IxEthDBPriorityTable [out] - pointer to a user specified location where the table will be copied to
1315  *
1316  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1317  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1318  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1319  * @retval IX_ETH_DB_INVALID_ARG invalid priorityTable pointer
1320  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1321  */
1322 IX_ETH_DB_PUBLIC
1323 IxEthDBStatus ixEthDBPriorityMappingTableGet(IxEthDBPortId portID, IxEthDBPriorityTable priorityTable);
1324
1325 /**
1326  * @ingroup IxEthDB
1327  *
1328  * @fn IxEthDBStatus ixEthDBPriorityMappingClassSet(IxEthDBPortId portID, IxEthDBPriority userPriority, IxEthDBPriority trafficClass)
1329  *
1330  * @brief Sets one QoS/user priority => traffic class mapping in a port's priority mapping table
1331  *
1332  * This function establishes a mapping between a user (QoS) priority and an internal traffic class.
1333  * The mapping will be saved in the port's priority mapping table. Use this function when not all
1334  * the QoS priorities need remapping (see also @ref ixEthDBPriorityMappingTableSet)
1335  *
1336  * - Reentrant    - no
1337  * - ISR Callable - no
1338  *
1339  * @param portID @ref IxEthDBPortId [in] - ID of the port to set the mapping to
1340  * @param userPriority @ref IxEthDBPriority [in] - user (QoS) priority, between 0 and 7 (0 being the lowest)
1341  * @param trafficClass @ref IxEthDBPriority [in] - internal traffic class, between 0 and 3 (0 being the lowest)
1342  *
1343  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1344  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1345  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1346  * @retval IX_ETH_DB_INVALID_PRIORITY <i>userPriority</i> out of range or
1347  * <i>trafficClass</i> is beyond the number of currently available traffic classes
1348  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1349  * @retval IX_FAIL unknown OS or NPE communication error
1350  */
1351 IX_ETH_DB_PUBLIC
1352 IxEthDBStatus ixEthDBPriorityMappingClassSet(IxEthDBPortId portID, IxEthDBPriority userPriority, IxEthDBPriority trafficClass);
1353
1354 /**
1355  * @ingroup IxEthDB
1356  *
1357  * @fn IxEthDBStatus ixEthDBPriorityMappingClassGet(IxEthDBPortId portID, IxEthDBPriority userPriority, IxEthDBPriority *trafficClass)
1358  *
1359  * @brief Retrieves one QoS/user priority => traffic class mapping in a port's priority mapping table
1360  *
1361  * This function retrieves the internal traffic class associated with a QoS (user) priority from a given
1362  * port's priority mapping table. Use this function when not all the QoS priority mappings are
1363  * required (see also @ref ixEthDBPriorityMappingTableGet)
1364  *
1365  * - Reentrant    - no
1366  * - ISR Callable - no
1367  *
1368  * @param portID @ref IxEthDBPortId [in] - ID of the port to set the mapping to
1369  * @param userPriority @ref IxEthDBPriority [in] - user (QoS) priority, between 0 and 7 (0 being the lowest)
1370  * @param trafficClass @ref IxEthDBPriority [out] - location to write the corresponding internal traffic class to
1371  *
1372  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1373  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1374  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1375  * @retval IX_ETH_DB_INVALID_PRIORITY invalid userPriority value (out of range)
1376  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1377  * @retval IX_ETH_DB_INVALID_ARG invalid <i>trafficClass</i> pointer argument
1378  */
1379 IX_ETH_DB_PUBLIC
1380 IxEthDBStatus ixEthDBPriorityMappingClassGet(IxEthDBPortId portID, IxEthDBPriority userPriority, IxEthDBPriority *trafficClass);
1381
1382 /**
1383  * @ingroup IxEthDB
1384  *
1385  * @fn IxEthDBStatus ixEthDBEgressVlanEntryTaggingEnabledSet(IxEthDBPortId portID, IxEthDBVlanId vlanID, BOOL enabled)
1386  *
1387  * @brief Enables or disables Egress VLAN tagging for a port and a given VLAN
1388  *
1389  * This function enables or disables Egress VLAN tagging for the given port and VLAN ID.
1390  * If the VLAN tagging for a certain VLAN ID is enabled then all the frames to be
1391  * transmitted on the given port tagged with the same VLAN ID will be transmitted in a tagged format.
1392  * If tagging is not enabled for the given VLAN ID, the VLAN tag from the frames matching
1393  * this VLAN ID will be removed (the frames will be untagged).
1394  *
1395  * VLAN ID 4095 is reserved and should never be used with this function.
1396  * VLAN ID 0 has the special meaning of "No VLAN membership" and it is used in this
1397  * context to allow the port to send priority-tagged frames or not.
1398  *
1399  * By default, no Egress VLAN tagging is enabled on any port.
1400  *
1401  * - Reentrant    - no
1402  * - ISR Callable - no
1403  *
1404  * @param portID @ref IxEthDBPortId [in] - ID of the port to enable or disable the VLAN ID Egress tagging on
1405  * @param vlanID @ref IxEthDBVlanId [in] - VLAN ID to be matched against outgoing frames
1406  * @param enabled BOOL [in] - true to enable Egress VLAN tagging on the port and given VLAN, and
1407  *                false to disable Egress VLAN tagging
1408  *
1409  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1410  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1411  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1412  * @retval IX_ETH_DB_INVALID_VLAN invalid VLAN ID (out of range)
1413  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1414  * @retval IX_FAIL unknown OS or NPE communication error
1415  */
1416 IX_ETH_DB_PUBLIC
1417 IxEthDBStatus ixEthDBEgressVlanEntryTaggingEnabledSet(IxEthDBPortId portID, IxEthDBVlanId vlanID, BOOL enabled);
1418
1419 /**
1420  * @ingroup IxEthDB
1421  *
1422  * @fn IxEthDBStatus ixEthDBEgressVlanEntryTaggingEnabledGet(IxEthDBPortId portID, IxEthDBVlanId vlanID, BOOL *enabled)
1423  *
1424  * @brief Retrieves the Egress VLAN tagging enabling status for a port and VLAN ID
1425  *
1426  * @param portID [in] - ID of the port to extract the Egress VLAN ID tagging status from
1427  * @param vlanID VLAN [in] - ID whose tagging status is to be extracted
1428  * @param enabled [in] - user-specifed location where the status is copied to; following
1429  * the successfull execution of this function the value will be true if Egress VLAN
1430  * tagging is enabled for the given port and VLAN ID, and false otherwise
1431  *
1432  * - Reentrant    - no
1433  * - ISR Callable - no
1434  *
1435  * @see ixEthDBEgressVlanEntryTaggingEnabledGet
1436  *
1437  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1438  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1439  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1440  * @retval IX_ETH_DB_INVALID_VLAN invalid VLAN ID (out of range)
1441  * @retval IX_ETH_DB_INVALID_ARG invalid <i>enabled</i> argument pointer
1442  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1443  */
1444 IX_ETH_DB_PUBLIC
1445 IxEthDBStatus ixEthDBEgressVlanEntryTaggingEnabledGet(IxEthDBPortId portID, IxEthDBVlanId vlanID, BOOL *enabled);
1446
1447 /**
1448  * @ingroup IxEthDB
1449  *
1450  * @fn IxEthDBStatus ixEthDBEgressVlanRangeTaggingEnabledSet(IxEthDBPortId portID, IxEthDBVlanId vlanIDMin, IxEthDBVlanId vlanIDMax, BOOL enabled)
1451  *
1452  * @brief Enables or disables Egress VLAN tagging for a port and given VLAN range
1453  *
1454  * This function is very similar to @ref ixEthDBEgressVlanEntryTaggingEnabledSet with the
1455  * difference that it can manipulate the Egress tagging status on multiple VLAN IDs,
1456  * defined by a contiguous range. Note that both limits in the range are explicitly
1457  * included in the execution of this function.
1458  *
1459  * - Reentrant    - no
1460  * - ISR Callable - no
1461  *
1462  * @param portID @ref IxEthDBPortId [in] - ID of the port to enable or disable the VLAN ID Egress tagging on
1463  * @param vlanIDMin @ref IxEthDBVlanId [in] - start of the VLAN range to be matched against outgoing frames
1464  * @param vlanIDMax @ref IxEthDBVlanId [in] - end of the VLAN range to be matched against outgoing frames
1465  * @param enabled BOOL [in] - true to enable Egress VLAN tagging on the port and given VLAN range,
1466  *                and false to disable Egress VLAN tagging
1467  *
1468  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1469  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1470  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1471  * @retval IX_ETH_DB_INVALID_VLAN invalid VLAN ID (out of range), or do not constitute a range
1472  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1473  * @retval IX_ETH_DB_NO_PERMISSION attempted to explicitly remove the default port VLAN ID from the tagging table
1474  * @retval IX_FAIL unknown OS or NPE communication error
1475  *
1476  * @note Specifically removing the default port VLAN ID from the Egress tagging table by setting both vlanIDMin and vlanIDMax
1477  * to the VLAN ID portion of the PVID is not allowed by this function and will return IX_ETH_DB_NO_PERMISSION.
1478  * However, this can be circumvented, should the user specifically desire this, by either using a
1479  * larger range (vlanIDMin < vlanIDMax) or by using ixEthDBEgressVlanEntryTaggingEnabledSet.
1480  */
1481 IX_ETH_DB_PUBLIC
1482 IxEthDBStatus ixEthDBEgressVlanRangeTaggingEnabledSet(IxEthDBPortId portID, IxEthDBVlanId vlanIDMin, IxEthDBVlanId vlanIDMax, BOOL enabled);
1483
1484 /**
1485  * @ingroup IxEthDB
1486  *
1487  * @fn IxEthDBStatus ixEthDBEgressVlanTaggingEnabledSet(IxEthDBPortId portID, IxEthDBVlanSet vlanSet)
1488  *
1489  * @brief Sets the complete Egress VLAN tagging table for a port
1490  *
1491  * This function is used to set the VLAN tagging/untagging per VLAN ID for a given port
1492  * covering the entire VLAN ID range (0..4094). The <i>vlanSet</i> parameter is a 4096
1493  * bit array, each bit indicating the Egress behavior for the corresponding VLAN ID.
1494  * If a bit is set then outgoing frames with the corresponding VLAN ID will be transmitted
1495  * with the VLAN tag, otherwise the frame will be transmitted without the VLAN tag.
1496  *
1497  * Bit 0 has a special significance, indicating tagging or tag removal for priority-tagged
1498  * frames.
1499  *
1500  * Bit 4095 is reserved and should never be set (it will be ignored if set).
1501  *
1502  * - Reentrant    - no
1503  * - ISR Callable - no
1504  *
1505  * @param portID @ref IxEthDBPortId [in] - ID of the port whose Egress VLAN tagging behavior is set
1506  * @param vlanSet @ref IxEthDBVlanSet [in] - 4096 bit array controlling per-VLAN tagging and untagging
1507  *
1508  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1509  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1510  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1511  * @retval IX_ETH_DB_INVALID_ARG invalid <i>vlanSet</i> pointer
1512  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1513  * @retval IX_FAIL unknown OS or NPE communication error
1514  *
1515  * @warning This function will automatically add the default port VLAN ID to the Egress tagging table
1516  * every time it is called. The user should manually call ixEthDBEgressVlanEntryTaggingEnabledSet to
1517  * prevent tagging on the default port VLAN ID if the default behavior is not intended.
1518  */
1519 IX_ETH_DB_PUBLIC
1520 IxEthDBStatus ixEthDBEgressVlanTaggingEnabledSet(IxEthDBPortId portID, IxEthDBVlanSet vlanSet);
1521
1522 /**
1523  * @ingroup IxEthDB
1524  *
1525  * @fn IxEthDBStatus ixEthDBEgressVlanTaggingEnabledGet(IxEthDBPortId portID, IxEthDBVlanSet vlanSet)
1526  *
1527  * @brief Retrieves the complete Egress VLAN tagging table from a port
1528  *
1529  * This function copies the 4096 bit table controlling the Egress VLAN tagging into a user specified
1530  * area. Each bit in the array indicates whether tagging for the corresponding VLAN (the bit position
1531  * in the array) is enabled (the bit is set) or not (the bit is unset).
1532  *
1533  * Bit 4095 is reserved and should not be set (it will be ignored if set).
1534  *
1535  * @see ixEthDBEgressVlanTaggingEnabledSet
1536  *
1537  * @param portID @ref IxEthDBPortId [in] - ID of the port whose Egress VLAN tagging behavior is retrieved
1538  * @param vlanSet @ref IxEthDBVlanSet [out] - user location to copy the Egress tagging table into; should have
1539  * room to store 4096 bits (512 bytes)
1540  *
1541  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1542  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1543  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1544  * @retval IX_ETH_DB_INVALID_ARG invalid <i>vlanSet</i> pointer
1545  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1546  */
1547 IX_ETH_DB_PUBLIC
1548 IxEthDBStatus ixEthDBEgressVlanTaggingEnabledGet(IxEthDBPortId portID, IxEthDBVlanSet vlanSet);
1549
1550 /**
1551  * @ingroup IxEthDB
1552  *
1553  * @fn IxEthDBStatus ixEthDBIngressVlanTaggingEnabledSet(IxEthDBPortId portID, IxEthDBTaggingAction taggingAction)
1554  *
1555  * @brief Sets the Ingress VLAN tagging behavior for a port
1556  *
1557  * A port's Ingress tagging behavior is controlled by the taggingAction parameter,
1558  * which can take one of the following values:
1559  *
1560  * - IX_ETH_DB_PASS_THROUGH - leaves the frame unchanged (does not add or remove the VLAN tag)
1561  * - IX_ETH_DB_ADD_TAG - adds the VLAN tag if not present, using the default port VID
1562  * - IX_ETH_DB_REMOVE_TAG - removes the VLAN tag if present
1563  *
1564  * @param portID @ref IxEthDBPortId [in] - ID of the port whose Ingress VLAN tagging behavior is set
1565  * @param taggingAction @ref IxEthDBTaggingAction [in] - tagging behavior for the port
1566  *
1567  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1568  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1569  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1570  * @retval IX_ETH_DB_INVALID_ARG invalid <i>taggingAction</i> argument
1571  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1572  * @retval IX_FAIL unknown OS or NPE communication error
1573  */
1574 IX_ETH_DB_PUBLIC
1575 IxEthDBStatus ixEthDBIngressVlanTaggingEnabledSet(IxEthDBPortId portID, IxEthDBTaggingAction taggingAction);
1576
1577 /**
1578  * @ingroup IxEthDB
1579  *
1580  * @fn IxEthDBStatus ixEthDBIngressVlanTaggingEnabledGet(IxEthDBPortId portID, IxEthDBTaggingAction *taggingAction)
1581  *
1582  * @brief Retrieves the Ingress VLAN tagging behavior from a port (see @ref ixEthDBIngressVlanTaggingEnabledSet)
1583  *
1584  * @param portID @ref IxEthDBPortId [in] - ID of the port whose Ingress VLAN tagging behavior is set
1585  * @param taggingAction @ref IxEthDBTaggingAction [out] - location where the tagging behavior for the port is written to
1586  *
1587  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1588  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1589  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1590  * @retval IX_ETH_DB_INVALID_ARG invalid <i>taggingAction</i> pointer argument
1591  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1592  */
1593 IX_ETH_DB_PUBLIC
1594 IxEthDBStatus ixEthDBIngressVlanTaggingEnabledGet(IxEthDBPortId portID, IxEthDBTaggingAction *taggingAction);
1595
1596 /**
1597  * @ingroup IxEthDB
1598  *
1599  * @fn IxEthDBStatus ixEthDBVlanPortExtractionEnable(IxEthDBPortId portID, BOOL enable)
1600  *
1601  * @brief Enables or disables port ID extraction
1602  *
1603  * This feature can be used in the situation when a multi-port device (e.g. a switch)
1604  * is connected to an IXP4xx port and the device can provide incoming frame port
1605  * identification by tagging the TPID field in the Ethernet frame. Enabling
1606  * port extraction will instruct the NPE to copy the TPID field from the frame and
1607  * place it in the <i>ixp_ne_src_port</i> of the <i>ixp_buf</i> header. In addition,
1608  * the NPE restores the TPID field to 0.
1609  *
1610  * If the frame is not tagged the NPE will fill the <i>ixp_ne_src_port</i> with the
1611  * port ID of the MII interface the frame was received from.
1612  *
1613  * The TPID field is the least significant byte of the type/length field, which is
1614  * normally set to 0x8100 for 802.1Q-tagged frames.
1615  *
1616  * This feature is disabled by default.
1617  *
1618  * @param portID ID of the port to configure port ID extraction on
1619  * @param enable true to enable port ID extraction and false to disable it
1620  *
1621  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1622  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1623  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1624  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE VLAN/QoS feature is not available or not enabled for the port
1625  * @retval IX_FAIL unknown OS or NPE communication error
1626  */
1627 IX_ETH_DB_PUBLIC
1628 IxEthDBStatus ixEthDBVlanPortExtractionEnable(IxEthDBPortId portID, BOOL enable);
1629
1630 /**
1631  * @ingroup IxEthDB
1632  *
1633  * @fn IxEthDBStatus ixEthDBFeatureCapabilityGet(IxEthDBPortId portID, IxEthDBFeature *featureSet)
1634  *
1635  * @brief Retrieves the feature capability set for a port
1636  *
1637  * This function retrieves the feature capability set for a port or the common capabilities shared between all
1638  * the ports, writing the feature capability set in a user specified location.
1639  *
1640  * The feature capability set will consist of a set formed by OR-ing one or more of the following values:
1641  * - IX_ETH_DB_LEARNING - Learning feature; enables EthDB to learn MAC address (filtering) records, including 802.1Q enabled records
1642  * - IX_ETH_DB_FILTERING - Filtering feature; enables EthDB to communicate with the NPEs for downloading filtering information in the NPEs; depends on the learning feature
1643  * - IX_ETH_DB_VLAN_QOS - VLAN/QoS feature; enables EthDB to configure NPEs to operate in VLAN/QoS aware modes
1644  * - IX_ETH_DB_FIREWALL - Firewall feature; enables EthDB to configure NPEs to operate in firewall mode, using white/black address lists
1645  * - IX_ETH_DB_SPANNING_TREE_PROTOCOL - Spanning tree protocol feature; enables EthDB to configure the NPEs as STP nodes
1646  * - IX_ETH_DB_WIFI_HEADER_CONVERSION - WiFi 802.3 to 802.11 header conversion feature; enables EthDB to handle WiFi conversion data
1647  *
1648  * Note that EthDB provides only the LEARNING feature for non-NPE ports.
1649  *
1650  * @param portID @ref IxEthDBPortId [in] - ID of the port to retrieve the capability set for
1651  * (use IX_ETH_DB_ALL_PORTS to retrieve the common capabilities shared between all the ports)
1652  * @param featureSet @ref IxEthDBFeature [out] - location where the capability set will be written to
1653  *
1654  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1655  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1656  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1657  * @retval IX_ETH_DB_INVALID_ARG invalid <i>featureSet</i> pointer
1658  */
1659 IX_ETH_DB_PUBLIC
1660 IxEthDBStatus ixEthDBFeatureCapabilityGet(IxEthDBPortId portID, IxEthDBFeature *featureSet);
1661
1662 /**
1663  * @ingroup IxEthDB
1664  *
1665  * @fn IxEthDBStatus ixEthDBFeatureEnable(IxEthDBPortId portID, IxEthDBFeature feature, BOOL enabled)
1666  *
1667  * @brief Enables or disables one or more EthDB features
1668  *
1669  * Selects one or more features (see @ref ixEthDBFeatureCapabilityGet for a description of the supported
1670  * features) to be enabled or disabled on the selected port (or all the ports).
1671  *
1672  * Note that some features are mutually incompatible:
1673  * - IX_ETH_DB_FILTERING is incompatible with IX_ETH_DB_WIFI_HEADER_CONVERSION
1674  *
1675  * Also note that some features require other features to be enabled:
1676  * - IX_ETH_DB_FILTERING requires IX_ETH_DB_LEARNING
1677  *
1678  * This function will either enable the entire selected feature set for the selected port (or all the ports),
1679  * in which case it will return IX_ETH_DB_SUCCESS, or in case of error it will not enable any feature at all
1680  * and return an appropriate error message.
1681  *
1682  * The following features are enabled by default (for ports with the respective capability),
1683  * for compatibility reasons with previous versions of CSR:
1684  * - IX_ETH_DB_LEARNING
1685  * - IX_ETH_DB_FILTERING
1686  *
1687  * All other features are disabled by default and require manual enabling using ixEthDBFeatureEnable.
1688  *
1689  * <b>Default settings for VLAN, QoS, Firewall and WiFi header conversion features:</b>
1690  *
1691  * <i>VLAN</i>
1692  *
1693  * When the VLAN/QoS feature is enabled for a port for the first time the default VLAN behavior
1694  * of the port is set to be as <b>permissive</b> (it will accept all the frames) and
1695  * <b>non-interferential</b> (it will not change any frames) as possible:
1696  * - the port VLAN ID (VID) is set to 0
1697  * - the Ingress acceptable frame filter is set to accept all frames
1698  * - the VLAN port membership is set to the complete VLAN range (0 - 4094)
1699  * - the Ingress tagging mode is set to pass-through (will not change frames)
1700  * - the Egress tagging mode is to send tagged frames in the entire VLAN range (0 - 4094)
1701  *
1702  * Note that further disabling and re-enabling the VLAN feature for a given port will not reset the port VLAN behavior
1703  * to the settings listed above. Any VLAN settings made by the user are kept.
1704  *
1705  * <i>QoS</i>
1706  *
1707  * The following default priority mapping table will be used (as per IEEE 802.1Q and IEEE 802.1D):
1708  *
1709  * <table border="1"> <caption> QoS traffic classes  </caption>
1710  *    <tr> <td> <b> QoS priority <td> <b> Default traffic class <td> <b> Traffic type </b>
1711  *    <tr> <td>      0       <td>           1           <td> Best effort, default class for unexpedited traffic
1712  *    <tr> <td>      1       <td>           0           <td> Background traffic
1713  *    <tr> <td>      2       <td>           0           <td> Spare bandwidth
1714  *    <tr> <td>      3       <td>           1           <td> Excellent effort
1715  *    <tr> <td>      4       <td>           2           <td> Controlled load
1716  *    <tr> <td>      5       <td>           2           <td> Video traffic
1717  *    <tr> <td>      6       <td>           3           <td> Voice traffic
1718  *    <tr> <td>      7       <td>           3           <td> Network control
1719  * </table>
1720  *
1721  * <i> Firewall </i>
1722  *
1723  * The port firewall is configured by default in <b>black-list mode</b>, and the firewall address table is empty.
1724  * This means the firewall will not filter any frames until the feature is configured and the firewall table is
1725  * downloaded to the NPE.
1726  *
1727  * <i> Spanning Tree </i>
1728  *
1729  * The port is set to <b>STP unblocked mode</b>, therefore it will accept all frames until re-configured.
1730  *
1731  * <i> WiFi header conversion </i>
1732  *
1733  * The WiFi header conversion database is empty, therefore no actual header conversion will take place until this
1734  * feature is configured and the conversion table downloaded to the NPE.
1735  *
1736  * @param portID @ref IxEthDBPortId [in] - ID of the port to enable or disable the features on (use IX_ETH_DB_ALL_PORTS for all the ports)
1737  * @param feature @ref IxEthDBFeature [in] - feature or feature set to enable or disable
1738  * @param enabled BOOL [in] - true to enable the feature and false to disable it
1739  *
1740  * @note Certain features, from a functional point of view, cannot be disabled as such at NPE level;
1741  * when such features are set to <i>disabled</i> using the EthDB API they will be configured in such
1742  * a way to determine a behavior equivalent to the feature being disabled. As well as this, disabled
1743  * features cannot be configured or accessed via the EthDB API (except for getting their status).
1744  *
1745  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1746  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1747  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1748  * @retval IX_ETH_DB_NO_PERMISSION attempted to enable mutually exclusive features,
1749  * or a feature that depends on another feature which is not present or enabled
1750  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE at least one of the features selected is unavailable
1751  * @retval IX_FAIL unknown OS or NPE communication error
1752  */
1753 IX_ETH_DB_PUBLIC
1754 IxEthDBStatus ixEthDBFeatureEnable(IxEthDBPortId portID, IxEthDBFeature feature, BOOL enabled);
1755
1756 /**
1757  * @ingroup IxEthDB
1758  *
1759  * @fn IxEthDBStatus ixEthDBFeatureStatusGet(IxEthDBPortId portID, IxEthDBFeature feature, BOOL *present, BOOL *enabled)
1760  *
1761  * @brief Retrieves the availability and status of a feature set
1762  *
1763  * This function returns the availability and status for a feature set.
1764  * Note that if more than one feature is selected (e.g. IX_ETH_DB_LEARNING | IX_ETH_DB_FILTERING)
1765  * the "present" and "enabled" return values will be set to true only if all the features in the
1766  * feature set are present and enabled (not only some).
1767  *
1768  * @param portID @ref IxEthDBPortId [in] - ID of the port
1769  * @param feature @ref IxEthDBFeature [in] - identifier of the feature to retrieve the status for
1770  * @param present BOOL [out] - location where a boolean flag indicating whether this feature is present will be written to
1771  * @param enabled BOOL [out] - location where a boolean flag indicating whether this feature is enabled will be written to
1772  *
1773  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1774  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1775  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1776  * @retval IX_ETH_DB_INVALID_ARG either <i>present</i> or <i>enabled</i> pointer argument is invalid
1777  */
1778 IX_ETH_DB_PUBLIC
1779 IxEthDBStatus ixEthDBFeatureStatusGet(IxEthDBPortId portID, IxEthDBFeature feature, BOOL *present, BOOL *enabled);
1780
1781 /**
1782  * @ingroup IxEthDB
1783  *
1784  * @fn IxEthDBStatus ixEthDBFeaturePropertyGet(IxEthDBPortId portID, IxEthDBFeature feature, IxEthDBProperty property, IxEthDBPropertyType *type, void *value)
1785  *
1786  * @brief Retrieves the value of a feature property
1787  *
1788  * The EthDB features usually contain feature-specific properties describing or
1789  * controlling how the feature operates. While essential properties (e.g. the
1790  * firewall operating mode) have their own API, secondary properties can be
1791  * retrieved using this function.
1792  *
1793  * Properties can be read-only or read-write. ixEthDBFeaturePropertyGet operates with
1794  * both types of features.
1795  *
1796  * Properties have types associated with them. A descriptor indicating the property
1797  * type is returned in the <i>type</i> argument for convenience.
1798  *
1799  * The currently supported properties and their corresponding features are as follows:
1800  *
1801  * <table border="1"> <caption> Properties for IX_ETH_DB_VLAN_QOS </caption>
1802  *    <tr> <td> <b>        Property identifier                  <td> <b> Property type          <td> <b> Property value                   <td> <b> Read-Only </b>
1803  *    <tr> <td> IX_ETH_DB_QOS_TRAFFIC_CLASS_COUNT_PROPERTY      <td> IX_ETH_DB_INTEGER_PROPERTY <td> number of internal traffic classes   <td> Yes
1804  *    <tr> <td> IX_ETH_DB_QOS_TRAFFIC_CLASS_0_RX_QUEUE_PROPERTY <td> IX_ETH_DB_INTEGER_PROPERTY <td> queue assignment for traffic class 0 <td> Yes
1805  *    <tr> <td> IX_ETH_DB_QOS_TRAFFIC_CLASS_1_RX_QUEUE_PROPERTY <td> IX_ETH_DB_INTEGER_PROPERTY <td> queue assignment for traffic class 1 <td> Yes
1806  *    <tr> <td> IX_ETH_DB_QOS_TRAFFIC_CLASS_2_RX_QUEUE_PROPERTY <td> IX_ETH_DB_INTEGER_PROPERTY <td> queue assignment for traffic class 2 <td> Yes
1807  *    <tr> <td> IX_ETH_DB_QOS_TRAFFIC_CLASS_3_RX_QUEUE_PROPERTY <td> IX_ETH_DB_INTEGER_PROPERTY <td> queue assignment for traffic class 3 <td> Yes
1808  *    <tr> <td> IX_ETH_DB_QOS_TRAFFIC_CLASS_4_RX_QUEUE_PROPERTY <td> IX_ETH_DB_INTEGER_PROPERTY <td> queue assignment for traffic class 4 <td> Yes
1809  *    <tr> <td> IX_ETH_DB_QOS_TRAFFIC_CLASS_5_RX_QUEUE_PROPERTY <td> IX_ETH_DB_INTEGER_PROPERTY <td> queue assignment for traffic class 5 <td> Yes
1810  *    <tr> <td> IX_ETH_DB_QOS_TRAFFIC_CLASS_6_RX_QUEUE_PROPERTY <td> IX_ETH_DB_INTEGER_PROPERTY <td> queue assignment for traffic class 6 <td> Yes
1811  *    <tr> <td> IX_ETH_DB_QOS_TRAFFIC_CLASS_7_RX_QUEUE_PROPERTY <td> IX_ETH_DB_INTEGER_PROPERTY <td> queue assignment for traffic class 7 <td> Yes
1812  * </table>
1813  *
1814  * @see ixEthDBFeaturePropertySet
1815  *
1816  * @param portID @ref IxEthDBPortId [in] - ID of the port
1817  * @param feature @ref IxEthDBFeature [in] - EthDB feature for which the property is retrieved
1818  * @param property @ref IxEthDBProperty [in] - property identifier
1819  * @param type @ref IxEthDBPropertyType [out] - location where the property type will be stored
1820  * @param value void [out] - location where the property value will be stored
1821  *
1822  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1823  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1824  * @retval IX_ETH_DB_INVALID_ARG invalid property identifier, <i>type</i> or <i>value</i> pointer arguments
1825  * @retval IX_ETH_DB_FAIL incorrect property value or unknown error
1826  */
1827 IX_ETH_DB_PUBLIC
1828 IxEthDBStatus ixEthDBFeaturePropertyGet(IxEthDBPortId portID, IxEthDBFeature feature, IxEthDBProperty property, IxEthDBPropertyType *type, void *value);
1829
1830 /**
1831  * @ingroup IxEthDB
1832  *
1833  * @fn IxEthDBStatus ixEthDBFeaturePropertySet(IxEthDBPortId portID, IxEthDBFeature feature, IxEthDBProperty property, void *value)
1834  *
1835  * @brief Sets the value of a feature property
1836  *
1837  * Unlike @ref ixEthDBFeaturePropertyGet, this function operates only with read-write properties
1838  *
1839  * The currently supported properties and their corresponding features are as follows:
1840  *
1841  *   - IX_ETH_DB_QOS_QUEUE_CONFIGURATION_COMPLETE (for IX_ETH_DB_VLAN_QOS): freezes the availability of traffic classes
1842  *     to the number of traffic classes currently in use
1843  *
1844  * Note that this function creates deep copies of the property values; once the function is invoked the client
1845  * can free or reuse the memory area containing the original property value.
1846  *
1847  * Copy behavior for different property types is defined as follows:
1848  *
1849  *   - IX_ETH_DB_INTEGER_PROPERTY   - 4 bytes are copied from the source location
1850  *   - IX_ETH_DB_STRING_PROPERTY    - the source string will be copied up to the NULL '\0' string terminator, maximum of 255 characters
1851  *   - IX_ETH_DB_MAC_ADDR_PROPERTY  - 6 bytes are copied from the source location
1852  *   - IX_ETH_DB_BOOL_PROPERTY      - 4 bytes are copied from the source location; the only allowed values are true (1L) and false (0L)
1853  *
1854  * @see ixEthDBFeaturePropertySet
1855  *
1856  * @warning IX_ETH_DB_QOS_QUEUE_CONFIGURATION_COMPLETE is provided for EthAcc internal use;
1857  * do not attempt to set this property directly
1858  *
1859  * @param portID @ref IxEthDBPortId [in] - ID of the port
1860  * @param feature @ref IxEthDBFeature [in] - EthDB feature for which the property is set
1861  * @param property @ref IxEthDBProperty [in] - property identifier
1862  * @param value void [in] - location where the property value is to be copied from
1863  *
1864  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1865  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1866  * @retval IX_ETH_DB_INVALID_ARG invalid property identifier, <i>value</i> pointer, or invalid property value
1867  */
1868 IX_ETH_DB_PUBLIC
1869 IxEthDBStatus ixEthDBFeaturePropertySet(IxEthDBPortId portID, IxEthDBFeature feature, IxEthDBProperty property, void *value);
1870
1871 /**
1872  * @ingroup IxEthDB
1873  *
1874  * @fn IxEthDBStatus ixEthDBDatabaseClear(IxEthDBPortId portID, IxEthDBRecordType recordType)
1875  *
1876  * @brief Deletes a set of record types from the Ethernet Database
1877  *
1878  * This function deletes all the records of certain types (specified in the recordType filter)
1879  * associated with a port. Additionally, the IX_ETH_DB_ALL_PORTS value can be used as port ID
1880  * to indicate that the specified record types should be deleted for all the ports.
1881  *
1882  * The record type filter can be an ORed combination of the following types:
1883  *
1884  * <caption> Record types </caption>
1885  *    - IX_ETH_DB_FILTERING_RECORD      <table><caption> Filtering record </caption>
1886  *                                               <tr><td> MAC address <td> static/dynamic type <td> age </tr>
1887  *                                             </table>
1888  *
1889  *    - IX_ETH_DB_FILTERING_VLAN_RECORD <table><caption> VLAN-enabled filtering record </caption>
1890  *                                               <tr><td> MAC address <td> static/dynamic type <td> age <td> 802.1Q tag </tr>
1891  *                                             </table>
1892  *
1893  *    - IX_ETH_DB_WIFI_RECORD           <table><caption> WiFi header conversion record </caption>
1894  *                                                <tr><td> MAC address <td> optional gateway MAC address <td> </tr>
1895  *                                             </table>
1896  *
1897  *    - IX_ETH_DB_FIREWALL_RECORD       <table><caption> Firewall record </caption>
1898  *                                                <tr><td> MAC address </tr>
1899  *                                             </table>
1900  *    - IX_ETH_DB_ALL_RECORD_TYPES
1901  *
1902  * Any combination of the above types is valid e.g.
1903  *
1904  *    (IX_ETH_DB_FILTERING_RECORD | IX_ETH_DB_FILTERING_VLAN_RECORD | IX_ETH_DB_FIREWALL_RECORD),
1905  *
1906  * although some might be redundant (it is not an error to do so) e.g.
1907  *
1908  *    (IX_ETH_DB_FILTERING_RECORD | IX_ETH_DB_ALL_RECORD_TYPES)
1909  *
1910  * @param portID @ref IxEthDBPortId [in] - ID of the port
1911  * @param recordType @ref IxEthDBRecordType [in] - record type filter
1912  *
1913  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1914  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1915  * @retval IX_ETH_DB_INVALID_ARG invalid <i>recordType</i> filter
1916  *
1917  * @note If the record type filter contains any unrecognized value (hence the
1918  * IX_ETH_DB_INVALID_ARG error value is returned) no actual records will be deleted.
1919  */
1920 IX_ETH_DB_PUBLIC
1921 IxEthDBStatus ixEthDBDatabaseClear(IxEthDBPortId portID, IxEthDBRecordType recordType);
1922
1923 /**
1924  * @ingroup IxEthDB
1925  *
1926  * @fn IxEthDBStatus ixEthDBWiFiStationEntryAdd(IxEthDBPortId portID, IxEthDBMacAddr *macAddr)
1927  *
1928  * @brief Adds an "Access Point to Station" record to the database, for 802.3 => 802.11 frame
1929  * header conversion
1930  *
1931  * Frame header conversion is controlled by the set of MAC addresses
1932  * added using @ref ixEthDBWiFiStationEntryAdd and @ref ixEthDBWiFiAccessPointEntryAdd.
1933  * Conversion arguments are added using @ref ixEthDBWiFiFrameControlSet,
1934  * @ref ixEthDBWiFiDurationIDSet and @ref ixEthDBWiFiBBSIDSet.
1935  *
1936  * Note that adding the same MAC address twice will not return an error
1937  * (but will not accomplish anything either), while re-adding a record previously added
1938  * as an "Access Point to Access Point" will migrate the record to the "Access Point
1939  * to Station" type.
1940  *
1941  * @param portID @ref IxEthDBPortId [in] - ID of the port
1942  * @param macAddr @ref IxEthDBMacAddr [in] - MAC address to add
1943  *
1944  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1945  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1946  * @retval IX_ETH_DB_INVALID_ARG macAddr is an invalid pointer
1947  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE WiFi feature not enabled
1948  * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> pointer argument
1949  * @retval IX_ETH_DB_NOMEM maximum number of records reached
1950  * @retval IX_ETH_DB_BUSY lock condition or transaction in progress, try again later
1951  */
1952 IX_ETH_DB_PUBLIC
1953 IxEthDBStatus ixEthDBWiFiStationEntryAdd(IxEthDBPortId portID, IxEthDBMacAddr *macAddr);
1954
1955 /**
1956  * @ingroup IxEthDB
1957  *
1958  * @fn IxEthDBStatus ixEthDBWiFiAccessPointEntryAdd(IxEthDBPortId portID, IxEthDBMacAddr *macAddr, IxEthDBMacAddr *gatewayMacAddr)
1959  *
1960  * @brief Adds an "Access Point to Access Point" record to the database
1961  *
1962  * @see ixEthDBWiFiStationEntryAdd
1963  *
1964  * Note that adding the same MAC address twice will simply overwrite the previously
1965  * defined gateway MAC address value in the same record, if the record was previously of the
1966  * "Access Point to Access Point" type.
1967  *
1968  * Re-adding a MAC address as "Access Point to Access Point", which was previously added as
1969  * "Access Point to Station" will migrate the record type to "Access Point to Access Point" and
1970  * record the gateway MAC address.
1971  *
1972  * @param portID @ref IxEthDBPortId [in] - ID of the port
1973  * @param macAddr @ref IxEthDBMacAddr [in] - MAC address to add
1974  * @param gatewayMacAddr @ref IxEthDBMacAddr [in] - MAC address of the gateway Access Point
1975  *
1976  * @retval IX_ETH_DB_SUCCESS operation completed successfully
1977  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
1978  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
1979  * @retval IX_ETH_DB_INVALID_ARG macAddr is an invalid pointer
1980  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE WiFi feature not enabled
1981  * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> or <i>gatewayMacAddr</i> pointer argument
1982  * @retval IX_ETH_DB_NOMEM maximum number of records reached
1983  * @retval IX_ETH_DB_BUSY lock condition or transaction in progress, try again later
1984  */
1985 IX_ETH_DB_PUBLIC
1986 IxEthDBStatus ixEthDBWiFiAccessPointEntryAdd(IxEthDBPortId portID, IxEthDBMacAddr *macAddr, IxEthDBMacAddr *gatewayMacAddr);
1987
1988 /**
1989  * @ingroup IxEthDB
1990  *
1991  * @fn IxEthDBStatus ixEthDBWiFiEntryRemove(IxEthDBPortId portID, IxEthDBMacAddr *macAddr)
1992  *
1993  * @brief Removes a WiFi station record
1994  *
1995  * This function removes both types of WiFi records ("Access Point to Station" and
1996  * "Access Point to Access Point").
1997  *
1998  * @param portID @ref IxEthDBPortId [in] - ID of the port
1999  * @param macAddr @ref IxEthDBMacAddr [in] - MAC address to remove
2000  *
2001  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2002  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
2003  * @retval IX_ETH_DB_PORT_UNINITIALIZED port is not initialized
2004  * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> pointer argument
2005  * @retval IX_ETH_DB_NO_SUCH_ADDR specified address was not found in the database
2006  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE WiFi feature not enabled
2007  * @retval IX_ETH_DB_BUSY lock condition or transaction in progress, try again later
2008  */
2009 IX_ETH_DB_PUBLIC
2010 IxEthDBStatus ixEthDBWiFiEntryRemove(IxEthDBPortId portID, IxEthDBMacAddr *macAddr);
2011
2012 /**
2013  * @ingroup IxEthDB
2014  *
2015  * @fn IxEthDBStatus ixEthDBWiFiConversionTableDownload(IxEthDBPortId portID)
2016  *
2017  * @brief Downloads the MAC address table for 802.3 => 802.11 frame header
2018  * conversion to the NPE
2019  *
2020  * Note that the frame conversion MAC address table must be individually downloaded
2021  * to each NPE for which the frame header conversion feature is enabled (i.e. it
2022  * is not possible to specify IX_ETH_DB_ALL_PORTS).
2023  *
2024  * @param portID @ref IxEthDBPortId [in] - ID of the port
2025  *
2026  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2027  * @retval IX_ETH_DB_PORT_UNINITIALIZED port not initialized
2028  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
2029  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE WiFi feature not enabled
2030  * @retval IX_ETH_DB_FAIL unknown OS or NPE communication error
2031  */
2032 IX_ETH_DB_PUBLIC
2033 IxEthDBStatus ixEthDBWiFiConversionTableDownload(IxEthDBPortId portID);
2034
2035 /**
2036  * @ingroup IxEthDB
2037  *
2038  * @fn IxEthDBStatus ixEthDBWiFiFrameControlSet(IxEthDBPortId portID, UINT16 frameControl)
2039  *
2040  * @brief Sets the GlobalFrameControl field
2041  *
2042  * The GlobalFrameControl field is a 2-byte value inserted in the <i>Frame Control</i>
2043  * field for all 802.3 to 802.11 frame header conversions
2044  *
2045  * @param portID @ref IxEthDBPortId [in] - ID of the port
2046  * @param frameControl UINT16 [in] - GlobalFrameControl value
2047  *
2048  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2049  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
2050  * @retval IX_ETH_DB_PORT_UNINITIALIZED port not initialized
2051  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE WiFi feature not enabled
2052  * @retval IX_ETH_DB_FAIL unknown OS or NPE communication error
2053  */
2054 IX_ETH_DB_PUBLIC
2055 IxEthDBStatus ixEthDBWiFiFrameControlSet(IxEthDBPortId portID, UINT16 frameControl);
2056
2057 /**
2058  * @ingroup IxEthDB
2059  *
2060  * @fn IxEthDBStatus ixEthDBWiFiDurationIDSet(IxEthDBPortId portID, UINT16 durationID)
2061  *
2062  * @brief Sets the GlobalDurationID field
2063  *
2064  * The GlobalDurationID field is a 2-byte value inserted in the <i>Duration/ID</i>
2065  * field for all 802.3 to 802.11 frame header conversions
2066  *
2067  * @param portID @ref IxEthDBPortId [in] - ID of the port
2068  * @param durationID UINT16 [in] - GlobalDurationID field
2069  *
2070  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2071  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
2072  * @retval IX_ETH_DB_PORT_UNINITIALIZED port not initialized
2073  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE WiFi feature not enabled
2074  * @retval IX_ETH_DB_FAIL unknown OS or NPE communication error
2075  */
2076 IX_ETH_DB_PUBLIC
2077 IxEthDBStatus ixEthDBWiFiDurationIDSet(IxEthDBPortId portID, UINT16 durationID);
2078
2079 /**
2080  * @ingroup IxEthDB
2081  *
2082  * @fn IxEthDBStatus ixEthDBWiFiBBSIDSet(IxEthDBPortId portID, IxEthDBMacAddr *bbsid)
2083  *
2084  * @brief Sets the BBSID field
2085  *
2086  * The BBSID field is a 6-byte value which
2087  * identifies the infrastructure of the service set managed
2088  * by the Access Point having the IXP400 as its processor. The value
2089  * is written in the <i>BBSID</i> field of the 802.11 frame header.
2090  * The BBSID value is the MAC address of the Access Point.
2091  *
2092  * @param portID @ref IxEthDBPortId [in] - ID of the port
2093  * @param bbsid @ref IxEthDBMacAddr [in] - pointer to 6 bytes containing the BSSID
2094  *
2095  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2096  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
2097  * @retval IX_ETH_DB_PORT_UNINITIALIZED port not initialized
2098  * @retval IX_ETH_DB_INVALID_ARG invalid <i>bbsid</i> pointer argument
2099  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE WiFi feature not enabled
2100  * @retval IX_ETH_DB_FAIL unknown OS or NPE communication error
2101  */
2102 IX_ETH_DB_PUBLIC
2103 IxEthDBStatus ixEthDBWiFiBBSIDSet(IxEthDBPortId portID, IxEthDBMacAddr *bbsid);
2104
2105 /**
2106  * @ingroup IxEthDB
2107  *
2108  * @fn IxEthDBStatus ixEthDBSpanningTreeBlockingStateSet(IxEthDBPortId portID, BOOL blocked)
2109  *
2110  * @brief Sets the STP blocked/unblocked state for a port
2111  *
2112  * @param portID @ref IxEthDBPortId [in] - ID of the port
2113  * @param blocked BOOL [in] - true to set the port as STP blocked, false to set it as unblocked
2114  *
2115  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2116  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
2117  * @retval IX_ETH_DB_PORT_UNINITIALIZED port not initialized
2118  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE Spanning Tree Protocol feature not enabled
2119  * @retval IX_ETH_DB_FAIL unknown OS or NPE communication error
2120  */
2121 IX_ETH_DB_PUBLIC
2122 IxEthDBStatus ixEthDBSpanningTreeBlockingStateSet(IxEthDBPortId portID, BOOL blocked);
2123
2124 /**
2125  * @ingroup IxEthDB
2126  *
2127  * @fn IxEthDBStatus ixEthDBSpanningTreeBlockingStateGet(IxEthDBPortId portID, BOOL *blocked)
2128  *
2129  * @brief Retrieves the STP blocked/unblocked state for a port
2130  *
2131  * @param portID @ref IxEthDBPortId [in] - ID of the port
2132  * @param blocked BOOL * [in] - set to true if the port is STP blocked, false otherwise
2133  *
2134  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2135  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
2136  * @retval IX_ETH_DB_PORT_UNINITIALIZED port not initialized
2137  * @retval IX_ETH_DB_INVALID_ARG invalid <i>blocked</i> pointer argument
2138  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE Spanning Tree Protocol feature not enabled
2139  */
2140 IX_ETH_DB_PUBLIC
2141 IxEthDBStatus ixEthDBSpanningTreeBlockingStateGet(IxEthDBPortId portID, BOOL *blocked);
2142
2143 /**
2144  * @ingroup IxEthDB
2145  *
2146  * @fn IxEthDBStatus ixEthDBFirewallModeSet(IxEthDBPortId portID, IxEthDBFirewallMode mode)
2147  *
2148  * @brief Sets the firewall mode to use white or black listing
2149  *
2150  * When enabled, the NPE MAC address based firewall support operates in two modes:
2151  *
2152  * - white-list mode (MAC address based admission)
2153  *    - <i>mode</i> set to IX_ETH_DB_FIREWALL_WHITE_LIST
2154  *    - only packets originating from MAC addresses contained in the firewall address list
2155  *      are allowed on the Rx path
2156  * - black-list mode (MAC address based blocking)
2157  *    - <i>mode</i> set to IX_ETH_DB_FIREWALL_BLACK_LIST
2158  *    - packets originating from MAC addresses contained in the firewall address list
2159  *      are discarded
2160  *
2161  * @param portID @ref IxEthDBPortId [in] - ID of the port
2162  * @param mode @ref IxEthDBFirewallMode [in] - firewall mode (IX_ETH_DB_FIREWALL_WHITE_LIST or IX_ETH_DB_FIREWALL_BLACK_LIST)
2163  *
2164  * @note by default the firewall operates in black-list mode with an empty address
2165  * list, hence it doesn't filter any packets
2166  *
2167  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2168  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
2169  * @retval IX_ETH_DB_PORT_UNINITIALIZED port not initialized
2170  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE Firewall feature not enabled
2171  * @retval IX_ETH_DB_INVALID_ARGUMENT <i>mode</i> argument is not a valid firewall configuration mode
2172  * @retval IX_ETH_DB_FAIL unknown OS or NPE communication error
2173 */
2174 IX_ETH_DB_PUBLIC
2175 IxEthDBStatus ixEthDBFirewallModeSet(IxEthDBPortId portID, IxEthDBFirewallMode mode);
2176
2177 /**
2178  * @ingroup IxEthDB
2179  *
2180  * @fn ixEthDBFirewallInvalidAddressFilterEnable(IxEthDBPortId portID, BOOL enable)
2181  *
2182  * @brief Enables or disables invalid MAC address filtering
2183  *
2184  * According to IEEE802 it is illegal for a source address to be a multicast
2185  * or broadcast address. If this feature is enabled the NPE inspects the source
2186  * MAC addresses of incoming frames and discards them if invalid addresses are
2187  * detected.
2188  *
2189  * By default this service is enabled, if the firewall feature is supported by the
2190  * NPE image.
2191  *
2192  * @param portID ID of the port
2193  * @param enable true to enable invalid MAC address filtering and false to disable it
2194  *
2195  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2196  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
2197  * @retval IX_ETH_DB_PORT_UNINITIALIZED port not initialized
2198  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE Firewall feature not enabled
2199  * @retval IX_ETH_DB_FAIL unknown OS or NPE communication error
2200  */
2201 IX_ETH_DB_PUBLIC
2202 IxEthDBStatus ixEthDBFirewallInvalidAddressFilterEnable(IxEthDBPortId portID, BOOL enable);
2203
2204 /**
2205  * @ingroup IxEthDB
2206  *
2207  * @fn IxEthDBStatus ixEthDBFirewallEntryAdd(IxEthDBPortId portID, IxEthDBMacAddr *macAddr)
2208  *
2209  * @brief Adds a MAC address to the firewall address list
2210  *
2211  * Note that adding the same MAC address twice will not return an error
2212  * but will not actually accomplish anything.
2213  *
2214  * The firewall MAC address list has a limited number of entries; once
2215  * the maximum number of entries has been reached this function will failed
2216  * to add more addresses, returning IX_ETH_DB_NOMEM.
2217  *
2218  * @param portID @ref IxEthDBPortId [in] - ID of the port
2219  * @param macAddr @ref IxEthDBMacAddr [in] - MAC address to be added
2220  *
2221  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2222  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
2223  * @retval IX_ETH_DB_PORT_UNINITIALIZED port not initialized
2224  * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> pointer argument
2225  * @retval IX_ETH_DB_NOMEM maximum number of records reached
2226  * @retval IX_ETH_DB_BUSY lock condition or transaction in progress, try again later
2227  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE Firewall feature not enabled
2228  */
2229 IX_ETH_DB_PUBLIC
2230 IxEthDBStatus ixEthDBFirewallEntryAdd(IxEthDBPortId portID, IxEthDBMacAddr *macAddr);
2231
2232 /**
2233  * @ingroup IxEthDB
2234  *
2235  * @fn IxEthDBStatus ixEthDBFirewallEntryRemove(IxEthDBPortId portID, IxEthDBMacAddr *macAddr)
2236  *
2237  * @brief Removes a MAC address from the firewall address list
2238  *
2239  * @param portID @ref IxEthDBPortId [in] - ID of the port
2240  * @param macAddr @ref IxEthDBMacAddr [in] - MAC address to be removed
2241  *
2242  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2243  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
2244  * @retval IX_ETH_DB_PORT_UNINITIALIZED port not initialized
2245  * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> pointer argument
2246  * @retval IX_ETH_DB_NO_SUCH_ADDR address not found
2247  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE Firewall feature not enabled
2248  */
2249 IX_ETH_DB_PUBLIC
2250 IxEthDBStatus ixEthDBFirewallEntryRemove(IxEthDBPortId portID, IxEthDBMacAddr *macAddr);
2251
2252 /**
2253  * @ingroup IxEthDB
2254  *
2255  * @fn IxEthDBStatus ixEthDBFirewallTableDownload(IxEthDBPortId portID)
2256  *
2257  * @brief Downloads the MAC firewall table to a port
2258  *
2259  * @param portID ID of the port
2260  *
2261  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2262  * @retval IX_ETH_DB_INVALID_PORT portID is not a valid port identifier
2263  * @retval IX_ETH_DB_PORT_UNINITIALIZED port not initialized
2264  * @retval IX_ETH_DB_FEATURE_UNAVAILABLE Firewall feature not enabled
2265  * @retval IX_ETH_DB_FAIL unknown OS or NPE communication error
2266  */
2267 IX_ETH_DB_PUBLIC
2268 IxEthDBStatus ixEthDBFirewallTableDownload(IxEthDBPortId portID);
2269
2270 /**
2271  * @ingroup IxEthDB
2272  *
2273  * @fn IxEthDBStatus ixEthDBUserFieldSet(IxEthDBRecordType recordType, IxEthDBMacAddr *macAddr, IxEthDBPortId portID, IxEthDBVlanId vlanID, void *field)
2274  *
2275  * @brief Adds a user-defined field to a database record
2276  *
2277  * This function associates a user-defined field to a database record.
2278  * The user-defined field is passed as a <i>(void *)</i> parameter, hence it can be used
2279  * for any purpose (such as identifying a structure). Retrieving the user-defined field from
2280  * a record is done using @ref ixEthDBUserFieldGet. Note that EthDB never uses the user-defined
2281  * field for any internal operation and it is not aware of the significance of its contents. The
2282  * field is only stored as a pointer.
2283  *
2284  * The database record is identified using a combination of the given parameters, depending on the record type.
2285  * All the record types require the record MAC address.
2286  *
2287  * - IX_ETH_DB_FILTERING_RECORD requires only the MAC address
2288  * - IX_ETH_DB_VLAN_FILTERING_RECORD requires the MAC address and the VLAN ID
2289  * - IX_ETH_DB_WIFI_RECORD requires the MAC address and the portID
2290  * - IX_ETH_DB_FIREWALL_RECORD requires the MAC address and the portID
2291  *
2292  * Please note that if a parameter is not required it is completely ignored (it does not undergo parameter checking).
2293  * The user-defined field can be cleared using a <b>NULL</b> <i>field</i> parameter.
2294  *
2295  * @param recordType @ref IxEthDBRecordType [in] - type of record (can be IX_ETH_DB_FILTERING_RECORD,
2296  * IX_ETH_DB_FILTERING_VLAN_RECORD, IX_ETH_DB_WIFI_RECORD or IX_ETH_DB_FIREWALL_RECORD)
2297  * @param portID @ref IxEthDBPortId [in] - ID of the port (required only for WIFI and FIREWALL records)
2298  * @param macAddr @ref IxEthDBMacAddr * [in] - MAC address of the record
2299  * @param vlanID @ref IxEthDBVlanId [in] - VLAN ID of the record (required only for FILTERING_VLAN records)
2300  * @param field void * [in] - user defined field
2301  *
2302  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2303  * @retval IX_ETH_DB_INVALID_PORT portID was required but it is not a valid port identifier
2304  * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> pointer argument
2305  * @retval IX_ETH_DB_NO_SUCH_ADDR record not found
2306  */
2307 IX_ETH_DB_PUBLIC
2308 IxEthDBStatus ixEthDBUserFieldSet(IxEthDBRecordType recordType, IxEthDBMacAddr *macAddr, IxEthDBPortId portID, IxEthDBVlanId vlanID, void *field);
2309
2310 /**
2311  * @ingroup IxEthDB
2312  *
2313  * @fn IxEthDBStatus ixEthDBUserFieldGet(IxEthDBRecordType recordType, IxEthDBMacAddr *macAddr, IxEthDBPortId portID, IxEthDBVlanId vlanID, void **field)
2314  *
2315  * @brief Retrieves a user-defined field from a database record
2316  *
2317  * The database record is identified using a combination of the given parameters, depending on the record type.
2318  * All the record types require the record MAC address.
2319  *
2320  * - IX_ETH_DB_FILTERING_RECORD requires only the MAC address
2321  * - IX_ETH_DB_VLAN_FILTERING_RECORD requires the MAC address and the VLAN ID
2322  * - IX_ETH_DB_WIFI_RECORD requires the MAC address and the portID
2323  * - IX_ETH_DB_FIREWALL_RECORD requires the MAC address and the portID
2324  *
2325  * Please note that if a parameter is not required it is completely ignored (it does not undergo parameter checking).
2326  *
2327  * If no user-defined field was registered with the specified record then <b>NULL</b> will be written
2328  * at the location specified by <i>field</i>.
2329  *
2330  * @param recordType type of record (can be IX_ETH_DB_FILTERING_RECORD, IX_ETH_DB_FILTERING_VLAN_RECORD, IX_ETH_DB_WIFI_RECORD
2331  * or IX_ETH_DB_FIREWALL_RECORD)
2332  * @param portID ID of the port (required only for WIFI and FIREWALL records)
2333  * @param macAddr MAC address of the record
2334  * @param vlanID VLAN ID of the record (required only for FILTERING_VLAN records)
2335  * @param field location to write the user defined field into
2336  *
2337  * @retval IX_ETH_DB_SUCCESS operation completed successfully
2338  * @retval IX_ETH_DB_INVALID_PORT portID was required but it is not a valid port identifier
2339  * @retval IX_ETH_DB_INVALID_ARG invalid <i>macAddr</i> or <i>field</i> pointer arguments
2340  * @retval IX_ETH_DB_NO_SUCH_ADDR record not found
2341  */
2342 IX_ETH_DB_PUBLIC
2343 IxEthDBStatus ixEthDBUserFieldGet(IxEthDBRecordType recordType, IxEthDBMacAddr *macAddr, IxEthDBPortId portId, IxEthDBVlanId vlanID, void **field);
2344
2345 /**
2346  * @}
2347  */
2348
2349 #endif /* IxEthDB_H */