describe existing code.

Add straw plan for 802.11 integration.

(comments, please).


git-svn-id: http://gnuradio.org/svn/gnuradio/trunk@4146 221aa14e-8319-0410-a670-987f0aec2ac5

1 files changed, 216 insertions, 2 deletions

diff --git a/README.organization b/README.organization
index 15d9b24ff..5f5ec64d9 100644
--- a/README.organization
+++ b/README.organization
@@ -1,9 +1,13 @@
 [This file is currently not baked and does not claim to represent
 consensus.]
 
+* Introduction
+
 This file describes the current organization of the GNU Radio source
 tree.  It is intended to be both descriptive and normative.
 
+* Unresolved issues in organization
+
 The big issues are:
 
 1) Should we separate by "code needed to implement protocol/modulation
@@ -21,9 +25,24 @@ click instead of GNU Radio, should we have a clean separation of
 MAC/PHY within GNU Radio, to facilitate using MACs implemented in
 various places?
 
+4) Examples abound, and many are in gnuradio-examples.  It might be
+better to put examples near the code they use, and to separate useful
+programs (like USRP benchmarks) from true examples.  Examples should
+probably be installed in $prefix/share/examples/gnuradio.
+
+* Plan (normative) [[NOT BAKED!!!  NO CONSENSUS!!!]]
+
+Create a new module gr-packet, to hold blocks generally relevant to
+sending blocks of data.  Create subdirectories within gr-packet for
+specific protocols (e.g. 802.11, GNU Radio's GMSK "protocol").
+
+Convert tunnel.py to be OS-independent and a general source/sink
+block, decoupling modulation from OS plumbing.
+
+* Pointers to code to be integrated
 
 The immediate question is how to integrate the 802.11 implementation
-done by BBN, available at:
+done by BBN (and assigned to FSF), available at:
 
   http://acert.ir.bbn.com/viewvc/adroitgrdevel/adroitgrdevel/gr-bbn/
 
@@ -31,4 +50,199 @@ This contains blocks at various places in the stack, and gdt believs
 that putting them in an 802.11 module will lead to less reuse and less
 of a tendency to generalize.
 
-[need pointers to existing documentation of big picture and what's where]
+* Organization of the GNU Radio source tree (mostly descriptive)
+
+The GNU Radio source tree is rooted at the directory containing this
+file; see README for how to get it if you're using a release or
+tarball.
+
+Within this directory, there are a number of subdirectories, most of
+which can be enabled or disabled independently.  See README for how to
+do that; this document is concerned with describing what each module
+does enough to help someone who is familiar enough with GNU Radio to
+write new code to choose where to put it.  The list is not exhaustive.
+The description of some modules also lists things that don't belong,
+tagged with ?M.
+
+** gnuradio-core [foundational code for the rest of GNU Radio]
+
+(gen_interpolator_taps is not installed.  Why?  How is it used?)
+
+doc: glue to use with doxygen
+
+?M doc/other/tv-channel-frequencies: (TV specific) 
+
+?M src/lib/g72x:
+  G.711 family codec
+
+src/lib/filter:
+  implementation and coefficient generation
+src/lib/general:
+  foundational blocks not specific to any technology:
+    type conversion, {de,}vectorization, add, sub
+    rms power, throttle, sources, sinks, squelch base class
+
+  general blocks:
+    agc, pll, sync, costas loop, power squelch, quadrature demod
+  
+  ?M framer/correlator 
+  ?M packet source/sink
+
+src/lib/io:
+  basic file io, message io
+  oscope (trigger support)
+  i2c bus
+  ?M microtune eval board (like USRP; should probably have own module)
+  ?M SDR1000
+
+src/lib/omnithread:
+  portable threading library (for when POSIX isn't portable enough)
+
+src/lib/reed-solomon:
+  reed-solomon implementation.  Unclear how/whether it's wrapped into
+  blocks.
+
+src/lib/runtime:
+  blocks (basic, hier) and associated buffering
+  flowgraphs
+  timers
+  doubly-mapped circular buffers
+
+src/lib/swig:
+  code to wrap the rest in python
+  ?M atsc.i (cruft? moved?)
+
+src/python:
+  build utilities
+
+src/python/bin:
+  ?M microtune.py: microtune control program (installed and EXTRA_DIST!)
+
+src/python/gnuradio:
+  audio base class
+  engineering notation support
+  test harness support
+  test code (not installed)
+  basic block/flow_graph
+
+src/tests:
+  test code
+  ?M test_atsc.cc (# in Makefile.am, but still present)
+
+src/utils:
+  octave and Scheme scripts (not installed)
+
+** usrp
+
+This contains code to deal with the USRP, but not GNU Radio support.
+
+?M fusb
+  The "fusb" abstraction is arguably useful for all interface devices
+  that use USB, not just the USRP.
+
+** gr-usrp
+
+Code to use the USRP with GNU Radio.
+
+?M Arguably the Gnu Radio/USRP benchmarks belong here, but are in -examples
+
+** gr-audio-alsa
+** gr-audio-jack
+** gr-audio-oss
+** gr-audio-osx
+** gr-audio-portaudio
+** gr-audio-windows
+  [All of these support audio for some particular audio backend.
+
+** gr-atsc
+  ATSC (HDTV) transmitter and receiver.
+  All blocks seem to be specific to ATSC.
+  ?M Perhaps some blocks should be abstracted out for reuse with other
+     than ATSC parameters.
+
+** gr-comedi
+  This module is missing a README that explains what it does.
+  http://www.comedi.org/
+
+** gr-error-correcting-codes
+  This module intends to provide generic error-correcting code
+  support, rather than implementing coding for a particular standard.
+  Currently it has support for convolutional, viterbi, and turbo
+  codes.
+
+** gr-gsm-fr-vocoder
+  GSM 06.10 full rate vocoder, and gsm library
+  (Note that the presence of this argues for moving the G.711 code discussed above.)
+
+** gr-pager
+  POCSAG and FLEX
+  (gdt suspects there are blocks in here that could be generalized.)
+
+** gr-radar
+  ?radar  (not clear)
+
+** gr-radio-astronomy
+  seems to use only standard blocks from python
+
+** gr-trellis
+  This module provides trellis code support, and appears generic.
+
+** gr-video-sdl
+  This appears to be like the audio modules, but for video and
+  specifically for SDL.  Unlike audio which has a base class, there
+  does not appear to be an abstract video class in gnuradio-core.
+
+** gr-wxgui
+  Support for using wxwidgets from python.
+  ?M (Linux-specific??) code to use the Griffin Powermate (and hook it to a GUI)
+  glue to connect FFT and scope to gui
+  
+** pmt
+  polymorphic types (building block)
+
+** mblock
+  Message block implementation.
+  Note that mblock being a module means that signal processing blocks
+  that are mblock-aware must depend on this module and thus probably
+  cannot be in gnuradio-core.  Thus, m-block wrappers for the blocks
+  in gnuradio-core must be elsewhere and it is maybe a good idea to
+  move them to someplace like gnuradio-common where the streaming and
+  m-block versions can be together.
+
+** ezdop
+  Code to deal with the ezdop direction-finding hardware.
+
+** gr-ezdop
+  Glue code to use the ezdop from GNU Radio.
+
+** gr-rdf
+  (Currently empty) code to perform direction finding.
+
+** gnuradio-examples
+
+  It's arguable that all of these are misplaced, and that examples
+  belong with the code that they use.
+
+  Bona fide examples (code not intended to be useful except for reading):
+    c++/dial_tone (how to do things only in C++)
+    python/audio
+
+  Test programs:
+    python/channel-coding
+    python/digital-voice
+    python/multi-antenna (?)
+
+  Programs in between test and useful:
+    python/digital
+      ?M tunnel.py: glue to get packets to Linux, conflates modulation
+      and packet handling
+    python/multi_usrp
+    python/networking/measurement_slave (goes with what?)
+
+  ?M Programs intended to be useful
+    python/apps/hf_{explorer,radio}
+
+  ?M Kitchen sink:
+    python/usrp
+      benchmarks, test, basic fm/wfm/tv receivers, spectrum sensing,
+      fft, oscope