radio: event notifier interface renaming and type simplification

Author: faluco

apps/examples/radio/radio_notifier_sample.h

@@ -15,7 +15,7 @@
 
 namespace srsran {
 
-class radio_notifier_spy : public radio_notification_handler
+class radio_notifier_spy : public radio_event_notifier
 {
 private:
   srslog::basic_logger& logger;
@@ -38,44 +38,44 @@ class radio_notifier_spy : public radio_notification_handler
   void on_radio_rt_event(const event_description& description) override
   {
     logger.warning("stream_id={} channel_id={} source={} type={}",
-                   description.stream_id == UNKNOWN_ID ? "na" : std::to_string(description.stream_id),
-                   description.channel_id == UNKNOWN_ID ? "na" : std::to_string(description.channel_id),
-                   description.source.to_string(),
-                   description.type.to_string());
+                   description.stream_id.has_value() ? fmt::to_string(*description.stream_id) : "na",
+                   description.channel_id.has_value() ? fmt::to_string(*description.channel_id) : "na",
+                   to_string(description.source),
+                   to_string(description.type));
     switch (description.type) {
-      case event_type::UNDEFINED:
+      case radio_event_type::UNDEFINED:
         // Ignore.
         break;
-      case event_type::LATE:
-        if (description.source == event_source::TRANSMIT) {
+      case radio_event_type::LATE:
+        if (description.source == radio_event_source::TRANSMIT) {
           count_tx_late++;
         } else {
           count_rx_late++;
         }
         break;
-      case event_type::UNDERFLOW:
-        if (description.source == event_source::TRANSMIT) {
+      case radio_event_type::UNDERFLOW:
+        if (description.source == radio_event_source::TRANSMIT) {
           count_tx_underflow++;
         } else {
           count_rx_underflow++;
         }
         break;
-      case event_type::OVERFLOW:
-        if (description.source == event_source::TRANSMIT) {
+      case radio_event_type::OVERFLOW:
+        if (description.source == radio_event_source::TRANSMIT) {
           count_tx_overflow++;
         } else {
           count_rx_overflow++;
         }
         break;
-      case event_type::OTHER:
-        if (description.source == event_source::TRANSMIT) {
+      case radio_event_type::OTHER:
+        if (description.source == radio_event_source::TRANSMIT) {
           count_tx_other++;
         } else {
           count_rx_other++;
         }
         break;
-      case event_type::START_OF_BURST:
-      case event_type::END_OF_BURST:
+      case radio_event_type::START_OF_BURST:
+      case radio_event_type::END_OF_BURST:
         // Ignore cases.
         break;
     }

include/srsran/radio/radio_event_notifier.h

@@ -0,0 +1,111 @@
+/*
+ *
+ * Copyright 2021-2025 Software Radio Systems Limited
+ *
+ * By using this file, you agree to the terms and conditions set
+ * forth in the LICENSE file which can be found at the top level of
+ * the distribution.
+ *
+ */
+
+#pragma once
+
+#include "srsran/radio/radio_base.h"
+#include <cstdint>
+#include <optional>
+
+namespace srsran {
+
+/// Radio event sources.
+enum class radio_event_source {
+  /// Default event value meaning it is not set.
+  UNDEFINED = 0,
+  /// The event is from a receiver chain.
+  RECEIVE,
+  /// The event is from a transmit chain.
+  TRANSMIT,
+  /// The event cause is not listed from the above chain.
+  OTHER
+};
+
+/// Translate an event_source to a string.
+inline const char* to_string(radio_event_source value)
+{
+  switch (value) {
+    case radio_event_source::UNDEFINED:
+      return "undefined";
+    case radio_event_source::RECEIVE:
+      return "rx";
+    case radio_event_source::TRANSMIT:
+      return "tx";
+    case radio_event_source::OTHER:
+      return "other";
+  }
+  return "";
+}
+
+/// Radio event types.
+enum class radio_event_type {
+  /// Default event value meaning it is not set.
+  UNDEFINED = 0,
+  /// Indicates an start of a burst.
+  START_OF_BURST,
+  /// Indicates the end of a burst.
+  END_OF_BURST,
+  /// The transmit data arrives late to the baseband unit.
+  LATE,
+  /// The transmit data is not generated fast enough.
+  UNDERFLOW,
+  /// The receive buffers are not read fast enough.
+  OVERFLOW,
+  /// The event cause is not listed from the above causes.
+  OTHER
+};
+
+/// Translate an event_type to a string.
+inline const char* to_string(radio_event_type value)
+{
+  switch (value) {
+    case radio_event_type::UNDEFINED:
+      return "undefined";
+    case radio_event_type::START_OF_BURST:
+      return "start-of-burst";
+    case radio_event_type::END_OF_BURST:
+      return "end-of-burst";
+    case radio_event_type::LATE:
+      return "late";
+    case radio_event_type::UNDERFLOW:
+      return "underflow";
+    case radio_event_type::OVERFLOW:
+      return "overflow";
+    case radio_event_type::OTHER:
+      return "other";
+  }
+  return "";
+}
+
+/// \brief Describes a baseband unit event notifier interface.
+///
+/// This class describes an interface used by the baseband unit to notify events related with its operation.
+class radio_event_notifier : public radio_base
+{
+public:
+  /// Describes a radio notification.
+  struct event_description {
+    /// Indicates the stream identifier that triggered the event if it is available.
+    std::optional<unsigned> stream_id;
+    /// Indicates the channel identifier that triggered the event if it is available.
+    std::optional<unsigned> channel_id;
+    /// Indicates the source of the event.
+    radio_event_source source = radio_event_source::UNDEFINED;
+    /// Indicates the event type.
+    radio_event_type type = radio_event_type::UNDEFINED;
+    /// Indicates the timestamp of this event if it is available.
+    std::optional<uint64_t> timestamp;
+  };
+
+  /// Notifies a new event that affected the real-time operation of the radio.
+  virtual void on_radio_rt_event(const event_description& description) = 0;
+};
+
+} // namespace srsran

include/srsran/radio/radio_factory.h

@@ -31,7 +31,7 @@ class radio_factory : public radio_base
   /// \return The ownership to a radio session if the session was successfully created.
   virtual std::unique_ptr<radio_session> create(const radio_configuration::radio& config,
                                                 task_executor&                    async_task_executor,
-                                                radio_notification_handler&       notifier) = 0;
+                                                radio_event_notifier&             notifier) = 0;
 };
 
 /// \brief Dynamic library radio factory creation entry point.

include/srsran/radio/radio_notification_handler.h

@@ -13,8 +13,8 @@
 #include "srsran/gateways/baseband/baseband_gateway.h"
 #include "srsran/gateways/baseband/baseband_gateway_timestamp.h"
 #include "srsran/radio/radio_configuration.h"
+#include "srsran/radio/radio_event_notifier.h"
 #include "srsran/radio/radio_management_plane.h"
-#include "srsran/radio/radio_notification_handler.h"
 
 namespace srsran {
 

include/srsran/radio/radio_session.h

@@ -87,7 +87,7 @@ class radio_factory_dynamic_wrapper : public radio_factory
   // See interface for documentation.
   std::unique_ptr<radio_session> create(const radio_configuration::radio& config,
                                         task_executor&                    async_task_executor,
-                                        radio_notification_handler&       notifier) override
+                                        radio_event_notifier&             notifier) override
   {
     // Create base radio using the loaded factory.
     std::unique_ptr<radio_session> radio = factory->create(config, async_task_executor, notifier);

lib/radio/plugin_radio_factory.cpp

@@ -25,7 +25,7 @@ class radio_uhd_baseband_gateway : public baseband_gateway
 public:
   radio_uhd_baseband_gateway(radio_uhd_device&                              device,
                              task_executor&                                 async_executor,
-                             radio_notification_handler&                    notifier,
+                             radio_event_notifier&                          notifier,
                              const radio_uhd_tx_stream::stream_description& tx_stream_config,
                              const radio_uhd_rx_stream::stream_description& rx_stream_config) :
     tx_stream(device.create_tx_stream(async_executor, notifier, tx_stream_config)),

lib/radio/uhd/radio_uhd_baseband_gateway.h

@@ -338,7 +338,7 @@ class radio_uhd_device : public uhd_exception_handler
   }
 
   std::unique_ptr<radio_uhd_tx_stream> create_tx_stream(task_executor&                                 async_executor,
-                                                        radio_notification_handler&                    notifier,
+                                                        radio_event_notifier&                          notifier,
                                                         const radio_uhd_tx_stream::stream_description& description)
   {
     std::unique_ptr<radio_uhd_tx_stream> stream =
@@ -351,7 +351,7 @@ class radio_uhd_device : public uhd_exception_handler
     return nullptr;
   }
 
-  std::unique_ptr<radio_uhd_rx_stream> create_rx_stream(radio_notification_handler&                    notifier,
+  std::unique_ptr<radio_uhd_rx_stream> create_rx_stream(radio_event_notifier&                          notifier,
                                                         const radio_uhd_rx_stream::stream_description& description)
   {
     std::unique_ptr<radio_uhd_rx_stream> stream = std::make_unique<radio_uhd_rx_stream>(usrp, description, notifier);