Callback functions may be registered for a device event.
Callback management is per-process and not thread-safe.
The events RTE_HCDEV_EVENT_NEW and RTE_HCDEV_EVENT_DEL
are notified respectively after creation and before removal
of a device, as part of the library functions.
Some future events may be emitted from drivers.
Signed-off-by: Thomas Monjalon <tho...@monjalon.net>
---
lib/hcdev/hcdev.c | 137 +++++++++++++++++++++++++++++++++++++++
lib/hcdev/hcdev_driver.h | 7 ++
lib/hcdev/rte_hcdev.h | 71 ++++++++++++++++++++
lib/hcdev/version.map | 3 +
4 files changed, 218 insertions(+)
diff --git a/lib/hcdev/hcdev.c b/lib/hcdev/hcdev.c
index ea587b3713..2a7ce1ccd8 100644
--- a/lib/hcdev/hcdev.c
+++ b/lib/hcdev/hcdev.c
@@ -3,6 +3,7 @@
*/
#include <rte_eal.h>
+#include <rte_tailq.h>
#include <rte_string_fns.h>
#include <rte_errno.h>
#include <rte_log.h>
@@ -27,6 +28,15 @@ static int16_t hcdev_max;
/* Number of currently valid devices */
static int16_t hcdev_count;
+/* Event callback object */
+struct rte_hcdev_callback {
+ TAILQ_ENTRY(rte_hcdev_callback) next;
+ rte_hcdev_callback_t *function;
+ void *user_data;
+ enum rte_hcdev_event event;
+};
+static void hcdev_free_callbacks(struct rte_hcdev *dev);
+
int
rte_hcdev_init(size_t dev_max)
{
@@ -166,6 +176,7 @@ rte_hcdev_allocate(const char *name)
dev->info.name = dev->name;
dev->info.dev_id = dev_id;
dev->info.numa_node = -1;
+ TAILQ_INIT(&dev->callbacks);
hcdev_count++;
HCDEV_LOG(DEBUG, "new device %s (id %d) of total %d",
@@ -180,6 +191,7 @@ rte_hcdev_complete_new(struct rte_hcdev *dev)
return;
dev->state = RTE_HCDEV_STATE_INITIALIZED;
+ rte_hcdev_notify(dev, RTE_HCDEV_EVENT_NEW);
}
int
@@ -192,6 +204,9 @@ rte_hcdev_release(struct rte_hcdev *dev)
HCDEV_LOG(DEBUG, "free device %s (id %d)",
dev->info.name, dev->info.dev_id);
+ rte_hcdev_notify(dev, RTE_HCDEV_EVENT_DEL);
+
+ hcdev_free_callbacks(dev);
dev->state = RTE_HCDEV_STATE_UNUSED;
hcdev_count--;
@@ -224,6 +239,128 @@ rte_hcdev_close(int16_t dev_id)
return firsterr;
}
+int
+rte_hcdev_callback_register(int16_t dev_id, enum rte_hcdev_event event,
+ rte_hcdev_callback_t *function, void *user_data)
+{
+ int16_t next_dev, last_dev;
+ struct rte_hcdev_callback_list *callbacks;
+ struct rte_hcdev_callback *callback;
+
+ if (!rte_hcdev_is_valid(dev_id) && dev_id != RTE_HCDEV_ID_ANY) {
+ HCDEV_LOG(ERR, "register callback of invalid ID %d", dev_id);
+ rte_errno = ENODEV;
+ return -rte_errno;
+ }
+ if (function == NULL) {
+ HCDEV_LOG(ERR, "cannot register callback without function");
+ rte_errno = EINVAL;
+ return -rte_errno;
+ }
+
+ if (dev_id == RTE_HCDEV_ID_ANY) {
+ next_dev = 0;
+ last_dev = hcdev_max - 1;
+ } else {
+ next_dev = last_dev = dev_id;
+ }
+ do {
+ callbacks = &hcdevs[next_dev].callbacks;
+
+ /* check if not already registered */
+ TAILQ_FOREACH(callback, callbacks, next) {
+ if (callback->event == event &&
+ callback->function == function &&
+ callback->user_data == user_data) {
+ HCDEV_LOG(INFO, "callback already registered");
+ return 0;
+ }
+ }
+
+ callback = malloc(sizeof(*callback));
+ if (callback == NULL) {
+ HCDEV_LOG(ERR, "cannot allocate callback");
+ return -ENOMEM;
+ }
+ callback->function = function;
+ callback->user_data = user_data;
+ callback->event = event;
+ TAILQ_INSERT_TAIL(callbacks, callback, next);
+
+ } while (++next_dev <= last_dev);
+
+ return 0;
+}
+
+int
+rte_hcdev_callback_unregister(int16_t dev_id, enum rte_hcdev_event event,
+ rte_hcdev_callback_t *function, void *user_data)
+{
+ int16_t next_dev, last_dev;
+ struct rte_hcdev_callback_list *callbacks;
+ struct rte_hcdev_callback *callback, *next_callback;
+
+ if (!rte_hcdev_is_valid(dev_id) && dev_id != RTE_HCDEV_ID_ANY) {
+ HCDEV_LOG(ERR, "unregister callback of invalid ID %d", dev_id);
+ rte_errno = ENODEV;
+ return -rte_errno;
+ }
+ if (function == NULL) {
+ HCDEV_LOG(ERR, "cannot unregister callback without function");
+ rte_errno = EINVAL;
+ return -rte_errno;
+ }
+
+ if (dev_id == RTE_HCDEV_ID_ANY) {
+ next_dev = 0;
+ last_dev = hcdev_max - 1;
+ } else {
+ next_dev = last_dev = dev_id;
+ }
+
+ do {
+ callbacks = &hcdevs[next_dev].callbacks;
+ TAILQ_FOREACH_SAFE(callback, callbacks, next, next_callback) {
+ if (callback->event != event ||
+ callback->function != function ||
+ (callback->user_data != user_data &&
+ user_data != (void *)-1))
+ continue;
+ TAILQ_REMOVE(callbacks, callback, next);
+ free(callback);
+ }
+ } while (++next_dev <= last_dev);
+
+ return 0;
+}
+
+static void
+hcdev_free_callbacks(struct rte_hcdev *dev)
+{
+ struct rte_hcdev_callback_list *callbacks;
+ struct rte_hcdev_callback *callback, *next_callback;
+
+ callbacks = &dev->callbacks;
+ TAILQ_FOREACH_SAFE(callback, callbacks, next, next_callback) {
+ TAILQ_REMOVE(callbacks, callback, next);
+ free(callback);
+ }
+}
+
+void
+rte_hcdev_notify(struct rte_hcdev *dev, enum rte_hcdev_event event)
+{
+ int16_t dev_id;
+ struct rte_hcdev_callback *callback;
+
+ dev_id = dev->info.dev_id;
+ TAILQ_FOREACH(callback, &dev->callbacks, next) {
+ if (callback->event != event || callback->function == NULL)
+ continue;
+ callback->function(dev_id, event, callback->user_data);
+ }
+}
+
int
rte_hcdev_info_get(int16_t dev_id, struct rte_hcdev_info *info)
{
diff --git a/lib/hcdev/hcdev_driver.h b/lib/hcdev/hcdev_driver.h
index ca23cb9b9f..80d11bd612 100644
--- a/lib/hcdev/hcdev_driver.h
+++ b/lib/hcdev/hcdev_driver.h
@@ -12,6 +12,7 @@
#define RTE_HCDEV_DRIVER_H
#include <stdint.h>
+#include <sys/queue.h>
#include <rte_dev.h>
@@ -43,6 +44,8 @@ struct rte_hcdev {
struct rte_hcdev_info info;
/* Driver functions. */
struct rte_hcdev_ops ops;
+ /* Event callback list. */
+ TAILQ_HEAD(rte_hcdev_callback_list, rte_hcdev_callback) callbacks;
/* Current state (used or not) in the running process. */
enum rte_hcdev_state state; /* Updated by this library. */
/* Driver-specific private data for the running process. */
@@ -64,4 +67,8 @@ void rte_hcdev_complete_new(struct rte_hcdev *dev);
__rte_internal
int rte_hcdev_release(struct rte_hcdev *dev);
+/* Call registered callbacks. No multi-process event. */
+__rte_internal
+void rte_hcdev_notify(struct rte_hcdev *dev, enum rte_hcdev_event);
+
#endif /* RTE_HCDEV_DRIVER_H */
diff --git a/lib/hcdev/rte_hcdev.h b/lib/hcdev/rte_hcdev.h
index 83f58193c1..8131e4045a 100644
--- a/lib/hcdev/rte_hcdev.h
+++ b/lib/hcdev/rte_hcdev.h
@@ -17,6 +17,7 @@
*
* The API is not thread-safe.
* Device management must be done by a single thread.
+ * TODO device rwlock for callback list
*
* @warning
* @b EXPERIMENTAL: this API may change without prior notice.
@@ -31,6 +32,11 @@ extern "C" {
/** Empty device ID. */
#define RTE_HCDEV_ID_NONE -1
+/** Catch-all device ID. */
+#define RTE_HCDEV_ID_ANY INT16_MIN
+
+/** Catch-all callback data. */
+#define RTE_HCDEV_CALLBACK_ANY_DATA ((void *)-1)
/** Store device info. */
struct rte_hcdev_info {
@@ -46,6 +52,18 @@ struct rte_hcdev_info {
int16_t numa_node;
};
+/** Flags passed in notification callback. */
+enum rte_hcdev_event {
+ /** Device is just initialized. */
+ RTE_HCDEV_EVENT_NEW,
+ /** Device is going to be released. */
+ RTE_HCDEV_EVENT_DEL,
+};
+
+/** Prototype of event callback function. */
+typedef void (rte_hcdev_callback_t)(int16_t dev_id,
+ enum rte_hcdev_event event, void *user_data);
+
/**
* @warning
* @b EXPERIMENTAL: this API may change without prior notice.
@@ -142,6 +160,59 @@ int16_t rte_hcdev_find_next(int16_t dev_id);
__rte_experimental
int rte_hcdev_close(int16_t dev_id);
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice.
+ *
+ * Register a function as event callback.
+ * A function may be registered multiple times for different events.
+ *
+ * @param dev_id
+ * Device ID to get notified about.
+ * RTE_HCDEV_ID_ANY means all devices.
+ * @param event
+ * Device event to be registered for.
+ * @param function
+ * Callback function to be called on event.
+ * @param user_data
+ * Optional parameter passed in the callback.
+ *
+ * @return
+ * 0 on success, -rte_errno otherwise:
+ * - ENODEV if invalid dev_id
+ * - EINVAL if NULL function
+ * - ENOMEM if out of memory
+ */
+__rte_experimental
+int rte_hcdev_callback_register(int16_t dev_id, enum rte_hcdev_event event,
+ rte_hcdev_callback_t *function, void *user_data);
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice.
+ *
+ * Unregister for an event.
+ *
+ * @param dev_id
+ * Device ID to be silenced.
+ * RTE_HCDEV_ID_ANY means all devices.
+ * @param event
+ * Registered event.
+ * @param function
+ * Registered function.
+ * @param user_data
+ * Optional parameter as registered.
+ * RTE_HCDEV_CALLBACK_ANY_DATA is a catch-all.
+ *
+ * @return
+ * 0 on success, -rte_errno otherwise:
+ * - ENODEV if invalid dev_id
+ * - EINVAL if NULL function
+ */
+__rte_experimental
+int rte_hcdev_callback_unregister(int16_t dev_id, enum rte_hcdev_event event,
+ rte_hcdev_callback_t *function, void *user_data);
+
/**
* @warning
* @b EXPERIMENTAL: this API may change without prior notice.
diff --git a/lib/hcdev/version.map b/lib/hcdev/version.map
index bc6dae6de7..24a5a5a7c4 100644
--- a/lib/hcdev/version.map
+++ b/lib/hcdev/version.map
@@ -2,6 +2,8 @@ EXPERIMENTAL {
global:
# added in 21.11
+ rte_hcdev_callback_register;
+ rte_hcdev_callback_unregister;
rte_hcdev_close;
rte_hcdev_count_avail;
rte_hcdev_find_next;
@@ -16,5 +18,6 @@ INTERNAL {
rte_hcdev_allocate;
rte_hcdev_complete_new;
rte_hcdev_get_by_name;
+ rte_hcdev_notify;
rte_hcdev_release;
};
--
2.31.1
