GNU Radio Manual and C++ API Reference  3.7.9.2
The Free & Open Software Radio Ecosystem
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
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/shared_ptr.hpp>
29 #include <boost/format.hpp>
30 
31 namespace gr {
32  namespace 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  {
62  protected:
64 
65  public:
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 
74  public:
75  typedef boost::shared_ptr<generic_decoder> sptr;
76 
77  generic_decoder(void) {};
78  generic_decoder(std::string name);
79  virtual ~generic_decoder();
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() */
231  FEC_API float get_shift(generic_decoder::sptr my_decoder);
232 
233  /*! see generic_decoder::get_history() */
234  FEC_API int get_history(generic_decoder::sptr my_decoder);
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 */
FEC_API const char * get_decoder_output_conversion(generic_decoder::sptr my_decoder)
FEC_API const char * get_decoder_input_conversion(generic_decoder::sptr my_decoder)
gr::logger_ptr d_logger
Definition: generic_decoder.h:63
std::string d_name
Definition: generic_decoder.h:71
static int base_unique_id
Definition: generic_decoder.h:68
General FEC decoding block that takes in a decoder variable object (derived from gr::fec::general_dec...
Definition: decoder.h:66
FEC_API int get_decoder_input_size(generic_decoder::sptr my_decoder)
Parent class for FECAPI objects.
Definition: generic_decoder.h:60
virtual float get_iterations()
Definition: generic_decoder.h:221
FEC_API int get_decoder_output_size(generic_decoder::sptr my_decoder)
Include this header to use the message passing features.
Definition: logger.h:131
#define FEC_API
Definition: gr-fec/include/gnuradio/fec/api.h:30
generic_decoder(void)
Definition: generic_decoder.h:77
FEC_API int get_history(generic_decoder::sptr my_decoder)
log4cpp::Category * logger_ptr
GR_LOG macrosThese macros wrap the standard LOG4CPP_LEVEL macros. The availablie macros are: LOG_DEBU...
Definition: logger.h:149
FEC_API float get_shift(generic_decoder::sptr my_decoder)
boost::shared_ptr< generic_decoder > sptr
Definition: generic_decoder.h:75
int my_id
Definition: generic_decoder.h:69
std::string alias()
Definition: generic_decoder.h:72
FEC_API int get_decoder_output_item_size(generic_decoder::sptr my_decoder)
FEC_API int get_decoder_input_item_size(generic_decoder::sptr my_decoder)