#include <uhd/rfnoc/node.hpp>

Inheritance diagram for uhd::rfnoc::node_t:

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

using uhd::rfnoc::node_t::action_handler_t = std::function<void(const res_source_info&, action_info::sptr)>

◆ 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

enum 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 ( )

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

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
	)

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_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.

◆ 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 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() [2/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_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_info	The 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.
action	A reference to the action info object.

Exceptions

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

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 Defining Properties.

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

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

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

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

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

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.

Public Types

Public Member Functions

Static Public Attributes

Protected Types

Protected Member Functions

Static Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ action_handler_t

◆ forwarding_map_t

◆ graph_mutex_callback_t

◆ prop_ptrs_t

◆ resolve_callback_t

◆ resolver_fn_t

Member Enumeration Documentation

◆ forwarding_policy_t

Constructor & Destructor Documentation

◆ node_t()

◆ ~node_t()

Member Function Documentation

◆ add_property_resolver()

◆ check_topology()

◆ clear_command_time()

◆ get_command_time()

◆ get_num_input_ports()

◆ get_num_output_ports()

◆ get_property() [1/2]

◆ get_property() [2/2]

◆ get_property_ids()

◆ get_unique_id()

◆ post_action()

◆ register_action_handler()

◆ register_property()

◆ set_action_forwarding_map()

◆ set_action_forwarding_policy()

◆ set_command_time()

◆ set_prop_forwarding_map()

◆ set_prop_forwarding_policy()

◆ set_properties()

◆ set_property() [1/2]

◆ set_property() [2/2]

◆ shutdown()

Friends And Related Function Documentation

◆ node_accessor_t

Member Data Documentation

◆ ALWAYS_DIRTY

◆ ANY_PORT