source: SVN/rincon/u-boot/cpu/ixp/npe/include/IxEthDB.h @ 55

Last change on this file since 55 was 55, checked in by Tim Harvey, 22 months ago

rincon: added latest u-boot source

restored form server backup

Signed-off-by: Tim Harvey <tharvey@…>

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