[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-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-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