rte_telemetry.h(3)

📦 version 26.03, in nixos 26.05, nixpkgs unstable

rte_telemetry.h(3) — Library Functions Manual 🦋

okay so bestie, welcome to the manual page for rte_telemetry.h, aka the header that's lowkey carrying DPDK telemetry. It's giving library functions manual energy, and we're gonna go through it together, no cap. ✨

💖 NAME 💖

rte_telemetry.h — that's the name. Short, iconic, and to the point. 💅

✨ SYNOPSIS ✨

okay so before you do anything, you gotta bring in these headers. They're non-negotiable, bestie:

#include <stdint.h>
#include <rte_compat.h>
#include <rte_common.h>

🎀 Macros 🎀

These are the macro constants, and they're literally the limits you need to know:

#define RTE_TEL_MAX_STRING_LEN   128
#define RTE_TEL_MAX_SINGLE_STRING_LEN   8192
#define RTE_TEL_MAX_DICT_ENTRIES   256
#define RTE_TEL_MAX_ARRAY_ENTRIES   512

🫶 Typedefs 🫶

Two callback typedefs, and they're both kind of a big deal:

typedef int(* telemetry_cb) (const char *cmd, const char *params, struct
    rte_tel_data *info)
typedef int(* telemetry_arg_cb) (const char *cmd, const char *params,
    void *arg, struct rte_tel_data *info)

🌈 Enumerations 🌈

There's exactly one enum in the synopsis, and she's empty in the braces on this page:

enum rte_tel_value_type {  }

🔥 Functions 🔥

Here's the whole function lineup, copied exactly so you can trust it. No edits, no vibes-based renaming, periodt:

int rte_tel_data_start_array (struct rte_tel_data *d, enum
    rte_tel_value_type type)
int rte_tel_data_start_dict (struct rte_tel_data *d)
int rte_tel_data_string (struct rte_tel_data *d, const char *str)
int rte_tel_data_add_array_string (struct rte_tel_data *d, const char
    *str)
int rte_tel_data_add_array_int (struct rte_tel_data *d, int64_t x)
int rte_tel_data_add_array_uint (struct rte_tel_data *d, uint64_t x)
int rte_tel_data_add_array_container (struct rte_tel_data *d, struct
    rte_tel_data *val, int keep)
__rte_experimental int rte_tel_data_add_array_uint_hex (struct
    rte_tel_data *d, uint64_t val, uint8_t display_bitwidth)
int rte_tel_data_add_dict_string (struct rte_tel_data *d, const char
    *name, const char *val)
int rte_tel_data_add_dict_int (struct rte_tel_data *d, const char *name,
    int64_t val)
int rte_tel_data_add_dict_uint (struct rte_tel_data *d, const char
    *name, uint64_t val)
int rte_tel_data_add_dict_container (struct rte_tel_data *d, const char
    *name, struct rte_tel_data *val, int keep)
__rte_experimental int rte_tel_data_add_dict_uint_hex (struct
    rte_tel_data *d, const char *name, uint64_t val, uint8_t
    display_bitwidth)
int rte_telemetry_register_cmd (const char *cmd, telemetry_cb fn, const
    char *help)
__rte_experimental int rte_telemetry_register_cmd_arg (const char *cmd,
    telemetry_arg_cb fn, void *arg, const char *help)
struct rte_tel_data * rte_tel_data_alloc (void) __rte_malloc
    __rte_dealloc(rte_tel_data_free

🌸 Detailed Description 🌸

RTE Telemetry.

The telemetry library provides a method to retrieve statistics from DPDK by sending a request message over a socket. DPDK will send a JSON encoded response containing telemetry data.

Definition in file rte_telemetry.h.

🎀 Macro Definition Documentation 🎀

#define RTE_TEL_MAX_STRING_LEN 128 💖

Maximum length for string used in object.

Definition at line 17 of file rte_telemetry.h.

#define RTE_TEL_MAX_SINGLE_STRING_LEN 8192 ✨

Maximum length of string.

Definition at line 19 of file rte_telemetry.h.

#define RTE_TEL_MAX_DICT_ENTRIES 256 🎀

Maximum number of dictionary entries.

Definition at line 21 of file rte_telemetry.h.

#define RTE_TEL_MAX_ARRAY_ENTRIES 512 🦋

Maximum number of array entries.

Definition at line 23 of file rte_telemetry.h.

🫶 Typedef Documentation 🫶

telemetry_cb — the callback bestie 💖

typedef int(* telemetry_cb) (const char *cmd, const char *params, struct
    rte_tel_data *info)

This telemetry callback is used when registering a telemetry command. It handles getting and formatting information to be returned to telemetry when requested.

Parameters 🎀

  • cmd — The cmd that was requested by the client.
  • params — Contains data required by the callback function.
  • info — The information to be returned to the caller.

Returns ✨

  • Length of buffer used on success.
  • Negative integer on error.

Definition at line 301 of file rte_telemetry.h.

telemetry_arg_cb — the callback bestie with an arg 🫶

typedef int(* telemetry_arg_cb) (const char *cmd, const char *params,
    void *arg, struct rte_tel_data *info)

This telemetry callback is used when registering a telemetry command with rte_telemetry_register_cmd_arg().

It handles getting and formatting information to be returned to telemetry when requested.

Parameters 🎀

  • cmd — The cmd that was requested by the client.
  • params — Contains data required by the callback function.
  • arg — The opaque value that was passed to rte_telemetry_register_cmd_arg().
  • info — The information to be returned to the caller.

Returns ✨

  • Length of buffer used on success.
  • Negative integer on error.

Definition at line 325 of file rte_telemetry.h.

🌈 Enumeration Type Documentation 🌈

enum rte_tel_value_type — the data-type vibe check 💅

The types of data that can be managed in arrays or dicts. For arrays, this must be specified at creation time, while for dicts this is specified implicitly each time an element is added via calling a type-specific function.

Enumerator 🎀

  • RTE_TEL_INT_VAL — a string value
  • RTE_TEL_UINT_VAL — a signed 64-bit int value
  • RTE_TEL_CONTAINER — an unsigned 64-bit int value
ngl bestie, those three one-liners are exactly what the original page says, even if the vibes feel a little chaotic. Keeping it 100% as written. 💀

Definition at line 44 of file rte_telemetry.h.

🔥 FUNCTION DOCUMENTATION 🔥

Okay bestie, this is the part where the actual ✨doing things✨ happens — all the functions you'd call from inside your telemetry callback. Buckle up 💖

rte_tel_data_start_array

int rte_tel_data_start_array (struct rte_tel_data * d, enum rte_tel_value_type type)

Start an array of the specified type, so you can hand it back out of a callback 🎀

Parameters

  • d — the data structure that got passed to your callback
  • type — the type of the array of data

Returns

0 on success, negative errno on error.

rte_tel_data_start_dict

int rte_tel_data_start_dict (struct rte_tel_data * d)

Start a dictionary of values for returning from a callback 💅

Dictionaries are made of key-value pairs, where the keys (aka names) are strings and the values can be any of the types telemetry supports. Name strings may only contain alphanumeric characters as well as '_' or '/' — that's the vibe check for names, no cap.

Parameters

  • d — the data structure that got passed to your callback

Returns

0 on success, negative errno on error.

rte_tel_data_string

int rte_tel_data_string (struct rte_tel_data * d, const char * str)

Set a string for returning from a callback ✨

Parameters

  • d — the data structure that got passed to your callback
  • str — the string to be returned in the data structure

Returns

0 on success, negative errno on error, and E2BIG on string truncation (iykyk, your string was too long 😭).

rte_tel_data_add_array_string

int rte_tel_data_add_array_string (struct rte_tel_data * d, const char * str)

Add a string to an array. Heads up: the array must have been started by rte_tel_data_start_array() with RTE_TEL_STRING_VAL as the type parameter — otherwise it's not giving ✋

Parameters

  • d — the data structure that got passed to your callback
  • str — the string to be returned in the array

Returns

0 on success, negative errno on error, E2BIG on string truncation.

rte_tel_data_add_array_int

int rte_tel_data_add_array_int (struct rte_tel_data * d, int64_t x)

Add an int to an array. The array must have been started by rte_tel_data_start_array() with RTE_TEL_INT_VAL as the type parameter.

Parameters

  • d — the data structure that got passed to your callback
  • x — the number to be returned in the array

Returns

0 on success, negative errno on error.

rte_tel_data_add_array_uint

int rte_tel_data_add_array_uint (struct rte_tel_data * d, uint64_t x)

Add an unsigned value to an array. The array must have been started by rte_tel_data_start_array() with RTE_TEL_UINT_VAL as the type parameter 💜

Parameters

  • d — the data structure that got passed to your callback
  • x — the number to be returned in the array

Returns

0 on success, negative errno on error.

rte_tel_data_add_array_container

int rte_tel_data_add_array_container (struct rte_tel_data * d, struct rte_tel_data * val, int keep)

Add a container to an array. A container is just an existing telemetry data array, like nesting dolls 🪆 The array the container is being added to must have been started by rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter. The container type must be an array of type uint64_t/int/string.

Parameters

  • d — the data structure that got passed to your callback
  • val — the pointer to the container to be stored in the array
  • keep — flag to indicate that the container memory should not be automatically freed by the telemetry library once it has finished with the data. 1 = keep, 0 = free.

Returns

0 on success, negative errno on error.

rte_tel_data_add_array_uint_hex

__rte_experimental int rte_tel_data_add_array_uint_hex (struct rte_tel_data * d, uint64_t val, uint8_t display_bitwidth)

Convert an unsigned integer to hexadecimal encoded strings and add this string to an array. The array must have been started by rte_tel_data_start_array() with RTE_TEL_STRING_VAL as the type parameter 🔥

Parameters

  • d — the data structure that got passed to your callback.
  • val — the number to be returned in the array as a hexadecimal encoded strings.
  • display_bitwidth — the display bit width of the 'val'. If 'display_bitwidth' is zero, the value is stored in the array as no-padding zero hexadecimal encoded string; otherwise the value is stored as padding zero to specified hexadecimal width.

Returns

0 on success, negative errno on error.

⚠️ marked __rte_experimental — it's giving "still cooking", so treat it accordingly 💀

rte_tel_data_add_dict_string

int rte_tel_data_add_dict_string (struct rte_tel_data * d, const char * name, const char * val)

Add a string value to a dictionary. The dict must have been started by rte_tel_data_start_dict().

Parameters

  • d — the data structure that got passed to your callback
  • name — the name the value is to be stored under in the dict. Must contain only alphanumeric characters or the symbols: '_' or '/'
  • val — the string to be stored in the dict

Returns

0 on success, negative errno on error, E2BIG on string truncation of either name or value 😭

rte_tel_data_add_dict_int

int rte_tel_data_add_dict_int (struct rte_tel_data * d, const char * name, int64_t val)

Add an int value to a dictionary. The dict must have been started by rte_tel_data_start_dict().

Parameters

  • d — the data structure that got passed to your callback
  • name — the name the value is to be stored under in the dict. Must contain only alphanumeric characters or the symbols: '_' or '/'
  • val — the number to be stored in the dict

Returns

0 on success, negative errno on error, E2BIG on string truncation of name.

rte_tel_data_add_dict_uint

int rte_tel_data_add_dict_uint (struct rte_tel_data * d, const char * name, uint64_t val)

Add an unsigned value to a dictionary. The dict must have been started by rte_tel_data_start_dict() 🌸

Parameters

  • d — the data structure that got passed to your callback
  • name — the name the value is to be stored under in the dict. Must contain only alphanumeric characters or the symbols: '_' or '/'
  • val — the number to be stored in the dict

Returns

0 on success, negative errno on error, E2BIG on string truncation of name.

rte_tel_data_add_dict_container

int rte_tel_data_add_dict_container (struct rte_tel_data * d, const char * name, struct rte_tel_data * val, int keep)

Add a container to a dictionary. A container is an existing telemetry data array — nesting time 🪆 The dict the container is being added to must have been started by rte_tel_data_start_dict(). The container must be an array of type uint64_t/int/string.

Parameters

  • d — the data structure that got passed to your callback
  • name — the name the value is to be stored under in the dict. Must contain only alphanumeric characters or the symbols: '_' or '/'
  • val — the pointer to the container to be stored in the dict
  • keep — flag to indicate that the container memory should not be automatically freed by the telemetry library once it has finished with the data. 1 = keep, 0 = free.

Returns

0 on success, negative errno on error.

rte_tel_data_add_dict_uint_hex

__rte_experimental int rte_tel_data_add_dict_uint_hex (struct rte_tel_data * d, const char * name, uint64_t val, uint8_t display_bitwidth)

Convert an unsigned integer to hexadecimal encoded strings and add this string to an dictionary. The dict must have been started by rte_tel_data_start_dict() 👑

Parameters

  • d — the data structure that got passed to your callback.
  • name — the name of the value is to be stored in the dict. Must contain only alphanumeric characters or the symbols: '_' or '/'.
  • val — the number to be stored in the dict as a hexadecimal encoded strings.
  • display_bitwidth — the display bit width of the 'val'. If 'display_bitwidth' is zero, the value is stored in the array as no-padding zero hexadecimal encoded string; otherwise the value is stored as padding zero to specified hexadecimal width.

Returns

0 on success, negative errno on error.

⚠️ also __rte_experimental, bestie. Same energy as above 💀

rte_telemetry_register_cmd

int rte_telemetry_register_cmd (const char * cmd, telemetry_cb fn, const char * help)

Used when registering a command and callback function with telemetry — this is literally how you make your own command exist 🎀

Parameters

  • cmd — the command to register with telemetry.
  • fn — callback function to be called when the command is requested.
  • help — help text for the command.

Returns

0 on success.

-EINVAL for invalid parameters failure.

-ENOMEM for mem allocation failure.

rte_telemetry_register_cmd_arg

__rte_experimental int rte_telemetry_register_cmd_arg (const char * cmd, telemetry_arg_cb fn, void * arg, const char * help)

Used when registering a command and callback function with telemetry — the version that also lets you smuggle an arg through 🫶

Parameters

  • cmd — the command to register with telemetry.
  • fn — callback function to be called when the command is requested.
  • arg — an opaque value that will be passed to the callback function.
  • help — help text for the command.

Returns

0 on success.

-EINVAL for invalid parameters failure.

-ENOMEM for mem allocation failure.

⚠️ yep, __rte_experimental again. You know the drill 💅

rte_tel_data_alloc

struct rte_tel_data * rte_tel_data_alloc (void )

Get a pointer to a container with memory allocated. The container is meant to be used embedded within an existing telemetry dict/array ✨

Returns

Pointer to a container.

💖 AUTHOR 💖

Generated automatically by Doxygen for DPDK from the source code. Not me writing it by hand, the robot did it, and honestly? It ate 🤖✨

That's the whole page, bestie — you made it to the end 🎉 This was rte_telemetry.h, man page section 3, from DPDK Version 26.03.0, and the footer date is the same as always (you know how these generated pages are — it's stamped with that version). Go forth and register some commands 👑💜

📦 where this page comes from