Scroll to navigation

rte_graph_feature_arc.h(3) Library Functions Manual 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_feature_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_feature_arcs)
__rte_experimental int rte_graph_feature_arc_create (struct rte_graph_feature_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_register *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_feature_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 control plane before any packet is steered for its processing in the dataplane. For eg: incoming IPv4 packets are routed only after a valid IPv4 address 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 interface 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 interface.

When more than one protocols are present in a networking layer (say IPv4, IP tables, IPsec etc), it becomes imperative to steer packets (in dataplane) 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 protocol order i.e. pre-routing or post-routing etc. This implies that protocols are configured differently at each networking layer and in each traffic 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 protocols 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_feature_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_feature_node. Packets steering from start_node to feature nodes are controlled in control plane via rte_graph_feature_enable(), rte_graph_feature_disable().

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_register::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_feature_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 reference of allocated resource can be passed from control plane to dataplane via app_cookie argument in rte_graph_feature_enable(). A corresponding dataplane 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_register::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_feature_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_feature_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_feature_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 feature 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 resources (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 application 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 iteration 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_REGISTER()
  • There is also no limit for number of indexes (rte_graph_feature_arc_register::max_indexes). There is also a provision for each RTE_GRAPH_FEATURE_REGISTER() to override number of indexes via rte_graph_feature_register::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_feature_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:



    RTE_INIT(__rte_graph_feature_register_##reg)                                    \


    {                                                                               \


        __rte_graph_feature_register(&reg, __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:




    RTE_INIT(__rte_graph_feature_arc_register_##reg)                                \


    {                                                                               \


        __rte_graph_feature_arc_register(&reg, __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 create 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_REGISTER().




So, total number of supported arcs = num_feature_arcs +
    NUMBER_OF(RTE_GRAPH_FEATURE_ARC_REGISTER())




Returns


0: Success <0: Failure


rte_graph_feature_arc_init(0) is valid call which will
    accommodates constructor based arc registration






__rte_experimental int rte_graph_feature_arc_create (struct rte_graph_feature_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_feature_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_register * 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
    feature_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
  interface_id/port_id etc


feature_name Name of the node which is already added via
  rte_graph_feature_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_feature_register::notifier_cb(), if it is set, to notify
  feature caller This object can be passed NULL as well if no RCU
  synchronization is required


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
  interface_id/port_id etc


feature_name Name of the node which is already added via
  rte_graph_feature_add()


qsbr RCU QSBR object. After disabling feature, API calls
  rte_rcu_qsbr_synchronize() followed by call to struct
  RTE_GRAPH_FEATURE_ARC_REGISTER::notifier_cb(), if it is set, to notify feature
  caller. This object can be passed NULL as well if no RCU synchronization 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 feature arc across all indexes. If a single feature is enabled on
    all interfaces, 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_feature_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
    DPDK