3 * Copyright 2004 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 2, 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_runtime.h>
30 * \brief The abstract base class for all signal processing blocks.
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.
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.
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
48 * general_work is called to perform the signal processing in the block.
49 * It reads the input items and writes the output items.
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; }
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.
70 unsigned history () const { return d_history; }
71 void set_history (unsigned history) { d_history = history; }
74 * \brief return true if this block has a fixed input to output rate
76 * If true, then fixed_rate_in_to_out and fixed_rate_out_to_in may be called.
78 bool fixed_rate() const { return d_fixed_rate; }
80 // ----------------------------------------------------------------
81 // override these to define your behavior
82 // ----------------------------------------------------------------
85 * \brief Estimate input requirements given output request
87 * \param noutput_items number of output items to produce
88 * \param ninput_items_required number of input items required on each input stream
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.
94 virtual void forecast (int noutput_items,
95 gr_vector_int &ninput_items_required);
98 * \brief compute output items from input items
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
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
108 * general_work must call consume or consume_each to indicate how many items
109 * were consumed on each input stream.
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;
117 * \brief Confirm that ninputs and noutputs is an acceptable combination.
119 * \param ninputs number of input streams connected
120 * \param noutputs number of output streams connected
122 * \returns true if this is a valid configuration for this block.
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.
129 virtual bool check_topology (int ninputs, int noutputs);
132 * \brief Called to enable drivers, etc for i/o devices.
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.
139 virtual bool start();
142 * \brief Called to disable drivers, etc for i/o devices.
146 // ----------------------------------------------------------------
149 * \brief Constrain the noutput_items argument passed to forecast and general_work
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.
155 void set_output_multiple (int multiple);
156 int output_multiple () const { return d_output_multiple; }
159 * \brief Tell the scheduler \p how_many_items of input stream \p which_input were consumed.
161 void consume (int which_input, int how_many_items);
164 * \brief Tell the scheduler \p how_many_items were consumed on each input stream.
166 void consume_each (int how_many_items);
169 * \brief Set the approximate output rate / input rate
171 * Provide a hint to the buffer allocator and scheduler.
172 * The default relative_rate is 1.0
174 * decimators have relative_rates < 1.0
175 * interpolators have relative_rates > 1.0
177 void set_relative_rate (double relative_rate);
180 * \brief return the approximate output rate / input rate
182 double relative_rate () const { return d_relative_rate; }
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.
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.
195 virtual int fixed_rate_ninput_to_noutput(int ninput);
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.
202 virtual int fixed_rate_noutput_to_ninput(int noutput);
204 // ----------------------------------------------------------------------------
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
221 gr_block (const std::string &name,
222 gr_io_signature_sptr input_signature,
223 gr_io_signature_sptr output_signature);
225 //! may only be called during constructor
226 void set_input_signature (gr_io_signature_sptr iosig){
227 d_input_signature = iosig;
230 //! may only be called during constructor
231 void set_output_signature (gr_io_signature_sptr iosig){
232 d_output_signature = iosig;
235 void set_fixed_rate(bool fixed_rate){ d_fixed_rate = fixed_rate; }
237 // These are really only for internal use, but leaving them public avoids
238 // having to work up an ever-varying list of friends
241 gr_block_detail_sptr detail () const { return d_detail; }
242 void set_detail (gr_block_detail_sptr detail) { d_detail = detail; }
245 long gr_block_ncurrently_allocated ();
247 #endif /* INCLUDED_GR_BLOCK_H */