gr_block.h

Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2004,2007 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   virtual ~gr_block ();
00061 
00062   /*!
00063    * Assume block computes y_i = f(x_i, x_i-1, x_i-2, x_i-3...)
00064    * History is the number of x_i's that are examined to produce one y_i.
00065    * This comes in handy for FIR filters, where we use history to
00066    * ensure that our input contains the appropriate "history" for the
00067    * filter.   History should be equal to the number of filter taps.
00068    */
00069   unsigned history () const { return d_history; }
00070   void  set_history (unsigned history) { d_history = history; }
00071   
00072   /*!
00073    * \brief return true if this block has a fixed input to output rate
00074    *
00075    * If true, then fixed_rate_in_to_out and fixed_rate_out_to_in may be called.
00076    */
00077   bool fixed_rate() const { return d_fixed_rate; }
00078 
00079   // ----------------------------------------------------------------
00080   //            override these to define your behavior
00081   // ----------------------------------------------------------------
00082 
00083   /*!
00084    * \brief  Estimate input requirements given output request
00085    *
00086    * \param noutput_items           number of output items to produce
00087    * \param ninput_items_required   number of input items required on each input stream
00088    *
00089    * Given a request to product \p noutput_items, estimate the number of
00090    * data items required on each input stream.  The estimate doesn't have
00091    * to be exact, but should be close.
00092    */
00093   virtual void forecast (int noutput_items,
00094                          gr_vector_int &ninput_items_required);
00095 
00096   /*!
00097    * \brief compute output items from input items
00098    *
00099    * \param noutput_items       number of output items to write on each output stream
00100    * \param ninput_items        number of input items available on each input stream
00101    * \param input_items         vector of pointers to the input items, one entry per input stream
00102    * \param output_items        vector of pointers to the output items, one entry per output stream
00103    *
00104    * \returns number of items actually written to each output stream, or -1 on EOF.
00105    * It is OK to return a value less than noutput_items.  -1 <= return value <= noutput_items
00106    *
00107    * general_work must call consume or consume_each to indicate how many items
00108    * were consumed on each input stream.
00109    */
00110   virtual int general_work (int noutput_items,
00111                             gr_vector_int &ninput_items,
00112                             gr_vector_const_void_star &input_items,
00113                             gr_vector_void_star &output_items) = 0;
00114 
00115   /*!
00116    * \brief Called to enable drivers, etc for i/o devices.
00117    *
00118    * This allows a block to enable an associated driver to begin
00119    * transfering data just before we start to execute the scheduler.
00120    * The end result is that this reduces latency in the pipeline when
00121    * dealing with audio devices, usrps, etc.
00122    */
00123   virtual bool start();
00124 
00125   /*!
00126    * \brief Called to disable drivers, etc for i/o devices.
00127    */
00128   virtual bool stop();
00129 
00130   // ----------------------------------------------------------------
00131 
00132   /*!
00133    * \brief Constrain the noutput_items argument passed to forecast and general_work
00134    *
00135    * set_output_multiple causes the scheduler to ensure that the noutput_items
00136    * argument passed to forecast and general_work will be an integer multiple
00137    * of \param multiple  The default value of output multiple is 1.
00138    */
00139   void set_output_multiple (int multiple);
00140   int  output_multiple () const { return d_output_multiple; }
00141 
00142   /*!
00143    * \brief Tell the scheduler \p how_many_items of input stream \p which_input were consumed.
00144    */
00145   void consume (int which_input, int how_many_items);
00146 
00147   /*!
00148    * \brief Tell the scheduler \p how_many_items were consumed on each input stream.
00149    */
00150   void consume_each (int how_many_items);
00151 
00152   /*!
00153    * \brief Set the approximate output rate / input rate
00154    *
00155    * Provide a hint to the buffer allocator and scheduler.
00156    * The default relative_rate is 1.0
00157    *
00158    * decimators have relative_rates < 1.0
00159    * interpolators have relative_rates > 1.0
00160    */
00161   void  set_relative_rate (double relative_rate);
00162 
00163   /*!
00164    * \brief return the approximate output rate / input rate
00165    */
00166   double relative_rate () const { return d_relative_rate; }
00167 
00168   /*
00169    * The following two methods provide special case info to the
00170    * scheduler in the event that a block has a fixed input to output
00171    * ratio.  gr_sync_block, gr_sync_decimator and gr_sync_interpolator
00172    * override these.  If you're fixed rate, subclass one of those.
00173    */
00174   /*!
00175    * \brief Given ninput samples, return number of output samples that will be produced.
00176    * N.B. this is only defined if fixed_rate returns true.
00177    * Generally speaking, you don't need to override this.
00178    */
00179   virtual int fixed_rate_ninput_to_noutput(int ninput);
00180 
00181   /*!
00182    * \brief Given noutput samples, return number of input samples required to produce noutput.
00183    * N.B. this is only defined if fixed_rate returns true.
00184    * Generally speaking, you don't need to override this.
00185    */
00186   virtual int fixed_rate_noutput_to_ninput(int noutput);
00187 
00188   // ----------------------------------------------------------------------------
00189 
00190  private:
00191 
00192   int                   d_output_multiple;
00193   double                d_relative_rate;        // approx output_rate / input_rate
00194   gr_block_detail_sptr  d_detail;                   // implementation details
00195   unsigned              d_history;
00196   bool                  d_fixed_rate;
00197     
00198  protected:
00199 
00200   gr_block (const std::string &name,
00201             gr_io_signature_sptr input_signature,
00202             gr_io_signature_sptr output_signature);
00203 
00204   void set_fixed_rate(bool fixed_rate){ d_fixed_rate = fixed_rate; }
00205 
00206   // These are really only for internal use, but leaving them public avoids
00207   // having to work up an ever-varying list of friends
00208 
00209  public:
00210   gr_block_detail_sptr detail () const { return d_detail; }
00211   void set_detail (gr_block_detail_sptr detail) { d_detail = detail; }
00212 };
00213 
00214 typedef std::vector<gr_block_sptr> gr_block_vector_t;
00215 typedef std::vector<gr_block_sptr>::iterator gr_block_viter_t;
00216 
00217 inline gr_block_sptr cast_to_block_sptr(gr_basic_block_sptr p)
00218 {
00219   return boost::dynamic_pointer_cast<gr_block, gr_basic_block>(p);
00220 }
00221 
00222 
00223 std::ostream&
00224 operator << (std::ostream& os, const gr_block *m);
00225 
00226 #endif /* INCLUDED_GR_BLOCK_H */

Generated on Wed Jul 29 06:31:38 2009 for GNU Radio 3.2.2 C++ API by  doxygen 1.5.9