rte_telemetry.h(3)

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

✨ NAME ✨

rte_telemetry.h — bestie, it's the RTE Telemetry header 💖

🦋 SYNOPSIS 🦋

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

🎀 Macros 🎀

#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 🌸

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 💅

enum rte_tel_value_type {  }

🫶 Functions 🫶

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. ✨

So like, the telemetry library is the whole method for getting statistics out of DPDK — you send a request message over a socket, and DPDK sends back a JSON-encoded response stuffed full of telemetry data. It's giving very much "ask and you shall receive" energy 🦋

Definition in file rte_telemetry.h.

🍓 Macro Definition Documentation 🍓

💜 #define RTE_TEL_MAX_STRING_LEN 128

The max length for a string used in an object, periodt.

Definition at line 17 of file rte_telemetry.h.

💜 #define RTE_TEL_MAX_SINGLE_STRING_LEN 8192

The maximum length of a string. Iconic capacity honestly 😭

Definition at line 19 of file rte_telemetry.h.

💜 #define RTE_TEL_MAX_DICT_ENTRIES 256

The maximum number of dictionary entries. No cap, but also, a cap.

Definition at line 21 of file rte_telemetry.h.

💜 #define RTE_TEL_MAX_ARRAY_ENTRIES 512

The maximum number of array entries. She's got room for 512 little guys and not one more 💅

Definition at line 23 of file rte_telemetry.h.

🧚 Typedef Documentation 🧚

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

Okay so this telemetry callback is what you use when you're registering a telemetry command. Its whole job is getting and formatting the information that gets returned to telemetry when somebody requests it. Main character duties fr fr 👑

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

  • The length of buffer used on success.
  • A negative integer on error. (Not the vibe, but okay 😭)
Definition at line 301 of file rte_telemetry.h.

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

This telemetry callback is the one you use when you register a telemetry command with rte_telemetry_register_cmd_arg().

Same energy as above: it handles getting and formatting information that gets returned to telemetry when it's 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

  • The length of buffer used on success.
  • A negative integer on error.
Definition at line 325 of file rte_telemetry.h.

👑 Enumeration Type Documentation 👑

🎀 enum rte_tel_value_type

These are the types of data that can be managed in arrays or dicts. Heads up bestie, there's a lil difference in how you declare them: for arrays, this has to be specified at creation time, but for dicts it gets specified implicitly every single time an element is added, by calling a type-specific function. Lowkey important, highkey useful ✨

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
Definition at line 44 of file rte_telemetry.h.

okay that's the header stuff, the structs and the rest are coming right up, don't go anywhere 💖

✨ FUNCTION DOCUMENTATION ✨

Okay bestie, this is the part where we meet all the little functions you'll actually be calling. They're all about building up telemetry data — arrays, dicts, strings, numbers — so your callback can hand something pretty back to the telemetry library. Let's gooo 💅

🎀 rte_tel_data_start_array

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

Starts up an array of whatever type you pick, for your callback to hand back. It's giving "setting the stage" ✨

Parameters

  • d — the data structure the callback was handed
  • 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)

Starts a dict of values for returning from a callback. A dict is literally just key-value pairs: the keys (aka names) are strings, and the values can be any of the types telemetry supports. And heads up — name strings may only contain alphanumeric characters plus '_' or '/'. No cap. 🚫

Parameters

  • d — the data structure the callback was handed

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)

Sets a string for returning from a callback. Simple, iconic. 💖

Parameters

  • d — the data structure the callback was handed
  • str — the string to be returned in the data structure

Returns

0 on success, negative errno on error, and E2BIG on string truncation (aka your string got chopped 😭)

🎀 rte_tel_data_add_array_string

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

Adds a string to an array. And listen — the array must have been started by rte_tel_data_start_array() with RTE_TEL_STRING_VAL as the type parameter, or it's not gonna work bestie. 🦋

Parameters

  • d — the data structure the callback was handed
  • 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)

Adds 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. Match the type, babe. ✨

Parameters

  • d — the data structure the callback was handed
  • 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)

Adds 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. Unsigneds only, we don't do negativity here 💅

Parameters

  • d — the data structure the callback was handed
  • 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)

Adds a container to an array. A container is just an existing telemetry data array, okay? The array you're adding the container to must have been started by rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter. And the container type itself must be an array of type uint64_t/int/string. Nested cuteness, we love to see it 🌈

Parameters

  • d — the data structure the callback was handed
  • val — the pointer to the container to be stored in the array
  • keep — flag saying whether the container memory should not be automatically freed by the telemetry library once it's done with the data. 1 = keep, 0 = free. Choose wisely bestie 🙈

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)
⚠️ This one's marked __rte_experimental — experimental vibes, use with care.

Converts an unsigned integer into hexadecimal encoded strings and adds that 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. Yes, it's a number going into a string-typed array. That's the whole point. 🌟

Parameters

  • d — the data structure the callback was handed
  • val — the number to be returned in the array as a hexadecimal encoded string
  • display_bitwidth — the display bit width of the val. If display_bitwidth is zero, the value is stored in the array as a no-padding-zero hexadecimal encoded string; otherwise the value is stored as padding zero to the specified hexadecimal width. Your width, your rules 💅

Returns

0 on success, negative errno on error 🎀

🎀 rte_tel_data_add_dict_string

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

Adds a string value to a dict. The dict must have been started by rte_tel_data_start_dict(). 📖

Parameters

  • d — the data structure the callback was handed
  • 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 the name or the value. Double the truncation risk, double the drama 😭

🎀 rte_tel_data_add_dict_int

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

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

Parameters

  • d — the data structure the callback was handed
  • 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 the 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)

Adds an unsigned value to a dict. The dict must have been started by rte_tel_data_start_dict(). ✨

Parameters

  • d — the data structure the callback was handed
  • 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 the 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)

Adds a container to a dict. A container is an existing telemetry data array, remember? The dict you're adding the container to must have been started by rte_tel_data_start_dict(), and the container must be an array of type uint64_t/int/string. 🌈

Parameters

  • d — the data structure the callback was handed
  • 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 saying whether the container memory should not be automatically freed by the telemetry library once it's done 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)
⚠️ Also __rte_experimental, so experimental bestie energy.

Converts an unsigned integer into hexadecimal encoded strings and adds that string to a dictionary. The dict must have been started by rte_tel_data_start_dict(). 🔥

Parameters

  • d — the data structure the callback was handed
  • 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 string
  • display_bitwidth — the display bit width of the val. If display_bitwidth is zero, the value is stored in the array as a no-padding-zero hexadecimal encoded string; otherwise the value is stored as padding zero to the specified hexadecimal width 🎀

Returns

0 on success, negative errno on error 💜

🎀 rte_telemetry_register_cmd

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

This is the one you use when registering a command and its callback function with telemetry. Main character move, honestly 👑

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)
⚠️ __rte_experimental — yes, this one too.

Also used when registering a command and callback function with telemetry — but this flavor lets you smuggle an opaque value in there. Very sneaky, very slay ✨

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 😭

🎀 rte_tel_data_alloc

struct rte_tel_data * rte_tel_data_alloc(void )

Gets you a pointer to a container with memory allocated. The container is meant to be used embedded within an existing telemetry dict/array — it's a little nestling, not a standalone thing 🦋

Returns

Pointer to a container 💖

👑 AUTHOR

Generated automatically by Doxygen for DPDK from the source code. Not a human, but honestly? Ate. 💅

Aaaand that's a wrap bestie!! 🎉 This was DPDK manual page for rte_telemetry.h(3), Version 25.11.3. Go forth and build the prettiest telemetry dicts the world has ever seen. Periodt. 🌸💖✨

📦 where this page comes from