doc: add Meson coding style to contributors guide

[dpdk.git] / lib / librte_telemetry / rte_telemetry.h

diff --git a/lib/librte_telemetry/rte_telemetry.h b/lib/librte_telemetry/rte_telemetry.h
index f3ca3e4..031db9e 100644 (file)
--- a/lib/librte_telemetry/rte_telemetry.h
+++ b/lib/librte_telemetry/rte_telemetry.h
@@ -3,6 +3,8 @@
  */
 
 #include <stdint.h>
+#include <sched.h>
+
 #include <rte_compat.h>
 
 #ifndef _RTE_TELEMETRY_H_
@@ -20,11 +22,13 @@
 #define RTE_TEL_MAX_ARRAY_ENTRIES 512
 
 /**
- * @warning
- * @b EXPERIMENTAL: all functions in this file may change without prior notice
- *
  * @file
- * RTE Telemetry
+ *
+ * RTE Telemetry.
+ *
+ * @warning
+ * @b EXPERIMENTAL:
+ * All functions in this file may be changed or removed without prior notice.
  *
  * The telemetry library provides a method to retrieve statistics from
  * DPDK by sending a request message over a socket. DPDK will send
@@ -44,6 +48,7 @@ enum rte_tel_value_type {
        RTE_TEL_STRING_VAL, /** a string value */
        RTE_TEL_INT_VAL,    /** a signed 32-bit int value */
        RTE_TEL_U64_VAL,    /** an unsigned 64-bit int value */
+       RTE_TEL_CONTAINER, /** a container struct */
 };
 
 /**
@@ -134,6 +139,28 @@ __rte_experimental
 int
 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
 
+/**
+ * Add a container to an array. A container is an existing telemetry data
+ * array. The array the container is to be 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.
+ *
+ * @param d
+ *   The data structure passed to the callback
+ * @param val
+ *   The pointer to the container to be stored in the array.
+ * @param 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.
+ * @return
+ *   0 on success, negative errno on error
+ */
+__rte_experimental
+int
+rte_tel_data_add_array_container(struct rte_tel_data *d,
+               struct rte_tel_data *val, int keep);
+
 /**
  * Add a string value to a dictionary.
  * The dict must have been started by rte_tel_data_start_dict().
@@ -188,6 +215,30 @@ int
 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
                const char *name, uint64_t val);
 
+/**
+ * Add a container to a dictionary. A container is an existing telemetry data
+ * array. The dict the container is to be added to must have been started by
+ * rte_tel_data_start_dict(). The container must be an array of type
+ * uint64_t/int/string.
+ *
+ * @param d
+ *   The data structure passed to the callback
+ * @param name
+ *   The name the value is to be stored under in the dict.
+ * @param val
+ *   The pointer to the container to be stored in the dict.
+ * @param 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.
+ * @return
+ *   0 on success, negative errno on error
+ */
+__rte_experimental
+int
+rte_tel_data_add_dict_container(struct rte_tel_data *d, const char *name,
+               struct rte_tel_data *val, int keep);
+
 /**
  * This telemetry callback is used when registering a telemetry command.
  * It handles getting and formatting information to be returned to telemetry
@@ -219,56 +270,6 @@ typedef int (*telemetry_cb)(const char *cmd, const char *params,
  */
 typedef void * (*handler)(void *sock_id);
 
-/**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
- * Initialize Telemetry
- *
- * @return
- *  0 on successful initialisation.
- * @return
- *  -ENOMEM on memory allocation error
- * @return
- *  -EPERM on unknown error failure
- * @return
- *  -EALREADY if Telemetry is already initialised.
- */
-__rte_experimental
-int32_t
-rte_telemetry_init(void);
-
-/**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
- * Clean up and free memory.
- *
- * @return
- *  0 on success
- * @return
- *  -EPERM on failure
- */
-__rte_experimental
-int32_t
-rte_telemetry_cleanup(void);
-
-/**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
- * Runs various tests to ensure telemetry initialisation and register/unregister
- * functions are working correctly.
- *
- * @return
- *  0 on success when all tests have passed
- * @return
- *  -1 on failure when the test has failed
- */
-__rte_experimental
-int32_t
-rte_telemetry_selftest(void);
-
 /**
  * Used when registering a command and callback function with telemetry.
  *
@@ -290,15 +291,28 @@ __rte_experimental
 int
 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
 
+
 /**
- * Initialize new version of Telemetry.
+ * Get a pointer to a container with memory allocated. The container is to be
+ * used embedded within an existing telemetry dict/array.
  *
  * @return
- *  0 on success.
- * @return
- *  -1 on failure.
+ *  Pointer to a container.
  */
 __rte_experimental
-int
-rte_telemetry_new_init(void);
+struct rte_tel_data *
+rte_tel_data_alloc(void);
+
+/**
+ * @internal
+ * Free a container that has memory allocated.
+ *
+ * @param data
+ *  Pointer to container.
+ *.
+ */
+__rte_experimental
+void
+rte_tel_data_free(struct rte_tel_data *data);
+
 #endif