3 * Copyright 2004,2007,2009 Free Software Foundation, Inc.
5 * This file is part of GNU Radio
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)
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.
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.
23 #ifndef INCLUDED_GR_BLOCK_H
24 #define INCLUDED_GR_BLOCK_H
26 #include <gr_basic_block.h>
29 * \brief The abstract base class for all 'terminal' processing blocks.
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.
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.
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.
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
52 * general_work is called to perform the signal processing in the block.
53 * It reads the input items and writes the output items.
56 class gr_block : public gr_basic_block {
60 //! Magic return values from general_work
62 WORK_CALLED_PRODUCE = -2,
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.
75 unsigned history () const { return d_history; }
76 void set_history (unsigned history) { d_history = history; }
79 * \brief Return true if this block has a fixed input to output rate.
81 * If true, then fixed_rate_in_to_out and fixed_rate_out_to_in may be called.
83 bool fixed_rate() const { return d_fixed_rate; }
85 // ----------------------------------------------------------------
86 // override these to define your behavior
87 // ----------------------------------------------------------------
90 * \brief Estimate input requirements given output request
92 * \param noutput_items number of output items to produce
93 * \param ninput_items_required number of input items required on each input stream
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.
99 virtual void forecast (int noutput_items,
100 gr_vector_int &ninput_items_required);
103 * \brief compute output items from input items
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
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
113 * general_work must call consume or consume_each to indicate how many items
114 * were consumed on each input stream.
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;
122 * \brief Called to enable drivers, etc for i/o devices.
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.
129 virtual bool start();
132 * \brief Called to disable drivers, etc for i/o devices.
136 // ----------------------------------------------------------------
139 * \brief Constrain the noutput_items argument passed to forecast and general_work
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.
145 void set_output_multiple (int multiple);
146 int output_multiple () const { return d_output_multiple; }
149 * \brief Tell the scheduler \p how_many_items of input stream \p which_input were consumed.
151 void consume (int which_input, int how_many_items);
154 * \brief Tell the scheduler \p how_many_items were consumed on each input stream.
156 void consume_each (int how_many_items);
159 * \brief Tell the scheduler \p how_many_items were produced on output stream \p which_output.
161 * If the block's general_work method calls produce, \p general_work must return WORK_CALLED_PRODUCE.
163 void produce (int which_output, int how_many_items);
166 * \brief Set the approximate output rate / input rate
168 * Provide a hint to the buffer allocator and scheduler.
169 * The default relative_rate is 1.0
171 * decimators have relative_rates < 1.0
172 * interpolators have relative_rates > 1.0
174 void set_relative_rate (double relative_rate);
177 * \brief return the approximate output rate / input rate
179 double relative_rate () const { return d_relative_rate; }
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.
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.
192 virtual int fixed_rate_ninput_to_noutput(int ninput);
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.
199 virtual int fixed_rate_noutput_to_ninput(int noutput);
201 // ----------------------------------------------------------------------------
205 int d_output_multiple;
206 double d_relative_rate; // approx output_rate / input_rate
207 gr_block_detail_sptr d_detail; // implementation details
213 gr_block (const std::string &name,
214 gr_io_signature_sptr input_signature,
215 gr_io_signature_sptr output_signature);
217 void set_fixed_rate(bool fixed_rate){ d_fixed_rate = fixed_rate; }
219 // These are really only for internal use, but leaving them public avoids
220 // having to work up an ever-varying list of friends
223 gr_block_detail_sptr detail () const { return d_detail; }
224 void set_detail (gr_block_detail_sptr detail) { d_detail = detail; }
227 typedef std::vector<gr_block_sptr> gr_block_vector_t;
228 typedef std::vector<gr_block_sptr>::iterator gr_block_viter_t;
230 inline gr_block_sptr cast_to_block_sptr(gr_basic_block_sptr p)
232 return boost::dynamic_pointer_cast<gr_block, gr_basic_block>(p);
237 operator << (std::ostream& os, const gr_block *m);
239 #endif /* INCLUDED_GR_BLOCK_H */