Files beginning with Gr* define classes that inherit from VrSigProc.
These are high level signal processing modules that can be glued
together in your signal processing chain.

All the others are either lower level routines which implement the
functionality of the Gr* modules, but are easier to test (fewer
dependencies), or they are general purpose.

gr_fir_???.{h,cc}, where ??? are in F, S or C are low level Finite
Impulse Response Filters.  These turn out to be where the bulk of the
cycles are burned in many applications.  The ??? suffix  specifies the
input type, output type and tap type of the arguments.  We've
implemented the most frequently used ones.

[Once upon a time this stuff was done with templates
(gr_fir<iType,oType,tapType>), but this turned out to be a headache.
The code appeared to trigger a bug in GCC where we were getting
multiple definitions of unrelated stuff when we started subclassing
partially specialized templates.  It was also not obvious as to to
what combinations of iType, oType and tapType actually worked.  We're
now explicit, and the world is a safer place to live...]

The top level routines for FIR filtering are:

    GrFIRfilterFFF : Float input, Float output, Float taps
	-- general purpose

    GrFIRfilterCCF : Complex input, Complex output, Float taps
	-- applying real filter to a complex signal

    GrFIRfilterFCC : Float input, Complex output, Complex taps
	-- applying complex filter to float input

    GrFIRfilterSCC : Short input, Complex output, Complex taps
	-- applying complex filter to short input.  Quantizes complex
           coefficients to 16 bits and uses MMX or SSE2 as appropriate


The combination of down conversion (frequency translation) and channel
selection (filtering) is performed with:

    GrFreqXlatingFIRfilterSFC : Short input, Float taps, Complex baseband output
        -- quantizes complex coefficents to 16 bits and uses MMX or
	   SSE2 (128-bit MMX) as appropriate [optimization to be done].

    GrFreqXlatingFIRfilterFFC : Float input, Float taps, Complex baseband output
       -- 3dnow or SSE as appropriate.


[ The stuff described from here down is used to implement the routines
  above.  This info is only relevant to those who are hacking the internals ]


A bit of indirection is involved in selecting the fastest
implementation for any given platform.  The lower level classes
gr_fir_FFF.h, gr_fir_CCF, gr_fir_FCC and gr_fir_SCC have i/o
signatures similar to the high level clases above.   These
should be considered the abstract base classes that you
work with.  Note that they are not actually abstract (they've got a
default implementation; this might be considered a bug), but they
should not be directly instantiated by user code.

Instead of directly instantiating a gr_fir_FFF, for example, your code
should actually:

       #include <gr_fir_util.h>

       // let the system pick the best implementation for you
       gr_fir_FFF *filter = gr_fir_util::create_gr_fir_FFF (my_taps);

Clear?  The same for all the other gr_fir_XXX's.



Performance hacking can be done by subclassing the appropriate
base class.  For example, on the x86 platform, there are two
additional classes derived from gr_fir_FFF, gr_fir_FFF_sse and
gr_fir_FFF_3dnow.  These classes are then made available to the rest
of the system by virtue of being added to gr_fir_sysconfig_x86.cc,
along with any guards (CPUID checks) needed to ensure that only
compatible code is executed on the current hardware.


TO DO
------

* Move all the machine specific code to a subdirectory, then have
configure symlink to the right directory.  This will allow us to build on
any platform without choking.  There is generic code for all routines,
only the machine dependent speedup will be lacking. 

* Add an interface to gr_fir_util that will return a vector of all
valid constructors with descriptive names for each i/o signature.
This will allow the test code and benchmarking code to be blissfully
ignorant of what platform they're running on.  The actual building of
the vectors should be done bottom up through the gr_fir_sysconfig
hierarchy. 

