Merge remote-tracking branch 'mbant/docs/structure' into docs/structure

author: Tom Rondeau <tom@trondeau.com> 2014-07-23 16:57:12 -0400
committer: Tom Rondeau <tom@trondeau.com> 2014-07-23 16:57:12 -0400
commit: dd7006e59d96e9961f243b2b17f468e6e1854bcc (patch)
tree: c7043216dba0349e6c124843d731002bc56e3ebf /docs/doxygen/other
parent: 3751ea9b2f07afe2e03aef6df561fe0a9effc377 (diff)
parent: a9c3d8ff3bc31117309004c16860d18f26369311 (diff)
8 files changed, 694 insertions, 494 deletions
diff --git a/docs/doxygen/other/build_guide.dox b/docs/doxygen/other/build_guide.dox
new file mode 100644
index 0000000000..e831e8a560
--- /dev/null
+++ b/docs/doxygen/other/build_guide.dox
@@ -0,0 +1,160 @@
+/*! \page build_guide Build Instructions and Information
+
+\section dependencies Dependencies
+
+The list of GNU Radio dependencies and the minimum required versions,
+if any, to build the various GNU Radio components.
+
+Most of these components do not need to be individually compiled or
+installed. Instead, rely on your operating system's package manager or
+binary installation process (the <b>apt-get</b> system in Debian and
+Ubuntu, <b>yum</b> in RedHat and Fedora, etc.). GNU Radio tries to keep an
+up-to-date build guide for the majority of the supported operating
+systems on gnuradio.org
+(http://gnuradio.org/redmine/projects/gnuradio/wiki/BuildGuide).
+
+Not all dependencies are required for all components, and not all
+components are required for a given installation. The list of required
+components is determined by what the user requires from GNU Radio. If,
+for example, you do not use any Comedi-based hardware, do not worry
+about building gr-comedi.
+
+Before trying to build these from source, please try your system's
+installation tool (apt-get, pkg_install, YaST, yum, urpmi, etc.)
+first. Most recent systems have these packages available.
+
+\subsection dep_global Global Dependencies
+\li git                      http://code.google.com/p/msysgit
+\li cmake       (>= 2.6)     http://www.cmake.org/cmake/resources/software.html
+\li boost       (>= 1.35)    http://www.boostpro.com/download
+\li cppunit     (>= 1.9.14)  http://gaiacrtn.free.fr/cppunit/index.html
+\li fftw3f      (>= 3.0)     http://www.fftw.org/install/windows.html
+
+\subsection dep_python Python Wrappers
+\li python      (>= 2.5)     http://www.python.org/download/
+\li swig        (>= 1.3.31)  http://www.swig.org/download.html
+\li numpy       (>= 1.1.0)   http://sourceforge.net/projects/numpy/files/NumPy/
+
+\subsection dep_docs docs: Building the documentation
+\li doxygen     (>= 1.5)     http://www.stack.nl/~dimitri/doxygen/download.html
+
+\subsection dep_grc grc: The GNU Radio Companion
+\li Cheetah     (>= 2.0)     http://www.cheetahtemplate.org/
+\li pygtk       (>= 2.10)    http://www.pygtk.org/downloads.html
+
+\subsection dep_wavelet gr-wavelet: Collection of wavelet blocks
+\li gsl	        (>= 1.10)    http://gnuwin32.sourceforge.net/packages/gsl.htm
+
+\subsection dep_gr_qtgui gr-qtgui: The QT-based Graphical User Interface
+\li qt	        (>= 4.4)     http://qt.nokia.com/downloads/
+\li qwt         (>= 5.2)     http://sourceforge.net/projects/qwt/
+\li pyqt        (>= 4.4)     http://www.riverbankcomputing.co.uk/software/pyqt/download
+\li pyqwt       (>= 5.2)     http://pyqwt.sourceforge.net/download.html
+
+\subsection dep_gr_wxgui gr-wxgui: The WX-based Graphical User Interface
+\li wxpython    (>= 2.8)     http://www.wxpython.org/
+\li python-lxml (>= 1.3.6)   http://lxml.de/
+
+\subsection dep_gr_audio gr-audio: Audio Subsystems (system/OS dependent)
+\li audio-alsa  (>= 0.9)     http://www.alsa-project.org
+\li audio-jack  (>= 0.8)     http://jackaudio.org/
+\li portaduio   (>= 19)      http://www.portaudio.com/
+\li audio-oss   (>= 1.0)     http://www.opensound.com/oss.html
+\li audio-osx
+\li audio-windows
+
+It is not necessary to satisfy all of these dependencies; just the
+one(s) that are right for your system. On Linux, don't expect
+audio-osx and audio-windows to be either satisfied or built.
+
+\subsection dep_uhd uhd: The Ettus USRP Hardware Driver Interface
+\li uhd         (>= 3.0.0)   http://code.ettus.com/redmine/ettus/projects/uhd/wiki
+
+\subsection dep_gr_video_sdl gr-video-sdl: PAL and NTSC display
+\li SDL	        (>= 1.2.0)   http://www.libsdl.org/download-1.2.php
+
+\subsection dep_gr_comedi gr-comedi: Comedi hardware interface
+\li comedilib   (>= 0.8)     http://www.comedi.org/
+
+\subsection dep_gr_log gr-log: Logging Tools (Optional)
+\li log4cpp     (>= 1.0)  http://log4cpp.sourceforge.net/
+
+
+\section build_gr_cmake Building GNU Radio
+
+GNU Radio is built using the Cmake build system
+(http://www.cmake.org/). The standard build method is as follows:
+
+\code
+$ mkdir $(builddir)
+$ cd $(builddir)
+$ cmake [OPTIONS] $(srcdir)
+$ make
+$ make test
+$ sudo make install
+\endcode
+
+The \$(builddir) is the directory in which the code is built. This
+<b>cannot</b> be the same path as where the source code resides. Often,
+\$(builddir) is \$(srcdir)/build.
+
+\subsection Cmake Options
+
+Options can be used to specify where to find various library or
+include file dependencies that are not automatically being found
+(-DCMAKE_PREFIX_PATH) or set the prefix
+(-DCMAKE_INSTALL_PREFIX=(dir)).
+
+Components can also be enabled and disabled through the options. For a
+component named *gr-comp*, the option to disable would look like:
+-DENABLE_GR_COMP=off. The "off" could also be "false" or "no", and
+cmake is not case sensitive about these options. Similarly, "true",
+"on", or "yes" will turn this component on. All components are enabled
+by default.
+
+An example is -DENABLE_PYTHON=False turns off building any Python or
+Swigging components. The result will be the GNU Radio libraries and
+C++ programs/applications/examples. No Python or GRC files will be
+built or installed.
+
+The -DENABLE_DEFAULT=False can be used to disable all
+components. Individual components can then be selectively turned back
+on. For example, just buidling the VOLK library can be
+done with this:
+
+\code
+cmake -DENABLE_DEFAULT=Off -DENABLE_VOLK=True <srcdir>
+\endcode
+
+
+The build type allows you to specify the build as a debug or release
+version. Each type sets different flags for different purposes. To set
+the build type, use:
+
+\code
+-DCMAKE_BUILD_TYPE="Release"|"Debug"
+\endcode
+
+If not specified, the "Release" mode is the defaulted to.
+
+"Release" mode sets the '-O3' optimization flag.
+
+"Debug" mode sets '-g -O2' flags to export debug symbols and reduce
+the optimization to make the libraries easier to debug and step
+through.
+
+
+\subsection build_gr_cmake_e100 Building for the E100
+
+To build GNU Radio on the Ettus Research E100 embedded platforms,
+Cmake has to know that the processors uses the NEON extensions. Use
+the
+
+\code
+cmake -DCMAKE_CXX_FLAGS:STRING="-mcpu=cortex-a8 -mfpu=neon -mfloat-abi=softfp -g" \
+      -DCMAKE_C_FLAGS:STRING="-mcpu=cortex-a8 -mfpu=neon -mfloat-abi=softfp -g" \
+       <gr_source_dir>
+\endcode
+
+*/
+
diff --git a/docs/doxygen/other/components.dox b/docs/doxygen/other/components.dox
new file mode 100644
index 0000000000..1e98beb6f2
--- /dev/null
+++ b/docs/doxygen/other/components.dox
@@ -0,0 +1,34 @@
+/*! \page page_components Components
+
+\section components_blocks GNU Radio Blocks
+
+GNU Radio uses discrete signal processing blocks that are connected
+together to perform your signal processing application. This manual
+contain a list of all GNU Radio <a href="modules.html"><b>C++ Blocks</b></a>,
+sorted by category.
+
+Please note that at this time, we haven't found an acceptable way to
+provide unified documentation for the C++ parts of the system and the
+parts written in Python (mostly hierarchical blocks).  Until this gets
+worked out, please bear with us, or better yet, solve it for us!
+
+\section components_list In-tree components
+
+All our in-tree components have their own top-level documentation:
+
+\li \subpage page_analog
+\li \subpage page_audio
+\li \subpage page_blocks
+\li \subpage page_channels
+\li \subpage page_ctrlport
+\li \subpage page_digital
+\li \subpage page_fcd
+\li \subpage page_fec
+\li \subpage page_fft
+\li \subpage page_filter
+\li \subpage page_qtgui
+\li \subpage page_uhd
+\li \subpage page_vocoder
+\li \subpage page_zeromq
+
+*/
diff --git a/docs/doxygen/other/main_page.dox b/docs/doxygen/other/main_page.dox
index 62ea8a9929..67487ddfd6 100644
--- a/docs/doxygen/other/main_page.dox
+++ b/docs/doxygen/other/main_page.dox
@@ -4,505 +4,22 @@
 
 Welcome to GNU Radio!
 
-For details about GNU Radio and using it, please see the <a
-href="http://gnuradio.org" target="_blank"><b>main project page</b></a>.
+For details about GNU Radio and using it, please see the
+<a href="http://gnuradio.org" target="_blank"><b>main project page</b></a>.
 
 Other information about the project and discussion about GNU Radio,
 software radio, and communication theory in general can be found at
 the <a href="http://www.trondeau.com" target="_blank"><b>GNU Radio blog</b></a>.
 
+This manual is split into two parts: A usage manual and a reference. The usage manual
+deals with concepts of GNU Radio, introductions, how to build GNU Radio etc.
+The reference contains a list of all GNU Radio components, sorted by in-tree components,
+modules, files, namespaces and classes.
 
-\section build Building GNU Radio
+To access these parts, follow these links or use the tree browser in the left sidebar.
+A search function is also available at the top right.
 
-See the \ref build_guide page for details about the project's
-dependencies and build process.
-
-Once built, look on <a href="http://gnuradio.org" target="_blank">gnuradio.org</a> for
-tutorials on using the software system and see \ref
-page_exploring_gnuradio for a few simple examples exploring GNU Radio.
-
-
-\section blocks GNU Radio Blocks
-
-GNU Radio uses discrete signal processing blocks that are connected
-together to perform your signal processing application. This manual
-contain a list of all GNU Radio <a href="modules.html"><b>C++ Blocks</b></a>.
-
-Please note that at this time, we haven't found an acceptable way to
-provide unified documentation for the C++ parts of the system and the
-parts written in Python (mostly hierarchical blocks).  Until this gets
-worked out, please bear with us, or better yet, solve it for us!
-
-
-\section toc Manual Contents
-More details on packages in GNU Radio:
-\li \ref page_audio
-\li \ref page_digital
-\li \ref page_qtgui
-\li \ref page_uhd
-\li \ref page_vocoder
-
-More details on GNU Radio concepts:
-\li \ref page_logger
-\li \ref page_pmt
-\li \ref page_msg_passing
-\li \ref page_stream_tags
-\li \ref page_metadata
-\li \ref volk_guide
-\li \ref page_perf_counters
-\li \ref page_pfb
-\li \ref page_affinity
-\li \ref page_tagged_stream_blocks
-\li \ref page_ofdm
-\li \ref page_packet_data
-
-
-\section flowgraph Operating a Flowgraph
-
-The basic data structure in GNU Radio is the flowgraph, which
-represents the connections of the blocks through which a continuous
-stream of samples flows. The concept of a flowgraph is an acyclic
-directional graph with one or more source blocks (to insert samples
-into the flowgraph), one or more sink blocks (to terminate or export
-samples from the flowgraph), and any signal processing blocks in
-between.
-
-A program must at least create a GNU Radio 'top_block', which
-represents the top-most structure of the flowgraph. The top blocks
-provide the overall control and hold methods such as 'start,' 'stop,'
-and 'wait.'
-
-The general construction of a GNU Radio application is to create a
-gr_top_block, instantiate the blocks, connect the blocks together, and
-then start the gr_top_block. The following program shows how this is
-done. A single source and sink are used with a FIR filter between
-them.
-
-\code
-    from gnuradio import gr, blocks, filter, analog
-
-    class my_topblock(gr.top_block):
-        def __init__(self):
-            gr.top_block.__init__(self)
-
-            amp = 1
-            taps = filter.firdes.low_pass(1, 1, 0.1, 0.01)
-
-            self.src = analog.noise_source_c(analog.GR_GAUSSIAN, amp)
-            self.flt = filter.fir_filter_ccf(1, taps)
-            self.snk = blocks.null_sink(gr.sizeof_gr_complex)
-
-            self.connect(self.src, self.flt, self.snk)
-
-    if __name__ == "__main__":
-        tb = my_topblock()
-        tb.start()
-        tb.wait()
-\endcode
-
-The 'tb.start()' starts the data flowing through the flowgraph while
-the 'tb.wait()' is the equivalent of a thread's 'join' operation and
-blocks until the gr_top_block is done.
-
-An alternative to using the 'start' and 'wait' methods, a 'run' method is
-also provided for convenience that is a blocking start call;
-equivalent to the above 'start' followed by a 'wait.'
-
-
-\subsection latency Latency and Throughput
-
-By default, GNU Radio runs a scheduler that attempts to optimize
-throughput. Using a dynamic scheduler, blocks in a flowgraph pass
-chunks of items from sources to sinks. The sizes of these chunks will
-vary depending on the speed of processing. For each block, the number
-of items is can process is dependent on how much space it has in its
-output buffer(s) and how many items are available on the input
-buffer(s).
-
-The consequence of this is that often a block may be called with a very
-large number of items to process (several thousand). In terms of
-speed, this is efficient since now the majority of the processing time
-is taken up with processing samples. Smaller chunks mean more calls
-into the scheduler to retrieve more data. The downside to this is that
-it can lead to large latency while a block is processing a large chunk
-of data.
-
-To combat this problem, the gr_top_block can be passed a limit on the
-number of output items a block will ever receive. A block may get less
-than this number, but never more, and so it serves as an upper limit
-to the latency any block will exhibit. By limiting the number of items
-per call to a block, though, we increase the overhead of the
-scheduler, and so reduce the overall efficiency of the application.
-
-To set the maximum number of output items, we pass a value into the
-'start' or 'run' method of the gr_top_block:
-
-\code
-     tb.start(1000)
-     tb.wait()
-or
-     tb.run(1000)
-\endcode
-
-Using this method, we place a global restriction on the size of items
-to all blocks. Each block, though, has the ability to overwrite this
-with its own limit. Using the 'set_max_noutput_items(m)' method for an
-individual block will overwrite the global setting. For example, in
-the following code, the global setting is 1000 items max, except for
-the FIR filter, which can receive up to 2000 items.
-
-\code
-     tb.flt.set_max_noutput_items(2000)
-     tb.run(1000)
-\endcode
-
-In some situations, you might actually want to restrict the size of
-the buffer itself. This can help to prevent a buffer who is blocked
-for data from just increasing the amount of items in its buffer, which
-will then cause an increased latency for new samples. You can set the
-size of an output buffer for each output port for every block.
-
-WARNING: This is an advanced feature in GNU Radio and should not be
-used without a full understanding of this concept as explained below.
-
-To set the output buffer size of a block, you simply call:
-
-\code
-     tb.blk0.set_max_output_buffer(2000)
-     tb.blk1.set_max_output_buffer(1, 2000)
-     tb.start()
-     print tb.blk1.max_output_buffer(0)
-     print tb.blk1.max_output_buffer(1)
-\endcode
-
-In the above example, all ports of blk0 are set to a buffer size of
-2000 in _items_ (not bytes), and blk1 only sets the size for output
-port 1, any and all other ports use the default. The third and fourth
-lines just print out the buffer sizes for ports 0 and 1 of blk1. This
-is done after start() is called because the values are updated based
-on what is actually allocated to the block's buffers.
-
-NOTES:
-
-1. Buffer length assignment is done once at runtime (i.e., when run()
-or start() is called). So to set the max buffer lengths, the
-set_max_output_buffer calls must be done before this.
-
-2. Once the flowgraph is started, the buffer lengths for a block are
-set and cannot be dynamically changed, even during a
-lock()/unlock(). If you need to change the buffer size, you will have
-to delete the block and rebuild it, and therefore must disconnect and
-reconnect the blocks.
-
-3. This can affect throughput. Large buffers are designed to improve
-the efficiency and speed of the program at the expense of
-latency. Limiting the size of the buffer may decrease performance.
-
-4. The real buffer size is actually based on a minimum granularity of
-the system. Typically, this is a page size, which is typically 4096
-bytes. This means that any buffer size that is specified with this
-command will get rounded up to the nearest granularity (e.g., page)
-size. When calling max_output_buffer(port) after the flowgraph is
-started, you will get how many items were actually allocated in the
-buffer, which may be different than what was initially specified.
-
-
-\section reconfigure Reconfiguring Flowgraphs
-
-It is possible to reconfigure the flowgraph at runtime. The
-reconfiguration is meant for changes in the flowgraph structure, not
-individual parameter settings of the blocks. For example, changing the
-constant in a gr::blocks::add_const_cc block can be done while the flowgraph is
-running using the 'set_k(k)' method.
-
-Reconfiguration is done by locking the flowgraph, which stops it from
-running and processing data, performing the reconfiguration, and then
-restarting the graph by unlocking it.
-
-The following example code shows a graph that first adds two
-gr::analog::noise_source_c blocks and then replaces the
-gr::blocks::add_cc block with a gr::blocks::sub_cc block to then
-subtract the sources.
-
-\code
-from gnuradio import gr, analog, blocks
-import time
-
-class mytb(gr.top_block):
-    def __init__(self):
-        gr.top_block.__init__(self)
-
-        self.src0 = analog.noise_source_c(analog.GR_GAUSSIAN, 1)
-        self.src1 = analog.noise_source_c(analog.GR_GAUSSIAN, 1)
-        self.add  = blocks.add_cc()
-        self.sub  = blocks.sub_cc()
-        self.head = blocks.head(gr.sizeof_gr_complex, 1000000)
-        self.snk  = blocks.file_sink(gr.sizeof_gr_complex, "output.32fc")
-
-        self.connect(self.src0, (self.add,0))
-        self.connect(self.src1, (self.add,1))
-        self.connect(self.add, self.head)
-        self.connect(self.head, self.snk)
-
-def main():
-    tb = mytb()
-    tb.start()
-    time.sleep(0.01)
-
-    # Stop flowgraph and disconnect the add block
-    tb.lock()
-    tb.disconnect(tb.add, tb.head)
-    tb.disconnect(tb.src0, (tb.add,0))
-    tb.disconnect(tb.src1, (tb.add,1))
-
-    # Connect the sub block and restart
-    tb.connect(tb.sub, tb.head)
-    tb.connect(tb.src0, (tb.sub,0))
-    tb.connect(tb.src1, (tb.sub,1))
-    tb.unlock()
-
-    tb.wait()
-
-if __name__ == "__main__":
-    main()
-\endcode
-
-During reconfiguration, the maximum noutput_items value can be changed
-either globally using the 'set_max_noutput_items(m)' on the gr_top_block
-object or locally using the 'set_max_noutput_items(m)' on any given
-block object.
-
-A block also has a 'unset_max_noutput_items()' method that unsets the
-local max noutput_items value so that block reverts back to using the
-global value.
-
-The following example expands the previous example but sets and resets
-the max noutput_items both locally and globally.
-
-\code
-from gnuradio import gr, analog, blocks
-import time
-
-class mytb(gr.top_block):
-    def __init__(self):
-        gr.top_block.__init__(self)
-
-        self.src0 = analog.noise_source_c(analog.GR_GAUSSIAN, 1)
-        self.src1 = analog.noise_source_c(analog.GR_GAUSSIAN, 1)
-        self.add  = blocks.add_cc()
-        self.sub  = blocks.sub_cc()
-        self.head = blocks.head(gr.sizeof_gr_complex, 1000000)
-        self.snk  = blocks.file_sink(gr.sizeof_gr_complex, "output.32fc")
-
-        self.connect(self.src0, (self.add,0))
-        self.connect(self.src1, (self.add,1))
-        self.connect(self.add, self.head)
-        self.connect(self.head, self.snk)
-
-def main():
-    # Start the gr_top_block after setting some max noutput_items.
-    tb = mytb()
-    tb.src1.set_max_noutput_items(2000)
-    tb.start(100)
-    time.sleep(0.01)
-
-    # Stop flowgraph and disconnect the add block
-    tb.lock()
-
-    tb.disconnect(tb.add, tb.head)
-    tb.disconnect(tb.src0, (tb.add,0))
-    tb.disconnect(tb.src1, (tb.add,1))
-
-    # Connect the sub block
-    tb.connect(tb.sub, tb.head)
-    tb.connect(tb.src0, (tb.sub,0))
-    tb.connect(tb.src1, (tb.sub,1))
-
-    # Set new max_noutput_items for the gr_top_block
-    # and unset the local value for src1
-    tb.set_max_noutput_items(1000)
-    tb.src1.unset_max_noutput_items()
-    tb.unlock()
-
-    tb.wait()
-
-if __name__ == "__main__":
-    main()
-\endcode
-
-
-\section volk_main Using Volk in GNU Radio
-
-The \ref volk_guide page provides an overview of how to incorporate
-and use Volk in GNU Radio blocks.
-
-Many blocks have already been converted to use Volk in their calls, so
-they can also serve as examples. See the
-gr::blocks::complex_to_<type>.h files for examples of various blocks
-that make use of Volk.
-
-
-\section prefs Configuration / Preference Files
-
-GNU Radio defines some of its basic behavior through a set of
-configuration files located in
-${prefix}/etc/gnuradio/conf.d. Different components have different
-files listed in here for the various properties. These will be read
-once when starting a GNU Radio application, so updates during runtime
-will not affect them.
-
-The configuration files use the following format:
-
-\code
-# Stuff from section 1
-[section1]
-var1 = value1
-var2 = value2 # value of 2
-
-# Stuff from section 2
-[section2]
-var3 = value3
-\endcode
-
-In this file, the hash mark ('#') indicates a comment and blank lines
-are ignored. Section labels are defined inside square brackets as a
-group distinguisher. All options must be associated with a section
-name. The options are listed one per line with the option name is
-given followed by an equals ('=') sign and then the value.
-
-All section and option names must not have white spaces. If a value
-must have white space, the it MUST be put inside quotes. Any quoted
-value will have its white space preserved and the quotes internally
-will be stripped. As an example, on Apple desktops, an output device
-of "Display Audio" is a possible output device and can be set as:
-
-\code
-[audio_osx]
-default_output_device = "Display Audio"
-\endcode
-
-The result will pass Display Audio to the audio setup.
-
-The value of an option can be a string or number and retrieved through
-a few different interfaces. There is a single preference object
-created when GNU Radio is launched. In Python, you can get this by
-making a new variable:
-
-\code
-p = gr.prefs()
-\endcode
-
-Similarly, in C++, we get a reference to the object by explicitly
-calling for the singleton of the object:
-
-\code
-  prefs *p = prefs::singleton();
-\endcode
-
-The methods associated with this preferences object are (from class gr::prefs):
-
-\code
-  bool has_section(string section)
-  bool has_option(string section, string option)
-  string get_string(string section, string option, string default_val)
-  bool get_bool(string section, string option, bool default_val)
-  long get_long(string section, string option, long default_val)
-  double get_double(string section, string option, double default_val)
-\endcode
-
-When setting a Boolean value, we can use 0, 1, "True", "true",
-"False", "false", "On", "on", "Off", and "off".
-
-All configuration preferences in these files can also be overloaded by
-an environmental variable. The environmental variable is named based
-on the section and option name from the configuration file as:
-
-\code
-  GR_CONF_<SECTION>_<OPTION> = <value>
-\endcode
-
-The "GR_CONF_" is a prefix to identify this as a GNU Radio
-configuration variable and the section and option names are in
-uppercase. The value is the same format that would be used in the
-config file itself.
-
-
-
-\section oot_config_page Out-of-Tree Configuration
-
-New as of 3.6.5.
-
-Using gr_modtool, each package comes with the ability to easily locate
-the gnuradio-runtime library using the 'find_package(GnuradioRuntime)'
-cmake command. This only locates the gnuradio-runtime library and
-include directory, which is enough for most simple projects.
-
-As projects become more complicated and start needing to rely on other
-GNU Radio components like gnuradio-blocks or gnuradio-filter, for
-example, and when they become dependent on certain API compatibility
-versions of GNU Radio, we need something more. And so we have
-introduced the GnuradioConfig.cmake file.
-
-When GNU Radio is installed, it also installs a GNU Radio-specific
-cmake config file that we can use for more advanced compatibility
-issues of our projects. This tool allows us to specific the API
-compatible version and a set of components that are required.
-
-Taking the above example, say we have built against version 3.6.5 with
-features that were introduced in this version and we need the blocks
-and filter components as well as the main core library. We fist set a
-cmake variable GR_REQUIRED_COMPONENTS to the components we need. We
-then use the 'find_package' command and also set a minimum required
-API compatible version. Since we are on the 3.6 API version, the
-minimum required version is "3.6.5". The code in the CMakeLists.txt
-file would look like this:
-
-\code
-  set(GR_REQUIRED_COMPONENTS RUNTIME BLOCKS FILTER)
-  find_package(Gnuradio 3.6.5)
-\endcode
-
-Note that the capitalization is important on both lines.
-
-If the installed version of GNU Radio is 3.6.4 or some other API
-version like 3.5 or 3.7, the Cmake configuration will fail with the
-version error. Likewise, if libgnuradio-filter was not installed as
-part of GNU Radio, the configuration will also fail.
-
-\subsection oot_config_path_page Install Path
-
-Cmake has to know where to find either the package config files or the
-GnuradioConfig.cmake script. The package config files are located in
-$prefix/lib/pkgconfig while all of the Cmake scripts from GNU Radio
-are installed into $prefix/lib/cmake/gnuradio.
-
-If the installed GNU Radio $prefix is '/usr' or '/usr/local', then
-everything should work fine. If the GNU Radio install $prefix is
-something else, then Cmake must be told where to find it. This can be
-done in a few ways:
-
-1. If you are installing the out-of-tree module into the same $prefix,
-then you would be setting '-DCMAKE_INSTALL_PREFIX' on the
-configuration command line. This is enough to tell Cmake where to look
-for the configuration files.
-
-2. Cmake will try to find the package config (*.pc) files. If it can,
-these files will instruct Cmake where to look for the rest of the
-configuration options. If this is not set, it can be set as:
-
-\code
-    export PKG_CONFIG_PATH=$prefix/lib/pkgconfg:$PKG_CONFIG_PATH
-\endcode
-
-3. Set the CMAKE_PREFIX_PATH environmental variable to $prefix.
-
-\code
-    export CMAKE_PREFIX_PATH=$prefix:$CMAKE_PREFIX_PATH
-\endcode
-
-
-With method 1, you will be installing your OOT project into the same
-$prefix as GNU Radio. With methods 2 and 3, you can install your
-component anywhere you like (using -DCMAKE_INSTALL_PREFIX).
+\li \subpage page_usage "Part I - GNU Radio Usage"
+\li \subpage page_components "Part II - Reference"
 
 */
diff --git a/docs/doxygen/other/oot_config.dox b/docs/doxygen/other/oot_config.dox
new file mode 100644
index 0000000000..bb441c5060
--- /dev/null
+++ b/docs/doxygen/other/oot_config.dox
@@ -0,0 +1,78 @@
+/*! \page page_oot_config Out-of-Tree Configuration
+
+New as of 3.6.5.
+
+Using gr_modtool, each package comes with the ability to easily locate
+the gnuradio-runtime library using the 'find_package(GnuradioRuntime)'
+cmake command. This only locates the gnuradio-runtime library and
+include directory, which is enough for most simple projects.
+
+As projects become more complicated and start needing to rely on other
+GNU Radio components like gnuradio-blocks or gnuradio-filter, for
+example, and when they become dependent on certain API compatibility
+versions of GNU Radio, we need something more. And so we have
+introduced the GnuradioConfig.cmake file.
+
+When GNU Radio is installed, it also installs a GNU Radio-specific
+cmake config file that we can use for more advanced compatibility
+issues of our projects. This tool allows us to specific the API
+compatible version and a set of components that are required.
+
+Taking the above example, say we have built against version 3.6.5 with
+features that were introduced in this version and we need the blocks
+and filter components as well as the main core library. We fist set a
+cmake variable GR_REQUIRED_COMPONENTS to the components we need. We
+then use the 'find_package' command and also set a minimum required
+API compatible version. Since we are on the 3.6 API version, the
+minimum required version is "3.6.5". The code in the CMakeLists.txt
+file would look like this:
+
+\code
+  set(GR_REQUIRED_COMPONENTS RUNTIME BLOCKS FILTER)
+  find_package(Gnuradio 3.6.5)
+\endcode
+
+Note that the capitalization is important on both lines.
+
+If the installed version of GNU Radio is 3.6.4 or some other API
+version like 3.5 or 3.7, the Cmake configuration will fail with the
+version error. Likewise, if libgnuradio-filter was not installed as
+part of GNU Radio, the configuration will also fail.
+
+\section oot_config_path_page Install Path
+
+Cmake has to know where to find either the package config files or the
+GnuradioConfig.cmake script. The package config files are located in
+$prefix/lib/pkgconfig while all of the Cmake scripts from GNU Radio
+are installed into $prefix/lib/cmake/gnuradio.
+
+If the installed GNU Radio $prefix is '/usr' or '/usr/local', then
+everything should work fine. If the GNU Radio install $prefix is
+something else, then Cmake must be told where to find it. This can be
+done in a few ways:
+
+1. If you are installing the out-of-tree module into the same $prefix,
+then you would be setting '-DCMAKE_INSTALL_PREFIX' on the
+configuration command line. This is enough to tell Cmake where to look
+for the configuration files.
+
+2. Cmake will try to find the package config (*.pc) files. If it can,
+these files will instruct Cmake where to look for the rest of the
+configuration options. If this is not set, it can be set as:
+
+\code
+    export PKG_CONFIG_PATH=$prefix/lib/pkgconfg:$PKG_CONFIG_PATH
+\endcode
+
+3. Set the CMAKE_PREFIX_PATH environmental variable to $prefix.
+
+\code
+    export CMAKE_PREFIX_PATH=$prefix:$CMAKE_PREFIX_PATH
+\endcode
+
+
+With method 1, you will be installing your OOT project into the same
+$prefix as GNU Radio. With methods 2 and 3, you can install your
+component anywhere you like (using -DCMAKE_INSTALL_PREFIX).
+
+*/
diff --git a/docs/doxygen/other/operating_fg.dox b/docs/doxygen/other/operating_fg.dox
new file mode 100644
index 0000000000..b075ca648a
--- /dev/null
+++ b/docs/doxygen/other/operating_fg.dox
@@ -0,0 +1,278 @@
+/*! \page page_operating_fg Handling flow graphs
+
+\section flowgraph Operating a Flowgraph
+
+The basic data structure in GNU Radio is the flowgraph, which
+represents the connections of the blocks through which a continuous
+stream of samples flows. The concept of a flowgraph is an acyclic
+directional graph with one or more source blocks (to insert samples
+into the flowgraph), one or more sink blocks (to terminate or export
+samples from the flowgraph), and any signal processing blocks in
+between.
+
+A program must at least create a GNU Radio 'top_block', which
+represents the top-most structure of the flowgraph. The top blocks
+provide the overall control and hold methods such as 'start,' 'stop,'
+and 'wait.'
+
+The general construction of a GNU Radio application is to create a
+gr_top_block, instantiate the blocks, connect the blocks together, and
+then start the gr_top_block. The following program shows how this is
+done. A single source and sink are used with a FIR filter between
+them.
+
+\code
+    from gnuradio import gr, blocks, filter, analog
+
+    class my_topblock(gr.top_block):
+        def __init__(self):
+            gr.top_block.__init__(self)
+
+            amp = 1
+            taps = filter.firdes.low_pass(1, 1, 0.1, 0.01)
+
+            self.src = analog.noise_source_c(analog.GR_GAUSSIAN, amp)
+            self.flt = filter.fir_filter_ccf(1, taps)
+            self.snk = blocks.null_sink(gr.sizeof_gr_complex)
+
+            self.connect(self.src, self.flt, self.snk)
+
+    if __name__ == "__main__":
+        tb = my_topblock()
+        tb.start()
+        tb.wait()
+\endcode
+
+The 'tb.start()' starts the data flowing through the flowgraph while
+the 'tb.wait()' is the equivalent of a thread's 'join' operation and
+blocks until the gr_top_block is done.
+
+An alternative to using the 'start' and 'wait' methods, a 'run' method is
+also provided for convenience that is a blocking start call;
+equivalent to the above 'start' followed by a 'wait.'
+
+
+\subsection latency Latency and Throughput
+
+By default, GNU Radio runs a scheduler that attempts to optimize
+throughput. Using a dynamic scheduler, blocks in a flowgraph pass
+chunks of items from sources to sinks. The sizes of these chunks will
+vary depending on the speed of processing. For each block, the number
+of items is can process is dependent on how much space it has in its
+output buffer(s) and how many items are available on the input
+buffer(s).
+
+The consequence of this is that often a block may be called with a very
+large number of items to process (several thousand). In terms of
+speed, this is efficient since now the majority of the processing time
+is taken up with processing samples. Smaller chunks mean more calls
+into the scheduler to retrieve more data. The downside to this is that
+it can lead to large latency while a block is processing a large chunk
+of data.
+
+To combat this problem, the gr_top_block can be passed a limit on the
+number of output items a block will ever receive. A block may get less
+than this number, but never more, and so it serves as an upper limit
+to the latency any block will exhibit. By limiting the number of items
+per call to a block, though, we increase the overhead of the
+scheduler, and so reduce the overall efficiency of the application.
+
+To set the maximum number of output items, we pass a value into the
+'start' or 'run' method of the gr_top_block:
+
+\code
+     tb.start(1000)
+     tb.wait()
+or
+     tb.run(1000)
+\endcode
+
+Using this method, we place a global restriction on the size of items
+to all blocks. Each block, though, has the ability to overwrite this
+with its own limit. Using the 'set_max_noutput_items(m)' method for an
+individual block will overwrite the global setting. For example, in
+the following code, the global setting is 1000 items max, except for
+the FIR filter, which can receive up to 2000 items.
+
+\code
+     tb.flt.set_max_noutput_items(2000)
+     tb.run(1000)
+\endcode
+
+In some situations, you might actually want to restrict the size of
+the buffer itself. This can help to prevent a buffer who is blocked
+for data from just increasing the amount of items in its buffer, which
+will then cause an increased latency for new samples. You can set the
+size of an output buffer for each output port for every block.
+
+WARNING: This is an advanced feature in GNU Radio and should not be
+used without a full understanding of this concept as explained below.
+
+To set the output buffer size of a block, you simply call:
+
+\code
+     tb.blk0.set_max_output_buffer(2000)
+     tb.blk1.set_max_output_buffer(1, 2000)
+     tb.start()
+     print tb.blk1.max_output_buffer(0)
+     print tb.blk1.max_output_buffer(1)
+\endcode
+
+In the above example, all ports of blk0 are set to a buffer size of
+2000 in _items_ (not bytes), and blk1 only sets the size for output
+port 1, any and all other ports use the default. The third and fourth
+lines just print out the buffer sizes for ports 0 and 1 of blk1. This
+is done after start() is called because the values are updated based
+on what is actually allocated to the block's buffers.
+
+NOTES:
+
+1. Buffer length assignment is done once at runtime (i.e., when run()
+or start() is called). So to set the max buffer lengths, the
+set_max_output_buffer calls must be done before this.
+
+2. Once the flowgraph is started, the buffer lengths for a block are
+set and cannot be dynamically changed, even during a
+lock()/unlock(). If you need to change the buffer size, you will have
+to delete the block and rebuild it, and therefore must disconnect and
+reconnect the blocks.
+
+3. This can affect throughput. Large buffers are designed to improve
+the efficiency and speed of the program at the expense of
+latency. Limiting the size of the buffer may decrease performance.
+
+4. The real buffer size is actually based on a minimum granularity of
+the system. Typically, this is a page size, which is typically 4096
+bytes. This means that any buffer size that is specified with this
+command will get rounded up to the nearest granularity (e.g., page)
+size. When calling max_output_buffer(port) after the flowgraph is
+started, you will get how many items were actually allocated in the
+buffer, which may be different than what was initially specified.
+
+
+\section reconfigure Reconfiguring Flowgraphs
+
+It is possible to reconfigure the flowgraph at runtime. The
+reconfiguration is meant for changes in the flowgraph structure, not
+individual parameter settings of the blocks. For example, changing the
+constant in a gr::blocks::add_const_cc block can be done while the flowgraph is
+running using the 'set_k(k)' method.
+
+Reconfiguration is done by locking the flowgraph, which stops it from
+running and processing data, performing the reconfiguration, and then
+restarting the graph by unlocking it.
+
+The following example code shows a graph that first adds two
+gr::analog::noise_source_c blocks and then replaces the
+gr::blocks::add_cc block with a gr::blocks::sub_cc block to then
+subtract the sources.
+
+\code
+from gnuradio import gr, analog, blocks
+import time
+
+class mytb(gr.top_block):
+    def __init__(self):
+        gr.top_block.__init__(self)
+
+        self.src0 = analog.noise_source_c(analog.GR_GAUSSIAN, 1)
+        self.src1 = analog.noise_source_c(analog.GR_GAUSSIAN, 1)
+        self.add  = blocks.add_cc()
+        self.sub  = blocks.sub_cc()
+        self.head = blocks.head(gr.sizeof_gr_complex, 1000000)
+        self.snk  = blocks.file_sink(gr.sizeof_gr_complex, "output.32fc")
+
+        self.connect(self.src0, (self.add,0))
+        self.connect(self.src1, (self.add,1))
+        self.connect(self.add, self.head)
+        self.connect(self.head, self.snk)
+
+def main():
+    tb = mytb()
+    tb.start()
+    time.sleep(0.01)
+
+    # Stop flowgraph and disconnect the add block
+    tb.lock()
+    tb.disconnect(tb.add, tb.head)
+    tb.disconnect(tb.src0, (tb.add,0))
+    tb.disconnect(tb.src1, (tb.add,1))
+
+    # Connect the sub block and restart
+    tb.connect(tb.sub, tb.head)
+    tb.connect(tb.src0, (tb.sub,0))
+    tb.connect(tb.src1, (tb.sub,1))
+    tb.unlock()
+
+    tb.wait()
+
+if __name__ == "__main__":
+    main()
+\endcode
+
+During reconfiguration, the maximum noutput_items value can be changed
+either globally using the 'set_max_noutput_items(m)' on the gr_top_block
+object or locally using the 'set_max_noutput_items(m)' on any given
+block object.
+
+A block also has a 'unset_max_noutput_items()' method that unsets the
+local max noutput_items value so that block reverts back to using the
+global value.
+
+The following example expands the previous example but sets and resets
+the max noutput_items both locally and globally.
+
+\code
+from gnuradio import gr, analog, blocks
+import time
+
+class mytb(gr.top_block):
+    def __init__(self):
+        gr.top_block.__init__(self)
+
+        self.src0 = analog.noise_source_c(analog.GR_GAUSSIAN, 1)
+        self.src1 = analog.noise_source_c(analog.GR_GAUSSIAN, 1)
+        self.add  = blocks.add_cc()
+        self.sub  = blocks.sub_cc()
+        self.head = blocks.head(gr.sizeof_gr_complex, 1000000)
+        self.snk  = blocks.file_sink(gr.sizeof_gr_complex, "output.32fc")
+
+        self.connect(self.src0, (self.add,0))
+        self.connect(self.src1, (self.add,1))
+        self.connect(self.add, self.head)
+        self.connect(self.head, self.snk)
+
+def main():
+    # Start the gr_top_block after setting some max noutput_items.
+    tb = mytb()
+    tb.src1.set_max_noutput_items(2000)
+    tb.start(100)
+    time.sleep(0.01)
+
+    # Stop flowgraph and disconnect the add block
+    tb.lock()
+
+    tb.disconnect(tb.add, tb.head)
+    tb.disconnect(tb.src0, (tb.add,0))
+    tb.disconnect(tb.src1, (tb.add,1))
+
+    # Connect the sub block
+    tb.connect(tb.sub, tb.head)
+    tb.connect(tb.src0, (tb.sub,0))
+    tb.connect(tb.src1, (tb.sub,1))
+
+    # Set new max_noutput_items for the gr_top_block
+    # and unset the local value for src1
+    tb.set_max_noutput_items(1000)
+    tb.src1.unset_max_noutput_items()
+    tb.unlock()
+
+    tb.wait()
+
+if __name__ == "__main__":
+    main()
+\endcode
+
+
+*/
+
diff --git a/docs/doxygen/other/prefs.dox b/docs/doxygen/other/prefs.dox
new file mode 100644
index 0000000000..46f68c447e
--- /dev/null
+++ b/docs/doxygen/other/prefs.dox
@@ -0,0 +1,87 @@
+/*! \page page_prefs Configuration files
+
+\section prefs Configuration / Preference Files
+
+GNU Radio defines some of its basic behavior through a set of
+configuration files located in
+${prefix}/etc/gnuradio/conf.d. Different components have different
+files listed in here for the various properties. These will be read
+once when starting a GNU Radio application, so updates during runtime
+will not affect them.
+
+The configuration files use the following format:
+
+\code
+# Stuff from section 1
+[section1]
+var1 = value1
+var2 = value2 # value of 2
+
+# Stuff from section 2
+[section2]
+var3 = value3
+\endcode
+
+In this file, the hash mark ('#') indicates a comment and blank lines
+are ignored. Section labels are defined inside square brackets as a
+group distinguisher. All options must be associated with a section
+name. The options are listed one per line with the option name is
+given followed by an equals ('=') sign and then the value.
+
+All section and option names must not have white spaces. If a value
+must have white space, the it MUST be put inside quotes. Any quoted
+value will have its white space preserved and the quotes internally
+will be stripped. As an example, on Apple desktops, an output device
+of "Display Audio" is a possible output device and can be set as:
+
+\code
+[audio_osx]
+default_output_device = "Display Audio"
+\endcode
+
+The result will pass Display Audio to the audio setup.
+
+The value of an option can be a string or number and retrieved through
+a few different interfaces. There is a single preference object
+created when GNU Radio is launched. In Python, you can get this by
+making a new variable:
+
+\code
+p = gr.prefs()
+\endcode
+
+Similarly, in C++, we get a reference to the object by explicitly
+calling for the singleton of the object:
+
+\code
+  prefs *p = prefs::singleton();
+\endcode
+
+The methods associated with this preferences object are (from class gr::prefs):
+
+\code
+  bool has_section(string section)
+  bool has_option(string section, string option)
+  string get_string(string section, string option, string default_val)
+  bool get_bool(string section, string option, bool default_val)
+  long get_long(string section, string option, long default_val)
+  double get_double(string section, string option, double default_val)
+\endcode
+
+When setting a Boolean value, we can use 0, 1, "True", "true",
+"False", "false", "On", "on", "Off", and "off".
+
+All configuration preferences in these files can also be overloaded by
+an environmental variable. The environmental variable is named based
+on the section and option name from the configuration file as:
+
+\code
+  GR_CONF_<SECTION>_<OPTION> = <value>
+\endcode
+
+The "GR_CONF_" is a prefix to identify this as a GNU Radio
+configuration variable and the section and option names are in
+uppercase. The value is the same format that would be used in the
+config file itself.
+
+*/
diff --git a/docs/doxygen/other/usage.dox b/docs/doxygen/other/usage.dox
new file mode 100644
index 0000000000..90c638e96d
--- /dev/null
+++ b/docs/doxygen/other/usage.dox
@@ -0,0 +1,42 @@
+/*! \page page_usage Usage Manual
+
+Note: Once built, check out <a href="http://gnuradio.org" target="_blank">gnuradio.org</a> for
+more tutorials on using the software system and examples.
+
+<b>Getting Started</b>
+
+\li \subpage build_guide - Installation notes, dependencies etc.
+\li \subpage page_exploring_gnuradio
+\li \subpage page_operating_fg
+
+
+<b>Metadata and Messages</b>
+
+\li \subpage page_pmt
+\li \subpage page_metadata
+\li \subpage page_msg_passing
+\li \subpage page_stream_tags
+\li \subpage page_tagged_stream_blocks
+
+<b>Advanced Development Topics</b>
+
+\li \subpage page_logger
+\li \subpage page_perf_counters
+\li \subpage page_affinity
+\li \subpage page_prefs
+
+<b>Signal Processing and Digital Communications</b>
+
+\li \subpage page_pfb
+\li \subpage page_ofdm
+\li \subpage page_packet_data
+
+<b>Out-of-tree Modules</b>
+
+\li \subpage page_oot_config
+
+<b>VOLK</b>
+
+\li \subpage volk_guide - How to incorporate and use VOLK in GNU Radio blocks
+
+*/
diff --git a/docs/doxygen/other/extra_pages.dox b/docs/doxygen/other/volk_guide.dox
index 2a707f81aa..8fc8c3fe86 100644
--- a/docs/doxygen/other/extra_pages.dox
+++ b/docs/doxygen/other/volk_guide.dox
@@ -159,9 +159,13 @@ cmake -DCMAKE_CXX_FLAGS:STRING="-mcpu=cortex-a8 -mfpu=neon -mfloat-abi=softfp -g
 */
 
 
-
 /*! \page volk_guide Instructions for using VOLK in GNU Radio
 
+Note: Many blocks have already been converted to use Volk in their calls, so
+they can also serve as examples. See the
+gr::blocks::complex_to_<type>.h files for examples of various blocks
+that make use of Volk.
+
 \section volk_intro Introduction
 
 VOLK is the Vector-Optimized Library of Kernels. It is a library that
author	Tom Rondeau <tom@trondeau.com>	2014-07-23 16:57:12 -0400
committer	Tom Rondeau <tom@trondeau.com>	2014-07-23 16:57:12 -0400
commit	dd7006e59d96e9961f243b2b17f468e6e1854bcc (patch)
tree	c7043216dba0349e6c124843d731002bc56e3ebf /docs/doxygen/other
parent	3751ea9b2f07afe2e03aef6df561fe0a9effc377 (diff)
parent	a9c3d8ff3bc31117309004c16860d18f26369311 (diff)