USRP Hardware Driver and USRP Manual  Version: 4.7.0.0
UHD and USRP Manual
uhd::rfnoc::mb_controller Class Referenceabstract

#include <uhd/rfnoc/mb_controller.hpp>

Inheritance diagram for uhd::rfnoc::mb_controller:
uhd::features::discoverable_feature_getter_iface

Classes

class  timekeeper
 

Public Types

using sptr = std::shared_ptr< mb_controller >
 
using sync_source_t = device_addr_t
 
using sync_source_updater_t = std::function< void(const sync_source_t &sync_source)>
 

Public Member Functions

 ~mb_controller () override=default
 
size_t get_num_timekeepers () const
 Returns the number of timekeepers, which equals the number of timebases. More...
 
timekeeper::sptr get_timekeeper (const size_t tk_idx) const
 Return a reference to the tk_idx-th timekeeper on this motherboard. More...
 
virtual void init ()
 
virtual std::string get_mboard_name () const =0
 
virtual void set_time_source (const std::string &source)=0
 
virtual std::string get_time_source () const =0
 
virtual std::vector< std::string > get_time_sources () const =0
 
virtual void set_clock_source (const std::string &source)=0
 
virtual std::string get_clock_source () const =0
 
virtual std::vector< std::string > get_clock_sources () const =0
 
virtual void set_sync_source (const std::string &clock_source, const std::string &time_source)=0
 
virtual void set_sync_source (const uhd::device_addr_t &sync_source)=0
 
virtual uhd::device_addr_t get_sync_source () const =0
 
virtual std::vector< uhd::device_addr_tget_sync_sources ()=0
 
virtual void set_clock_source_out (const bool enb)=0
 
virtual void set_time_source_out (const bool enb)=0
 
virtual uhd::sensor_value_t get_sensor (const std::string &name)=0
 
virtual std::vector< std::string > get_sensor_names ()=0
 
virtual uhd::usrp::mboard_eeprom_t get_eeprom ()=0
 
virtual bool synchronize (std::vector< mb_controller::sptr > &mb_controllers, const uhd::time_spec_t &time_spec=uhd::time_spec_t(0.0), const bool quiet=false)
 
virtual std::vector< std::string > get_gpio_banks () const
 
virtual std::vector< std::string > get_gpio_srcs (const std::string &bank) const
 
virtual std::vector< std::string > get_gpio_src (const std::string &bank)
 
virtual void set_gpio_src (const std::string &bank, const std::vector< std::string > &src)
 
virtual void register_sync_source_updater (sync_source_updater_t callback_f)
 
- Public Member Functions inherited from uhd::features::discoverable_feature_getter_iface
virtual ~discoverable_feature_getter_iface ()=default
 
template<typename T >
T & get_feature ()
 Retrieves a feature of the specified type. More...
 
template<typename T >
bool has_feature ()
 Determines whether a given feature exists. More...
 
virtual std::vector< std::string > enumerate_features ()=0
 Enumerate all discoverable features present on the device. More...
 

Protected Member Functions

void register_timekeeper (const size_t idx, timekeeper::sptr tk)
 

Detailed Description

A default block controller for blocks that can't be found in the registry

Member Typedef Documentation

◆ sptr

◆ sync_source_t

◆ sync_source_updater_t

using uhd::rfnoc::mb_controller::sync_source_updater_t = std::function<void(const sync_source_t& sync_source)>

Callback function for changing sync sources

When a sync source is changed, the sync source callback function is called to notify any registrants of the update

Constructor & Destructor Documentation

◆ ~mb_controller()

uhd::rfnoc::mb_controller::~mb_controller ( )
overridedefault

Member Function Documentation

◆ get_clock_source()

virtual std::string uhd::rfnoc::mb_controller::get_clock_source ( ) const
pure virtual

Get the currently set clock source

Returns
the string representing the clock source

◆ get_clock_sources()

virtual std::vector<std::string> uhd::rfnoc::mb_controller::get_clock_sources ( ) const
pure virtual

Get a list of possible clock sources

Returns
a vector of strings for possible settings

◆ get_eeprom()

virtual uhd::usrp::mboard_eeprom_t uhd::rfnoc::mb_controller::get_eeprom ( )
pure virtual

Return the motherboard EEPROM data

◆ get_gpio_banks()

virtual std::vector<std::string> uhd::rfnoc::mb_controller::get_gpio_banks ( ) const
virtual

Return the list of GPIO banks that are controlled by this MB controller

Note that this list may be empty. Only if the MB controller has any control over GPIOs, do the get listed here.

◆ get_gpio_src()

virtual std::vector<std::string> uhd::rfnoc::mb_controller::get_gpio_src ( const std::string &  bank)
virtual

Return the current sources for a given GPIO bank

◆ get_gpio_srcs()

virtual std::vector<std::string> uhd::rfnoc::mb_controller::get_gpio_srcs ( const std::string &  bank) const
virtual

Return a list of possible sources to drive GPIOs

Sources can be "PS", for when an embedded device can drive the pins from software, "Radio#0", if a radio block can drive them, and so on.

◆ get_mboard_name()

virtual std::string uhd::rfnoc::mb_controller::get_mboard_name ( ) const
pure virtual

Get canonical name for this USRP motherboard

Returns
a string representing the name

◆ get_num_timekeepers()

size_t uhd::rfnoc::mb_controller::get_num_timekeepers ( ) const

Returns the number of timekeepers, which equals the number of timebases.

◆ get_sensor()

virtual uhd::sensor_value_t uhd::rfnoc::mb_controller::get_sensor ( const std::string &  name)
pure virtual

Get a motherboard sensor value

Parameters
namethe name of the sensor
Returns
a sensor value object

◆ get_sensor_names()

virtual std::vector<std::string> uhd::rfnoc::mb_controller::get_sensor_names ( )
pure virtual

Get a list of possible motherboard sensor names

Returns
a vector of sensor names

◆ get_sync_source()

virtual uhd::device_addr_t uhd::rfnoc::mb_controller::get_sync_source ( ) const
pure virtual

Get the currently set sync source

Returns
the dictionary representing the sync source settings

◆ get_sync_sources()

virtual std::vector<uhd::device_addr_t> uhd::rfnoc::mb_controller::get_sync_sources ( )
pure virtual

Get a list of available sync sources

Returns
the dictionary representing the sync source settings

◆ get_time_source()

virtual std::string uhd::rfnoc::mb_controller::get_time_source ( ) const
pure virtual

Get the currently set time source

Returns
the string representing the time source

◆ get_time_sources()

virtual std::vector<std::string> uhd::rfnoc::mb_controller::get_time_sources ( ) const
pure virtual

Get a list of possible time sources.

Returns
a vector of strings for possible settings

◆ get_timekeeper()

timekeeper::sptr uhd::rfnoc::mb_controller::get_timekeeper ( const size_t  tk_idx) const

Return a reference to the tk_idx-th timekeeper on this motherboard.

◆ init()

virtual void uhd::rfnoc::mb_controller::init ( )
inlinevirtual

Run initializations of this motherboard that have to occur post-block init

◆ register_sync_source_updater()

virtual void uhd::rfnoc::mb_controller::register_sync_source_updater ( sync_source_updater_t  callback_f)
virtual

Register a callback function to update sync sources

This callback alerts those registered that a change has occurred to a sync source, whether that be the clock_source, time_source, or both via sync_source.

Parameters
callback_fThe function to call when a sync source is updated

◆ register_timekeeper()

void uhd::rfnoc::mb_controller::register_timekeeper ( const size_t  idx,
timekeeper::sptr  tk 
)
protected

Stash away a timekeeper. This needs to be called by the implementer of mb_controller.

◆ set_clock_source()

virtual void uhd::rfnoc::mb_controller::set_clock_source ( const std::string &  source)
pure virtual

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 source are 'internal', 'external'. Refer to the specific device manual for a full list of options.

If the value for for 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:

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:

Parameters
sourcea string representing the time source
Exceptions
uhd::value_errorif source is an invalid option

◆ set_clock_source_out()

virtual void uhd::rfnoc::mb_controller::set_clock_source_out ( const bool  enb)
pure virtual

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.

Parameters
enbtrue to output the clock source.

◆ set_gpio_src()

virtual void uhd::rfnoc::mb_controller::set_gpio_src ( const std::string &  bank,
const std::vector< std::string > &  src 
)
virtual

Set the source for GPIO pins on a given bank.

Exceptions
uhd::key_errorif the bank does not exist
uhd::value_errorif the source does not exist
uhd::not_implemented_errorif the current motherboard does not support this feature

◆ set_sync_source() [1/2]

virtual void uhd::rfnoc::mb_controller::set_sync_source ( const std::string &  clock_source,
const std::string &  time_source 
)
pure virtual

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"))

Parameters
clock_sourceA string representing the clock source
time_sourceA string representing the time source
Exceptions
uhd::value_errorif the sources don't actually exist

◆ set_sync_source() [2/2]

virtual void uhd::rfnoc::mb_controller::set_sync_source ( const uhd::device_addr_t sync_source)
pure virtual

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:

graph->get_mb_controller(0)->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.

Note: Reconfiguring the sync source may affect the clocking within the FPGAs of USRPs, and affect timekeeping as well as proper functioning of blocks that depend on these clocks. It is therefore strongly recommended to configure clock and time source before doing anything else. In particular, setting the device time should be done after calling this, and there should be no ongoing streaming operation while reconfiguring the sync source.

Parameters
sync_sourceA dictionary representing the various source settings.
Exceptions
uhd::value_errorif the sources don't actually exist or if the combination of clock and time source is invalid.

◆ set_time_source()

virtual void uhd::rfnoc::mb_controller::set_time_source ( const std::string &  source)
pure virtual

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 source are 'internal', 'external'. Refer to the specific device manual for a full list of options.

If the value for for 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:

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:

Parameters
sourcea string representing the time source
Exceptions
uhd::value_errorif source is an invalid option

◆ set_time_source_out()

virtual void uhd::rfnoc::mb_controller::set_time_source_out ( const bool  enb)
pure virtual

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.

Parameters
enbtrue to output the time source.

◆ synchronize()

virtual bool uhd::rfnoc::mb_controller::synchronize ( std::vector< mb_controller::sptr > &  mb_controllers,
const uhd::time_spec_t time_spec = uhd::time_spec_t(0.0),
const bool  quiet = false 
)
virtual

Synchronize a list of motherboards in time and frequency

Note: When a uhd::rfnoc_graph is instantiated, this method is called on all motherboards.

The exact steps taken when calling this method are hardware-specific, but primarily can be split in three steps in a specific order:

  1. Pre-timekeeper sync tasks (things here could affect timekeepers)
  2. Timekeeper sync (timekeepers are perfectly aligned after this step)
  3. Post-timekeeper sync ( anything here should not affect timekeepers) This ensures that timekeepers will not lose synchronization. In all cases these will ensure that:
  • Any hardware settings that need to be applied to synchronize will be configured. For example, the X3x0 DAC (AD9146) requires synchronization triggers for all the DACs to run synchronously, and the X4x0 RFSoC requires programming an identical tile latency.
  • Timekeepers are synchronized. That means that timekeepers with the same clock rate increment are in unison, and at all times have the same time. This allows sending timed commands to the motherboards and expect them to be executed at the same time.
Parameters
mb_controllersA list of motherboard controllers to synchronize. Any motherboard controllers that could not be synchronized because they're incompatible with this motherboard controller are removed from the list. On return, the list should be (ideally) identical to its value at call time.
time_specTime specification to synchronize mb_controllers to
quietIf true, don't print any errors or warnings if synchronization fails. During initialization of uhd::rfnoc_graph, UHD will call synchronize() on all motherboards with quiet set to true.
Returns
true if all motherboards that were listed in mb_controllers could be synchronized.

The documentation for this class was generated from the following file: