git.gag.com Git - debian/gnuradio/blob - gnuradio-core/src/lib/general/README

   1 Files beginning with Gr* define classes that inherit from VrSigProc.
   2 These are high level signal processing modules that can be glued
   3 together in your signal processing chain.
   4
   5 All the others are either lower level routines which implement the
   6 functionality of the Gr* modules, but are easier to test (fewer
   7 dependencies), or they are general purpose.
   8
   9 gr_fir_???.{h,cc}, where ??? are in F, S or C are low level Finite
  10 Impulse Response Filters.  These turn out to be where the bulk of the
  11 cycles are burned in many applications.  The ??? suffix  specifies the
  12 input type, output type and tap type of the arguments.  We've
  13 implemented the most frequently used ones.
  14
  15 [Once upon a time this stuff was done with templates
  16 (gr_fir<iType,oType,tapType>), but this turned out to be a headache.
  17 The code appeared to trigger a bug in GCC where we were getting
  18 multiple definitions of unrelated stuff when we started subclassing
  19 partially specialized templates.  It was also not obvious as to to
  20 what combinations of iType, oType and tapType actually worked.  We're
  21 now explicit, and the world is a safer place to live...]
  22
  23 The top level routines for FIR filtering are:
  24
  25     GrFIRfilterFFF : Float input, Float output, Float taps
  26         -- general purpose
  27
  28     GrFIRfilterCCF : Complex input, Complex output, Float taps
  29         -- applying real filter to a complex signal
  30
  31     GrFIRfilterFCC : Float input, Complex output, Complex taps
  32         -- applying complex filter to float input
  33
  34     GrFIRfilterSCC : Short input, Complex output, Complex taps
  35         -- applying complex filter to short input.  Quantizes complex
  36            coefficients to 16 bits and uses MMX or SSE2 as appropriate
  37
  38
  39 The combination of down conversion (frequency translation) and channel
  40 selection (filtering) is performed with:
  41
  42     GrFreqXlatingFIRfilterSFC : Short input, Float taps, Complex baseband output
  43         -- quantizes complex coefficents to 16 bits and uses MMX or
  44            SSE2 (128-bit MMX) as appropriate [optimization to be done].
  45
  46     GrFreqXlatingFIRfilterFFC : Float input, Float taps, Complex baseband output
  47        -- 3dnow or SSE as appropriate.
  48
  49
  50 [ The stuff described from here down is used to implement the routines
  51   above.  This info is only relevant to those who are hacking the internals ]
  52
  53
  54 A bit of indirection is involved in selecting the fastest
  55 implementation for any given platform.  The lower level classes
  56 gr_fir_FFF.h, gr_fir_CCF, gr_fir_FCC and gr_fir_SCC have i/o
  57 signatures similar to the high level clases above.   These
  58 should be considered the abstract base classes that you
  59 work with.  Note that they are not actually abstract (they've got a
  60 default implementation; this might be considered a bug), but they
  61 should not be directly instantiated by user code.
  62
  63 Instead of directly instantiating a gr_fir_FFF, for example, your code
  64 should actually:
  65
  66        #include <gr_fir_util.h>
  67
  68        // let the system pick the best implementation for you
  69        gr_fir_FFF *filter = gr_fir_util::create_gr_fir_FFF (my_taps);
  70
  71 Clear?  The same for all the other gr_fir_XXX's.
  72
  73
  74
  75 Performance hacking can be done by subclassing the appropriate
  76 base class.  For example, on the x86 platform, there are two
  77 additional classes derived from gr_fir_FFF, gr_fir_FFF_sse and
  78 gr_fir_FFF_3dnow.  These classes are then made available to the rest
  79 of the system by virtue of being added to gr_fir_sysconfig_x86.cc,
  80 along with any guards (CPUID checks) needed to ensure that only
  81 compatible code is executed on the current hardware.
  82
  83
  84 TO DO
  85 ------
  86
  87 * Move all the machine specific code to a subdirectory, then have
  88 configure symlink to the right directory.  This will allow us to build on
  89 any platform without choking.  There is generic code for all routines,
  90 only the machine dependent speedup will be lacking.
  91
  92 * Add an interface to gr_fir_util that will return a vector of all
  93 valid constructors with descriptive names for each i/o signature.
  94 This will allow the test code and benchmarking code to be blissfully
  95 ignorant of what platform they're running on.  The actual building of
  96 the vectors should be done bottom up through the gr_fir_sysconfig
  97 hierarchy.
  98