rte_graph_feature_arc.h(3) DPDK rte_graph_feature_arc.h(3) NAME rte_graph_feature_arc.h SYNOPSIS #include <assert.h> #include <errno.h> #include <signal.h> #include <stddef.h> #include <stdint.h> #include <stdio.h> #include <stdlib.h> #include <string.h> #include <rte_common.h> #include <rte_compat.h> #include <rte_debug.h> #include <rte_graph.h> #include <rte_rcu_qsbr.h> Data Structures struct rte_graph_feature_register struct rte_graph_feature_arc_register Macros #define RTE_GRAPH_FEATURE_ARC_NAMELEN RTE_NODE_NAMESIZE #define RTE_GRAPH_FEATURE_ARC_INITIALIZER ((rte_graph_fea- ture_arc_t)UINT16_MAX) #define RTE_GRAPH_FEATURE_REGISTER(reg) #define RTE_GRAPH_FEATURE_ARC_REGISTER(reg) Typedefs typedef uint16_t rte_graph_feature_arc_t typedef uint8_t rte_graph_feature_t typedef uint32_t rte_graph_feature_data_t typedef void(* rte_graph_feature_change_notifier_cb_t) (const char *arc_name, const char *feature_name, rte_node_t feature_node_id, uint32_t index, bool enable_disable, uint16_t app_cookie) typedef uint16_t(* rte_graph_feature_override_index_cb_t) (void) Functions __rte_experimental int rte_graph_feature_arc_init (uint16_t num_fea- ture_arcs) __rte_experimental int rte_graph_feature_arc_create (struct rte_graph_fea- ture_arc_register *reg, rte_graph_feature_arc_t *_arc) __rte_experimental int rte_graph_feature_arc_lookup_by_name (const char *arc_name, rte_graph_feature_arc_t *_arc) __rte_experimental int rte_graph_feature_add (struct rte_graph_feature_reg- ister *feat_reg) __rte_experimental int rte_graph_feature_enable (rte_graph_feature_arc_t _arc, uint32_t index, const char *feature_name, uint16_t app_cookie, struct rte_rcu_qsbr *qsbr) __rte_experimental int rte_graph_feature_disable (rte_graph_feature_arc_t _arc, uint32_t index, const char *feature_name, struct rte_rcu_qsbr *qsbr) __rte_experimental int rte_graph_feature_lookup (rte_graph_feature_arc_t arc, const char *feature_name, rte_graph_feature_t *feature) __rte_experimental int rte_graph_feature_arc_destroy (rte_graph_fea- ture_arc_t _arc) __rte_experimental int rte_graph_feature_arc_cleanup (void) __rte_experimental uint32_t rte_graph_feature_arc_num_features (rte_graph_feature_arc_t _arc) __rte_experimental uint32_t rte_graph_feature_arc_num_enabled_features (rte_graph_feature_arc_t _arc) __rte_experimental char * rte_graph_feature_arc_feature_to_name (rte_graph_feature_arc_t _arc, rte_graph_feature_t feature) __rte_experimental int rte_graph_feature_arc_feature_to_node (rte_graph_feature_arc_t _arc, rte_graph_feature_t feature, rte_node_t *node) __rte_experimental uint32_t rte_graph_feature_arc_names_get (char *arc_names[]) Detailed Description Warning EXPERIMENTAL: All functions in this file may be changed or removed without prior notice. Graph Feature Arc API Define APIs and structures/variables with respect to feature arc * Feature arc(s) * Feature(s) In a typical network stack, often a protocol must be first enabled in con- trol plane before any packet is steered for its processing in the data- plane. For eg: incoming IPv4 packets are routed only after a valid IPv4 ad- dress is assigned to the received interface. In other words, often packets received on an interface need to be steered to protocol not based on the packet content but based on whether the protocol is configured on the in- terface or not. Protocols can be enabled/disabled multiple times at runtime in the control plane. Protocols enabled on one interface may not be enabled on another in- terface. When more than one protocols are present in a networking layer (say IPv4, IP tables, IPsec etc), it becomes imperative to steer packets (in data- plane) across each protocol processing in a defined sequential order. In ingress direction, stack decides to perform IPsec decryption first before IP validation while in egress direction IPsec encryption is performed after IP forwarding. In the case of IP tables, users can enable rules in any pro- tocol order i.e. pre-routing or post-routing etc. This implies that proto- cols are configured differently at each networking layer and in each traf- fic direction. A feature arc represents an ordered list of features/protocols nodes at the given networking layer and in a given direction. It provides a high level abstraction to enable/disable features on an index at runtime and provide a mechanism to steer packets across these feature nodes in a generic manner. Here index corresponds to either interface index, route index, flow index or classification index etc. as it is deemed suitable to configure proto- cols at the networking layer. Some typical examples of protocols which are configured based on * Interface Index (like IPv4 VRF, Port mirroring, Port based IPsec etc) * Routes Index (like Route based IPsec etc) * Flow index (like SDN) * Classification Index (like ACL based protocol steering) Feature arc also provides a way to steer packets from in-built DPDK feature nodes to out-of-tree feature nodes and vice-versa without any code changes required in DPDK in-built node's fast path functions. This way it allows application to override default packet path defined by in-built DPDK nodes. Features enabled on one index may not be enabled on another index hence packets received on an interface 'X' should be treated independently from packets received on interface 'Y'. A given feature might consume packet (if it's configured to consume) or may forward it to next enabled feature. For instance, 'IPsec input' feature may consume/drop all packets with 'Protect' policy action while all packets with policy action as 'Bypass' may be forwarded to next enabled feature (with in same feature arc) A feature arc in a graph is represented via start_node and end_fea- ture_node. Feature nodes are added between start_node and end_feature_node. Packets enter feature arc path via start_node while they exit from end_fea- ture_node. Packets steering from start_node to feature nodes are controlled in control plane via rte_graph_feature_enable(), rte_graph_feature_dis- able(). This library facilitates rte graph based applications to implement stack functionalities described above by providing 'edge' to the next enabled feature node in fast path In order to use feature-arc APIs, applications needs to do following in control plane: * Create feature arc object using RTE_GRAPH_FEATURE_ARC_REGISTER() * New feature nodes (In-built or out-of-tree) can be added to an arc via RTE_GRAPH_FEATURE_REGISTER(). RTE_GRAPH_FEATURE_REGISTER() has rte_graph_feature_register::runs_after and rte_graph_feature_regis- ter::runs_before to specify protocol ordering constraints. * Before calling rte_graph_create(), rte_graph_feature_arc_init() API must be called. If rte_graph_feature_arc_init() is not called by application, feature arc library has no affect. * Features can be enabled/disabled on any index at runtime via rte_graph_feature_enable(), rte_graph_feature_disable(). * Feature arc can be destroyed via rte_graph_feature_arc_destroy() If a given feature likes to control number of indexes (which is higher than rte_graph_feature_arc_register::max_indexes) it can do so by setting rte_graph_feature_register::override_index_cb(). As part of rte_graph_fea- ture_arc_init(), all rte_graph_feature_register::override_index_cb(), if set, are called and with maximum value returned by any of the feature is used for rte_graph_feature_arc_create() Before enabling a feature, control plane might allocate certain resources (like VRF table for IP lookup or IPsec SA for inbound policy etc). A refer- ence of allocated resource can be passed from control plane to dataplane via app_cookie argument in rte_graph_feature_enable(). A corresponding dat- aplane API rte_graph_feature_data_app_cookie_get() can be used to retrieve same cookie in fast path. When a feature is disabled, resources allocated during feature enable can be safely released via registering a callback in rte_graph_feature_regis- ter::notifier_cb(). See fast path synchronization section below for more details. If current feature node is not consuming packet, it might want to send it to next enabled feature. Depending upon current node is a: * start_node (via rte_graph_feature_data_first_feature_get()) * feature nodes added between start_node and end_node (via rte_graph_fea- ture_data_next_feature_get()) * end_feature_node (must not call any feature arc steering APIs) as from this node packet exits feature arc Above APIs deals with fast path object: feature_data (struct rte_graph_fea- ture_data), which is unique for every index per feature with in a feature arc. It holds three data fields: next node edge, next enabled feature data and app_cookie. rte_mbuf carries [feature_data] into feature arc specific mbuf dynamic field. See rte_graph_feature_arc_mbuf_dynfields and rte_graph_fea- ture_arc_mbuf_dynfields_get() for more details. Fast path synchronization Any feature enable/disable in control plane does not require stopping of worker cores. rte_graph_feature_enable()/rte_graph_feature_disable() APIs are almost thread-safe avoiding any RCU usage. Only condition when race condition could occur is when application is trying to enable/disable fea- ture very fast for [feature, index] combination. In that case, application should use rte_graph_feature_enable(), rte_graph_feature_disable() APIs with RCU argument RCU synchronization may also be required when application needs to free re- sources (using rte_graph_feature_register::notifier_cb()) which it may have allocated during feature enable. Resources can be freed only when no worker core is not acting on it. If RCU argument to rte_graph_feature_enable(), rte_graph_feature_disable() is non-NULL, as part of APIs: * rte_rcu_qsbr_synchronize() is called to synchronize all worker cores * If set, rte_graph_feature_register::notifier_cb() is called in which ap- plication can safely release resources associated with [feature, index] It is application responsibility to pass valid RCU argument to APIs. It is recommended that application calls rte_rcu_qsbr_quiescent() after every it- eration of rte_graph_walk() Constraints * rte_graph_feature_arc_init(), rte_graph_feature_arc_create() and rte_graph_feature_add() must be called before rte_graph_create(). * rte_graph_feature_enable(), rte_graph_feature_disable() should be called after rte_graph_create() * Not more than 63 features can be added to a feature arc. There is no limit to number of feature arcs i.e. number of RTE_GRAPH_FEATURE_ARC_REG- ISTER() * There is also no limit for number of indexes (rte_graph_feature_arc_reg- ister::max_indexes). There is also a provision for each RTE_GRAPH_FEA- TURE_REGISTER() to override number of indexes via rte_graph_feature_reg- ister::override_index_cb() * A feature node cannot be part of more than one arc due to performance reason. Optional Usage Feature arc is added as an optional functionality to the graph library hence an application may choose not to use it by skipping explicit call to rte_graph_feature_arc_init(). In that case feature arc would be a no-op for application. Definition in file rte_graph_feature_arc.h. Macro Definition Documentation #define RTE_GRAPH_FEATURE_ARC_NAMELEN RTE_NODE_NAMESIZE Length of feature arc name Definition at line 206 of file rte_graph_feature_arc.h. #define RTE_GRAPH_FEATURE_ARC_INITIALIZER ((rte_graph_fea- ture_arc_t)UINT16_MAX) Initializer values for ARC, Feature, Feature data Definition at line 209 of file rte_graph_feature_arc.h. #define RTE_GRAPH_FEATURE_REGISTER(reg) Value:.PP RTE_INIT(__rte_graph_feature_register_##reg) \ { \ __rte_graph_feature_register(®, __func__, __LINE__); \ } constructor to register feature to an arc Definition at line 346 of file rte_graph_feature_arc.h. #define RTE_GRAPH_FEATURE_ARC_REGISTER(reg) Value:.PP RTE_INIT(__rte_graph_feature_arc_register_##reg) \ { \ __rte_graph_feature_arc_register(®, __func__, __LINE__); \ } constructor to register a feature arc Definition at line 353 of file rte_graph_feature_arc.h. Typedef Documentation typedef uint16_t rte_graph_feature_arc_t rte_graph feature arc object Definition at line 214 of file rte_graph_feature_arc.h. typedef uint8_t rte_graph_feature_t rte_graph feature object Definition at line 217 of file rte_graph_feature_arc.h. typedef uint32_t rte_graph_feature_data_t rte_graph feature data object Definition at line 220 of file rte_graph_feature_arc.h. typedef void(* rte_graph_feature_change_notifier_cb_t) (const char *arc_name, const char *feature_name, rte_node_t feature_node_id, uint32_t index, bool enable_disable, uint16_t app_cookie) feature notifier callback called when feature is enabled/disabled Definition at line 223 of file rte_graph_feature_arc.h. typedef uint16_t(* rte_graph_feature_override_index_cb_t) (void) cb for overriding arc->max_indexes via RTE_GRAPH_FEATURE_REGISTER() Definition at line 231 of file rte_graph_feature_arc.h. Function Documentation __rte_experimental int rte_graph_feature_arc_init (uint16_t num_feature_arcs) Initialize feature arc subsystem This API * Initializes feature arc module and alloc associated memory * creates feature arc for every RTE_GRAPH_FEATURE_ARC_REGISTER() * Add feature node to a feature arc for every RTE_GRAPH_FEATURE_REGISTER() * Replaces all RTE_NODE_REGISTER()->process() functions for * Every start_node/end_feature_node provided in arc registration * Every feature node provided in feature registration Parameters num_feature_arcs Number of feature arcs that application wants to cre- ate by explicitly using 'rte_graph_feature_arc_create()' API. Number of RTE_GRAPH_FEATURE_ARC_REGISTER() should be excluded from this count as API internally calculates number of RTE_GRAPH_FEATURE_ARC_REGIS- TER(). So, total number of supported arcs = num_feature_arcs + NUM- BER_OF(RTE_GRAPH_FEATURE_ARC_REGISTER()) Returns 0: Success <0: Failure rte_graph_feature_arc_init(0) is valid call which will accommodates con- structor based arc registration __rte_experimental int rte_graph_feature_arc_create (struct rte_graph_fea- ture_arc_register * reg, rte_graph_feature_arc_t * _arc) Create a feature arc. This API can be skipped if RTE_GRAPH_FEATURE_ARC_REGISTER() is used Parameters reg Pointer to struct rte_graph_feature_arc_register _arc Feature arc object Returns 0: Success <0: Failure __rte_experimental int rte_graph_feature_arc_lookup_by_name (const char * arc_name, rte_graph_feature_arc_t * _arc) Get feature arc object with name Parameters arc_name Feature arc name provided to successful rte_graph_fea- ture_arc_create() _arc Feature arc object returned. Valid only when API returns SUCCESS Returns 0: Success <0: Failure. __rte_experimental int rte_graph_feature_add (struct rte_graph_feature_regis- ter * feat_reg) Add a feature to already created feature arc. This API is not required in case RTE_GRAPH_FEATURE_REGISTER() is used Parameters feat_reg Pointer to struct rte_graph_feature_register Must be called before rte_graph_create() rte_graph_feature_add() is not allowed after call to rte_graph_feature_enable() so all features must be added before they can be enabled When called by application, then fea- ture_node_id should be appropriately set as freg->feature_node_id = freg->feature_node->id; Returns 0: Success <0: Failure __rte_experimental int rte_graph_feature_enable (rte_graph_feature_arc_t _arc, uint32_t index, const char * feature_name, uint16_t app_cookie, struct rte_rcu_qsbr * qsbr) Enable feature within a feature arc Must be called after rte_graph_create(). Parameters _arc Feature arc object returned by rte_graph_feature_arc_create() or rte_graph_feature_arc_lookup_by_name() index Application specific index. Can be corresponding to inter- face_id/port_id etc feature_name Name of the node which is already added via rte_graph_fea- ture_add() app_cookie Application specific data which is retrieved in fast path qsbr RCU QSBR object. After enabling feature, API calls rte_rcu_qsbr_synchronize() followed by call to struct rte_graph_fea- ture_register::notifier_cb(), if it is set, to notify feature caller This object can be passed NULL as well if no RCU synchronization is re- quired Returns 0: Success <0: Failure __rte_experimental int rte_graph_feature_disable (rte_graph_feature_arc_t _arc, uint32_t index, const char * feature_name, struct rte_rcu_qsbr * qsbr) Disable already enabled feature within a feature arc Must be called after rte_graph_create(). API is NOT Thread-safe Parameters _arc Feature arc object returned by rte_graph_feature_arc_create() or rte_graph_feature_arc_lookup_by_name() index Application specific index. Can be corresponding to inter- face_id/port_id etc feature_name Name of the node which is already added via rte_graph_fea- ture_add() qsbr RCU QSBR object. After disabling feature, API calls rte_rcu_qsbr_synchronize() followed by call to struct RTE_GRAPH_FEA- TURE_ARC_REGISTER::notifier_cb(), if it is set, to notify feature caller. This object can be passed NULL as well if no RCU synchroniza- tion is required Returns 0: Success <0: Failure __rte_experimental int rte_graph_feature_lookup (rte_graph_feature_arc_t arc, const char * feature_name, rte_graph_feature_t * feature) Get rte_graph_feature_t object from feature name Parameters arc Feature arc object returned by rte_graph_feature_arc_create() or rte_graph_feature_arc_lookup_by_name() feature_name Feature name provided to rte_graph_feature_add() feature Feature object Returns 0: Success <0: Failure __rte_experimental int rte_graph_feature_arc_destroy (rte_graph_feature_arc_t _arc) Delete feature_arc object Parameters _arc Feature arc object returned by rte_graph_feature_arc_create() or rte_graph_feature_arc_lookup_by_name() Returns 0: Success <0: Failure __rte_experimental int rte_graph_feature_arc_cleanup (void) Cleanup all feature arcs Returns 0: Success <0: Failure __rte_experimental uint32_t rte_graph_feature_arc_num_features (rte_graph_feature_arc_t _arc) Slow path API to know how many features are added (NOT enabled) within a feature arc Parameters _arc Feature arc object Returns : Number of added features to arc __rte_experimental uint32_t rte_graph_feature_arc_num_enabled_features (rte_graph_feature_arc_t _arc) Slow path API to know how many features are currently enabled within a fea- ture arc across all indexes. If a single feature is enabled on all inter- faces, this API would return 'number_of_interfaces' as count (but not '1') Parameters _arc Feature arc object Returns : Number of enabled features across all indexes __rte_experimental char * rte_graph_feature_arc_feature_to_name (rte_graph_feature_arc_t _arc, rte_graph_feature_t feature) Slow path API to get feature node name from rte_graph_feature_t object Parameters _arc Feature arc object feature Feature object Returns : Name of the feature node __rte_experimental int rte_graph_feature_arc_feature_to_node (rte_graph_fea- ture_arc_t _arc, rte_graph_feature_t feature, rte_node_t * node) Slow path API to get corresponding rte_node_t from rte_graph_feature_t Parameters _arc Feature arc object feature Feature object node rte_node_t of feature node, Valid only when API returns SUCCESS Returns : 0 on success, < 0 on failure __rte_experimental uint32_t rte_graph_feature_arc_names_get (char * arc_names[]) Slow path API to dump valid feature arc names Parameters arc_names Buffer to copy the arc names. The NULL value is allowed in that case, the function returns the size of the array that needs to be allocated. Returns When next_nodes == NULL, it returns the size of the array else number of item copied. Author Generated automatically by Doxygen for DPDK from the source code. Version 25.11.0 Thu Aug 27 2026 rte_graph_feature_arc.h(3)
NAME | SYNOPSIS | Detailed Description | Macro Definition Documentation | Typedef Documentation | Function Documentation | Author
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=RTE_GRAPH_FEATURE_REGISTER&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>