table of contents
| rte_swx_table_learner.h(3) | DPDK | rte_swx_table_learner.h(3) |
NAME¶
rte_swx_table_learner.h
SYNOPSIS¶
#include <stdint.h>
#include <sys/types.h>
#include <rte_compat.h>
#include 'rte_swx_hash_func.h'
Data Structures¶
struct rte_swx_table_learner_params
Macros¶
#define RTE_SWX_TABLE_LEARNER_N_KEY_TIMEOUTS_MAX 16
Functions¶
__rte_experimental uint64_t
rte_swx_table_learner_footprint_get (struct
rte_swx_table_learner_params *params)
__rte_experimental uint64_t rte_swx_table_learner_mailbox_size_get
(void)
__rte_experimental void * rte_swx_table_learner_create (struct
rte_swx_table_learner_params *params, int numa_node)
__rte_experimental int rte_swx_table_learner_timeout_update (void
*table, uint32_t key_timeout_id, uint32_t key_timeout)
__rte_experimental int rte_swx_table_learner_lookup (void *table, void
*mailbox, uint64_t time, uint8_t **key, uint64_t *action_id, uint8_t
**action_data, size_t *entry_id, int *hit)
__rte_experimental uint32_t rte_swx_table_learner_add (void *table,
void *mailbox, uint64_t time, uint64_t action_id, uint8_t *action_data,
uint32_t key_timeout_id)
__rte_experimental void rte_swx_table_learner_rearm (void *table, void
*mailbox, uint64_t time)
__rte_experimental void rte_swx_table_learner_rearm_new (void *table,
void *mailbox, uint64_t time, uint32_t key_timeout_id)
__rte_experimental void rte_swx_table_learner_delete (void *table, void
*mailbox)
__rte_experimental void rte_swx_table_learner_free (void *table)
Detailed Description¶
RTE SWX Learner Table
The learner table API.
This table type is typically used for learning or connection tracking, where it allows for the implementation of the 'add on miss' scenario: whenever the lookup key is not found in the table (lookup miss), the data plane can decide to add this key to the table with a given action with no control plane intervention. Likewise, the table keys expire based on a configurable timeout and are thus automatically removed from the table with no control plane intervention.
The keys are not automatically rearmed on lookup hit. To delay the key expiration, the key timer has to be explicitly reinitialized on lookup hit. The key will be kept in the table as long as it is frequently hit and explicitly rearmed on every hit.
Operation overview: 1) Lookup miss: a) add: Add the current input key (the key that missed the lookup) to the table with given action, action parameters and expiration timeout. This is the way to populate the table (which is empty initially). Data plane operation. b) Do nothing: Keep the current input key out of the table. 2) Lookup hit: a) add: Update the action, action parameters and/or the expiration timeout for the current input key, which is already in the table. The expiration timer of the key is automatically rearmed. Data plane operation. b) rearm: Rearm the expiration timer for the current input key, which is already in the table. The timeout value used for the expiration timer is either the same as the one currently associated with the key or a new one can be provided as input. Data plane operation. c) delete: Delete the current input key from the table. The purpose of this operation is to force the deletion of the key from the table before the key expires on timeout due to inactivity. Data plane operation. d) Do nothing: Keep the expiration timer of the current input key running down. This key will thus expire naturally, unless it is hit again as part of a subsequent lookup operation, when the key timer can be rearmed or re-added to prolong its life.
Definition in file rte_swx_table_learner.h.
Macro Definition Documentation¶
#define RTE_SWX_TABLE_LEARNER_N_KEY_TIMEOUTS_MAX 16¶
Maximum number of key timeout values per learner table.
Definition at line 58 of file rte_swx_table_learner.h.
Function Documentation¶
__rte_experimental uint64_t rte_swx_table_learner_footprint_get (struct rte_swx_table_learner_params * params)¶
Learner table memory footprint get
Parameters
Returns
__rte_experimental uint64_t rte_swx_table_learner_mailbox_size_get (void)¶
Learner table mailbox size get
The mailbox is used to store the context of a lookup operation that is in progress and it is passed as a parameter to the lookup operation. This allows for multiple concurrent lookup operations into the same table.
Returns
__rte_experimental void* rte_swx_table_learner_create (struct rte_swx_table_learner_params * params, int numa_node)¶
Learner table create
Parameters
numa_node Non-Uniform Memory Access (NUMA) node.
Returns
__rte_experimental int rte_swx_table_learner_timeout_update (void * table, uint32_t key_timeout_id, uint32_t key_timeout)¶
Learner table key timeout update
Parameters
key_timeout_id Key timeout ID. Must be less than the configured n_key_timeouts value.
key_timeout Key timeout value measured in seconds.
Returns
__rte_experimental int rte_swx_table_learner_lookup (void * table, void * mailbox, uint64_t time, uint8_t ** key, uint64_t * action_id, uint8_t ** action_data, size_t * entry_id, int * hit)¶
Learner table key lookup
The table lookup operation searches a given key in the table and upon its completion it returns an indication of whether the key is found in the table (lookup hit) or not (lookup miss). In case of lookup hit, the action_id and the action_data associated with the key are also returned.
Multiple invocations of this function may be required in order to complete a single table lookup operation for a given table and a given lookup key. The completion of the table lookup operation is flagged by a return value of 1; in case of a return value of 0, the function must be invoked again with exactly the same arguments.
The mailbox argument is used to store the context of an on-going table key lookup operation, and possibly an associated key add operation. The mailbox mechanism allows for multiple concurrent table key lookup and add operations into the same table.
The table entry consists of the action ID and the action data. Each table entry is unique, even though different table entries can have identical content, i.e. same values for the action ID and the action data. The table entry ID is also returned by the table lookup operation. It can be used to index into an external array of resources such as counters, registers or meters to identify the resource directly associated with the current table entry with no need to store the corresponding index into the table entry. The index of the external resource is thus auto-generated instead of being stored in the table entry.
Parameters
mailbox Mailbox for the current table lookup operation.
time Current time measured in CPU clock cycles.
key Lookup key. Its size must be equal to the table key_size.
action_id ID of the action associated with the key. Must point to a valid 64-bit variable. Only valid when the function returns 1 and hit is set to true.
action_data Action data for the action_id action. Must point to a valid array of table action_data_size bytes. Only valid when the function returns 1 and hit is set to true.
entry_id Table entry unique ID. Must point to a valid 32-bit variable. Only valid when the function returns 1 and hit is set to true.
hit Only valid when the function returns 1. Set to non-zero (true) on table lookup hit and to zero (false) on table lookup miss.
Returns
__rte_experimental uint32_t rte_swx_table_learner_add (void * table, void * mailbox, uint64_t time, uint64_t action_id, uint8_t * action_data, uint32_t key_timeout_id)¶
Learner table key add
This operation takes the latest key that was looked up in the table and adds it to the table with the given action ID and action data. Typically, this operation is only invoked when the latest lookup operation in the current table resulted in lookup miss.
Parameters
mailbox Mailbox for the current operation.
time Current time measured in CPU clock cycles.
action_id ID of the action associated with the key.
action_data Action data for the action_id action.
key_timeout_id Key timeout ID.
Returns
__rte_experimental void rte_swx_table_learner_rearm (void * table, void * mailbox, uint64_t time)¶
Learner table key rearm with same timeout value
This operation takes the latest key that was looked up in the table and, in case of lookup hit, it rearms its expiration timer using the same timeout value currently associated with the key.
Parameters
mailbox Mailbox for the current operation.
time Current time measured in CPU clock cycles.
__rte_experimental void rte_swx_table_learner_rearm_new (void * table, void * mailbox, uint64_t time, uint32_t key_timeout_id)¶
Learner table key rearm with given timeout value
This operation takes the latest key that was looked up in the table and, in case of lookup hit, it rearms its expiration timer using the given timeout value.
Parameters
mailbox Mailbox for the current operation.
time Current time measured in CPU clock cycles.
key_timeout_id Key timeout ID.
__rte_experimental void rte_swx_table_learner_delete (void * table, void * mailbox)¶
Learner table key delete
This operation takes the latest key that was looked up in the table and deletes it from the table. Typically, this operation is only invoked to force the deletion of the key before the key expires on timeout due to inactivity.
Parameters
mailbox Mailbox for the current operation.
__rte_experimental void rte_swx_table_learner_free (void * table)¶
Learner table free
Parameters
Author¶
Generated automatically by Doxygen for DPDK from the source code.
| Fri Dec 15 2023 | Version 23.11.0 |