GNU Radio 3.4.0 C++ API
gr_block.h
Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2004,2007,2009,2010 Free Software Foundation, Inc.
00004  * 
00005  * This file is part of GNU Radio
00006  * 
00007  * GNU Radio is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 3, or (at your option)
00010  * any later version.
00011  * 
00012  * GNU Radio is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  * 
00017  * You should have received a copy of the GNU General Public License
00018  * along with GNU Radio; see the file COPYING.  If not, write to
00019  * the Free Software Foundation, Inc., 51 Franklin Street,
00020  * Boston, MA 02110-1301, USA.
00021  */
00022 
00023 #ifndef INCLUDED_GR_BLOCK_H
00024 #define INCLUDED_GR_BLOCK_H
00025 
00026 #include <gr_basic_block.h>
00027 
00028 /*!
00029  * \brief The abstract base class for all 'terminal' processing blocks.
00030  * \ingroup base_blk
00031  *
00032  * A signal processing flow is constructed by creating a tree of 
00033  * hierarchical blocks, which at any level may also contain terminal nodes
00034  * that actually implement signal processing functions. This is the base
00035  * class for all such leaf nodes.
00036  
00037  * Blocks have a set of input streams and output streams.  The
00038  * input_signature and output_signature define the number of input
00039  * streams and output streams respectively, and the type of the data
00040  * items in each stream.
00041  *
00042  * Although blocks may consume data on each input stream at a
00043  * different rate, all outputs streams must produce data at the same
00044  * rate.  That rate may be different from any of the input rates.
00045  *
00046  * User derived blocks override two methods, forecast and general_work,
00047  * to implement their signal processing behavior. forecast is called
00048  * by the system scheduler to determine how many items are required on
00049  * each input stream in order to produce a given number of output
00050  * items.
00051  *
00052  * general_work is called to perform the signal processing in the block.
00053  * It reads the input items and writes the output items.
00054  */
00055 
00056 class gr_block : public gr_basic_block {
00057 
00058  public:
00059   
00060   //! Magic return values from general_work
00061   enum {
00062     WORK_CALLED_PRODUCE = -2,
00063     WORK_DONE = -1
00064   };
00065 
00066   enum tag_propagation_policy_t {
00067     TPP_DONT = 0,
00068     TPP_ALL_TO_ALL = 1,
00069     TPP_ONE_TO_ONE = 2
00070   };
00071 
00072   virtual ~gr_block ();
00073 
00074   /*!
00075    * Assume block computes y_i = f(x_i, x_i-1, x_i-2, x_i-3...)
00076    * History is the number of x_i's that are examined to produce one y_i.
00077    * This comes in handy for FIR filters, where we use history to
00078    * ensure that our input contains the appropriate "history" for the
00079    * filter.   History should be equal to the number of filter taps.
00080    */
00081   unsigned history () const { return d_history; }
00082   void  set_history (unsigned history) { d_history = history; }
00083   
00084   /*!
00085    * \brief Return true if this block has a fixed input to output rate.
00086    *
00087    * If true, then fixed_rate_in_to_out and fixed_rate_out_to_in may be called.
00088    */
00089   bool fixed_rate() const { return d_fixed_rate; }
00090 
00091   // ----------------------------------------------------------------
00092   //            override these to define your behavior
00093   // ----------------------------------------------------------------
00094 
00095   /*!
00096    * \brief  Estimate input requirements given output request
00097    *
00098    * \param noutput_items           number of output items to produce
00099    * \param ninput_items_required   number of input items required on each input stream
00100    *
00101    * Given a request to product \p noutput_items, estimate the number of
00102    * data items required on each input stream.  The estimate doesn't have
00103    * to be exact, but should be close.
00104    */
00105   virtual void forecast (int noutput_items,
00106                          gr_vector_int &ninput_items_required);
00107 
00108   /*!
00109    * \brief compute output items from input items
00110    *
00111    * \param noutput_items       number of output items to write on each output stream
00112    * \param ninput_items        number of input items available on each input stream
00113    * \param input_items         vector of pointers to the input items, one entry per input stream
00114    * \param output_items        vector of pointers to the output items, one entry per output stream
00115    *
00116    * \returns number of items actually written to each output stream, or -1 on EOF.
00117    * It is OK to return a value less than noutput_items.  -1 <= return value <= noutput_items
00118    *
00119    * general_work must call consume or consume_each to indicate how many items
00120    * were consumed on each input stream.
00121    */
00122   virtual int general_work (int noutput_items,
00123                             gr_vector_int &ninput_items,
00124                             gr_vector_const_void_star &input_items,
00125                             gr_vector_void_star &output_items) = 0;
00126 
00127   /*!
00128    * \brief Called to enable drivers, etc for i/o devices.
00129    *
00130    * This allows a block to enable an associated driver to begin
00131    * transfering data just before we start to execute the scheduler.
00132    * The end result is that this reduces latency in the pipeline when
00133    * dealing with audio devices, usrps, etc.
00134    */
00135   virtual bool start();
00136 
00137   /*!
00138    * \brief Called to disable drivers, etc for i/o devices.
00139    */
00140   virtual bool stop();
00141 
00142   // ----------------------------------------------------------------
00143 
00144   /*!
00145    * \brief Constrain the noutput_items argument passed to forecast and general_work
00146    *
00147    * set_output_multiple causes the scheduler to ensure that the noutput_items
00148    * argument passed to forecast and general_work will be an integer multiple
00149    * of \param multiple  The default value of output multiple is 1.
00150    */
00151   void set_output_multiple (int multiple);
00152   int  output_multiple () const { return d_output_multiple; }
00153 
00154   /*!
00155    * \brief Tell the scheduler \p how_many_items of input stream \p which_input were consumed.
00156    */
00157   void consume (int which_input, int how_many_items);
00158 
00159   /*!
00160    * \brief Tell the scheduler \p how_many_items were consumed on each input stream.
00161    */
00162   void consume_each (int how_many_items);
00163 
00164   /*!
00165    * \brief Tell the scheduler \p how_many_items were produced on output stream \p which_output.
00166    *
00167    * If the block's general_work method calls produce, \p general_work must return WORK_CALLED_PRODUCE.
00168    */
00169   void produce (int which_output, int how_many_items);
00170 
00171   /*!
00172    * \brief Set the approximate output rate / input rate
00173    *
00174    * Provide a hint to the buffer allocator and scheduler.
00175    * The default relative_rate is 1.0
00176    *
00177    * decimators have relative_rates < 1.0
00178    * interpolators have relative_rates > 1.0
00179    */
00180   void  set_relative_rate (double relative_rate);
00181 
00182   /*!
00183    * \brief return the approximate output rate / input rate
00184    */
00185   double relative_rate () const { return d_relative_rate; }
00186 
00187   /*
00188    * The following two methods provide special case info to the
00189    * scheduler in the event that a block has a fixed input to output
00190    * ratio.  gr_sync_block, gr_sync_decimator and gr_sync_interpolator
00191    * override these.  If you're fixed rate, subclass one of those.
00192    */
00193   /*!
00194    * \brief Given ninput samples, return number of output samples that will be produced.
00195    * N.B. this is only defined if fixed_rate returns true.
00196    * Generally speaking, you don't need to override this.
00197    */
00198   virtual int fixed_rate_ninput_to_noutput(int ninput);
00199 
00200   /*!
00201    * \brief Given noutput samples, return number of input samples required to produce noutput.
00202    * N.B. this is only defined if fixed_rate returns true.
00203    * Generally speaking, you don't need to override this.
00204    */
00205   virtual int fixed_rate_noutput_to_ninput(int noutput);
00206 
00207   /*!
00208    * \brief Return the number of items read on input stream which_input
00209    */
00210   uint64_t nitems_read(unsigned int which_input);
00211 
00212   /*!
00213    * \brief  Return the number of items written on output stream which_output
00214    */
00215   uint64_t nitems_written(unsigned int which_output);
00216 
00217   /*!
00218    * \brief Asks for the policy used by the scheduler to moved tags downstream.
00219    */
00220   tag_propagation_policy_t tag_propagation_policy();
00221 
00222   /*!
00223    * \brief Set the policy by the scheduler to determine how tags are moved downstream.
00224    */
00225   void set_tag_propagation_policy(tag_propagation_policy_t p);
00226 
00227   // ----------------------------------------------------------------------------
00228 
00229  private:
00230 
00231   int                   d_output_multiple;
00232   double                d_relative_rate;        // approx output_rate / input_rate
00233   gr_block_detail_sptr  d_detail;               // implementation details
00234   unsigned              d_history;
00235   bool                  d_fixed_rate;
00236   tag_propagation_policy_t d_tag_propagation_policy; // policy for moving tags downstream
00237     
00238  protected:
00239   gr_block (void){} //allows pure virtual interface sub-classes
00240   gr_block (const std::string &name,
00241             gr_io_signature_sptr input_signature,
00242             gr_io_signature_sptr output_signature);
00243 
00244   void set_fixed_rate(bool fixed_rate){ d_fixed_rate = fixed_rate; }
00245 
00246   
00247   /*!
00248    * \brief  Adds a new tag onto the given output buffer.
00249    * 
00250    * \param which_output an integer of which output stream to attach the tag
00251    * \param abs_offset   a uint64 number of the absolute item number
00252    *                     assicated with the tag. Can get from nitems_written.
00253    * \param key          the tag key as a PMT symbol
00254    * \param value        any PMT holding any value for the given key
00255    * \param srcid        optional source ID specifier; defaults to PMT_F
00256    */
00257   void add_item_tag(unsigned int which_output,
00258                     uint64_t abs_offset,
00259                     const pmt::pmt_t &key,
00260                     const pmt::pmt_t &value,
00261                     const pmt::pmt_t &srcid=pmt::PMT_F);
00262 
00263   /*!
00264    * \brief Given a [start,end), returns a vector of all tags in the range.
00265    *
00266    * Range of counts is from start to end-1.
00267    *
00268    * Tags are tuples of:
00269    *      (item count, source id, key, value)
00270    *
00271    * \param v            a vector reference to return tags into
00272    * \param which_input  an integer of which input stream to pull from
00273    * \param abs_start    a uint64 count of the start of the range of interest
00274    * \param abs_end      a uint64 count of the end of the range of interest
00275    */
00276   void get_tags_in_range(std::vector<pmt::pmt_t> &v,
00277                          unsigned int which_input,
00278                          uint64_t abs_start,
00279                          uint64_t abs_end);
00280   
00281   /*!
00282    * \brief Given a [start,end), returns a vector of all tags in the range
00283    * with a given key.
00284    *
00285    * Range of counts is from start to end-1.
00286    *
00287    * Tags are tuples of:
00288    *      (item count, source id, key, value)
00289    *
00290    * \param v            a vector reference to return tags into
00291    * \param which_input  an integer of which input stream to pull from
00292    * \param abs_start    a uint64 count of the start of the range of interest
00293    * \param abs_end      a uint64 count of the end of the range of interest
00294    * \param key          a PMT symbol key to filter only tags of this key
00295    */
00296   void get_tags_in_range(std::vector<pmt::pmt_t> &v,
00297                          unsigned int which_input,
00298                          uint64_t abs_start,
00299                          uint64_t abs_end,
00300                          const pmt::pmt_t &key);
00301 
00302   // These are really only for internal use, but leaving them public avoids
00303   // having to work up an ever-varying list of friends
00304 
00305  public:
00306   gr_block_detail_sptr detail () const { return d_detail; }
00307   void set_detail (gr_block_detail_sptr detail) { d_detail = detail; }
00308 };
00309 
00310 typedef std::vector<gr_block_sptr> gr_block_vector_t;
00311 typedef std::vector<gr_block_sptr>::iterator gr_block_viter_t;
00312 
00313 inline gr_block_sptr cast_to_block_sptr(gr_basic_block_sptr p)
00314 {
00315   return boost::dynamic_pointer_cast<gr_block, gr_basic_block>(p);
00316 }
00317 
00318 
00319 std::ostream&
00320 operator << (std::ostream& os, const gr_block *m);
00321 
00322 #endif /* INCLUDED_GR_BLOCK_H */