USRP Hardware Driver and USRP Manual  Version: 4.6.0.0
UHD and USRP Manual
node.hpp
Go to the documentation of this file.
1 //
2 // Copyright 2019 Ettus Research, a National Instruments Brand
3 //
4 // SPDX-License-Identifier: GPL-3.0-or-later
5 //
6 
7 #pragma once
8 
9 #include <uhd/rfnoc/actions.hpp>
10 #include <uhd/rfnoc/dirtifier.hpp>
11 #include <uhd/rfnoc/property.hpp>
13 #include <uhd/types/time_spec.hpp>
14 #include <uhd/utils/log.hpp>
15 #include <uhd/utils/scope_exit.hpp>
16 #include <unordered_map>
17 #include <unordered_set>
18 #include <boost/graph/adjacency_list.hpp>
19 #include <functional>
20 #include <memory>
21 #include <mutex>
22 #include <string>
23 #include <tuple>
24 #include <vector>
25 
26 namespace uhd { namespace rfnoc {
27 
35 {
36 public:
37  using resolver_fn_t = std::function<void(void)>;
38  using resolve_callback_t = std::function<void(void)>;
39  using graph_mutex_callback_t = std::function<std::recursive_mutex&(void)>;
40  using action_handler_t =
41  std::function<void(const res_source_info&, action_info::sptr)>;
42  using forwarding_map_t =
43  std::unordered_map<res_source_info, std::vector<res_source_info>>;
44 
46  enum class forwarding_policy_t {
48  //(e.g., if it comes from input port 0, forward it to output port 0).
49  ONE_TO_ONE,
51  ONE_TO_FAN,
53  ONE_TO_ALL_IN,
55  ONE_TO_ALL_OUT,
57  ONE_TO_ALL,
59  DROP,
61  USE_MAP
62  };
63 
64  static const size_t ANY_PORT = size_t(~0);
65 
66  /**************************************************************************
67  * Structors
68  *************************************************************************/
69  node_t();
70 
71  virtual ~node_t() {}
72 
73  /******************************************
74  * Basic Operations
75  ******************************************/
77  // no two nodes cannot have the same ID.
78  //
79  // \returns The unique ID as a string
80  virtual std::string get_unique_id() const;
81 
88  virtual size_t get_num_input_ports() const = 0;
89 
96  virtual size_t get_num_output_ports() const = 0;
97 
98  /******************************************
99  * Property Specific
100  ******************************************/
101 
110  std::vector<std::string> get_property_ids() const;
111 
127  template <typename prop_data_t>
128  void set_property(
129  const std::string& id, const prop_data_t& val, const size_t instance = 0);
130 
163  void set_properties(const uhd::device_addr_t& props, const size_t instance = 0);
164 
182  template <typename prop_data_t>
183  const prop_data_t& get_property(
184  const std::string& id, const size_t instance = 0) /* mutable */;
185 
201  virtual void set_command_time(uhd::time_spec_t time, const size_t instance);
202 
207  virtual uhd::time_spec_t get_command_time(const size_t instance) const;
208 
214  virtual void clear_command_time(const size_t instance);
215 
216 protected:
217  /******************************************
218  * Internal Registration Functions
219  ******************************************/
220  using prop_ptrs_t = std::vector<property_base_t*>;
221 
242  void register_property(
243  property_base_t* prop, resolve_callback_t&& clean_callback = nullptr);
244 
279  void add_property_resolver(
280  prop_ptrs_t&& inputs, prop_ptrs_t&& outputs, resolver_fn_t&& resolver_fn);
281 
282  /**************************************************************************
283  * Property forwarding
284  *************************************************************************/
305  void set_prop_forwarding_policy(
306  forwarding_policy_t policy, const std::string& prop_id = "");
307 
329  void set_prop_forwarding_map(const forwarding_map_t& map);
330 
342  template <typename prop_data_t>
343  void set_property(
344  const std::string& id, const prop_data_t& val, const res_source_info& src_info);
345 
357  template <typename prop_data_t>
358  const prop_data_t& get_property(
359  const std::string& id, const res_source_info& src_info) /* mutable */;
360 
361  /******************************************
362  * Internal action forwarding
363  ******************************************/
377  void register_action_handler(const std::string& id, action_handler_t&& handler);
378 
397  void set_action_forwarding_policy(
398  forwarding_policy_t policy, const std::string& action_key = "");
399 
422  void set_action_forwarding_map(const forwarding_map_t& map);
423 
435  void post_action(const res_source_info& edge_info, action_info::sptr action);
436 
437  /**************************************************************************
438  * Graph Interaction
439  *************************************************************************/
460  virtual bool check_topology(const std::vector<size_t>& connected_inputs,
461  const std::vector<size_t>& connected_outputs);
462 
468  virtual void shutdown();
469 
470  /**************************************************************************
471  * Attributes
472  *************************************************************************/
475 
476 private:
477  friend class node_accessor_t;
478 
483  property_base_t* _find_property(
484  res_source_info src_info, const std::string& id) const;
485 
491  uhd::utils::scope_exit::uptr _request_property_access(
492  property_base_t* prop, property_base_t::access_t access) const;
493 
498  template <typename PredicateType>
499  prop_ptrs_t filter_props(PredicateType&& predicate)
500  {
501  prop_ptrs_t filtered_props{};
502  for (const auto& type_prop_pair : _props) {
503  for (const auto& prop : type_prop_pair.second) {
504  if (predicate(prop)) {
505  filtered_props.push_back(prop);
506  }
507  }
508  }
509 
510  return filtered_props;
511  }
512 
520  property_base_t* inject_edge_property(
521  property_base_t* blueprint, res_source_info new_src_info);
522 
536  void init_props();
537 
561  void resolve_props();
562 
565  void resolve_all();
566 
572  void clean_props();
573 
577  void set_resolve_all_callback(resolve_callback_t&& resolver)
578  {
579  _resolve_all_cb = resolver;
580  }
581 
584  void clear_resolve_all_callback()
585  {
586  _resolve_all_cb = _default_resolve_all_cb;
587  }
588 
592  void set_graph_mutex_callback(graph_mutex_callback_t&& mutex)
593  {
594  _graph_mutex_cb = mutex;
595  }
596 
600  void clear_graph_mutex_callback()
601  {
602  _graph_mutex_cb = NULL;
603  }
604 
639  void forward_edge_property(
640  property_base_t* incoming_prop, const size_t incoming_port);
641 
642  /**************************************************************************
643  * Action-Related Methods
644  *************************************************************************/
648  void set_post_action_callback(action_handler_t&& post_handler)
649  {
650  _post_action_cb = std::move(post_handler);
651  }
652 
661  void receive_action(const res_source_info& src_info, action_info::sptr action);
662 
663  /**************************************************************************
664  * Private helpers
665  *************************************************************************/
667  bool _has_port(const res_source_info& port_info) const;
668 
670  template <typename prop_data_t>
671  void _set_property(
672  const std::string& id, const prop_data_t& val, const res_source_info& src_info);
673 
674  /****** Attributes *******************************************************/
676  // global property mutex, this only write-protects access to the property-
677  // related containers in this class.
678  mutable std::mutex _prop_mutex;
679 
681  std::unordered_map<res_source_info::source_t,
682  std::vector<property_base_t*>,
683  std::hash<size_t>>
684  _props;
685 
687  std::unordered_map<property_base_t*, resolve_callback_t> _clean_cb_registry;
688 
689  using property_resolver_t = std::tuple<prop_ptrs_t, prop_ptrs_t, resolver_fn_t>;
691  std::vector<property_resolver_t> _prop_resolvers;
692 
694  // This will return a global mutex to the graph. It is required to propagate
695  // properties on multithread applications.
696  graph_mutex_callback_t _graph_mutex_cb;
697 
699  // has changed, and that a property resolution needs to be performed.
700  resolve_callback_t _resolve_all_cb;
701 
703  // method.
704  const resolve_callback_t _default_resolve_all_cb = [this]() {
705  resolve_props();
706  clean_props();
707  };
708 
709 
711  // explicitly.
712  //
713  // Dynamic properties include properties defined in the block descriptor
714  // file, as well as new properties that get passed in during property
715  // propagation.
716  std::unordered_set<std::unique_ptr<property_base_t>> _dynamic_props;
717 
719  //
720  // The entry with the empty-string-key is the default policy.
721  std::unordered_map<std::string, forwarding_policy_t> _prop_fwd_policies{
722  {"", forwarding_policy_t::ONE_TO_ONE}};
723 
725  forwarding_map_t _prop_fwd_map;
726 
727  /**************************************************************************
728  * Action-related attributes
729  *************************************************************************/
730  mutable std::mutex _action_mutex;
731 
733  std::unordered_map<std::string, action_handler_t> _action_handlers;
734 
736  std::unordered_map<std::string, forwarding_policy_t> _action_fwd_policies{
737  {"", forwarding_policy_t::ONE_TO_ONE}};
738 
740  //
741  // The default callback will simply drop actions
742  action_handler_t _post_action_cb = [](const res_source_info&,
743  action_info::sptr) { /* nop */ };
744 
746  forwarding_map_t _action_fwd_map;
747 
748  /**************************************************************************
749  * Other attributes
750  *************************************************************************/
751  std::vector<uhd::time_spec_t> _cmd_timespecs;
752 }; // class node_t
753 
754 }} /* namespace uhd::rfnoc */
755 
756 #include <uhd/rfnoc/node.ipp>
std::function< void(const res_source_info &, action_info::sptr)> action_handler_t
Definition: node.hpp:41
std::vector< property_base_t * > prop_ptrs_t
Definition: node.hpp:220
static dirtifier_t ALWAYS_DIRTY
A dirtifyer object, useful for properties that always need updating.
Definition: node.hpp:474
Definition: time_spec.hpp:28
Definition: dirtifier.hpp:18
Definition: build_info.hpp:12
access_t
Definition: property.hpp:28
std::function< void(void)> resolve_callback_t
Definition: node.hpp:38
std::unordered_map< res_source_info, std::vector< res_source_info > > forwarding_map_t
Definition: node.hpp:43
std::shared_ptr< action_info > sptr
Definition: actions.hpp:32
forwarding_policy_t
Types of property/action forwarding for those not defined by the block itself.
Definition: node.hpp:46
source_t
Definition: res_source_info.hpp:21
std::function< std::recursive_mutex &(void)> graph_mutex_callback_t
Definition: node.hpp:39
Definition: res_source_info.hpp:17
std::unique_ptr< scope_exit > uptr
Definition: scope_exit.hpp:25
#define UHD_API
Definition: config.h:87
Definition: node.hpp:34
Definition: property.hpp:25
std::function< void(void)> resolver_fn_t
Definition: node.hpp:37
Definition: device_addr.hpp:37
virtual ~node_t()
Definition: node.hpp:71