rte_graph.h(3)

📦
version 25.11.3 · 11 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

rte_graph.h — bestie, it's the header for the DPDK graph framework. It lives in Library Functions Manual, section 3, which is the "you call these from your C code" section. iykyk. 🦋

✨ SYNOPSIS ✨

No cap, here's what you gotta #include before you do anything:

#include <stdbool.h>
#include <stdio.h>
#include <rte_common.h>
#include <rte_compat.h>

🌸 Data Structures 🌸

struct rte_graph_param
struct rte_graph_cluster_stats_param
struct rte_graph_cluster_node_stats
struct rte_node_xstats
struct rte_node_register

🎀 Macros 🎀

#define RTE_GRAPH_NAMESIZE   64
#define RTE_NODE_NAMESIZE   64
#define RTE_NODE_XSTAT_DESC_SIZE   64
#define RTE_GRAPH_PCAP_FILE_SZ   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_graph_foreach_node(count,  off,  graph,  node)
#define RTE_NODE_SOURCE_F   (1ULL << 0)
#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)
typedef void(* packets_enqueued_cb) (struct rte_graph *graph, uint64_t cb_priv)

👑 Functions 👑

rte_graph_t rte_graph_create (const char *name, struct rte_graph_param *prm)
int rte_graph_destroy (rte_graph_t id)
rte_graph_t rte_graph_clone (rte_graph_t id, const char *name, struct rte_graph_param *prm)
rte_graph_t rte_graph_from_name (const char *name)
char * rte_graph_id_to_name (rte_graph_t id)
int rte_graph_export (const char *name, FILE *f)
int rte_graph_model_mcore_dispatch_core_bind (rte_graph_t id, int lcore)
void rte_graph_model_mcore_dispatch_core_unbind (rte_graph_t id)
struct rte_graph * rte_graph_lookup (const char *name)
rte_graph_t rte_graph_max_count (void)
void rte_graph_dump (FILE *f, rte_graph_t id)
void rte_graph_list_dump (FILE *f)
void rte_graph_obj_dump (FILE *f, struct rte_graph *graph, bool all)
struct rte_node * rte_graph_node_get (rte_graph_t graph_id, rte_node_t node_id)
struct rte_node * rte_graph_node_get_by_name (const char *graph, const char *name)
struct rte_graph_cluster_stats * rte_graph_cluster_stats_create (const struct rte_graph_cluster_stats_param *prm)
void rte_graph_cluster_stats_destroy (struct rte_graph_cluster_stats *stat)
void rte_graph_cluster_stats_get (struct rte_graph_cluster_stats *stat, bool skip_cb)
void rte_graph_cluster_stats_reset (struct rte_graph_cluster_stats *stat)
rte_node_t __rte_node_register (const struct rte_node_register *node)
rte_node_t rte_node_clone (rte_node_t id, const char *name)
rte_node_t rte_node_from_name (const char *name)
char * rte_node_id_to_name (rte_node_t id)
rte_edge_t rte_node_edge_count (rte_node_t id)
rte_edge_t rte_node_edge_update (rte_node_t id, rte_edge_t from, const char **next_nodes, uint16_t nb_edges)
rte_edge_t rte_node_edge_shrink (rte_node_t id, rte_edge_t size)
rte_node_t rte_node_edge_get (rte_node_t id, char *next_nodes[])
rte_node_t rte_node_max_count (void)
void rte_node_dump (FILE *f, rte_node_t id)
void rte_node_list_dump (FILE *f)
static __rte_always_inline int rte_node_is_invalid (rte_node_t id)
__rte_experimental int rte_node_free (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 🌈

Okay so the whole vibe: the graph architecture takes your data processing functions and abstracts them as "node"s, then "link"s them together into one big complex "graph" — so your data processing functions stay reusable and modular. Periodt. 💅

This API gives you the graph framework operations — create, lookup, dump and destroy on graphs — plus node operations like clone, edge update, and edge shrink, etc. It also lets you spin up the stats cluster so you can monitor per-graph and per-node stats. Obsessed honestly.

Definition in file rte_graph.h.

🎀 Macro Definition Documentation 🎀

#define RTE_GRAPH_NAMESIZE 64

Max length of graph name. That's the ceiling bestie, don't be out here writing a longer name. 😭

Definition at line 31 of file rte_graph.h.

#define RTE_NODE_NAMESIZE 64

Max length of node name. Same energy, same number. ✨

Definition at line 32 of file rte_graph.h.

#define RTE_NODE_XSTAT_DESC_SIZE 64

Max length of node xstat description. Yes it's 64 again. The 64 agenda is real. 💀

Definition at line 33 of file rte_graph.h.

#define RTE_GRAPH_PCAP_FILE_SZ 64

Max length of pcap file name. Catch the theme? sixty-four. 🌸

Definition at line 34 of file rte_graph.h.

#define RTE_GRAPH_OFF_INVALID UINT32_MAX

Invalid graph offset — this is the "nah, that's not a real one" sentinel. 🚫

Definition at line 35 of file rte_graph.h.

#define RTE_NODE_ID_INVALID UINT32_MAX

Invalid node id. If you see this value, the node id is not it. 🙈

Definition at line 36 of file rte_graph.h.

#define RTE_EDGE_ID_INVALID UINT16_MAX

Invalid edge id. Sentinel city. 💜

Definition at line 37 of file rte_graph.h.

#define RTE_GRAPH_ID_INVALID UINT16_MAX

Invalid graph id. Also UINT16_MAX, also invalid, also iconic. 👑

Definition at line 38 of file rte_graph.h.

#define RTE_GRAPH_FENCE 0xdeadbeef12345678ULL

Graph fence data. Literally the funniest magic number in the whole header and I respect it so much. 🩷

Definition at line 39 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++)

Macro to browse rte_node objects after the graph creation. Your little iterator bestie. 🦋

Definition at line 408 of file rte_graph.h.

#define RTE_NODE_SOURCE_F (1ULL << 0)

Node type is source. Slay, it's bit 0. ⭐

Definition at line 498 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);                          \
}

Register a static node.

The static node is registered through the constructor scheme, thereby, it can be used in a multi-process scenario. (Yes, constructor scheme. It just Does That before your main even wakes up. 💅)

Parameters

  • node — Valid node pointer with name, process function, and next_nodes.

Definition at line 533 of file rte_graph.h.

🧚 Typedef Documentation 🧚

typedef uint32_t rte_graph_off_t

Graph offset type. Definition at line 41 of file rte_graph.h.

typedef uint32_t rte_node_t

Node id type. Definition at line 42 of file rte_graph.h.

typedef uint16_t rte_edge_t

Edge id type. Definition at line 43 of file rte_graph.h.

typedef uint16_t rte_graph_t

Graph id type. Definition at line 44 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 Node process function.

This is the function that gets invoked when the worker thread walks on nodes using rte_graph_walk(). Main character energy, truly.

Parameters

  • graph — Pointer to the graph object.
  • node — Pointer to the node object.
  • objs — Pointer to an array of objects to be processed.
  • nb_objs — Number of objects in the array.

Returns

Number of objects processed.

See also

rte_graph_walk()

Definition at line 95 of file rte_graph.h.

typedef int(* rte_node_init_t) (const struct rte_graph *graph, struct rte_node *node)

Node initialization function.

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

Parameters

  • graph — Pointer to the graph object.
  • node — Pointer to the node object.

Returns

  • 0: Success. -<0: Failure.
Watch that return value bestie — negative means it did NOT go well. 😭

See also

rte_graph_create()

Definition at line 115 of file rte_graph.h.

typedef void(* rte_node_fini_t) (const struct rte_graph *graph, struct rte_node *node)

Node finalization function.

The function invoked when the user destroys the graph using rte_graph_destroy(). Say bye bye properly. 🫶

Parameters

  • graph — Pointer to the graph object.
  • node — Pointer to the node object.

See also

rte_graph_destroy()

Definition at line 131 of file rte_graph.h.

Graph cluster stats callback.

Parameters

  • is_first — Flag to denote that stats are of the first node.
  • is_last — Flag to denote that stats are of the last node.
  • cookie — Cookie supplied during stats creation.
  • stats — Node cluster stats data.

Returns

  • 0: Success. -<0: Failure.

Definition at line 150 of file rte_graph.h.

typedef void(* packets_enqueued_cb) (struct rte_graph *graph, uint64_t cb_priv)

Graph dispatch enqueue notification callback. It's giving "hey bestie, something got enqueued."

Parameters

  • graph — Current graph.
  • cb_priv — Opaque argument given to the callback.

Definition at line 161 of file rte_graph.h.

ok that's the whole header layout, the macros, and every typedef — part 2 is pulling up next with the actual function documentation, so don't wander off 💖🌸

💖 Function Documentation 💖

🫶 rte_graph_t rte_graph_create (const char * name, struct rte_graph_param * prm)

okay bestie, this is THE one — it creates the Graph. It creates the memory reel, detects loops and finds isolated nodes. like it does the whole vibe check on your graph topology fr fr.

Parameters

  • name — unique name for this graph. One of one, no dupes allowed 💅
  • prm — graph parameter, includes node names and count to be included in this graph.

Returns

  • unique graph id on success, RTE_GRAPH_ID_INVALID otherwise. 😭 if you get the invalid one, something went wrong.

🦋 int rte_graph_destroy (rte_graph_t id)

Destroy Graph. It frees the Graph memory reel, that's it, that's the whole gig.

Parameters

  • id — id of the graph to destroy.

Returns

  • 0 on success, error otherwise.

✨ rte_graph_t rte_graph_clone (rte_graph_t id, const char * name, struct rte_graph_param * prm)

Clone Graph — the glow-up, but make it a copy.

It clones a graph from a static graph (a graph created from rte_graph_create()). And heads up: all cloned graphs attached to the parent graph MUST be destroyed together, for fast schedule design limitation reasons (stop ALL graph walk firstly). So no leaving a clone behind, she said what she said 🌸

Parameters

  • id — static graph id to clone from.
  • name — name of the new graph. The library prepends the parent graph name to the user-specified name. The final graph name will be, "parent graph name" + "-" + name. It's giving hyphenated surname energy 💅
  • prm — graph parameter, includes model-specific parameters in this graph.

Returns

  • valid graph id on success, RTE_GRAPH_ID_INVALID otherwise.

🎀 rte_graph_t rte_graph_from_name (const char * name)

Get graph id from graph name. name-to-id pipeline, iconic.

Parameters

  • name — name of the graph to get id.

Returns

  • graph id on success, RTE_GRAPH_ID_INVALID otherwise.

💜 char * rte_graph_id_to_name (rte_graph_t id)

Get graph name from graph id. the reverse direction bestie, id-to-name.

Parameters

  • id — id of the graph to get name.

Returns

  • graph name on success, NULL otherwise.

🌈 int rte_graph_export (const char * name, FILE * f)

Export the graph as graph viz dot file 🎨 yes it literally gives you a picture of your graph, slay.

Parameters

  • name — name of the graph to export.
  • f — file pointer to export the graph.

Returns

  • 0 on success, error otherwise.

👑 int rte_graph_model_mcore_dispatch_core_bind (rte_graph_t id, int lcore)

Bind graph with specific lcore for mcore dispatch model. pinning your graph to a core, main character energy.

Parameters

  • id — graph id to get the pointer of graph object.
  • lcore — the lcore where the graph will run on.

Returns

  • 0 on success, error otherwise.

🧚 void rte_graph_model_mcore_dispatch_core_unbind (rte_graph_t id)

Unbind graph with lcore for mcore dispatch model. undoing the bind, no hard feelings ✨

Parameters

  • id — graph id to get the pointer of graph object.

🔥 struct rte_graph * rte_graph_lookup (const char * name)

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. so like: look it up, then walk, walk, walk 🌸

Parameters

  • name — name of the graph.

Returns

  • graph pointer on success, NULL otherwise.

See also

  • rte_graph_walk()

⭐ rte_graph_t rte_graph_max_count (void )

Get maximum number of graph available.

Returns

  • maximum graph count.

💖 void rte_graph_dump (FILE * f, rte_graph_t id)

Dump the graph information to file. spilling all the graph tea, into a file 🫖

Parameters

  • f — file pointer to dump graph info.
  • id — graph id to get graph info.

🌸 void rte_graph_list_dump (FILE * f)

Dump all graphs information to file. every single graph, no graph left behind.

Parameters

  • f — file pointer to dump graph info.

🦋 void rte_graph_obj_dump (FILE * f, struct rte_graph * graph, bool all)

Dump graph information along with node info to file. graph AND node gossip together, obsessed.

Parameters

  • f — file pointer to dump graph info.
  • graph — graph pointer to get graph info.
  • all — true to dump nodes in the graph.

🎀 struct rte_node * rte_graph_node_get (rte_graph_t graph_id, rte_node_t node_id)

Get node object with in graph from id.

Parameters

  • graph_id — graph id to get node pointer from.
  • node_id — node id to get node pointer.

Returns

  • node pointer on success, NULL otherwise.

💜 struct rte_node * rte_graph_node_get_by_name (const char * graph, const char * name)

Get node pointer with in graph from name.

Parameters

  • graph — graph name to get node pointer from.
  • name — node name to get the node pointer.

Returns

  • node pointer on success, NULL otherwise.

🌈 struct rte_graph_cluster_stats * rte_graph_cluster_stats_create (const struct rte_graph_cluster_stats_param * prm)

Create graph stats cluster to aggregate runtime node stats. the group project where everyone's stats get collected 😌

Parameters

  • prm — parameters including file pointer to dump stats, Graph pattern to create cluster and callback function.

Returns

  • valid pointer on success, NULL otherwise.

👑 void rte_graph_cluster_stats_destroy (struct rte_graph_cluster_stats * stat)

Destroy cluster stats.

Parameters

  • stat — valid cluster pointer to destroy.

🧚 void rte_graph_cluster_stats_get (struct rte_graph_cluster_stats * stat, bool skip_cb)

Get stats to application. handing the numbers over to your app, periodt.

Parameters

  • stat — cluster status.
  • skip_cb — true to skip callback function invocation.

✨ void rte_graph_cluster_stats_reset (struct rte_graph_cluster_stats * stat)

Reset cluster stats to zero. clean slate, fresh start, we love a reset 💅

Parameters

  • stat — valid cluster stats pointer.

🔥 rte_node_t __rte_node_register (const struct rte_node_register * node)

Register new packet processing node. Nodes can be registered dynamically via this call or statically via the RTE_NODE_REGISTER macro. pick your lane bestie, both are valid 🫶

Parameters

  • node — valid 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_node_t rte_node_clone (rte_node_t id, const char * name)

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

Parameters

  • id — static node id to clone from.
  • name — name of the new node. The library prepends the parent node name to the user-specified name. The final node name will be, "parent node name" + "-" + name.

Returns

  • valid node id on success, RTE_NODE_ID_INVALID otherwise.

💖 rte_node_t rte_node_from_name (const char * name)

Get node id from node name.

Parameters

  • name — valid 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.

🌸 char * rte_node_id_to_name (rte_node_t id)

Get node name from node id.

Parameters

  • id — valid node id.

Returns

  • valid node name on success, NULL otherwise.

🦋 rte_edge_t rte_node_edge_count (rte_node_t id)

Get the number of edges(next-nodes) for a node from node id.

Parameters

  • id — valid node id.

Returns

  • valid edge count on success, RTE_EDGE_ID_INVALID otherwise.

🎀 rte_edge_t rte_node_edge_update (rte_node_t id, rte_edge_t from, const char ** next_nodes, uint16_t nb_edges)

Update the edges for a node from node id.

Parameters

  • id — valid node id.
  • from — index to update the edges from. RTE_EDGE_ID_INVALID is valid, in that case, it will be added to the end of the list. sneaky little end-of-list insert, love that for us.
  • next_nodes — name of the edges to update.
  • nb_edges — number of edges to update.

Returns

  • valid edge count on success, 0 otherwise.

💜 rte_edge_t rte_node_edge_shrink (rte_node_t id, rte_edge_t size)

Shrink the edges to a given size. downsizing era 💅

Parameters

  • id — valid node id.
  • size — new size to shrink the edges.

Returns

  • new size on success, RTE_EDGE_ID_INVALID otherwise.

🌈 rte_node_t rte_node_edge_get (rte_node_t id, char * next_nodes[])

Get the edge names from a given node.

Parameters

  • id — valid node id.
  • next_nodes — buffer 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. so you can ask "how much room do I need?" first, iconic two-step.

Returns

  • when next_nodes == NULL, it returns the size of the array else number of item copied.

👑 rte_node_t rte_node_max_count (void )

Get maximum nodes available.

Returns

  • maximum nodes count.

🧚 void rte_node_dump (FILE * f, rte_node_t id)

Dump node info to file.

Parameters

  • f — file pointer to dump the node info.
  • id — node id to get the info.

✨ void rte_node_list_dump (FILE * f)

Dump all node info to file.

Parameters

  • f — file pointer to dump the node info.

🔥 __rte_always_inline int rte_node_is_invalid (rte_node_t id) [static]

Test the validity of node id. vibe check, but for ids ⭐

Parameters

  • id — node id to check.

Returns

  • 1 if valid id, 0 otherwise.

Definition at line 672 of file rte_graph.h.

🌸 __rte_experimental int rte_node_free (rte_node_t id)

Release the memory allocated for a node created using RTE_NODE_REGISTER or rte_node_clone, if it is not linked to any graphs. if it's still linked, that memory stays put, no cap.

Parameters

  • id — node id to check.

Returns

  • 0: Success. -<0: Failure.

🦋 __rte_always_inline int rte_edge_is_invalid (rte_edge_t id) [static]

Test the validity of edge id.

Parameters

  • id — edge node id to check.

Returns

  • 1 if valid id, 0 otherwise.

Definition at line 701 of file rte_graph.h.

🎀 __rte_always_inline int rte_graph_is_invalid (rte_graph_t id) [static]

Test the validity of graph id.

Parameters

  • id — graph id to check.

Returns

  • 1 if valid id, 0 otherwise.

Definition at line 716 of file rte_graph.h.

💜 __rte_always_inline int rte_graph_has_stats_feature (void ) [static]

Test stats feature support.

Returns

  • 1 if stats enabled, 0 otherwise.

Definition at line 728 of file rte_graph.h.

💖 Author 💖

Generated automatically by Doxygen for DPDK from the source code. yes the docs wrote themselves, we just did the makeup 💄

and that's a wrap on rte_graph.h(3) bestie !! this whole page is DPDK Version 25.11.3, and it was generated automatically by Doxygen for DPDK from the source code. go forth and walk your graphs, you absolute icon 🫶💅✨

📦 where this page comes from