USRP Hardware Driver and USRP Manual  Version: 4.4.0.HEAD-0-g5fac246b
UHD and USRP Manual
uhd::rfnoc::node_t Class Referenceabstract

#include <uhd/rfnoc/node.hpp>

Inheritance diagram for uhd::rfnoc::node_t:
uhd::rfnoc::noc_block_base uhd::rfnoc::addsub_block_control uhd::rfnoc::block_control uhd::rfnoc::ddc_block_control uhd::rfnoc::dmafifo_block_control uhd::rfnoc::duc_block_control uhd::rfnoc::fft_block_control uhd::rfnoc::fir_filter_block_control uhd::rfnoc::fosphor_block_control uhd::rfnoc::keep_one_in_n_block_control uhd::rfnoc::logpwr_block_control uhd::rfnoc::moving_average_block_control uhd::rfnoc::null_block_control uhd::rfnoc::radio_control uhd::rfnoc::replay_block_control uhd::rfnoc::siggen_block_control uhd::rfnoc::split_stream_block_control uhd::rfnoc::switchboard_block_control uhd::rfnoc::vector_iir_block_control uhd::rfnoc::window_block_control

Public Types

enum  forwarding_policy_t {
  forwarding_policy_t::ONE_TO_ONE, forwarding_policy_t::ONE_TO_FAN, forwarding_policy_t::ONE_TO_ALL_IN, forwarding_policy_t::ONE_TO_ALL_OUT,
  forwarding_policy_t::ONE_TO_ALL, forwarding_policy_t::DROP, forwarding_policy_t::USE_MAP
}
 Types of property/action forwarding for those not defined by the block itself. More...
 
using resolver_fn_t = std::function< void(void)>
 
using resolve_callback_t = std::function< void(void)>
 
using graph_mutex_callback_t = std::function< std::recursive_mutex &(void)>
 
using action_handler_t = std::function< void(const res_source_info &, action_info::sptr)>
 
using forwarding_map_t = std::unordered_map< res_source_info, std::vector< res_source_info > >
 

Public Member Functions

 node_t ()
 
virtual ~node_t ()
 
virtual std::string get_unique_id () const
 Return a unique identifier string for this node. In every RFNoC graph,. More...
 
virtual size_t get_num_input_ports () const =0
 
virtual size_t get_num_output_ports () const =0
 
std::vector< std::string > get_property_ids () const
 
template<typename prop_data_t >
void set_property (const std::string &id, const prop_data_t &val, const size_t instance=0)
 
void set_properties (const uhd::device_addr_t &props, const size_t instance=0)
 
template<typename prop_data_t >
const prop_data_t & get_property (const std::string &id, const size_t instance=0)
 
virtual void set_command_time (uhd::time_spec_t time, const size_t instance)
 
virtual uhd::time_spec_t get_command_time (const size_t instance) const
 
virtual void clear_command_time (const size_t instance)
 

Static Public Attributes

static const size_t ANY_PORT = size_t(~0)
 

Protected Types

using prop_ptrs_t = std::vector< property_base_t * >
 

Protected Member Functions

void register_property (property_base_t *prop, resolve_callback_t &&clean_callback=nullptr)
 
void add_property_resolver (prop_ptrs_t &&inputs, prop_ptrs_t &&outputs, resolver_fn_t &&resolver_fn)
 
void set_prop_forwarding_policy (forwarding_policy_t policy, const std::string &prop_id="")
 
void set_prop_forwarding_map (const forwarding_map_t &map)
 
template<typename prop_data_t >
void set_property (const std::string &id, const prop_data_t &val, const res_source_info &src_info)
 
template<typename prop_data_t >
const prop_data_t & get_property (const std::string &id, const res_source_info &src_info)
 
void register_action_handler (const std::string &id, action_handler_t &&handler)
 
void set_action_forwarding_policy (forwarding_policy_t policy, const std::string &action_key="")
 
void set_action_forwarding_map (const forwarding_map_t &map)
 
void post_action (const res_source_info &edge_info, action_info::sptr action)
 
virtual bool check_topology (const std::vector< size_t > &connected_inputs, const std::vector< size_t > &connected_outputs)
 
virtual void shutdown ()
 

Static Protected Attributes

static dirtifier_t ALWAYS_DIRTY
 A dirtifyer object, useful for properties that always need updating. More...
 

Friends

class node_accessor_t
 

Detailed Description

The base class for all nodes within an RFNoC graph

The block supports the following types of data access:

  • High-level property access
  • Action execution

Member Typedef Documentation

◆ action_handler_t

◆ forwarding_map_t

using uhd::rfnoc::node_t::forwarding_map_t = std::unordered_map<res_source_info, std::vector<res_source_info> >

◆ graph_mutex_callback_t

using uhd::rfnoc::node_t::graph_mutex_callback_t = std::function<std::recursive_mutex&(void)>

◆ prop_ptrs_t

using uhd::rfnoc::node_t::prop_ptrs_t = std::vector<property_base_t*>
protected

◆ resolve_callback_t

using uhd::rfnoc::node_t::resolve_callback_t = std::function<void(void)>

◆ resolver_fn_t

using uhd::rfnoc::node_t::resolver_fn_t = std::function<void(void)>

Member Enumeration Documentation

◆ forwarding_policy_t

Types of property/action forwarding for those not defined by the block itself.

Enumerator
ONE_TO_ONE 

Forward the property/action to the opposite port with the same index.

ONE_TO_FAN 

Fan-out forwarding: Forward to all opposite ports.

ONE_TO_ALL_IN 

Forward the property to all input ports.

ONE_TO_ALL_OUT 

Forward the property to all output ports.

ONE_TO_ALL 

Forward the property to all ports.

DROP 

Property propagation ends here.

USE_MAP 

Forward the property based on a client-provided map.

Constructor & Destructor Documentation

◆ node_t()

uhd::rfnoc::node_t::node_t ( )

◆ ~node_t()

virtual uhd::rfnoc::node_t::~node_t ( )
inlinevirtual

Member Function Documentation

◆ add_property_resolver()

void uhd::rfnoc::node_t::add_property_resolver ( prop_ptrs_t &&  inputs,
prop_ptrs_t &&  outputs,
resolver_fn_t &&  resolver_fn 
)
protected

Add a resolver function to this block.

A resolver function is used to reconcile state changes in the block, and is triggered by a user or other upstream/downstream blocks. A block may have multiple resolvers.

Notes on resolvers:

  • Multiple resolvers may share properties for reading and a resolver may read multiple properties
  • A resolver may assume the properties are in a consistent state before it executes, but it must leave the properties in a consistent state when it completes.
  • The framework will perform run-time validation to ensure read/write property access is not violated. All properties can be read during execution, but only properties in the outputs list can be written to.
  • Resolvers are stored and executed in the same order they are added. That is to say, if two resolvers both share a condition that will trigger them, the first resolver to be added will be the first resolver to be executed. This allows to make some assumptions on the order of execution, in case resolvers have dependencies.
  • This method has no built-in thread safety, since it is typically only called in the constructor. If resolvers need to be added at runtime (which is considered advanced usage), then the block needs to serialize access to this function itself.

For more information, see Property Resolvers and Property Resolution.

Parameters
inputsThe properties that will cause this resolver to run
outputsThe properties that this resolver will write to
resolver_fnThe resolver function
Exceptions
uhd::runtime_errorif any of the properties listed is not registered

◆ check_topology()

virtual bool uhd::rfnoc::node_t::check_topology ( const std::vector< size_t > &  connected_inputs,
const std::vector< size_t > &  connected_outputs 
)
protectedvirtual

Check if the current connections "work" for this block

The default implementation simply checks if all connections are within the valid range, i.e., no connected_inputs element is larger than get_num_input_ports(), etc. This can be overridden, but keep in mind that blocks need some kind of tolerance here, because blocks may simply not be part of the current application, and left unconnected. This check is more meant for blocks that simply don't work of only one of two ports is connected, or situations like that.

Note that this method is always called when a graph is committed, i.e., no connections will be added or removed without calling this method again, unless the user bypasses calling uhd::rfnoc_graph::commit(). This method can therefore be used to make decisions about the behaviour of the block.

Parameters
connected_inputsA list of input ports that are connected
connected_outputsA list of output ports that are connected
Returns
true if the block can deal with this configuration

◆ clear_command_time()

virtual void uhd::rfnoc::node_t::clear_command_time ( const size_t  instance)
virtual

Standard API for resetting the command time

This will clear the time previously set by set_command_time(). It defaults to calling set_command_time(time_spec_t(0.0), instance)

◆ get_command_time()

virtual uhd::time_spec_t uhd::rfnoc::node_t::get_command_time ( const size_t  instance) const
virtual

Return a previously set command time

When no time was set, this will return uhd::time_spec_t::ASAP

◆ get_num_input_ports()

virtual size_t uhd::rfnoc::node_t::get_num_input_ports ( ) const
pure virtual

Return the number of input ports for this block.

This function needs to be overridden.

Returns
noc_id The number of ports

Implemented in uhd::rfnoc::noc_block_base.

◆ get_num_output_ports()

virtual size_t uhd::rfnoc::node_t::get_num_output_ports ( ) const
pure virtual

Return the number of output ports for this block.

This function needs to be overridden.

Returns
noc_id The number of ports

Implemented in uhd::rfnoc::noc_block_base.

◆ get_property() [1/2]

template<typename prop_data_t >
const prop_data_t & uhd::rfnoc::node_t::get_property ( const std::string &  id,
const res_source_info src_info 
)
protected

Get the value of a property.

This is like get_property(), but it also allows reading edge properties. All comments from get_property() still apply.

Template Parameters
prop_data_tThe data type of the property
Parameters
idThe identifier of the property to write.
src_infoSource info of this property
Returns
The value of the property.
Exceptions
uhd::lookup_errorif the property can't be found.

◆ get_property() [2/2]

template<typename prop_data_t >
const prop_data_t & uhd::rfnoc::node_t::get_property ( const std::string &  id,
const size_t  instance = 0 
)

Get the value of a specific block argument. The type of an argument must be known at compile time.

If the property does not exist, or if the property can be determined to be of a different type than prop_data_t due to the usage of runtime type information (RTTI), a lookup_error is thrown.

Note: Despite this being a "getter", this function is not declared const. This is because internally, it can resolve properties, which may cause changes within the object.

Template Parameters
prop_data_tThe data type of the property
Parameters
idThe identifier of the property to write.
instanceThe instance number of this property
Returns
The value of the property.
Exceptions
uhd::lookup_errorif the property can't be found.

◆ get_property_ids()

std::vector<std::string> uhd::rfnoc::node_t::get_property_ids ( ) const

Return the names of all possible user properties that can be accessed for this block.

Note that the type of the property is not auto-detectable.

Returns
A vector of all possible IDs of user properties supported by this block.

◆ get_unique_id()

virtual std::string uhd::rfnoc::node_t::get_unique_id ( ) const
virtual

Return a unique identifier string for this node. In every RFNoC graph,.

Reimplemented in uhd::rfnoc::noc_block_base.

◆ post_action()

void uhd::rfnoc::node_t::post_action ( const res_source_info edge_info,
action_info::sptr  action 
)
protected

Post an action to an up- or downstream node in the graph.

If the action is posted to an edge which is not connected, the action is lost.

Parameters
edge_infoThe edge to which this action is posted. If edge_info.type == INPUT_EDGE, the that means the action will be posted to an upstream node, on port edge_info.instance.
actionA reference to the action info object.
Exceptions
uhd::runtime_errorif edge_info is not either INPUT_EDGE or OUTPUT_EDGE

◆ register_action_handler()

void uhd::rfnoc::node_t::register_action_handler ( const std::string &  id,
action_handler_t &&  handler 
)
protected

Handle a request to perform an action. The default action handler ignores user action and forwards port actions.

Parameters
idThe action ID for which this action handler is valid. The first argument to the handler will be a uhd::rfnoc::action_info::sptr, and its id value will match this parameter (unless the same action handler is registered multiple times). If this function was previously called with the same id value, the previous action handler is overwritten.
handlerThe function that is called to handle the action. It needs to accept a uhd::rfnoc::res_source_info object, and a uhd::rfnoc::action_info::sptr.

◆ register_property()

void uhd::rfnoc::node_t::register_property ( property_base_t prop,
resolve_callback_t &&  clean_callback = nullptr 
)
protected

Register a property for this block

This is typically called from the constructor. It is possible to register properties later, but then the node must take care of serialization.

This has the intentional side-effect of setting the access mode to RW for the property. The idea is that after registering a property, the node might need some time to settle on the default value. The access mode will either be reset after the constructor is finished, or the next time properties are resolved.

For more information, see Defining Properties.

Parameters
propA reference to the property
clean_callbackA callback that gets executed whenever this property is dirty and gets marked clean
Exceptions
uhd::key_errorif another property with the same ID and source type is already registered

◆ set_action_forwarding_map()

void uhd::rfnoc::node_t::set_action_forwarding_map ( const forwarding_map_t map)
protected

Specify a table that maps how an action should be forwarded

Whenever this node is asked to handle an action that is not registered, and the forwarding policy for the particular action is set to USE_MAP, the node will consult a user-provided map to determine what to do with the action. The map's keys are the source edges for the incoming action and the value associated with each key is a vector of destination edges to which the action should be forwarded.

incoming action and the value is a vector of destination edges to which the action should be forwarded.

If there is no key in the map matching an incoming action's source edge, or if the value of the key is the empty vector, the action is dropped and not forwarded further.

The following conditions will generate exceptions at action forwarding time:

  • Any value in the destination vector represents a non-existent port
Parameters
mapThe map describing how actions should be forwarded

◆ set_action_forwarding_policy()

void uhd::rfnoc::node_t::set_action_forwarding_policy ( forwarding_policy_t  policy,
const std::string &  action_key = "" 
)
protected

Set an action forwarding policy

Whenever this node is asked to handle an action that is not registered, this is how the node knows what to do with the action. For example, the FIFO block controller will almost always want to pass on actions to the next block.

This method can be called more than once, and it will overwrite previous policies. Typically, this function should only ever be called from within the constructor.

Parameters
policyThe policy that is applied (see also forwarding_policy_t).
action_keyThe action key that this forwarding policy is applied to. If action_key is not given, it will apply to all properties, unless a different policy was given with a matching key.

◆ set_command_time()

virtual void uhd::rfnoc::node_t::set_command_time ( uhd::time_spec_t  time,
const size_t  instance 
)
virtual

Standard API for setting the command time

There are instances where commands need a time associated with them. For example, a block could have a 'freq' user property, which should be changed at a certain time. In that case, the block would have to be written to handle command times.

The reason there is no 'time' parameter in set_property() or other API calls is because there is no uniform definition of what the time means; it can change from block to block. The transformation of time to a tick count, for example, is non-standard.

The default implementation will simply stash away the time; it can be retrieved by calling get_command_time();

◆ set_prop_forwarding_map()

void uhd::rfnoc::node_t::set_prop_forwarding_map ( const forwarding_map_t map)
protected

Specify a table that maps how a property should be forwarded

Whenever this node is asked to handle a property that is not registered, and the forwarding policy for the particular property is set to USE_MAP, the node will consult a user-provided map to determine what to do with the property. The map's keys are the source edges for the incoming property and the value associated with each key is a vector of destination edges to which the property should be propagated.

If there is no key in the map matching an incoming property's source edge, or if the value of the key is the empty vector, the property is dropped and not propagated further.

The following conditions will generate exceptions at property propagation time:

  • Any value in the destination vector represents a non-existent port

See also Handling unknown properties.

Parameters
mapThe map describing how properties should be propagated

◆ set_prop_forwarding_policy()

void uhd::rfnoc::node_t::set_prop_forwarding_policy ( forwarding_policy_t  policy,
const std::string &  prop_id = "" 
)
protected

Set a property forwarding policy for dynamic properties

Whenever this node is asked to handle a property that is not registered, this is how the node knows what to do with the property. For example, the FIFO block controller will almost always want to pass on properties to the next block.

This method can be called more than once, and it will overwrite previous policies. However, once a property has been registered with this block, the policy is set. Typically, this function should only ever be called from within the constructor.

See also Handling unknown properties.

Parameters
policyThe policy that is applied (see also forwarding_policy_t).
prop_idThe property ID that this forwarding policy is applied to. If prop_id is not given, it will apply to all properties, unless a different policy was given with a matching ID.

◆ set_properties()

void uhd::rfnoc::node_t::set_properties ( const uhd::device_addr_t props,
const size_t  instance = 0 
)

Set multiple properties coming from a dictionary

This is equivalent to calling set_property() individually for every key/value pair of props. However, the type of the property will be automatically derived using RTTI. Only certain types are supported.

Property resolution happens after all properties have been updated.

This function allows the client to override the instance parameter for each property key/value pair passed in via the props parameter. If the key consists of the property name, followed by a colon (':') and then a number, the number following the colon is used to determine which instance of the property this set pertains to, and the instance parameter is ignored for that property. (Note that if the key does not have the colon and instance number override syntax, then instance is still used to determine which instance of the property to set. For example, in the following call:

node->set_properties("dog=10,cat:2=5,bird:0=0.5", 1)

instance 1 of node's 'dog' property is set to 10, the 1 coming from the instance parameter, instance 2 of the node's 'cat' property is set to 5 due to the override syntax provided in the string, and instance 0 of the node's 'bird' property is set to 0.5 due to its override.

If the instance override is malformed, that is, there is no number following the colon, or the number cannot be parsed as an integer, a value_error is thrown.

If a key in props is not a valid property of this block, a warning is logged, but no error is raised.

◆ set_property() [1/2]

template<typename prop_data_t >
void uhd::rfnoc::node_t::set_property ( const std::string &  id,
const prop_data_t &  val,
const res_source_info src_info 
)
protected

Set a specific property that belongs to this block.

This is like set_property(), but it also allows setting edge properties. All comments from set_property() still apply.

Template Parameters
prop_data_tThe data type of the property
Parameters
idThe identifier of the property to write. To find out which values of id are valid, call get_property_ids()
valThe new value of the property.
src_infoSource info of the property

◆ set_property() [2/2]

template<typename prop_data_t >
void uhd::rfnoc::node_t::set_property ( const std::string &  id,
const prop_data_t &  val,
const size_t  instance = 0 
)

Set a specific user property that belongs to this block.

Setting a user property will trigger a property resolution. This means that changing this block can have effects on other nodes.

If the property does not exist, or if the property can be determined to be of a different type than prop_data_t due to the usage of runtime type information (RTTI), a lookup_error is thrown.

Template Parameters
prop_data_tThe data type of the property
Parameters
idThe identifier of the property to write. To find out which values of id are valid, call get_property_ids()
instanceThe instance number of this property
valThe new value of the property.

◆ shutdown()

virtual void uhd::rfnoc::node_t::shutdown ( )
protectedvirtual

Perform a shutdown sequence

This is mostly relevant for noc_block_base implementations. See also noc_block_base::shutdown().

Friends And Related Function Documentation

◆ node_accessor_t

friend class node_accessor_t
friend

Member Data Documentation

◆ ALWAYS_DIRTY

dirtifier_t uhd::rfnoc::node_t::ALWAYS_DIRTY
staticprotected

A dirtifyer object, useful for properties that always need updating.

◆ ANY_PORT

const size_t uhd::rfnoc::node_t::ANY_PORT = size_t(~0)
static

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