| USRP Hardware Driver and Device Manual Version: 4.10.0.0 UHD and USRP Manual |

Loading...
Searching...
No Matches
uhd::rfnoc::node_t Class Referenceabstract

`#include <uhd/rfnoc/node.hpp>`

Inheritance diagram for uhd::rfnoc::node_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

## Public Types
enum class | action_mode_t { SYNC , ASYNC }
| Action execution modes. More...
enum class | forwarding_policy_t { ONE_TO_ONE , ONE_TO_FAN , ONE_TO_ALL_IN , ONE_TO_ALL_OUT , ONE_TO_ALL , DROP , 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
using | post_action_handler_t
using | forwarding_map_t

## 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,.
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, action_mode_t mode=action_mode_t::SYNC)
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.

## Friends
class | node_accessor_t

## Member Typedef Documentation

## ◆ action_handler_t

using uhd::rfnoc::node_t::action_handler_t

Initial value:
std::function<void(const res_source_info&, action_info::sptr)>
uhd::rfnoc::action_info::sptr
std::shared_ptr< action_info > sptr
Definition actions.hpp:39
uhd::rfnoc::res_source_info
Definition res_source_info.hpp:18

## ◆ forwarding_map_t

using uhd::rfnoc::node_t::forwarding_map_t

Initial value:
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)>

## ◆ post_action_handler_t

using uhd::rfnoc::node_t::post_action_handler_t

Initial value:
std::function<void(const res_source_info&, action_info::sptr, action_mode_t)>
uhd::rfnoc::node_t::action_mode_t
action_mode_t
Action execution modes.
Definition node.hpp:38

## ◆ 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

## ◆ action_mode_t

enum class uhd::rfnoc::node_t::action_mode_t
| strong

Action execution modes.

Enumerator
SYNC | Synchronous: wait for all actions to be processed.
ASYNC | Asynchronous: queue action and return immediately.

## ◆ forwarding_policy_t

enum class uhd::rfnoc::node_t::forwarding_policy_t
| strong

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 | ( |  | ) |
| inline virtual

## 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 props_resolvers.

Parameters

  inputs | The properties that will cause this resolver to run
  outputs | The properties that this resolver will write to
  resolver_fn | The resolver function

Exceptions

  uhd::runtime_error | if 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 )
| protected virtual

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_inputs | A list of input ports that are connected
  connected_outputs | A 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, uhd::rfnoc::test::mock_ddc_node_t, uhd::rfnoc::test::mock_edge_node_t, uhd::rfnoc::test::mock_fifo_t, uhd::rfnoc::test::mock_radio_node_t, uhd::rfnoc::test::mock_routing_node_t, uhd::rfnoc::test::mock_streamer_t, and uhd::rfnoc::test::mock_terminator_t.

## ◆ 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, uhd::rfnoc::test::mock_ddc_node_t, uhd::rfnoc::test::mock_edge_node_t, uhd::rfnoc::test::mock_fifo_t, uhd::rfnoc::test::mock_radio_node_t, uhd::rfnoc::test::mock_routing_node_t, uhd::rfnoc::test::mock_streamer_t, and uhd::rfnoc::test::mock_terminator_t.

## ◆ 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_t | The data type of the property

Parameters

  id | The identifier of the property to write.
  src_info | Source info of this property

Returns
  The value of the property.

Exceptions

  uhd::lookup_error | if 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_t | The data type of the property

Parameters

  id | The identifier of the property to write.
  instance | The instance number of this property

Returns
  The value of the property.

Exceptions

  uhd::lookup_error | if 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, uhd::rfnoc::test::mock_ddc_node_t, uhd::rfnoc::test::mock_edge_node_t, uhd::rfnoc::test::mock_fifo_t, uhd::rfnoc::test::mock_radio_node_t, uhd::rfnoc::test::mock_routing_node_t, uhd::rfnoc::test::mock_streamer_t, and uhd::rfnoc::test::mock_terminator_t.

## ◆ post_action()

void uhd::rfnoc::node_t::post_action | ( | const res_source_info & | edge_info,
|  | action_info::sptr | action,
|  | action_mode_t | mode = action_mode_t::SYNC )
| 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.

The action handling can be either asynchronous or synchronous based on the mode parameter. When asynchronous, the action is placed in a FIFO queue and the function returns immediately. When synchronous (default), the function waits until all actions in the queue have been processed before returning. Note that only one thread can post actions synchronously, if another thread attempts to do so, that will result in a deadlock. Therefore, never post actions from an action handler synchronously.

Parameters

  edge_info | The edge to which this action is posted. If edge_info.type == INPUT_EDGE, that means the action will be posted to an upstream node, on port edge_info.instance.
  action | A reference to the action info object.
  mode | Action execution mode (SYNC for synchronous, ASYNC for asynchronous)

Exceptions

  uhd::runtime_error | if edge_info is neither INPUT_EDGE nor 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

  id | The 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.
  handler | The 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 props_define.

Parameters

  prop | A reference to the property
  clean_callback | A callback that gets executed whenever this property is dirty and gets marked clean

Exceptions

  uhd::key_error | if 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

  map | The 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

  policy | The policy that is applied (see also forwarding_policy_t).
  action_key | The 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 props_unknown.

Parameters

  map | The 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 props_unknown.

Parameters

  policy | The policy that is applied (see also forwarding_policy_t).
  prop_id | The 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_t | The data type of the property

Parameters

  id | The identifier of the property to write. To find out which values of `id` are valid, call get_property_ids()
  val | The new value of the property.
  src_info | Source 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_t | The data type of the property

Parameters

  id | The identifier of the property to write. To find out which values of `id` are valid, call get_property_ids()
  instance | The instance number of this property
  val | The new value of the property.

## ◆ shutdown()

virtual void uhd::rfnoc::node_t::shutdown | ( |  | ) |
| protected virtual

Perform a shutdown sequence

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

## Friends And Related Symbol Documentation

## ◆ node_accessor_t

friend class node_accessor_t
| friend

## Member Data Documentation

## ◆ ALWAYS_DIRTY

dirtifier_t uhd::rfnoc::node_t::ALWAYS_DIRTY
| static protected

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:

- node.hpp
- node.ipp