describe existing code.

[debian/gnuradio] / README.organization

[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
foo", or related blocks. to (that are therefore not so likely to be
used together).

2) How do m-blocks impact organization?  If m-blocks are in a separate
module, which seems reasonable, then do we have most modules depend on
m-blocks rather than just core, or do we have two versions of blocks -
the classic continuous block and the m-block wrapped block?  If
m-blocks become the main path, what will be less awkward?

3) Because some (ADROIT at BBN) have proposed to implement MACs in
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 (and assigned to FSF), available at:

  http://acert.ir.bbn.com/viewvc/adroitgrdevel/adroitgrdevel/gr-bbn/

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.

* 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