rte_swx_table_learner.h File Reference

#include <stdint.h>
#include <sys/types.h>
#include <rte_compat.h>
#include "rte_swx_hash_func.h"

Go to the source code of this file.

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

RTE_SWX_TABLE_LEARNER_N_KEY_TIMEOUTS_MAX

#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_swx_table_learner_footprint_get()

__rte_experimental uint64_t rte_swx_table_learner_footprint_get

(

struct rte_swx_table_learner_params *

params

)

Learner table memory footprint get

Parameters

[in]

params

Table create parameters.

Returns

Table memory footprint in bytes.

rte_swx_table_learner_mailbox_size_get()

__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_swx_table_learner_create()

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

Learner table create

Parameters

[in]	params	Table creation parameters.
[in]	numa_node	Non-Uniform Memory Access (NUMA) node.

Returns

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

rte_swx_table_learner_timeout_update()

__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

[in]	table	Table handle.
[in]	key_timeout_id	Key timeout ID. Must be less than the configured n_key_timeouts value.
[in]	key_timeout	Key timeout value measured in seconds.

Returns

0 on success or the following error codes otherwise: -EINVAL: Invalid argument(s).

rte_swx_table_learner_lookup()

__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

[in]	table	Table handle.
[in]	mailbox	Mailbox for the current table lookup operation.
[in]	time	Current time measured in CPU clock cycles.
[in]	key	Lookup key. Its size must be equal to the table key_size.
[out]	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.
[out]	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.
[out]	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.
[out]	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_swx_table_learner_add()

__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

[in]	table	Table handle.
[in]	mailbox	Mailbox for the current operation.
[in]	time	Current time measured in CPU clock cycles.
[out]	action_id	ID of the action associated with the key.
[out]	action_data	Action data for the action_id action.
[in]	key_timeout_id	Key timeout ID.

Returns

0 on success, 1 or error (table full).

rte_swx_table_learner_rearm()

__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

[in]	table	Table handle.
[in]	mailbox	Mailbox for the current operation.
[in]	time	Current time measured in CPU clock cycles.

rte_swx_table_learner_rearm_new()

__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

[in]	table	Table handle.
[in]	mailbox	Mailbox for the current operation.
[in]	time	Current time measured in CPU clock cycles.
[in]	key_timeout_id	Key timeout ID.

rte_swx_table_learner_delete()

__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

[in]	table	Table handle.
[in]	mailbox	Mailbox for the current operation.

rte_swx_table_learner_free()

__rte_experimental void rte_swx_table_learner_free

(

void *

table

)

Learner table free

Parameters

[in]

table

Table handle.