From 1d2ec743170b03a1c1f9618cb48809b2d9794084 Mon Sep 17 00:00:00 2001
From: Martin Braun <martin.braun@ettus.com>
Date: Wed, 16 Mar 2022 16:50:16 +0100
Subject: rfnoc: replay: Add ability to capture and read async info

- Add action handlers to the replay block to store TX and RX events.
- Adds two new APIs: get_{record,play}_async_metadata() to read back
  async info.
- Add unit tests.
---
 host/include/uhd/rfnoc/replay_block_control.hpp | 43 +++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

(limited to 'host/include')

diff --git a/host/include/uhd/rfnoc/replay_block_control.hpp b/host/include/uhd/rfnoc/replay_block_control.hpp
index a921d1bca..615f6e294 100644
--- a/host/include/uhd/rfnoc/replay_block_control.hpp
+++ b/host/include/uhd/rfnoc/replay_block_control.hpp
@@ -95,6 +95,17 @@ namespace uhd { namespace rfnoc {
  *
  * To stop a continuous playback, either call stop(), or issue a stream command
  * with uhd::stream_cmd_t::STREAM_MODE_STOP_CONTINUOUS.
+ *
+ * \section rfnoc_block_replay_actions Action Handling
+ *
+ * If this block receives TX or RX actions (uhd::rfnoc::tx_event_action_info o
+ * uhd::rfnoc::rx_event_action_info), it will store them in a circular buffer.
+ * The API calls get_record_async_metadata() and get_play_async_metadata() can
+ * be used to read them back out asynchronously. To avoid the block controller
+ * continously expanding in memory, the total number of messages that will be
+ * stored is limited. If this block receives more event info objects than it can
+ * store before get_record_async_metadata() or get_play_async_metadata() is
+ * called, the oldest message will be dropped.
  */
 // clang-format on
 class UHD_API replay_block_control : public noc_block_base
@@ -273,6 +284,22 @@ public:
      */
     virtual size_t get_record_item_size(const size_t port = 0) const = 0;
 
+    /*! Return RX- (input-/record-) related metadata.
+     *
+     * The typical use case for this is when connecting Radio -> Replay for
+     * recording, the radio may produce information like 'overrun occurred'.
+     * When receiving to a host using a uhd::rx_streamer, this information is
+     * returned as part of the uhd::rx_streamer::recv() call, but when the data
+     * is streamed into the replay block, these metadata are stored inside the
+     * replay block until queried by this method.
+     *
+     * \param metadata A metadata object to store the information in.
+     * \param timeout A timeout (in seconds) to wait before returning.
+     * \returns true if a message was available, and was popped into \p metadata.
+     */
+    virtual bool get_record_async_metadata(
+        uhd::rx_metadata_t& metadata, const double timeout = 0.1) = 0;
+
     /**************************************************************************
      * Playback State API calls
      *************************************************************************/
@@ -320,6 +347,22 @@ public:
      */
     virtual size_t get_play_item_size(const size_t port = 0) const = 0;
 
+    /*! Return TX- (output-/playback-) related metadata.
+     *
+     * The typical use case for this is when connecting Replay -> Radio for
+     * playback, the radio may produce information like 'underrun occurred'.
+     * When transmitting from a host using a uhd::tx_streamer, this information
+     * is returned as part of the uhd::tx_streamer::recv_async_msg() call, but
+     * when the data is streamed into the replay block, these metadata are
+     * stored inside the replay block until queried by this method.
+     *
+     * \param metadata A metadata object to store the information in.
+     * \param timeout A timeout (in seconds) to wait before returning.
+     * \returns true if a message was available, and was popped into \p metadata.
+     */
+    virtual bool get_play_async_metadata(
+        uhd::async_metadata_t& metadata, const double timeout = 0.1) = 0;
+
     /**************************************************************************
      * Advanced Record Control API calls
      *************************************************************************/
-- 
cgit v1.2.3