diff options
Diffstat (limited to 'host/include')
| -rw-r--r-- | host/include/uhd/rfnoc/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | host/include/uhd/rfnoc/mb_controller.hpp | 352 | ||||
| -rw-r--r-- | host/include/uhd/rfnoc/noc_block_base.hpp | 19 | ||||
| -rw-r--r-- | host/include/uhd/rfnoc/noc_block_make_args.hpp | 7 | ||||
| -rw-r--r-- | host/include/uhd/rfnoc/registry.hpp | 25 | ||||
| -rw-r--r-- | host/include/uhd/rfnoc_graph.hpp | 11 |
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 |