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
           params Table create parameters.

       Returns
           Table memory footprint in bytes.

   __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
           Table mailbox footprint in bytes.

   __rte_experimental void * rte_swx_table_learner_create (struct rte_swx_table_learner_params * params, int
       numa_node)
       Learner table create

       Parameters
           params Table creation parameters.
           numa_node Non-Uniform Memory Access (NUMA) node.

       Returns
           Table handle, on success, or NULL, on error.

   __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
           table Table handle.
           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
           0 on success or the following error codes otherwise: -EINVAL: Invalid argument(s).

   __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
           table Table handle.
           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
           0 when the table lookup operation is not yet completed, and 1 when the table lookup operation is
           completed. No other return values are allowed.

   __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
           table Table handle.
           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
           0 on success, 1 or error (table full).

   __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
           table Table handle.
           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
           table Table handle.
           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
           table Table handle.
           mailbox Mailbox for the current operation.

   __rte_experimental void rte_swx_table_learner_free (void * table)
       Learner table free

       Parameters
           table Table handle.

Author

       Generated automatically by Doxygen for DPDK from the source code.

DPDK                                             Version 24.11.2                      rte_swx_table_learner.h(3)