From a9c3d8ff3bc31117309004c16860d18f26369311 Mon Sep 17 00:00:00 2001
From: Martin Braun <martin.braun@ettus.com>
Date: Wed, 16 Jul 2014 11:41:52 +0200
Subject: docs: Restructured intro page, added some manual pages
---
docs/doxygen/other/build_guide.dox | 160 ++++++++++++
docs/doxygen/other/components.dox | 34 +++
docs/doxygen/other/extra_pages.dox | 320 -----------------------
docs/doxygen/other/main_page.dox | 503 +-----------------------------------
docs/doxygen/other/oot_config.dox | 78 ++++++
docs/doxygen/other/operating_fg.dox | 278 ++++++++++++++++++++
docs/doxygen/other/prefs.dox | 87 +++++++
docs/doxygen/other/usage.dox | 42 +++
docs/doxygen/other/volk_guide.dox | 324 +++++++++++++++++++++++
9 files changed, 1013 insertions(+), 813 deletions(-)
create mode 100644 docs/doxygen/other/build_guide.dox
create mode 100644 docs/doxygen/other/components.dox
delete mode 100644 docs/doxygen/other/extra_pages.dox
create mode 100644 docs/doxygen/other/oot_config.dox
create mode 100644 docs/doxygen/other/operating_fg.dox
create mode 100644 docs/doxygen/other/prefs.dox
create mode 100644 docs/doxygen/other/usage.dox
create mode 100644 docs/doxygen/other/volk_guide.dox
(limited to 'docs/doxygen/other')
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/extra_pages.dox b/docs/doxygen/other/extra_pages.dox
deleted file mode 100644
index 2a707f81aa..0000000000
--- a/docs/doxygen/other/extra_pages.dox
+++ /dev/null
@@ -1,320 +0,0 @@
-/*! \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 portaudio (>= 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
-
-*/
-
-
-
-/*! \page volk_guide Instructions for using VOLK in GNU Radio
-
-\section volk_intro Introduction
-
-VOLK is the Vector-Optimized Library of Kernels. It is a library that
-contains kernels of hand-written SIMD code for different mathematical
-operations. Since each SIMD architecture can be greatly different and
-no compiler has yet come along to handle vectorization properly or
-highly efficiently, VOLK approaches the problem differently. For each
-architecture or platform that a developer wishes to vectorize for, a
-new proto-kernel is added to VOLK. At runtime, VOLK will select the
-correct proto-kernel. In this way, the users of VOLK call a kernel for
-performing the operation that is platform/architecture agnostic. This
-allows us to write portable SIMD code.
-
-VOLK kernels are always defined with a 'generic' proto-kernel, which
-is written in plain C. With the generic kernel, the kernel becomes
-portable to any platform. Kernels are then extended by adding
-proto-kernels for new platforms in which they are desired.
-
-A good example of a VOLK kernel with multiple proto-kernels defined is
-the volk_32f_s32f_multiply_32f_a. This kernel implements a scalar
-multiplication of a vector of floating point numbers (each item in the
-vector is multiplied by the same value). This kernel has the following
-proto-kernels that are defined for 'generic,' 'avx,' 'sse,' and 'orc.'
-
-\code
- void volk_32f_s32f_multiply_32f_a_generic
- void volk_32f_s32f_multiply_32f_a_sse
- void volk_32f_s32f_multiply_32f_a_avx
- void volk_32f_s32f_multiply_32f_a_orc
-\endcode
-
-These proto-kernels means that on platforms with AVX support, VOLK can
-select this option or the SSE option, depending on which is faster. On
-other platforms, the ORC SIMD compiler might provide a solution. If
-all else fails, VOLK can fall back on the generic proto-kernel, which
-will always work.
-
-Just a note on ORC. ORC is a SIMD compiler library that uses a generic
-assembly-like language for SIMD commands. Based on the available SIMD
-architecture of a system, it will try and compile a good
-solution. Tests show that the results of ORC proto-kernels are
-generally better than the generic versions but often not as good as
-the hand-tuned proto-kernels for a specific SIMD architecture. This
-is, of course, to be expected, and ORC provides a nice intermediary
-step to performance improvements until a specific hand-tuned
-proto-kernel can be made for a given platform.
-
-See <a
-href="http://gnuradio.org/redmine/projects/gnuradio/wiki/Volk">VOLK on
-gnuradio.org</a> for details on the VOLK naming scheme.
-
-
-\section volk_alignment Setting and Using Memory Alignment Information
-
-For VOLK to work as best as possible, we want to use memory-aligned
-SIMD calls, which means we have to have some way of knowing and
-controlling the alignment of the buffers passed to gr_block's work
-function. We set the alignment requirement for SIMD aligned memory
-calls with:
-
-\code
- const int alignment_multiple =
- volk_get_alignment() / output_item_size;
- set_alignment(std::max(1,alignment_multiple));
-\endcode
-
-The VOLK function 'volk_get_alignment' provides the alignment of the
-the machine architecture. We then base the alignment on the number of
-output items required to maintain the alignment, so we divide the
-number of alignment bytes by the number of bytes in an output items
-(sizeof(float), sizeof(gr_complex), etc.). This value is then set per
-block with the 'set_alignment' function.
-
-Because the scheduler tries to optimize throughput, the number of
-items available per call to work will change and depends on the
-availability of the read and write buffers. This means that it
-sometimes cannot produce a buffer that is properly memory
-aligned. This is an inevitable consequence of the scheduler
-system. Instead of requiring alignment, the scheduler enforces the
-alignment as much as possible, and when a buffer becomes unaligned,
-the scheduler will work to correct it as much as possible. If a
-block's buffers are unaligned, then, the scheduler sets a flag to
-indicate as much so that the block can then decide what best to
-do. The next section discusses the use of the aligned/unaligned
-information in a gr_block's work function.
-
-
-\section volk_work Calling VOLK kernels in Work()
-
-The buffers passed to work/general_work in a gr_block are not
-guaranteed to be aligned, but they will mostly be aligned whenever
-possible. When not aligned, the 'is_unaligned()' flag will be set so
-the scheduler knows to try to realign the buffers. We actually make
-calls to the VOLK dispatcher, which is mainly designed to check the
-buffer alignments and call the correct version of the kernel for
-us. From the user-level view of VOLK, calling the dispatcher allows us
-to ignore the concept of aligned versus unaligned. This looks like:
-
-\code
-int
-gr_some_block::work (int noutput_items,
- gr_vector_const_void_star &input_items,
- gr_vector_void_star &output_items)
-{
- const float *in = (const float *) input_items[0];
- float *out = (float *) output_items[0];
-
- // Call the dispatcher to check alignment and call the _a or _u
- // version of the kernel.
- volk_32f_something_32f(out, in, noutput_items);
-
- return noutput_items;
-}
-\endcode
-
-
-
-\section volk_tuning Tuning VOLK Performance
-
-VOLK comes with a profiler that will build a config file for the best
-SIMD architecture for your processor. Run volk_profile that is
-installed into $PREFIX/bin. This program tests all known VOLK kernels
-for each architecture supported by the processor. When finished, it
-will write to $HOME/.volk/volk_config the best architecture for the
-VOLK function. This file is read when using a function to know the
-best version of the function to execute.
-
-\subsection volk_hand_tuning Hand-Tuning Performance
-
-If you know a particular architecture works best for your processor,
-you can specify the particular architecture to use in the VOLK
-preferences file: $HOME/.volk/volk_config
-
-The file looks like:
-
-\code
- volk_<FUNCTION_NAME> <ARCHITECTURE>
-\endcode
-
-Where the "FUNCTION_NAME" is the particular function that you want to
-over-ride the default value and "ARCHITECTURE" is the VOLK SIMD
-architecture to use (generic, sse, sse2, sse3, avx, etc.). For
-example, the following config file tells VOLK to use SSE3 for the
-aligned and unaligned versions of a function that multiplies two
-complex streams together.
-
-\code
- volk_32fc_x2_multiply_32fc_a sse3
- volk_32fc_x2_multiply_32fc_u sse3
-\endcode
-
-\b Tip: if benchmarking GNU Radio blocks, it can be useful to have a
-volk_config file that sets all architectures to 'generic' as a way to
-test the vectorized versus non-vectorized implementations.
-
-*/
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/volk_guide.dox b/docs/doxygen/other/volk_guide.dox
new file mode 100644
index 0000000000..8fc8c3fe86
--- /dev/null
+++ b/docs/doxygen/other/volk_guide.dox
@@ -0,0 +1,324 @@
+/*! \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 portaudio (>= 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
+
+*/
+
+
+/*! \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
+contains kernels of hand-written SIMD code for different mathematical
+operations. Since each SIMD architecture can be greatly different and
+no compiler has yet come along to handle vectorization properly or
+highly efficiently, VOLK approaches the problem differently. For each
+architecture or platform that a developer wishes to vectorize for, a
+new proto-kernel is added to VOLK. At runtime, VOLK will select the
+correct proto-kernel. In this way, the users of VOLK call a kernel for
+performing the operation that is platform/architecture agnostic. This
+allows us to write portable SIMD code.
+
+VOLK kernels are always defined with a 'generic' proto-kernel, which
+is written in plain C. With the generic kernel, the kernel becomes
+portable to any platform. Kernels are then extended by adding
+proto-kernels for new platforms in which they are desired.
+
+A good example of a VOLK kernel with multiple proto-kernels defined is
+the volk_32f_s32f_multiply_32f_a. This kernel implements a scalar
+multiplication of a vector of floating point numbers (each item in the
+vector is multiplied by the same value). This kernel has the following
+proto-kernels that are defined for 'generic,' 'avx,' 'sse,' and 'orc.'
+
+\code
+ void volk_32f_s32f_multiply_32f_a_generic
+ void volk_32f_s32f_multiply_32f_a_sse
+ void volk_32f_s32f_multiply_32f_a_avx
+ void volk_32f_s32f_multiply_32f_a_orc
+\endcode
+
+These proto-kernels means that on platforms with AVX support, VOLK can
+select this option or the SSE option, depending on which is faster. On
+other platforms, the ORC SIMD compiler might provide a solution. If
+all else fails, VOLK can fall back on the generic proto-kernel, which
+will always work.
+
+Just a note on ORC. ORC is a SIMD compiler library that uses a generic
+assembly-like language for SIMD commands. Based on the available SIMD
+architecture of a system, it will try and compile a good
+solution. Tests show that the results of ORC proto-kernels are
+generally better than the generic versions but often not as good as
+the hand-tuned proto-kernels for a specific SIMD architecture. This
+is, of course, to be expected, and ORC provides a nice intermediary
+step to performance improvements until a specific hand-tuned
+proto-kernel can be made for a given platform.
+
+See <a
+href="http://gnuradio.org/redmine/projects/gnuradio/wiki/Volk">VOLK on
+gnuradio.org</a> for details on the VOLK naming scheme.
+
+
+\section volk_alignment Setting and Using Memory Alignment Information
+
+For VOLK to work as best as possible, we want to use memory-aligned
+SIMD calls, which means we have to have some way of knowing and
+controlling the alignment of the buffers passed to gr_block's work
+function. We set the alignment requirement for SIMD aligned memory
+calls with:
+
+\code
+ const int alignment_multiple =
+ volk_get_alignment() / output_item_size;
+ set_alignment(std::max(1,alignment_multiple));
+\endcode
+
+The VOLK function 'volk_get_alignment' provides the alignment of the
+the machine architecture. We then base the alignment on the number of
+output items required to maintain the alignment, so we divide the
+number of alignment bytes by the number of bytes in an output items
+(sizeof(float), sizeof(gr_complex), etc.). This value is then set per
+block with the 'set_alignment' function.
+
+Because the scheduler tries to optimize throughput, the number of
+items available per call to work will change and depends on the
+availability of the read and write buffers. This means that it
+sometimes cannot produce a buffer that is properly memory
+aligned. This is an inevitable consequence of the scheduler
+system. Instead of requiring alignment, the scheduler enforces the
+alignment as much as possible, and when a buffer becomes unaligned,
+the scheduler will work to correct it as much as possible. If a
+block's buffers are unaligned, then, the scheduler sets a flag to
+indicate as much so that the block can then decide what best to
+do. The next section discusses the use of the aligned/unaligned
+information in a gr_block's work function.
+
+
+\section volk_work Calling VOLK kernels in Work()
+
+The buffers passed to work/general_work in a gr_block are not
+guaranteed to be aligned, but they will mostly be aligned whenever
+possible. When not aligned, the 'is_unaligned()' flag will be set so
+the scheduler knows to try to realign the buffers. We actually make
+calls to the VOLK dispatcher, which is mainly designed to check the
+buffer alignments and call the correct version of the kernel for
+us. From the user-level view of VOLK, calling the dispatcher allows us
+to ignore the concept of aligned versus unaligned. This looks like:
+
+\code
+int
+gr_some_block::work (int noutput_items,
+ gr_vector_const_void_star &input_items,
+ gr_vector_void_star &output_items)
+{
+ const float *in = (const float *) input_items[0];
+ float *out = (float *) output_items[0];
+
+ // Call the dispatcher to check alignment and call the _a or _u
+ // version of the kernel.
+ volk_32f_something_32f(out, in, noutput_items);
+
+ return noutput_items;
+}
+\endcode
+
+
+
+\section volk_tuning Tuning VOLK Performance
+
+VOLK comes with a profiler that will build a config file for the best
+SIMD architecture for your processor. Run volk_profile that is
+installed into $PREFIX/bin. This program tests all known VOLK kernels
+for each architecture supported by the processor. When finished, it
+will write to $HOME/.volk/volk_config the best architecture for the
+VOLK function. This file is read when using a function to know the
+best version of the function to execute.
+
+\subsection volk_hand_tuning Hand-Tuning Performance
+
+If you know a particular architecture works best for your processor,
+you can specify the particular architecture to use in the VOLK
+preferences file: $HOME/.volk/volk_config
+
+The file looks like:
+
+\code
+ volk_<FUNCTION_NAME> <ARCHITECTURE>
+\endcode
+
+Where the "FUNCTION_NAME" is the particular function that you want to
+over-ride the default value and "ARCHITECTURE" is the VOLK SIMD
+architecture to use (generic, sse, sse2, sse3, avx, etc.). For
+example, the following config file tells VOLK to use SSE3 for the
+aligned and unaligned versions of a function that multiplies two
+complex streams together.
+
+\code
+ volk_32fc_x2_multiply_32fc_a sse3
+ volk_32fc_x2_multiply_32fc_u sse3
+\endcode
+
+\b Tip: if benchmarking GNU Radio blocks, it can be useful to have a
+volk_config file that sets all architectures to 'generic' as a way to
+test the vectorized versus non-vectorized implementations.
+
+*/
--
cgit v1.2.3