From 5d69a524f81f234b3fbc41d49ba18d6f6886baba Mon Sep 17 00:00:00 2001 From: jcorgan Date: Thu, 3 Aug 2006 04:51:51 +0000 Subject: Houston, we have a trunk. git-svn-id: http://gnuradio.org/svn/gnuradio/trunk@3122 221aa14e-8319-0410-a670-987f0aec2ac5 --- gnuradio-core/src/lib/general/README | 98 ++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 gnuradio-core/src/lib/general/README (limited to 'gnuradio-core/src/lib/general/README') diff --git a/gnuradio-core/src/lib/general/README b/gnuradio-core/src/lib/general/README new file mode 100644 index 000000000..26d829f1b --- /dev/null +++ b/gnuradio-core/src/lib/general/README @@ -0,0 +1,98 @@ +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), 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 + + // 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. + -- cgit