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

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2004 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_runtime.h>
  27 #include <string>
  28
  29 /*!
  30  * \brief The abstract base class for all signal processing blocks.
  31  * \ingroup block
  32  *
  33  * Blocks have a set of input streams and output streams.  The
  34  * input_signature and output_signature define the number of input
  35  * streams and output streams respectively, and the type of the data
  36  * items in each stream.
  37  *
  38  * Although blocks may consume data on each input stream at a
  39  * different rate, all outputs streams must produce data at the same
  40  * rate.  That rate may be different from any of the input rates.
  41  *
  42  * User derived blocks override two methods, forecast and general_work,
  43  * to implement their signal processing behavior. forecast is called
  44  * by the system scheduler to determine how many items are required on
  45  * each input stream in order to produce a given number of output
  46  * items.
  47  *
  48  * general_work is called to perform the signal processing in the block.
  49  * It reads the input items and writes the output items.
  50  */
  51
  52 class gr_block {
  53
  54  public:
  55
  56   virtual ~gr_block ();
  57
  58   std::string name () const { return d_name; }
  59   gr_io_signature_sptr input_signature () const  { return d_input_signature; }
  60   gr_io_signature_sptr output_signature () const { return d_output_signature; }
  61   long unique_id () const { return d_unique_id; }
  62
  63   /*!
  64    * Assume block computes y_i = f(x_i, x_i-1, x_i-2, x_i-3...)
  65    * History is the number of x_i's that are examined to produce one y_i.
  66    * This comes in handy for FIR filters, where we use history to
  67    * ensure that our input contains the appropriate "history" for the
  68    * filter.   History should be equal to the number of filter taps.
  69    */
  70   unsigned history () const { return d_history; }
  71   void  set_history (unsigned history) { d_history = history; }
  72
  73   /*!
  74    * \brief return true if this block has a fixed input to output rate
  75    *
  76    * If true, then fixed_rate_in_to_out and fixed_rate_out_to_in may be called.
  77    */
  78   bool fixed_rate() const { return d_fixed_rate; }
  79
  80   // ----------------------------------------------------------------
  81   //            override these to define your behavior
  82   // ----------------------------------------------------------------
  83
  84   /*!
  85    * \brief  Estimate input requirements given output request
  86    *
  87    * \param noutput_items           number of output items to produce
  88    * \param ninput_items_required   number of input items required on each input stream
  89    *
  90    * Given a request to product \p noutput_items, estimate the number of
  91    * data items required on each input stream.  The estimate doesn't have
  92    * to be exact, but should be close.
  93    */
  94   virtual void forecast (int noutput_items,
  95                          gr_vector_int &ninput_items_required);
  96
  97   /*!
  98    * \brief compute output items from input items
  99    *
 100    * \param noutput_items       number of output items to write on each output stream
 101    * \param ninput_items        number of input items available on each input stream
 102    * \param input_items         vector of pointers to the input items, one entry per input stream
 103    * \param output_items        vector of pointers to the output items, one entry per output stream
 104    *
 105    * \returns number of items actually written to each output stream, or -1 on EOF.
 106    * It is OK to return a value less than noutput_items.  -1 <= return value <= noutput_items
 107    *
 108    * general_work must call consume or consume_each to indicate how many items
 109    * were consumed on each input stream.
 110    */
 111   virtual int general_work (int noutput_items,
 112                             gr_vector_int &ninput_items,
 113                             gr_vector_const_void_star &input_items,
 114                             gr_vector_void_star &output_items) = 0;
 115
 116   /*!
 117    * \brief Confirm that ninputs and noutputs is an acceptable combination.
 118    *
 119    * \param ninputs     number of input streams connected
 120    * \param noutputs    number of output streams connected
 121    *
 122    * \returns true if this is a valid configuration for this block.
 123    *
 124    * This function is called by the runtime system whenever the
 125    * topology changes.  Most classes do not need to override this.
 126    * This check is in addition to the constraints specified by the input
 127    * and output gr_io_signatures.
 128    */
 129   virtual bool check_topology (int ninputs, int noutputs);
 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 when
 137    * 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 noutput_items
 152    * argument passed to forecast and general_work will be an integer multiple
 153    * of \param multiple  The default value of output multiple is 1.
 154    */
 155   void set_output_multiple (int multiple);
 156   int  output_multiple () const { return d_output_multiple; }
 157
 158   /*!
 159    * \brief Tell the scheduler \p how_many_items of input stream \p which_input were consumed.
 160    */
 161   void consume (int which_input, int how_many_items);
 162
 163   /*!
 164    * \brief Tell the scheduler \p how_many_items were consumed on each input stream.
 165    */
 166   void consume_each (int how_many_items);
 167
 168   /*!
 169    * \brief Set the approximate output rate / input rate
 170    *
 171    * Provide a hint to the buffer allocator and scheduler.
 172    * The default relative_rate is 1.0
 173    *
 174    * decimators have relative_rates < 1.0
 175    * interpolators have relative_rates > 1.0
 176    */
 177   void  set_relative_rate (double relative_rate);
 178
 179   /*!
 180    * \brief return the approximate output rate / input rate
 181    */
 182   double relative_rate () const { return d_relative_rate; }
 183
 184   /*
 185    * The following two methods provide special case info to the
 186    * scheduler in the event that a block has a fixed input to output
 187    * ratio.  gr_sync_block, gr_sync_decimator and gr_sync_interpolator
 188    * override these.  If you're fixed rate, subclass one of those.
 189    */
 190   /*!
 191    * \brief Given ninput samples, return number of output samples that will be produced.
 192    * N.B. this is only defined if fixed_rate returns true.
 193    * Generally speaking, you don't need to override this.
 194    */
 195   virtual int fixed_rate_ninput_to_noutput(int ninput);
 196
 197   /*!
 198    * \brief Given noutput samples, return number of input samples required to produce noutput.
 199    * N.B. this is only defined if fixed_rate returns true.
 200    * Generally speaking, you don't need to override this.
 201    */
 202   virtual int fixed_rate_noutput_to_ninput(int noutput);
 203
 204   // ----------------------------------------------------------------------------
 205
 206  private:
 207
 208   std::string           d_name;
 209   gr_io_signature_sptr  d_input_signature;
 210   gr_io_signature_sptr  d_output_signature;
 211   int                   d_output_multiple;
 212   double                d_relative_rate;        // approx output_rate / input_rate
 213   gr_block_detail_sptr  d_detail;               // implementation details
 214   long                  d_unique_id;            // convenient for debugging
 215   unsigned              d_history;
 216   bool                  d_fixed_rate;
 217
 218
 219  protected:
 220
 221   gr_block (const std::string &name,
 222             gr_io_signature_sptr input_signature,
 223             gr_io_signature_sptr output_signature);
 224
 225   //! may only be called during constructor
 226   void set_input_signature (gr_io_signature_sptr iosig){
 227     d_input_signature = iosig;
 228   }
 229
 230   //! may only be called during constructor
 231   void set_output_signature (gr_io_signature_sptr iosig){
 232     d_output_signature = iosig;
 233   }
 234
 235   void set_fixed_rate(bool fixed_rate){ d_fixed_rate = fixed_rate; }
 236
 237   // These are really only for internal use, but leaving them public avoids
 238   // having to work up an ever-varying list of friends
 239
 240  public:
 241   gr_block_detail_sptr detail () const { return d_detail; }
 242   void set_detail (gr_block_detail_sptr detail) { d_detail = detail; }
 243 };
 244
 245 long gr_block_ncurrently_allocated ();
 246
 247 #endif /* INCLUDED_GR_BLOCK_H */