DPDK  20.05.0-rc0
Data Structures | Macros | Typedefs | Functions
rte_graph.h File Reference
#include <stdbool.h>
#include <stdio.h>
#include <rte_common.h>
#include <rte_compat.h>

Go to the source code of this file.

Data Structures

struct  rte_graph_param
 
struct  rte_graph_cluster_stats_param
 
struct  rte_graph_cluster_node_stats
 
struct  rte_node_register
 

Macros

#define RTE_GRAPH_NAMESIZE   64
 
#define RTE_NODE_NAMESIZE   64
 
#define RTE_GRAPH_OFF_INVALID   UINT32_MAX
 
#define RTE_NODE_ID_INVALID   UINT32_MAX
 
#define RTE_EDGE_ID_INVALID   UINT16_MAX
 
#define RTE_GRAPH_ID_INVALID   UINT16_MAX
 
#define RTE_GRAPH_FENCE   0xdeadbeef12345678ULL
 
#define RTE_NODE_SOURCE_F   (1ULL << 0)
 
#define rte_graph_foreach_node(count, off, graph, node)
 
#define RTE_NODE_REGISTER(node)
 

Typedefs

typedef uint32_t rte_graph_off_t
 
typedef uint32_t rte_node_t
 
typedef uint16_t rte_edge_t
 
typedef uint16_t rte_graph_t
 
typedef uint16_t(* rte_node_process_t) (struct rte_graph *graph, struct rte_node *node, void **objs, uint16_t nb_objs)
 
typedef int(* rte_node_init_t) (const struct rte_graph *graph, struct rte_node *node)
 
typedef void(* rte_node_fini_t) (const struct rte_graph *graph, struct rte_node *node)
 
typedef int(* rte_graph_cluster_stats_cb_t) (bool is_first, bool is_last, void *cookie, const struct rte_graph_cluster_node_stats *stats)
 

Functions

__rte_experimental rte_graph_t rte_graph_create (const char *name, struct rte_graph_param *prm)
 
__rte_experimental rte_graph_t rte_graph_destroy (const char *name)
 
__rte_experimental rte_graph_t rte_graph_from_name (const char *name)
 
__rte_experimental char * rte_graph_id_to_name (rte_graph_t id)
 
__rte_experimental rte_graph_t rte_graph_export (const char *name, FILE *f)
 
__rte_experimental struct rte_graph * rte_graph_lookup (const char *name)
 
__rte_experimental rte_graph_t rte_graph_max_count (void)
 
__rte_experimental void rte_graph_dump (FILE *f, rte_graph_t id)
 
__rte_experimental void rte_graph_list_dump (FILE *f)
 
__rte_experimental void rte_graph_obj_dump (FILE *f, struct rte_graph *graph, bool all)
 
__rte_experimental struct rte_node * rte_graph_node_get (rte_graph_t graph_id, uint32_t node_id)
 
__rte_experimental struct rte_node * rte_graph_node_get_by_name (const char *graph, const char *name)
 
__rte_experimental struct rte_graph_cluster_stats * rte_graph_cluster_stats_create (const struct rte_graph_cluster_stats_param *prm)
 
__rte_experimental void rte_graph_cluster_stats_destroy (struct rte_graph_cluster_stats *stat)
 
__rte_experimental void rte_graph_cluster_stats_get (struct rte_graph_cluster_stats *stat, bool skip_cb)
 
__rte_experimental void rte_graph_cluster_stats_reset (struct rte_graph_cluster_stats *stat)
 
__rte_experimental rte_node_t __rte_node_register (const struct rte_node_register *node)
 
__rte_experimental rte_node_t rte_node_clone (rte_node_t id, const char *name)
 
__rte_experimental rte_node_t rte_node_from_name (const char *name)
 
__rte_experimental char * rte_node_id_to_name (rte_node_t id)
 
__rte_experimental rte_edge_t rte_node_edge_count (rte_node_t id)
 
__rte_experimental rte_edge_t rte_node_edge_update (rte_node_t id, rte_edge_t from, const char **next_nodes, uint16_t nb_edges)
 
__rte_experimental rte_edge_t rte_node_edge_shrink (rte_node_t id, rte_edge_t size)
 
__rte_experimental rte_node_t rte_node_edge_get (rte_node_t id, char *next_nodes[])
 
__rte_experimental rte_node_t rte_node_max_count (void)
 
__rte_experimental void rte_node_dump (FILE *f, rte_node_t id)
 
__rte_experimental void rte_node_list_dump (FILE *f)
 
static __rte_always_inline int rte_node_is_invalid (rte_node_t id)
 
static __rte_always_inline int rte_edge_is_invalid (rte_edge_t id)
 
static __rte_always_inline int rte_graph_is_invalid (rte_graph_t id)
 
static __rte_always_inline int rte_graph_has_stats_feature (void)
 

Detailed Description

Warning
EXPERIMENTAL: this API may change without prior notice

Graph architecture abstracts the data processing functions as "node" and "link" them together to create a complex "graph" to enable reusable/modular data processing functions.

This API enables graph framework operations such as create, lookup, dump and destroy on graph and node operations such as clone, edge update, and edge shrink, etc. The API also allows to create the stats cluster to monitor per graph and per node stats.

Definition in file rte_graph.h.

Macro Definition Documentation

#define RTE_GRAPH_NAMESIZE   64

Max length of graph name.

Examples:
examples/l3fwd-graph/main.c.

Definition at line 35 of file rte_graph.h.

#define RTE_NODE_NAMESIZE   64

Max length of node name.

Examples:
examples/l3fwd-graph/main.c.

Definition at line 36 of file rte_graph.h.

#define RTE_GRAPH_OFF_INVALID   UINT32_MAX

Invalid graph offset.

Definition at line 37 of file rte_graph.h.

#define RTE_NODE_ID_INVALID   UINT32_MAX

Invalid node id.

Definition at line 38 of file rte_graph.h.

#define RTE_EDGE_ID_INVALID   UINT16_MAX

Invalid edge id.

Definition at line 39 of file rte_graph.h.

#define RTE_GRAPH_ID_INVALID   UINT16_MAX

Invalid graph id.

Definition at line 40 of file rte_graph.h.

#define RTE_GRAPH_FENCE   0xdeadbeef12345678ULL

Graph fence data.

Definition at line 41 of file rte_graph.h.

#define RTE_NODE_SOURCE_F   (1ULL << 0)

Node type is source.

Definition at line 245 of file rte_graph.h.

#define rte_graph_foreach_node (   count,
  off,
  graph,
  node 
)
Value:
for (count = 0, off = graph->nodes_start, \
node = RTE_PTR_ADD(graph, off); \
count < graph->nb_nodes; \
off = node->next, node = RTE_PTR_ADD(graph, off), count++)
#define RTE_PTR_ADD(ptr, x)
Definition: rte_common.h:195

Macro to browse rte_node object after the graph creation

Definition at line 414 of file rte_graph.h.

#define RTE_NODE_REGISTER (   node)
Value:
RTE_INIT(rte_node_register_##node) \
{ \
node.parent_id = RTE_NODE_ID_INVALID; \
node.id = __rte_node_register(&node); \
}
__rte_experimental rte_node_t __rte_node_register(const struct rte_node_register *node)
#define RTE_INIT(func)
Definition: rte_common.h:152
#define RTE_NODE_ID_INVALID
Definition: rte_graph.h:38

Register a static node.

The static node is registered through the constructor scheme, thereby, it can be used in a multi-process scenario.

Parameters
nodeValid node pointer with name, process function, and next_nodes.

Definition at line 540 of file rte_graph.h.

Typedef Documentation

typedef uint32_t rte_graph_off_t

Graph offset type.

Definition at line 43 of file rte_graph.h.

typedef uint32_t rte_node_t

Node id type.

Definition at line 44 of file rte_graph.h.

typedef uint16_t rte_edge_t

Edge id type.

Definition at line 45 of file rte_graph.h.

typedef uint16_t rte_graph_t

Graph id type.

Definition at line 46 of file rte_graph.h.

typedef uint16_t(* rte_node_process_t) (struct rte_graph *graph, struct rte_node *node, void **objs, uint16_t nb_objs)

Node stats within cluster of graphs

Warning
EXPERIMENTAL: this API may change without prior notice

Node process function.

The function invoked when the worker thread walks on nodes using rte_graph_walk().

Parameters
graphPointer to the graph object.
nodePointer to the node object.
objsPointer to an array of objects to be processed.
nb_objsNumber of objects in the array.
Returns
Number of objects processed.
See also
rte_graph_walk()

Definition at line 101 of file rte_graph.h.

typedef int(* rte_node_init_t) (const struct rte_graph *graph, struct rte_node *node)
Warning
EXPERIMENTAL: this API may change without prior notice

Node initialization function.

The function invoked when the user creates the graph using rte_graph_create()

Parameters
graphPointer to the graph object.
nodePointer to the node object.
Returns
  • 0: Success. -<0: Failure.
See also
rte_graph_create()

Definition at line 124 of file rte_graph.h.

typedef void(* rte_node_fini_t) (const struct rte_graph *graph, struct rte_node *node)
Warning
EXPERIMENTAL: this API may change without prior notice

Node finalization function.

The function invoked when the user destroys the graph using rte_graph_destroy().

Parameters
graphPointer to the graph object.
nodePointer to the node object.
See also
rte_graph_destroy()

Definition at line 143 of file rte_graph.h.

typedef int(* rte_graph_cluster_stats_cb_t) (bool is_first, bool is_last, void *cookie, const struct rte_graph_cluster_node_stats *stats)
Warning
EXPERIMENTAL: this API may change without prior notice

Graph cluster stats callback.

Parameters
is_firstFlag to denote that stats are of the first node.
is_lastFlag to denote that stats are of the last node.
cookieCookie supplied during stats creation.
statsNode cluster stats data.
Returns
  • 0: Success. -<0: Failure.

Definition at line 165 of file rte_graph.h.

Function Documentation

__rte_experimental rte_graph_t rte_graph_create ( const char *  name,
struct rte_graph_param prm 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Create Graph.

Create memory reel, detect loops and find isolated nodes.

Parameters
nameUnique name for this graph.
prmGraph parameter, includes node names and count to be included in this graph.
Returns
Unique graph id on success, RTE_GRAPH_ID_INVALID otherwise.
Examples:
examples/l3fwd-graph/main.c.
__rte_experimental rte_graph_t rte_graph_destroy ( const char *  name)
Warning
EXPERIMENTAL: this API may change without prior notice

Destroy Graph.

Free Graph memory reel.

Parameters
nameName of the graph to destroy.
Returns
0 on success, error otherwise.
Examples:
examples/l3fwd-graph/main.c.
__rte_experimental rte_graph_t rte_graph_from_name ( const char *  name)
Warning
EXPERIMENTAL: this API may change without prior notice

Get graph id from graph name.

Parameters
nameName of the graph to get id.
Returns
Graph id on success, RTE_GRAPH_ID_INVALID otherwise.
__rte_experimental char* rte_graph_id_to_name ( rte_graph_t  id)
Warning
EXPERIMENTAL: this API may change without prior notice

Get graph name from graph id.

Parameters
idid of the graph to get name.
Returns
Graph name on success, NULL otherwise.
__rte_experimental rte_graph_t rte_graph_export ( const char *  name,
FILE *  f 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Export the graph as graph viz dot file

Parameters
nameName of the graph to export.
fFile pointer to export the graph.
Returns
0 on success, error otherwise.
__rte_experimental struct rte_graph* rte_graph_lookup ( const char *  name)
Warning
EXPERIMENTAL: this API may change without prior notice

Get graph object from its name.

Typical usage of this API to get graph objects in the worker thread and followed calling rte_graph_walk() in a loop.

Parameters
nameName of the graph.
Returns
Graph pointer on success, NULL otherwise.
See also
rte_graph_walk()
Examples:
examples/l3fwd-graph/main.c.
__rte_experimental rte_graph_t rte_graph_max_count ( void  )
Warning
EXPERIMENTAL: this API may change without prior notice

Get maximum number of graph available.

Returns
Maximum graph count on success, RTE_GRAPH_ID_INVALID otherwise.
__rte_experimental void rte_graph_dump ( FILE *  f,
rte_graph_t  id 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Dump the graph information to file.

Parameters
fFile pointer to dump graph info.
idGraph id to get graph info.
__rte_experimental void rte_graph_list_dump ( FILE *  f)
Warning
EXPERIMENTAL: this API may change without prior notice

Dump all graphs information to file

Parameters
fFile pointer to dump graph info.
__rte_experimental void rte_graph_obj_dump ( FILE *  f,
struct rte_graph *  graph,
bool  all 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Dump graph information along with node info to file

Parameters
fFile pointer to dump graph info.
graphGraph pointer to get graph info.
alltrue to dump nodes in the graph.
__rte_experimental struct rte_node* rte_graph_node_get ( rte_graph_t  graph_id,
uint32_t  node_id 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Get node object with in graph from id.

Parameters
graph_idGraph id to get node pointer from.
node_idNode id to get node pointer.
Returns
Node pointer on success, NULL otherwise.
__rte_experimental struct rte_node* rte_graph_node_get_by_name ( const char *  graph,
const char *  name 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Get node pointer with in graph from name.

Parameters
graphGraph name to get node pointer from.
nameNode name to get the node pointer.
Returns
Node pointer on success, NULL otherwise.
__rte_experimental struct rte_graph_cluster_stats* rte_graph_cluster_stats_create ( const struct rte_graph_cluster_stats_param prm)
Warning
EXPERIMENTAL: this API may change without prior notice

Create graph stats cluster to aggregate runtime node stats.

Parameters
prmParameters including file pointer to dump stats, Graph pattern to create cluster and callback function.
Returns
Valid pointer on success, NULL otherwise.
Examples:
examples/l3fwd-graph/main.c.
__rte_experimental void rte_graph_cluster_stats_destroy ( struct rte_graph_cluster_stats *  stat)
Warning
EXPERIMENTAL: this API may change without prior notice

Destroy cluster stats.

Parameters
statValid cluster pointer to destroy.
Examples:
examples/l3fwd-graph/main.c.
__rte_experimental void rte_graph_cluster_stats_get ( struct rte_graph_cluster_stats *  stat,
bool  skip_cb 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Get stats to application.

Parameters
[out]statCluster status.
skip_cbtrue to skip callback function invocation.
Examples:
examples/l3fwd-graph/main.c.
__rte_experimental void rte_graph_cluster_stats_reset ( struct rte_graph_cluster_stats *  stat)
Warning
EXPERIMENTAL: this API may change without prior notice

Reset cluster stats to zero.

Parameters
statValid cluster stats pointer.
__rte_experimental rte_node_t __rte_node_register ( const struct rte_node_register node)
Warning
EXPERIMENTAL: this API may change without prior notice

Register new packet processing node. Nodes can be registered dynamically via this call or statically via the RTE_NODE_REGISTER macro.

Parameters
nodeValid node pointer with name, process function and next_nodes.
Returns
Valid node id on success, RTE_NODE_ID_INVALID otherwise.
See also
RTE_NODE_REGISTER()
__rte_experimental rte_node_t rte_node_clone ( rte_node_t  id,
const char *  name 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Clone a node from static node(node created from RTE_NODE_REGISTER).

Parameters
idStatic node id to clone from.
nameName of the new node. The library prepends the parent node name to the user-specified the name. The final node name will be, "parent node name" + "-" + name.
Returns
Valid node id on success, RTE_NODE_ID_INVALID otherwise.
__rte_experimental rte_node_t rte_node_from_name ( const char *  name)
Warning
EXPERIMENTAL: this API may change without prior notice

Get node id from node name.

Parameters
nameValid node name. In the case of the cloned node, the name will be "parent node name" + "-" + name.
Returns
Valid node id on success, RTE_NODE_ID_INVALID otherwise.
__rte_experimental char* rte_node_id_to_name ( rte_node_t  id)
Warning
EXPERIMENTAL: this API may change without prior notice

Get node name from node id.

Parameters
idValid node id.
Returns
Valid node name on success, NULL otherwise.
__rte_experimental rte_edge_t rte_node_edge_count ( rte_node_t  id)
Warning
EXPERIMENTAL: this API may change without prior notice

Get the number of edges for a node from node id.

Parameters
idValid node id.
Returns
Valid edge count on success, RTE_EDGE_ID_INVALID otherwise.
__rte_experimental rte_edge_t rte_node_edge_update ( rte_node_t  id,
rte_edge_t  from,
const char **  next_nodes,
uint16_t  nb_edges 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Update the edges for a node from node id.

Parameters
idValid node id.
fromIndex to update the edges from. RTE_EDGE_ID_INVALID is valid, in that case, it will be added to the end of the list.
next_nodesName of the edges to update.
nb_edgesNumber of edges to update.
Returns
Valid edge count on success, 0 otherwise.
__rte_experimental rte_edge_t rte_node_edge_shrink ( rte_node_t  id,
rte_edge_t  size 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Shrink the edges to a given size.

Parameters
idValid node id.
sizeNew size to shrink the edges.
Returns
New size on success, RTE_EDGE_ID_INVALID otherwise.
__rte_experimental rte_node_t rte_node_edge_get ( rte_node_t  id,
char *  next_nodes[] 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Get the edge names from a given node.

Parameters
idValid node id.
[out]next_nodesBuffer to copy the edge 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.
__rte_experimental rte_node_t rte_node_max_count ( void  )
Warning
EXPERIMENTAL: this API may change without prior notice

Get maximum nodes created so far.

Returns
Maximum nodes count on success, 0 otherwise.
__rte_experimental void rte_node_dump ( FILE *  f,
rte_node_t  id 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Dump node info to file.

Parameters
fFile pointer to dump the node info.
idNode id to get the info.
__rte_experimental void rte_node_list_dump ( FILE *  f)
Warning
EXPERIMENTAL: this API may change without prior notice

Dump all node info to file.

Parameters
fFile pointer to dump the node info.
static __rte_always_inline int rte_node_is_invalid ( rte_node_t  id)
static
Warning
EXPERIMENTAL: this API may change without prior notice

Test the validity of node id.

Parameters
idNode id to check.
Returns
1 if valid id, 0 otherwise.

Definition at line 722 of file rte_graph.h.

static __rte_always_inline int rte_edge_is_invalid ( rte_edge_t  id)
static
Warning
EXPERIMENTAL: this API may change without prior notice

Test the validity of edge id.

Parameters
idEdge node id to check.
Returns
1 if valid id, 0 otherwise.

Definition at line 740 of file rte_graph.h.

static __rte_always_inline int rte_graph_is_invalid ( rte_graph_t  id)
static
Warning
EXPERIMENTAL: this API may change without prior notice

Test the validity of graph id.

Parameters
idGraph id to check.
Returns
1 if valid id, 0 otherwise.

Definition at line 758 of file rte_graph.h.

static __rte_always_inline int rte_graph_has_stats_feature ( void  )
static
Warning
EXPERIMENTAL: this API may change without prior notice

Test stats feature support.

Returns
1 if stats enabled, 0 otherwise.
Examples:
examples/l3fwd-graph/main.c.

Definition at line 773 of file rte_graph.h.