GNU Radio 3.7.1 C++ API
block.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2004,2007,2009,2010,2013 Free Software Foundation, Inc.
4  *
5  * This file is part of GNU Radio
6  *
7  * GNU Radio is free software; you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation; either version 3, or (at your option)
10  * any later version.
11  *
12  * GNU Radio is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with GNU Radio; see the file COPYING. If not, write to
19  * the Free Software Foundation, Inc., 51 Franklin Street,
20  * Boston, MA 02110-1301, USA.
21  */
22 
23 #ifndef INCLUDED_GR_RUNTIME_BLOCK_H
24 #define INCLUDED_GR_RUNTIME_BLOCK_H
25 
26 #include <gnuradio/api.h>
27 #include <gnuradio/basic_block.h>
28 #include <gnuradio/tags.h>
29 #include <gnuradio/logger.h>
30 
31 namespace gr {
32 
33  /*!
34  * \brief The abstract base class for all 'terminal' processing blocks.
35  * \ingroup base_blk
36  *
37  * A signal processing flow is constructed by creating a tree of
38  * hierarchical blocks, which at any level may also contain terminal
39  * nodes that actually implement signal processing functions. This
40  * is the base class for all such leaf nodes.
41  *
42  * Blocks have a set of input streams and output streams. The
43  * input_signature and output_signature define the number of input
44  * streams and output streams respectively, and the type of the data
45  * items in each stream.
46  *
47  * Although blocks may consume data on each input stream at a
48  * different rate, all outputs streams must produce data at the same
49  * rate. That rate may be different from any of the input rates.
50  *
51  * User derived blocks override two methods, forecast and
52  * general_work, to implement their signal processing
53  * behavior. forecast is called by the system scheduler to determine
54  * how many items are required on each input stream in order to
55  * produce a given number of output items.
56  *
57  * general_work is called to perform the signal processing in the
58  * block. It reads the input items and writes the output items.
59  */
61  {
62  public:
63 
64  //! Magic return values from general_work
65  enum {
66  WORK_CALLED_PRODUCE = -2,
67  WORK_DONE = -1
68  };
69 
71  TPP_DONT = 0,
74  };
75 
76  virtual ~block();
77 
78  /*!
79  * Assume block computes y_i = f(x_i, x_i-1, x_i-2, x_i-3...)
80  * History is the number of x_i's that are examined to produce one y_i.
81  * This comes in handy for FIR filters, where we use history to
82  * ensure that our input contains the appropriate "history" for the
83  * filter. History should be equal to the number of filter taps.
84  */
85  unsigned history() const { return d_history; }
86  void set_history(unsigned history) { d_history = history; }
87 
88  /*!
89  * \brief Return true if this block has a fixed input to output rate.
90  *
91  * If true, then fixed_rate_in_to_out and fixed_rate_out_to_in may be called.
92  */
93  bool fixed_rate() const { return d_fixed_rate; }
94 
95  // ----------------------------------------------------------------
96  // override these to define your behavior
97  // ----------------------------------------------------------------
98 
99  /*!
100  * \brief Estimate input requirements given output request
101  *
102  * \param noutput_items number of output items to produce
103  * \param ninput_items_required number of input items required on each input stream
104  *
105  * Given a request to product \p noutput_items, estimate the
106  * number of data items required on each input stream. The
107  * estimate doesn't have to be exact, but should be close.
108  */
109  virtual void forecast(int noutput_items,
110  gr_vector_int &ninput_items_required);
111 
112  /*!
113  * \brief compute output items from input items
114  *
115  * \param noutput_items number of output items to write on each output stream
116  * \param ninput_items number of input items available on each input stream
117  * \param input_items vector of pointers to the input items, one entry per input stream
118  * \param output_items vector of pointers to the output items, one entry per output stream
119  *
120  * \returns number of items actually written to each output stream, or -1 on EOF.
121  * It is OK to return a value less than noutput_items. -1 <= return value <= noutput_items
122  *
123  * general_work must call consume or consume_each to indicate how
124  * many items were consumed on each input stream.
125  */
126  virtual int general_work(int noutput_items,
127  gr_vector_int &ninput_items,
128  gr_vector_const_void_star &input_items,
129  gr_vector_void_star &output_items);
130 
131  /*!
132  * \brief Called to enable drivers, etc for i/o devices.
133  *
134  * This allows a block to enable an associated driver to begin
135  * transfering data just before we start to execute the scheduler.
136  * The end result is that this reduces latency in the pipeline
137  * when dealing with audio devices, usrps, etc.
138  */
139  virtual bool start();
140 
141  /*!
142  * \brief Called to disable drivers, etc for i/o devices.
143  */
144  virtual bool stop();
145 
146  // ----------------------------------------------------------------
147 
148  /*!
149  * \brief Constrain the noutput_items argument passed to forecast and general_work
150  *
151  * set_output_multiple causes the scheduler to ensure that the
152  * noutput_items argument passed to forecast and general_work will
153  * be an integer multiple of \param multiple The default value of
154  * output multiple is 1.
155  */
156  void set_output_multiple(int multiple);
157  int output_multiple() const { return d_output_multiple; }
158  bool output_multiple_set() const { return d_output_multiple_set; }
159 
160  /*!
161  * \brief Constrains buffers to work on a set item alignment (for SIMD)
162  *
163  * set_alignment_multiple causes the scheduler to ensure that the
164  * noutput_items argument passed to forecast and general_work will
165  * be an integer multiple of \param multiple The default value is
166  * 1.
167  *
168  * This control is similar to the output_multiple setting, except
169  * that if the number of items passed to the block is less than
170  * the output_multiple, this value is ignored and the block can
171  * produce like normal. The d_unaligned value is set to the number
172  * of items the block is off by. In the next call to general_work,
173  * the noutput_items is set to d_unaligned or less until
174  * d_unaligned==0. The buffers are now aligned again and the
175  * aligned calls can be performed again.
176  */
177  void set_alignment(int multiple);
178  int alignment() const { return d_output_multiple; }
179 
180  void set_unaligned(int na);
181  int unaligned() const { return d_unaligned; }
182  void set_is_unaligned(bool u);
183  bool is_unaligned() const { return d_is_unaligned; }
184 
185  /*!
186  * \brief Tell the scheduler \p how_many_items of input stream \p
187  * which_input were consumed.
188  */
189  void consume(int which_input, int how_many_items);
190 
191  /*!
192  * \brief Tell the scheduler \p how_many_items were consumed on
193  * each input stream.
194  */
195  void consume_each(int how_many_items);
196 
197  /*!
198  * \brief Tell the scheduler \p how_many_items were produced on
199  * output stream \p which_output.
200  *
201  * If the block's general_work method calls produce, \p
202  * general_work must return WORK_CALLED_PRODUCE.
203  */
204  void produce(int which_output, int how_many_items);
205 
206  /*!
207  * \brief Set the approximate output rate / input rate
208  *
209  * Provide a hint to the buffer allocator and scheduler.
210  * The default relative_rate is 1.0
211  *
212  * decimators have relative_rates < 1.0
213  * interpolators have relative_rates > 1.0
214  */
215  void set_relative_rate(double relative_rate);
216 
217  /*!
218  * \brief return the approximate output rate / input rate
219  */
220  double relative_rate() const { return d_relative_rate; }
221 
222  /*
223  * The following two methods provide special case info to the
224  * scheduler in the event that a block has a fixed input to output
225  * ratio. sync_block, sync_decimator and
226  * sync_interpolator override these. If you're fixed rate,
227  * subclass one of those.
228  */
229  /*!
230  * \brief Given ninput samples, return number of output samples that will be produced.
231  * N.B. this is only defined if fixed_rate returns true.
232  * Generally speaking, you don't need to override this.
233  */
234  virtual int fixed_rate_ninput_to_noutput(int ninput);
235 
236  /*!
237  * \brief Given noutput samples, return number of input samples required to produce noutput.
238  * N.B. this is only defined if fixed_rate returns true.
239  * Generally speaking, you don't need to override this.
240  */
241  virtual int fixed_rate_noutput_to_ninput(int noutput);
242 
243  /*!
244  * \brief Return the number of items read on input stream which_input
245  */
246  uint64_t nitems_read(unsigned int which_input);
247 
248  /*!
249  * \brief Return the number of items written on output stream which_output
250  */
251  uint64_t nitems_written(unsigned int which_output);
252 
253  /*!
254  * \brief Asks for the policy used by the scheduler to moved tags downstream.
255  */
256  tag_propagation_policy_t tag_propagation_policy();
257 
258  /*!
259  * \brief Set the policy by the scheduler to determine how tags are moved downstream.
260  */
261  void set_tag_propagation_policy(tag_propagation_policy_t p);
262 
263  /*!
264  * \brief Return the minimum number of output items this block can
265  * produce during a call to work.
266  *
267  * Should be 0 for most blocks. Useful if we're dealing with
268  * packets and the block produces one packet per call to work.
269  */
270  int min_noutput_items() const { return d_min_noutput_items; }
271 
272  /*!
273  * \brief Set the minimum number of output items this block can
274  * produce during a call to work.
275  *
276  * \param m the minimum noutput_items this block can produce.
277  */
278  void set_min_noutput_items(int m) { d_min_noutput_items = m; }
279 
280  /*!
281  * \brief Return the maximum number of output items this block will
282  * handle during a call to work.
283  */
284  int max_noutput_items();
285 
286  /*!
287  * \brief Set the maximum number of output items this block will
288  * handle during a call to work.
289  *
290  * \param m the maximum noutput_items this block will handle.
291  */
292  void set_max_noutput_items(int m);
293 
294  /*!
295  * \brief Clear the switch for using the max_noutput_items value of this block.
296  *
297  * When is_set_max_noutput_items() returns 'true', the scheduler
298  * will use the value returned by max_noutput_items() to limit the
299  * size of the number of items possible for this block's work
300  * function. If is_set_max_notput_items() returns 'false', then
301  * the scheduler ignores the internal value and uses the value set
302  * globally in the top_block.
303  *
304  * Use this value to clear the 'is_set' flag so the scheduler will
305  * ignore this. Use the set_max_noutput_items(m) call to both set
306  * a new value for max_noutput_items and to reenable its use in
307  * the scheduler.
308  */
309  void unset_max_noutput_items();
310 
311  /*!
312  * \brief Ask the block if the flag is or is not set to use the
313  * internal value of max_noutput_items during a call to work.
314  */
315  bool is_set_max_noutput_items();
316 
317  /*
318  * Used to expand the vectors that hold the min/max buffer sizes.
319  *
320  * Specifically, when -1 is used, the vectors are just initialized
321  * with 1 value; this is used by the flat_flowgraph to expand when
322  * required to add a new value for new ports on these blocks.
323  */
324  void expand_minmax_buffer(int port);
325 
326  /*!
327  * \brief Returns max buffer size on output port \p i.
328  */
329  long max_output_buffer(size_t i);
330 
331  /*!
332  * \brief Sets max buffer size on all output ports.
333  */
334  void set_max_output_buffer(long max_output_buffer);
335 
336  /*!
337  * \brief Sets max buffer size on output port \p port.
338  */
339  void set_max_output_buffer(int port, long max_output_buffer);
340 
341  /*!
342  * \brief Returns min buffer size on output port \p i.
343  */
344  long min_output_buffer(size_t i);
345 
346  /*!
347  * \brief Sets min buffer size on all output ports.
348  */
349  void set_min_output_buffer(long min_output_buffer);
350 
351  /*!
352  * \brief Sets min buffer size on output port \p port.
353  */
354  void set_min_output_buffer(int port, long min_output_buffer);
355 
356  // --------------- Performance counter functions -------------
357 
358  /*!
359  * \brief Gets instantaneous noutput_items performance counter.
360  */
361  float pc_noutput_items();
362 
363  /*!
364  * \brief Gets average noutput_items performance counter.
365  */
366  float pc_noutput_items_avg();
367 
368  /*!
369  * \brief Gets variance of noutput_items performance counter.
370  */
371  float pc_noutput_items_var();
372 
373  /*!
374  * \brief Gets instantaneous num items produced performance counter.
375  */
376  float pc_nproduced();
377 
378  /*!
379  * \brief Gets average num items produced performance counter.
380  */
381  float pc_nproduced_avg();
382 
383  /*!
384  * \brief Gets variance of num items produced performance counter.
385  */
386  float pc_nproduced_var();
387 
388  /*!
389  * \brief Gets instantaneous fullness of \p which input buffer.
390  */
391  float pc_input_buffers_full(int which);
392 
393  /*!
394  * \brief Gets average fullness of \p which input buffer.
395  */
396  float pc_input_buffers_full_avg(int which);
397 
398  /*!
399  * \brief Gets variance of fullness of \p which input buffer.
400  */
401  float pc_input_buffers_full_var(int which);
402 
403  /*!
404  * \brief Gets instantaneous fullness of all input buffers.
405  */
406  std::vector<float> pc_input_buffers_full();
407 
408  /*!
409  * \brief Gets average fullness of all input buffers.
410  */
411  std::vector<float> pc_input_buffers_full_avg();
412 
413  /*!
414  * \brief Gets variance of fullness of all input buffers.
415  */
416  std::vector<float> pc_input_buffers_full_var();
417 
418  /*!
419  * \brief Gets instantaneous fullness of \p which input buffer.
420  */
421  float pc_output_buffers_full(int which);
422 
423  /*!
424  * \brief Gets average fullness of \p which input buffer.
425  */
426  float pc_output_buffers_full_avg(int which);
427 
428  /*!
429  * \brief Gets variance of fullness of \p which input buffer.
430  */
431  float pc_output_buffers_full_var(int which);
432 
433  /*!
434  * \brief Gets instantaneous fullness of all output buffers.
435  */
436  std::vector<float> pc_output_buffers_full();
437 
438  /*!
439  * \brief Gets average fullness of all output buffers.
440  */
441  std::vector<float> pc_output_buffers_full_avg();
442 
443  /*!
444  * \brief Gets variance of fullness of all output buffers.
445  */
446  std::vector<float> pc_output_buffers_full_var();
447 
448  /*!
449  * \brief Gets instantaneous clock cycles spent in work.
450  */
451  float pc_work_time();
452 
453  /*!
454  * \brief Gets average clock cycles spent in work.
455  */
456  float pc_work_time_avg();
457 
458  /*!
459  * \brief Gets average clock cycles spent in work.
460  */
461  float pc_work_time_var();
462 
463  /*!
464  * \brief Gets total clock cycles spent in work.
465  */
466  float pc_work_time_total();
467 
468  /*!
469  * \brief Resets the performance counters
470  */
471  void reset_perf_counters();
472 
473  /*!
474  * \brief Sets up export of perf. counters to ControlPort. Only
475  * called by the scheduler.
476  */
477  void setup_pc_rpc();
478 
479  /*!
480  * \brief Checks if this block is already exporting perf. counters
481  * to ControlPort.
482  */
483  bool is_pc_rpc_set() { return d_pc_rpc_set; }
484 
485  /*!
486  * \brief If the block calls this in its constructor, it's
487  * perf. counters will not be exported.
488  */
489  void no_pc_rpc() { d_pc_rpc_set = true; }
490 
491 
492  // ----------------------------------------------------------------------------
493  // Functions to handle thread affinity
494 
495  /*!
496  * \brief Set the thread's affinity to processor core \p n.
497  *
498  * \param mask a vector of ints of the core numbers available to this block.
499  */
500  void set_processor_affinity(const std::vector<int> &mask);
501 
502  /*!
503  * \brief Remove processor affinity to a specific core.
504  */
505  void unset_processor_affinity();
506 
507  /*!
508  * \brief Get the current processor affinity.
509  */
510  std::vector<int> processor_affinity() { return d_affinity; }
511 
512  /*!
513  * \brief Get the current thread priority in use
514  */
515  int active_thread_priority();
516 
517  /*!
518  * \brief Get the current thread priority stored
519  */
520  int thread_priority();
521 
522  /*!
523  * \brief Set the current thread priority
524  */
525  int set_thread_priority(int priority);
526 
527  // ----------------------------------------------------------------------------
528 
529  private:
530  int d_output_multiple;
531  bool d_output_multiple_set;
532  int d_unaligned;
533  bool d_is_unaligned;
534  double d_relative_rate; // approx output_rate / input_rate
535  block_detail_sptr d_detail; // implementation details
536  unsigned d_history;
537  bool d_fixed_rate;
538  bool d_max_noutput_items_set; // if d_max_noutput_items is valid
539  int d_max_noutput_items; // value of max_noutput_items for this block
540  int d_min_noutput_items;
541  tag_propagation_policy_t d_tag_propagation_policy; // policy for moving tags downstream
542  std::vector<int> d_affinity; // thread affinity proc. mask
543  int d_priority; // thread priority level
544  bool d_pc_rpc_set;
545 
546  protected:
547  block(void) {} // allows pure virtual interface sub-classes
548  block(const std::string &name,
549  gr::io_signature::sptr input_signature,
550  gr::io_signature::sptr output_signature);
551 
552  void set_fixed_rate(bool fixed_rate) { d_fixed_rate = fixed_rate; }
553 
554  /*!
555  * \brief Adds a new tag onto the given output buffer.
556  *
557  * \param which_output an integer of which output stream to attach the tag
558  * \param abs_offset a uint64 number of the absolute item number
559  * assicated with the tag. Can get from nitems_written.
560  * \param key the tag key as a PMT symbol
561  * \param value any PMT holding any value for the given key
562  * \param srcid optional source ID specifier; defaults to PMT_F
563  */
564  inline void add_item_tag(unsigned int which_output,
565  uint64_t abs_offset,
566  const pmt::pmt_t &key,
567  const pmt::pmt_t &value,
568  const pmt::pmt_t &srcid=pmt::PMT_F)
569  {
570  tag_t tag;
571  tag.offset = abs_offset;
572  tag.key = key;
573  tag.value = value;
574  tag.srcid = srcid;
575  this->add_item_tag(which_output, tag);
576  }
577 
578  /*!
579  * \brief Adds a new tag onto the given output buffer.
580  *
581  * \param which_output an integer of which output stream to attach the tag
582  * \param tag the tag object to add
583  */
584  void add_item_tag(unsigned int which_output, const tag_t &tag);
585 
586  /*!
587  * \brief Removes a tag from the given input buffer.
588  *
589  * \param which_input an integer of which input stream to remove the tag from
590  * \param abs_offset a uint64 number of the absolute item number
591  * assicated with the tag. Can get from nitems_written.
592  * \param key the tag key as a PMT symbol
593  * \param value any PMT holding any value for the given key
594  * \param srcid optional source ID specifier; defaults to PMT_F
595  *
596  * If no such tag is found, does nothing.
597  */
598  inline void remove_item_tag(unsigned int which_input,
599  uint64_t abs_offset,
600  const pmt::pmt_t &key,
601  const pmt::pmt_t &value,
602  const pmt::pmt_t &srcid=pmt::PMT_F)
603  {
604  tag_t tag;
605  tag.offset = abs_offset;
606  tag.key = key;
607  tag.value = value;
608  tag.srcid = srcid;
609  this->remove_item_tag(which_input, tag);
610  }
611 
612  /*!
613  * \brief Removes a tag from the given input buffer.
614  *
615  * If no such tag is found, does nothing.
616  *
617  * \param which_input an integer of which input stream to remove the tag from
618  * \param tag the tag object to remove
619  */
620  void remove_item_tag(unsigned int which_input, const tag_t &tag);
621 
622  /*!
623  * \brief Given a [start,end), returns a vector of all tags in the range.
624  *
625  * Range of counts is from start to end-1.
626  *
627  * Tags are tuples of:
628  * (item count, source id, key, value)
629  *
630  * \param v a vector reference to return tags into
631  * \param which_input an integer of which input stream to pull from
632  * \param abs_start a uint64 count of the start of the range of interest
633  * \param abs_end a uint64 count of the end of the range of interest
634  */
635  void get_tags_in_range(std::vector<tag_t> &v,
636  unsigned int which_input,
637  uint64_t abs_start,
638  uint64_t abs_end);
639 
640  /*!
641  * \brief Given a [start,end), returns a vector of all tags in the
642  * range with a given key.
643  *
644  * Range of counts is from start to end-1.
645  *
646  * Tags are tuples of:
647  * (item count, source id, key, value)
648  *
649  * \param v a vector reference to return tags into
650  * \param which_input an integer of which input stream to pull from
651  * \param abs_start a uint64 count of the start of the range of interest
652  * \param abs_end a uint64 count of the end of the range of interest
653  * \param key a PMT symbol key to filter only tags of this key
654  */
655  void get_tags_in_range(std::vector<tag_t> &v,
656  unsigned int which_input,
657  uint64_t abs_start,
658  uint64_t abs_end,
659  const pmt::pmt_t &key);
660 
661  std::vector<long> d_max_output_buffer;
662  std::vector<long> d_min_output_buffer;
663 
664  /*! Used by block's setters and work functions to make
665  * setting/resetting of parameters thread-safe.
666  *
667  * Used by calling gr::thread::scoped_lock l(d_setlock);
668  */
670 
671  /*! Used by blocks to access the logger system.
672  */
675 
676  // These are really only for internal use, but leaving them public avoids
677  // having to work up an ever-varying list of friend GR_RUNTIME_APIs
678 
679  public:
680  block_detail_sptr detail() const { return d_detail; }
681  void set_detail(block_detail_sptr detail) { d_detail = detail; }
682  };
683 
684  typedef std::vector<block_sptr> block_vector_t;
685  typedef std::vector<block_sptr>::iterator block_viter_t;
686 
687  inline block_sptr cast_to_block_sptr(basic_block_sptr p)
688  {
689  return boost::dynamic_pointer_cast<block, basic_block>(p);
690  }
691 
692  std::ostream&
693  operator << (std::ostream& os, const block *m);
694 
695 } /* namespace gr */
696 
697 #endif /* INCLUDED_GR_RUNTIME_BLOCK_H */