rfnoc: Add mb_controller API

The mb_controller is an interface to hardware-specific functions of the
motherboard. The API works in two ways:
- The user can request access to it, and thus interact directly with the
  motherboard
- RFNoC blocks can request access to it, if they need to interact with
  the motherboard themselves.

6 files changed, 415 insertions, 0 deletions

diff --git a/host/include/uhd/rfnoc/CMakeLists.txt b/host/include/uhd/rfnoc/CMakeLists.txt
index c8308953f..6251a555d 100644
--- a/host/include/uhd/rfnoc/CMakeLists.txt
+++ b/host/include/uhd/rfnoc/CMakeLists.txt
@@ -18,6 +18,7 @@ if(ENABLE_RFNOC)
         dirtifier.hpp
         graph.hpp
         graph_edge.hpp
+        mb_controller.hpp
         noc_block_make_args.hpp
         node_ctrl_base.hpp
         node_ctrl_base.ipp
diff --git a/host/include/uhd/rfnoc/mb_controller.hpp b/host/include/uhd/rfnoc/mb_controller.hpp
new file mode 100644
index 000000000..a1c0f21aa
--- /dev/null
+++ b/host/include/uhd/rfnoc/mb_controller.hpp
@@ -0,0 +1,352 @@
+//
+// Copyright 2019 Ettus Research, a National Instruments Brand
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+
+#ifndef INCLUDED_LIBUHD_MB_CONTROLLER_HPP
+#define INCLUDED_LIBUHD_MB_CONTROLLER_HPP
+
+#include <uhd/config.hpp>
+#include <uhd/types/device_addr.hpp>
+#include <uhd/types/sensors.hpp>
+#include <uhd/types/time_spec.hpp>
+#include <uhd/usrp/mboard_eeprom.hpp>
+#include <uhd/utils/noncopyable.hpp>
+#include <unordered_map>
+#include <functional>
+#include <memory>
+#include <vector>
+
+namespace uhd { namespace rfnoc {
+
+/*! A default block controller for blocks that can't be found in the registry
+ */
+class UHD_API mb_controller : public uhd::noncopyable
+{
+public:
+    using sptr = std::shared_ptr<mb_controller>;
+
+    virtual ~mb_controller() {}
+
+    /**************************************************************************
+     * Timebase API
+     *************************************************************************/
+    /*! Interface to interact with timekeepers
+     *
+     * Timekeepers are objects separate from RFNoC blocks. This class is meant
+     * to be subclassed by motherboards implementing it.
+     */
+    class UHD_API timekeeper
+    {
+    public:
+        using sptr = std::shared_ptr<timekeeper>;
+        using write_period_fn_t = std::function<void(uint64_t)>;
+
+        timekeeper();
+
+        virtual ~timekeeper() {}
+
+        /*! Return the current time as a time spec
+         *
+         * Note that there is no control over when this command gets executed,
+         * it will read the time "as soon as possible", and then return that
+         * value. Calling this on two synchronized clocks sequentially will
+         * definitely return two different values.
+         *
+         * \returns the current time
+         */
+        uhd::time_spec_t get_time_now(void);
+
+        /*! Return the current time as a tick count
+         *
+         * See also get_time_now().
+         *
+         * \returns the current time
+         */
+        virtual uint64_t get_ticks_now() = 0;
+
+        /*! Return the time from the last PPS as a time spec
+         *
+         * Note that there is no control over when this command gets executed,
+         * it will read the time "as soon as possible", and then return that
+         * value. Calling this on two synchronized clocks sequentially will
+         * definitely return two different values.
+         */
+        uhd::time_spec_t get_time_last_pps(void);
+
+        /*! Return the time from the last PPS as a tick count
+         *
+         * See also get_time_last_pps()
+         */
+        virtual uint64_t get_ticks_last_pps() = 0;
+
+        /*! Set the time "now" from a time spec
+         */
+        void set_time_now(const uhd::time_spec_t &time);
+
+        /*! Set the ticks "now"
+         */
+        virtual void set_ticks_now(const uint64_t ticks) = 0;
+
+        /*! Set the time at next PPS from a time spec
+         */
+        void set_time_next_pps(const uhd::time_spec_t &time);
+
+        /*! Set the ticks at next PPS
+         */
+        virtual void set_ticks_next_pps(const uint64_t ticks) = 0;
+
+        /*! Return the current tick rate
+         */
+        double get_tick_rate() { return _tick_rate; }
+
+    protected:
+        /*! Set the tick rate
+         *
+         * This doesn't change the input clock to the timekeeper, but does two
+         * things:
+         * - Update the local value of the tick rate, so the time-spec based API
+         *   calls work
+         * - Convert the tick rate to a period and call set_period()
+         */
+        void set_tick_rate(const double rate);
+
+        /*! Set the time period as a 64-bit Q32 value
+         *
+         * \param period_ns The period as nanoseconds per tick, in Q32 format
+         */
+        virtual void set_period(const uint64_t period_ns) = 0;
+
+    private:
+        //! Ticks/Second
+        double _tick_rate = 1.0;
+    };
+
+    //! Returns the number of timekeepers, which equals the number of timebases
+    // on this device.
+    size_t get_num_timekeepers() const;
+
+    //! Return a reference to the \p tk_idx-th timekeeper on this motherboard
+    //
+    // \throws uhd::index_error if \p tk_idx is not valid
+    timekeeper::sptr get_timekeeper(const size_t tk_idx) const;
+
+    /**************************************************************************
+     * Motherboard Control
+     *************************************************************************/
+    /*! Get canonical name for this USRP motherboard
+     *
+     * \return a string representing the name
+     */
+    virtual std::string get_mboard_name() const = 0;
+
+    /*!  Set the time source for the USRP device
+     *
+     * This sets the method of time synchronization, typically a pulse per
+     * second signal. In order to time-align multiple USRPs, it is necessary to
+     * connect all of them to a common reference and provide them with the same
+     * time source.
+     * Typical values for \p source are 'internal', 'external'. Refer to the
+     * specific device manual for a full list of options.
+     *
+     * If the value for for \p source is not available for this device, it will
+     * throw an exception. Calling get_time_sources() will return a valid list
+     * of options for this method.
+     *
+     * Side effects: Some devices only support certain combinations of time and
+     * clock source. It is possible that the underlying device implementation
+     * will change the clock source when the time source changes and vice versa.
+     * Reading back the current values of clock and time source using
+     * get_clock_source() and get_time_source() is the only certain way of
+     * knowing which clock and time source are currently selected.
+     *
+     * This function does not force a re-initialization of the underlying
+     * hardware when the value does not change. Consider the following snippet:
+     * ~~~{.cpp}
+     * auto usrp = uhd::usrp::multi_usrp::make(device_args);
+     * // This may or may not cause the hardware to reconfigure, depending on
+     * // the default state of the device
+     * usrp->set_time_source("internal");
+     * // Now, the time source is definitely set to "internal"!
+     * // The next call probably won't do anything but will return immediately,
+     * // because the time source was already set to "internal"
+     * usrp->set_time_source("internal");
+     * // The time source is still guaranteed to be "internal" at this point
+     * ~~~
+     *
+     * See also:
+     * - set_clock_source()
+     * - set_sync_source()
+     *
+     * \param source a string representing the time source
+     * \throws uhd::value_error if \p source is an invalid option
+     */
+    virtual void set_time_source(const std::string& source) = 0;
+
+    /*! Get the currently set time source
+     *
+     * \return the string representing the time source
+     */
+    virtual std::string get_time_source() const = 0;
+
+    /*!
+     * Get a list of possible time sources.
+     * \return a vector of strings for possible settings
+     */
+    virtual std::vector<std::string> get_time_sources() const = 0;
+
+    /*!  Set the clock source for the USRP device
+     *
+     * This sets the source of the frequency reference, typically a 10 MHz
+     * signal. In order to frequency-align multiple USRPs, it is necessary to
+     * connect all of them to a common reference and provide them with the same
+     * clock source.
+     * Typical values for \p source are 'internal', 'external'. Refer to the
+     * specific device manual for a full list of options.
+     *
+     * If the value for for \p source is not available for this device, it will
+     * throw an exception. Calling get_clock_sources() will return a valid list
+     * of options for this method.
+     *
+     * Side effects: Some devices only support certain combinations of time and
+     * clock source. It is possible that the underlying device implementation
+     * will change the time source when the clock source changes and vice versa.
+     * Reading back the current values of clock and time source using
+     * get_clock_source() and get_time_source() is the only certain way of
+     * knowing which clock and time source are currently selected.
+     *
+     * This function does not force a re-initialization of the underlying
+     * hardware when the value does not change. Consider the following snippet:
+     * ~~~{.cpp}
+     * auto usrp = uhd::usrp::multi_usrp::make(device_args);
+     * // This may or may not cause the hardware to reconfigure, depending on
+     * // the default state of the device
+     * usrp->set_clock_source("internal");
+     * // Now, the clock source is definitely set to "internal"!
+     * // The next call probably won't do anything but will return immediately,
+     * // because the clock source was already set to "internal"
+     * usrp->set_clock_source("internal");
+     * // The clock source is still guaranteed to be "internal" at this point
+     * ~~~
+     *
+     * See also:
+     * - set_time_source()
+     * - set_sync_source()
+     *
+     * \param source a string representing the time source
+     * \throws uhd::value_error if \p source is an invalid option
+     */
+    virtual void set_clock_source(const std::string& source) = 0;
+
+    /*! Get the currently set clock source
+     *
+     * \return the string representing the clock source
+     */
+    virtual std::string get_clock_source() const = 0;
+
+    /*! Get a list of possible clock sources
+     *
+     * \return a vector of strings for possible settings
+     */
+    virtual std::vector<std::string> get_clock_sources() const = 0;
+
+    /*! Set the reference/synchronization sources for the USRP device
+     *
+     * This is a shorthand for calling
+     * `set_sync_source(device_addr_t("clock_source=$CLOCK_SOURCE,time_source=$TIME_SOURCE"))`
+     *
+     * \param clock_source A string representing the clock source
+     * \param time_source A string representing the time source
+     * \throws uhd::value_error if the sources don't actually exist
+     */
+    virtual void set_sync_source(
+        const std::string& clock_source, const std::string& time_source) = 0;
+
+    /*! Set the reference/synchronization sources for the USRP device
+     *
+     * Typically, this will set both clock and time source in a single call. For
+     * some USRPs, this may be significantly faster than calling
+     * set_time_source() and set_clock_source() individually.
+     *
+     * Example:
+     * ~~~{.cpp}
+     * auto usrp = uhd::usrp::multi_usrp::make("");
+     * usrp->set_sync_source(
+     *     device_addr_t("clock_source=external,time_source=external"));
+     * ~~~
+     *
+     * This function does not force a re-initialization of the underlying
+     * hardware when the value does not change. See also set_time_source() and
+     * set_clock_source() for more details.
+     *
+     * \param sync_source A dictionary representing the various source settings.
+     * \throws uhd::value_error if the sources don't actually exist or if the
+     *         combination of clock and time source is invalid.
+     */
+    virtual void set_sync_source(const uhd::device_addr_t& sync_source) = 0;
+
+    /*! Get the currently set sync source
+     *
+     * \return the dictionary representing the sync source settings
+     */
+    virtual uhd::device_addr_t get_sync_source() const = 0;
+
+    /*! Get a list of available sync sources
+     *
+     * \return the dictionary representing the sync source settings
+     */
+    virtual std::vector<uhd::device_addr_t> get_sync_sources() = 0;
+
+    /*! Send the clock source to an output connector
+     *
+     * This call is only applicable on devices with reference outputs.
+     * By default, the reference output will be enabled for ease of use.
+     * This call may be used to enable or disable the output.
+     * \param enb true to output the clock source.
+     */
+    virtual void set_clock_source_out(const bool enb) = 0;
+
+    /*! Send the time source to an output connector
+     *
+     * This call is only applicable on devices with PPS outputs.
+     * By default, the PPS output will be enabled for ease of use.
+     * This call may be used to enable or disable the output.
+     * \param enb true to output the time source.
+     */
+    virtual void set_time_source_out(const bool enb) = 0;
+
+    /*! Get a motherboard sensor value
+     *
+     * \param name the name of the sensor
+     * \return a sensor value object
+     */
+    virtual uhd::sensor_value_t get_sensor(const std::string& name) = 0;
+
+    /*! Get a list of possible motherboard sensor names
+     *
+     * \return a vector of sensor names
+     */
+    virtual std::vector<std::string> get_sensor_names() = 0;
+
+    /*! Return the motherboard EEPROM data
+     */
+    virtual uhd::usrp::mboard_eeprom_t get_eeprom() = 0;
+
+protected:
+    /*! Stash away a timekeeper. This needs to be called by the implementer of
+     * mb_controller.
+     */
+    void register_timekeeper(const size_t idx, timekeeper::sptr tk);
+
+private:
+    /**************************************************************************
+     * Attributes
+     *************************************************************************/
+    std::unordered_map<size_t, timekeeper::sptr> _timekeepers;
+};
+
+}} // namespace uhd::rfnoc
+
+#endif /* INCLUDED_LIBUHD_MB_CONTROLLER_HPP */
+
diff --git a/host/include/uhd/rfnoc/noc_block_base.hpp b/host/include/uhd/rfnoc/noc_block_base.hpp
index 0959e5bdd..4f3f2a2bc 100644
--- a/host/include/uhd/rfnoc/noc_block_base.hpp
+++ b/host/include/uhd/rfnoc/noc_block_base.hpp
@@ -23,6 +23,7 @@
 namespace uhd { namespace rfnoc {
 
 class clock_iface;
+class mb_controller;
 
 /*!
  * The primary interface to a NoC block in the FPGA
@@ -101,6 +102,19 @@ protected:
      */
     void set_tick_rate(const double tick_rate);
 
+    /*! Get access to the motherboard controller for this block's motherboard
+     *
+     * This will return a nullptr if this block doesn't have access to the
+     * motherboard. In order to gain access to the motherboard, the block needs
+     * to have requested access to the motherboard during the registration
+     * procedure. See also registry.hpp.
+     *
+     * Even if this block requested access to the motherboard controller, there
+     * is no guarantee that UHD will honour that request. It is therefore
+     * important to verify that the returned pointer is valid.
+     */
+    std::shared_ptr<mb_controller> get_mb_controller();
+
 private:
     /*! Update the tick rate of this block
      *
@@ -130,8 +144,13 @@ private:
     //! The actual tick rate of the current time base
     double _tick_rate;
 
+    //! Reference to the clock_iface object shared with the register_iface
     std::shared_ptr<clock_iface> _clock_iface;
 
+    //! Stores a reference to this block's motherboard's controller, if this
+    // block had requested and was granted access
+    std::shared_ptr<mb_controller> _mb_controller;
+
 }; // class noc_block_base
 
 }} /* namespace uhd::rfnoc */
diff --git a/host/include/uhd/rfnoc/noc_block_make_args.hpp b/host/include/uhd/rfnoc/noc_block_make_args.hpp
index d3679f973..2d42d476e 100644
--- a/host/include/uhd/rfnoc/noc_block_make_args.hpp
+++ b/host/include/uhd/rfnoc/noc_block_make_args.hpp
@@ -14,6 +14,7 @@
 namespace uhd { namespace rfnoc {
 
 class clock_iface;
+class mb_controller;
 
 /*! Data structure to hold the arguments passed into the noc_block_base ctor
  *
@@ -42,6 +43,12 @@ struct noc_block_base::make_args_t
     //! Clock interface object that is shared with the reg_iface
     std::shared_ptr<clock_iface> clk_iface;
 
+    //! Reference to the motherboard controller associated with this block.
+    //
+    // Note that this may not be populated -- most blocks do not gain access to
+    // the motherboard controller.
+    std::shared_ptr<mb_controller> mb_control;
+
     //! The subtree for this block
     uhd::property_tree::sptr tree;
 };
diff --git a/host/include/uhd/rfnoc/registry.hpp b/host/include/uhd/rfnoc/registry.hpp
index 18d896205..cc07d5c65 100644
--- a/host/include/uhd/rfnoc/registry.hpp
+++ b/host/include/uhd/rfnoc/registry.hpp
@@ -27,6 +27,12 @@
             NOC_ID, BLOCK_NAME, &CLASS_NAME##_make);                      \
     }
 
+#define UHD_RFNOC_BLOCK_REQUEST_MB_ACCESS(NOC_ID)              \
+    UHD_STATIC_BLOCK(rfnoc_block_##NOC_ID##_request_mb_access) \
+    {                                                          \
+        uhd::rfnoc::registry::request_mb_access(NOC_ID);       \
+    }
+
 namespace uhd { namespace rfnoc {
 
 /*! RFNoC Block Registry
@@ -71,6 +77,25 @@ public:
      */
     static void register_block_descriptor(const std::string& block_key,
         factory_t factory_fn);
+
+    /*! Call this after registering a block if it requires access to the
+     * mb_controller
+     *
+     * Note: This is a request to the framework, and may be denied.
+     *
+     * \param noc_id Noc-ID of the block that requires access to the mb_controller
+     */
+    static void request_mb_access(noc_block_base::noc_id_t noc_id);
+
+    /*! Call this after registering a block if it requires access to the
+     * mb_controller
+     *
+     * Note: This is a request to the framework, and may be denied.
+     *
+     * \param noc_id Noc-ID of the block that requires access to the mb_controller
+     */
+    static void request_mb_access(const std::string& block_key);
+
 };
 
 }} /* namespace uhd::rfnoc */
diff --git a/host/include/uhd/rfnoc_graph.hpp b/host/include/uhd/rfnoc_graph.hpp
index bdbac69f5..630f79751 100644
--- a/host/include/uhd/rfnoc_graph.hpp
+++ b/host/include/uhd/rfnoc_graph.hpp
@@ -20,6 +20,8 @@
 
 namespace uhd { namespace rfnoc {
 
+class mb_controller;
+
 /*! The core class for a UHD session with (an) RFNoC device(s)
  *
  * This class is a superset of uhd::device. It does not only hold a device
@@ -226,6 +228,15 @@ public:
      * \return a shared pointer to a new streamer
      */
     //virtual tx_streamer::sptr create_tx_streamer(const stream_args_t& args) = 0;
+
+    /**************************************************************************
+     * Hardware Control
+     *************************************************************************/
+    //! Return a reference to a motherboard controller
+    //
+    // See also uhd::rfnoc::mb_controller
+    virtual std::shared_ptr<mb_controller> get_mb_controller(
+        const size_t mb_index = 0) = 0;
 }; // class rfnoc_graph
 
 }}; // namespace uhd::rfnoc