git.gag.com Git - debian/gnuradio/blob - gnuradio-core/src/lib/runtime/gr_block.h

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2004,2007,2009 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_BLOCK_H
  24 #define INCLUDED_GR_BLOCK_H
  25
  26 #include <gr_basic_block.h>
  27
  28 /*!
  29  * \brief The abstract base class for all 'terminal' processing blocks.
  30  * \ingroup base_blk
  31  *
  32  * A signal processing flow is constructed by creating a tree of
  33  * hierarchical blocks, which at any level may also contain terminal nodes
  34  * that actually implement signal processing functions. This is the base
  35  * class for all such leaf nodes.
  36
  37  * Blocks have a set of input streams and output streams.  The
  38  * input_signature and output_signature define the number of input
  39  * streams and output streams respectively, and the type of the data
  40  * items in each stream.
  41  *
  42  * Although blocks may consume data on each input stream at a
  43  * different rate, all outputs streams must produce data at the same
  44  * rate.  That rate may be different from any of the input rates.
  45  *
  46  * User derived blocks override two methods, forecast and general_work,
  47  * to implement their signal processing behavior. forecast is called
  48  * by the system scheduler to determine how many items are required on
  49  * each input stream in order to produce a given number of output
  50  * items.
  51  *
  52  * general_work is called to perform the signal processing in the block.
  53  * It reads the input items and writes the output items.
  54  */
  55
  56 class gr_block : public gr_basic_block {
  57
  58  public:
  59
  60   //! Magic return values from general_work
  61   enum {
  62     WORK_CALLED_PRODUCE = -2,
  63     WORK_DONE = -1
  64   };
  65
  66   virtual ~gr_block ();
  67
  68   /*!
  69    * Assume block computes y_i = f(x_i, x_i-1, x_i-2, x_i-3...)
  70    * History is the number of x_i's that are examined to produce one y_i.
  71    * This comes in handy for FIR filters, where we use history to
  72    * ensure that our input contains the appropriate "history" for the
  73    * filter.   History should be equal to the number of filter taps.
  74    */
  75   unsigned history () const { return d_history; }
  76   void  set_history (unsigned history) { d_history = history; }
  77
  78   /*!
  79    * \brief Return true if this block has a fixed input to output rate.
  80    *
  81    * If true, then fixed_rate_in_to_out and fixed_rate_out_to_in may be called.
  82    */
  83   bool fixed_rate() const { return d_fixed_rate; }
  84
  85   // ----------------------------------------------------------------
  86   //            override these to define your behavior
  87   // ----------------------------------------------------------------
  88
  89   /*!
  90    * \brief  Estimate input requirements given output request
  91    *
  92    * \param noutput_items           number of output items to produce
  93    * \param ninput_items_required   number of input items required on each input stream
  94    *
  95    * Given a request to product \p noutput_items, estimate the number of
  96    * data items required on each input stream.  The estimate doesn't have
  97    * to be exact, but should be close.
  98    */
  99   virtual void forecast (int noutput_items,
 100                          gr_vector_int &ninput_items_required);
 101
 102   /*!
 103    * \brief compute output items from input items
 104    *
 105    * \param noutput_items       number of output items to write on each output stream
 106    * \param ninput_items        number of input items available on each input stream
 107    * \param input_items         vector of pointers to the input items, one entry per input stream
 108    * \param output_items        vector of pointers to the output items, one entry per output stream
 109    *
 110    * \returns number of items actually written to each output stream, or -1 on EOF.
 111    * It is OK to return a value less than noutput_items.  -1 <= return value <= noutput_items
 112    *
 113    * general_work must call consume or consume_each to indicate how many items
 114    * were consumed on each input stream.
 115    */
 116   virtual int general_work (int noutput_items,
 117                             gr_vector_int &ninput_items,
 118                             gr_vector_const_void_star &input_items,
 119                             gr_vector_void_star &output_items) = 0;
 120
 121   /*!
 122    * \brief Called to enable drivers, etc for i/o devices.
 123    *
 124    * This allows a block to enable an associated driver to begin
 125    * transfering data just before we start to execute the scheduler.
 126    * The end result is that this reduces latency in the pipeline when
 127    * dealing with audio devices, usrps, etc.
 128    */
 129   virtual bool start();
 130
 131   /*!
 132    * \brief Called to disable drivers, etc for i/o devices.
 133    */
 134   virtual bool stop();
 135
 136   // ----------------------------------------------------------------
 137
 138   /*!
 139    * \brief Constrain the noutput_items argument passed to forecast and general_work
 140    *
 141    * set_output_multiple causes the scheduler to ensure that the noutput_items
 142    * argument passed to forecast and general_work will be an integer multiple
 143    * of \param multiple  The default value of output multiple is 1.
 144    */
 145   void set_output_multiple (int multiple);
 146   int  output_multiple () const { return d_output_multiple; }
 147
 148   /*!
 149    * \brief Tell the scheduler \p how_many_items of input stream \p which_input were consumed.
 150    */
 151   void consume (int which_input, int how_many_items);
 152
 153   /*!
 154    * \brief Tell the scheduler \p how_many_items were consumed on each input stream.
 155    */
 156   void consume_each (int how_many_items);
 157
 158   /*!
 159    * \brief Tell the scheduler \p how_many_items were produced on output stream \p which_output.
 160    *
 161    * If the block's general_work method calls produce, \p general_work must return WORK_CALLED_PRODUCE.
 162    */
 163   void produce (int which_output, int how_many_items);
 164
 165   /*!
 166    * \brief Set the approximate output rate / input rate
 167    *
 168    * Provide a hint to the buffer allocator and scheduler.
 169    * The default relative_rate is 1.0
 170    *
 171    * decimators have relative_rates < 1.0
 172    * interpolators have relative_rates > 1.0
 173    */
 174   void  set_relative_rate (double relative_rate);
 175
 176   /*!
 177    * \brief return the approximate output rate / input rate
 178    */
 179   double relative_rate () const { return d_relative_rate; }
 180
 181   /*
 182    * The following two methods provide special case info to the
 183    * scheduler in the event that a block has a fixed input to output
 184    * ratio.  gr_sync_block, gr_sync_decimator and gr_sync_interpolator
 185    * override these.  If you're fixed rate, subclass one of those.
 186    */
 187   /*!
 188    * \brief Given ninput samples, return number of output samples that will be produced.
 189    * N.B. this is only defined if fixed_rate returns true.
 190    * Generally speaking, you don't need to override this.
 191    */
 192   virtual int fixed_rate_ninput_to_noutput(int ninput);
 193
 194   /*!
 195    * \brief Given noutput samples, return number of input samples required to produce noutput.
 196    * N.B. this is only defined if fixed_rate returns true.
 197    * Generally speaking, you don't need to override this.
 198    */
 199   virtual int fixed_rate_noutput_to_ninput(int noutput);
 200
 201   // ----------------------------------------------------------------------------
 202
 203  private:
 204
 205   int                   d_output_multiple;
 206   double                d_relative_rate;        // approx output_rate / input_rate
 207   gr_block_detail_sptr  d_detail;               // implementation details
 208   unsigned              d_history;
 209   bool                  d_fixed_rate;
 210
 211  protected:
 212
 213   gr_block (const std::string &name,
 214             gr_io_signature_sptr input_signature,
 215             gr_io_signature_sptr output_signature);
 216
 217   void set_fixed_rate(bool fixed_rate){ d_fixed_rate = fixed_rate; }
 218
 219   // These are really only for internal use, but leaving them public avoids
 220   // having to work up an ever-varying list of friends
 221
 222  public:
 223   gr_block_detail_sptr detail () const { return d_detail; }
 224   void set_detail (gr_block_detail_sptr detail) { d_detail = detail; }
 225 };
 226
 227 typedef std::vector<gr_block_sptr> gr_block_vector_t;
 228 typedef std::vector<gr_block_sptr>::iterator gr_block_viter_t;
 229
 230 inline gr_block_sptr cast_to_block_sptr(gr_basic_block_sptr p)
 231 {
 232   return boost::dynamic_pointer_cast<gr_block, gr_basic_block>(p);
 233 }
 234
 235
 236 std::ostream&
 237 operator << (std::ostream& os, const gr_block *m);
 238
 239 #endif /* INCLUDED_GR_BLOCK_H */