GNU Radio Manual and C++ API Reference 3.7.14.0
The Free & Open Software Radio Ecosystem
generic_decoder.h
Go to the documentation of this file.
1/* -*- c++ -*- */
2/*
3 * Copyright 2013-2014 Free Software Foundation, Inc.
4 *
5 * This file is part of GNU Radio
6 *
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)
10 * any later version.
11 *
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.
16 *
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.
21 */
22
23#ifndef INCLUDED_FEC_GENERIC_DECODER_H
24#define INCLUDED_FEC_GENERIC_DECODER_H
25
26#include <gnuradio/fec/api.h>
27#include <gnuradio/logger.h>
28#include <boost/format.hpp>
29#include <boost/shared_ptr.hpp>
30
31namespace gr {
32namespace fec {
33
34/*!
35 * \brief Parent class for FECAPI objects.
36 *
37 * \ingroup error_coding_blk
38 *
39 * \details
40 *
41 * Parent of a decoder variable class for FECAPI that will fit
42 * into the gr::fec::decoder block to handle FEC decoding. This
43 * class provides the basic information required to fit into the
44 * FECAPI structure. It provides information about input and
45 * output data types, potential data conversions, and a few other
46 * parameters useful to establish the decoder's behavior.
47 *
48 * We create objects from FECAPI-derived classes to go into the
49 * actual GNU Radio decoder block. Each object contains its own
50 * state and so there should be a one-to-one mapping of an FECAPI
51 * object and a GR decoder block. Sharing these objects is not
52 * guaranteed to be thread-safe.
53 *
54 * This is a pure virtual class and must be derived from by a
55 * child class.
56 *
57 * \sa gr::fec::code::cc_decoder
58 * \sa gr::fec::code::ccsds_decoder
59 */
61{
62protected:
64
65public:
66 friend class decoder;
67 virtual void generic_work(void* inbuffer, void* outbuffer) = 0;
68 static int base_unique_id;
69 int my_id;
70 int unique_id();
71 std::string d_name;
72 std::string alias() { return (boost::format("%s%d") % d_name % unique_id()).str(); }
73
74public:
75 typedef boost::shared_ptr<generic_decoder> sptr;
76
78 generic_decoder(std::string name);
80
81 /*!
82 * Returns the rate of the code. For every r input bits, there
83 * is 1 output bit, so the rate is 1/r. Used for setting things
84 * like the encoder block's relative rate.
85 *
86 * This function MUST be reimplemented by the child class.
87 */
88 virtual double rate() = 0;
89
90 /*!
91 * Returns the input size in items that the decoder object uses
92 * to decode a full frame. Often, this number is the number of
93 * bits per frame if the input format is unpacked. If the block
94 * expects packed bytes, then this value should be the number of
95 * bytes (number of bits / 8) per input frame.
96 *
97 * The child class MUST implement this function.
98 */
99 virtual int get_input_size() = 0;
100
101 /*!
102 * Returns the output size in items that the decoder object
103 * produces after decoding a full frame. Often, this number is
104 * the number of bits in the outputted frame if the input format
105 * is unpacked. If the block produces packed bytes, then this
106 * value should be the number of bytes (number of bits / 8) per
107 * frame produced. This value is generally something like
108 * get_input_size()/R for a 1/R rate code.
109 *
110 * The child class MUST implement this function.
111 */
112 virtual int get_output_size() = 0;
113
114 /*!
115 * Sets up history for the decoder when the decoder is required
116 * to look ahead in the data stream in order to finish
117 * its processing.
118 *
119 * The child class MAY implement this function. If not
120 * reimplemented, it returns 0.
121 */
122 virtual int get_history();
123
124 /*!
125 * Some decoders require the input items to float around a
126 * particular soft value. We can set that floating value by
127 * setting this value to return some non-zero number.
128 *
129 * The fec.extended_decoder block will use this to create an
130 * add_const_ff block before the decoder block to adjust all
131 * input samples appropriately.
132 *
133 * The child class MAY implement this function. If not
134 * reimplemented, it returns 0.
135 */
136 virtual float get_shift();
137
138 /*!
139 * Sets the size of an input item, as in the size of a char or
140 * float item.
141 *
142 * The child class SHOULD implement this function. If not
143 * reimplemented, it returns sizeof(float) as the decoders
144 * typically expect floating point input types.
145 */
146 virtual int get_input_item_size();
147
148 /*!
149 * Sets the size of an output item, as in the size of a char or
150 * float item.
151 *
152 * The child class SHOULD implement this function. If not
153 * reimplemented, it returns sizeof(char) as the decoders
154 * typically expect to produce bits or bytes.
155 */
156 virtual int get_output_item_size();
157
158 /*!
159 * Set up a conversion type required to setup the data properly
160 * for this decoder. The decoder itself will not implement the
161 * conversion and expects an external wrapper (e.g.,
162 * fec.extended_decoder) to read this value and "do the right
163 * thing" to format the data.
164 *
165 * The default behavior is 'none', which means no conversion is
166 * required. Whatever the get_input_item_size() value returns,
167 * the input is expected to conform directly to this.
168 *
169 * This may also return 'uchar', which indicates that the
170 * wrapper should convert the standard float samples to unsigned
171 * characters, either hard sliced or 8-bit soft symbols. See
172 * gr::fec::code::cc_decoder as an example decoder that uses
173 * this conversion format.
174 *
175 * If 'packed_bits', the block expects the inputs to be packed
176 * hard bits. Each input item is a unsigned char where each of
177 * the 8-bits is a hard bit value.
178 *
179 * The child class SHOULD implement this function. If not
180 * reimplemented, it returns "none".
181 */
182 virtual const char* get_input_conversion();
183
184 /*!
185 * Set up a conversion type required to understand the output
186 * style of this decoder. Generally, follow-on processing
187 * expects unpacked bits, so we specify the conversion type here
188 * to indicate what the wrapper (e.g., fec.extended_decoder)
189 * should do to convert the output samples from the decoder into
190 * unpacked bits.
191 *
192 * The default behavior is 'none', which means no conversion is
193 * required. This should mean that the output data is produced
194 * from this decoder as unpacked bit.
195 *
196 * If 'unpack', the block produces packed bytes that should be
197 * unpacked by the wrapper. See gr::fec::code::ccsds_decoder as
198 * an example of a decoder that produces packed bytes.
199 *
200 * The child class SHOULD implement this function. If not
201 * reimplemented, it returns "none".
202 */
203 virtual const char* get_output_conversion();
204
205 /*!
206 * Updates the size of a decoded frame.
207 *
208 * The child class MUST implement this function and interpret
209 * how the \p frame_size information affects the block's
210 * behavior. It should also provide bounds checks.
211 */
212 virtual bool set_frame_size(unsigned int frame_size) = 0;
213
214
215 /*!
216 * Get repetitions to decode.
217 *
218 * The child class should implement this function and return the
219 * number of iterations required to decode.
220 */
221 virtual float get_iterations() { return -1; }
222};
223
224/*! see generic_decoder::get_output_size() */
226
227/*! see generic_decoder::get_input_size() */
229
230/*! see generic_decoder::get_shift() */
232
233/*! see generic_decoder::get_history() */
235
236/*! see generic_decoder::get_input_item_size() */
238
239/*! see generic_decoder::get_output_item_size() */
241
242/*! see generic_decoder::get_input_conversion() */
244
245/*! see generic_decoder::get_output_conversion() */
247
248} /* namespace fec */
249} /* namespace gr */
250
251#endif /* INCLUDED_FEC_GENRIC_DECODER_H */
General FEC decoding block that takes in a decoder variable object (derived from gr::fec::general_dec...
Definition: decoder.h:67
Parent class for FECAPI objects.
Definition: generic_decoder.h:61
static int base_unique_id
Definition: generic_decoder.h:68
virtual int get_output_size()=0
virtual const char * get_input_conversion()
virtual int get_input_item_size()
gr::logger_ptr d_logger
Definition: generic_decoder.h:63
int my_id
Definition: generic_decoder.h:69
virtual double rate()=0
virtual int get_output_item_size()
virtual int get_input_size()=0
generic_decoder(void)
Definition: generic_decoder.h:77
virtual bool set_frame_size(unsigned int frame_size)=0
boost::shared_ptr< generic_decoder > sptr
Definition: generic_decoder.h:75
virtual float get_iterations()
Definition: generic_decoder.h:221
virtual float get_shift()
virtual int get_history()
std::string d_name
Definition: generic_decoder.h:71
std::string alias()
Definition: generic_decoder.h:72
generic_decoder(std::string name)
virtual const char * get_output_conversion()
virtual void generic_work(void *inbuffer, void *outbuffer)=0
#define FEC_API
Definition: gr-fec/include/gnuradio/fec/api.h:30
FEC_API int get_decoder_input_size(generic_decoder::sptr my_decoder)
FEC_API int get_decoder_input_item_size(generic_decoder::sptr my_decoder)
FEC_API int get_history(generic_decoder::sptr my_decoder)
FEC_API float get_shift(generic_decoder::sptr my_decoder)
FEC_API int get_decoder_output_size(generic_decoder::sptr my_decoder)
FEC_API int get_decoder_output_item_size(generic_decoder::sptr my_decoder)
FEC_API const char * get_decoder_input_conversion(generic_decoder::sptr my_decoder)
FEC_API const char * get_decoder_output_conversion(generic_decoder::sptr my_decoder)
Include this header to use the message passing features.
Definition: basic_block.h:45
void * logger_ptr
Definition: logger.h:696