3 * Copyright 2004,2007 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 {
63 * Assume block computes y_i = f(x_i, x_i-1, x_i-2, x_i-3...)
64 * History is the number of x_i's that are examined to produce one y_i.
65 * This comes in handy for FIR filters, where we use history to
66 * ensure that our input contains the appropriate "history" for the
67 * filter. History should be equal to the number of filter taps.
69 unsigned history () const { return d_history; }
70 void set_history (unsigned history) { d_history = history; }
73 * \brief return true if this block has a fixed input to output rate
75 * If true, then fixed_rate_in_to_out and fixed_rate_out_to_in may be called.
77 bool fixed_rate() const { return d_fixed_rate; }
79 // ----------------------------------------------------------------
80 // override these to define your behavior
81 // ----------------------------------------------------------------
84 * \brief Estimate input requirements given output request
86 * \param noutput_items number of output items to produce
87 * \param ninput_items_required number of input items required on each input stream
89 * Given a request to product \p noutput_items, estimate the number of
90 * data items required on each input stream. The estimate doesn't have
91 * to be exact, but should be close.
93 virtual void forecast (int noutput_items,
94 gr_vector_int &ninput_items_required);
97 * \brief compute output items from input items
99 * \param noutput_items number of output items to write on each output stream
100 * \param ninput_items number of input items available on each input stream
101 * \param input_items vector of pointers to the input items, one entry per input stream
102 * \param output_items vector of pointers to the output items, one entry per output stream
104 * \returns number of items actually written to each output stream, or -1 on EOF.
105 * It is OK to return a value less than noutput_items. -1 <= return value <= noutput_items
107 * general_work must call consume or consume_each to indicate how many items
108 * were consumed on each input stream.
110 virtual int general_work (int noutput_items,
111 gr_vector_int &ninput_items,
112 gr_vector_const_void_star &input_items,
113 gr_vector_void_star &output_items) = 0;
116 * \brief Called to enable drivers, etc for i/o devices.
118 * This allows a block to enable an associated driver to begin
119 * transfering data just before we start to execute the scheduler.
120 * The end result is that this reduces latency in the pipeline when
121 * dealing with audio devices, usrps, etc.
123 virtual bool start();
126 * \brief Called to disable drivers, etc for i/o devices.
130 // ----------------------------------------------------------------
133 * \brief Constrain the noutput_items argument passed to forecast and general_work
135 * set_output_multiple causes the scheduler to ensure that the noutput_items
136 * argument passed to forecast and general_work will be an integer multiple
137 * of \param multiple The default value of output multiple is 1.
139 void set_output_multiple (int multiple);
140 int output_multiple () const { return d_output_multiple; }
143 * \brief Tell the scheduler \p how_many_items of input stream \p which_input were consumed.
145 void consume (int which_input, int how_many_items);
148 * \brief Tell the scheduler \p how_many_items were consumed on each input stream.
150 void consume_each (int how_many_items);
153 * \brief Set the approximate output rate / input rate
155 * Provide a hint to the buffer allocator and scheduler.
156 * The default relative_rate is 1.0
158 * decimators have relative_rates < 1.0
159 * interpolators have relative_rates > 1.0
161 void set_relative_rate (double relative_rate);
164 * \brief return the approximate output rate / input rate
166 double relative_rate () const { return d_relative_rate; }
169 * The following two methods provide special case info to the
170 * scheduler in the event that a block has a fixed input to output
171 * ratio. gr_sync_block, gr_sync_decimator and gr_sync_interpolator
172 * override these. If you're fixed rate, subclass one of those.
175 * \brief Given ninput samples, return number of output samples that will be produced.
176 * N.B. this is only defined if fixed_rate returns true.
177 * Generally speaking, you don't need to override this.
179 virtual int fixed_rate_ninput_to_noutput(int ninput);
182 * \brief Given noutput samples, return number of input samples required to produce noutput.
183 * N.B. this is only defined if fixed_rate returns true.
184 * Generally speaking, you don't need to override this.
186 virtual int fixed_rate_noutput_to_ninput(int noutput);
188 // ----------------------------------------------------------------------------
192 int d_output_multiple;
193 double d_relative_rate; // approx output_rate / input_rate
194 gr_block_detail_sptr d_detail; // implementation details
200 gr_block (const std::string &name,
201 gr_io_signature_sptr input_signature,
202 gr_io_signature_sptr output_signature);
204 void set_fixed_rate(bool fixed_rate){ d_fixed_rate = fixed_rate; }
206 // These are really only for internal use, but leaving them public avoids
207 // having to work up an ever-varying list of friends
210 gr_block_detail_sptr detail () const { return d_detail; }
211 void set_detail (gr_block_detail_sptr detail) { d_detail = detail; }
214 typedef std::vector<gr_block_sptr> gr_block_vector_t;
215 typedef std::vector<gr_block_sptr>::iterator gr_block_viter_t;
217 inline gr_block_sptr cast_to_block_sptr(gr_basic_block_sptr p)
219 return boost::dynamic_pointer_cast<gr_block, gr_basic_block>(p);
224 operator << (std::ostream& os, const gr_block *m);
226 #endif /* INCLUDED_GR_BLOCK_H */