GNU Radio 3.2.2 C++ API
|
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 */