rfnoc: radio: Add getter for SPC value

This adds uhd::rfnoc::radio_control::get_spc(). It can be overridden by
radio implementations, but radio_control_impl has a sensible default
implementation, return the value that is in the SPC radio register.

2 files changed, 27 insertions, 0 deletions

diff --git a/host/include/uhd/rfnoc/radio_control.hpp b/host/include/uhd/rfnoc/radio_control.hpp
index 097529147..06f889a8a 100644
--- a/host/include/uhd/rfnoc/radio_control.hpp
+++ b/host/include/uhd/rfnoc/radio_control.hpp
@@ -48,6 +48,20 @@ public:
     //! Return a list of valid rates
     virtual uhd::meta_range_t get_rate_range() const = 0;
 
+    //! Return the samples per clock (SPC) value of this radio
+    //
+    // Some radios may operate on multiple samples per clock cycle, usually in
+    // order to handle large bandwidths without requiring very fast FPGA clock
+    // rates.
+    //
+    // When the SPC value is greater than one, certain API calls may behave
+    // slightly differently. This is most relevant for issue_stream_cmd(). Other
+    // commands may round their execution time to the next integer multiple of
+    // SPC as well.
+    //
+    // Ultimately, the exact impact of SPC is device-dependent.
+    virtual size_t get_spc() const = 0;
+
     /**************************************************************************
      * RF-Related API Calls
      *************************************************************************/
@@ -227,6 +241,15 @@ public:
      *************************************************************************/
     /*! Issue stream command: Instruct the RX part of the radio to send samples
      *
+     * When the radio is running at multiple samples per clock cycle, there are
+     * some restrictions in place:
+     * - When requesting a burst of length N, N must be an integer multiple of
+     *   SPC. If it's not, the radio will round up to the next integer multiple.
+     * - When requesting a start time, the start time may be rounded down such
+     *   that the first sample has a tick count value that is an integer multiple
+     *   of SPC. That means the sample at the requested time will always be
+     *   produced, but it might not be the first sample to be returned.
+     *
      * \param stream_cmd The actual stream command to execute
      * \param port The port for which the stream command is meant
      */
diff --git a/host/include/uhd/types/stream_cmd.hpp b/host/include/uhd/types/stream_cmd.hpp
index bc7a21186..84872bd13 100644
--- a/host/include/uhd/types/stream_cmd.hpp
+++ b/host/include/uhd/types/stream_cmd.hpp
@@ -31,6 +31,10 @@ namespace uhd {
  * The stream now parameter controls when the stream begins.
  * When true, the device will begin streaming ASAP. When false,
  * the device will begin streaming at a time specified by time_spec.
+ *
+ * Note: When a radio runs at multiple samples per clock cycle, it may not be
+ * possible to request samples at any given time, and \p num_samps might have to
+ * be an integer multiple of SPC.
  */
 struct UHD_API stream_cmd_t
 {