[Commit-gnuradio] [gnuradio] 03/06: docs: minor updates to the docs, including a new page for Python blocks.

[git]

This is an automated email from the git hooks/post-receive script.

trondeau pushed a commit to branch master
in repository gnuradio.

commit 115254847e9c6db03a417749f4e476ed3db95e70
Author: Tom Rondeau <address@hidden>
Date:   Fri Jul 25 21:58:09 2014 -0400

    docs: minor updates to the docs, including a new page for Python blocks.
---
 docs/doxygen/other/build_guide.dox             |  12 +-
 docs/doxygen/other/metadata.dox                |  15 +-
 docs/doxygen/other/msg_passing.dox             |   5 +
 docs/doxygen/other/python_blocks.dox           | 154 +++++++++++++++++++++
 docs/doxygen/other/usage.dox                   |   1 +
 docs/doxygen/other/volk_guide.dox              | 182 +------------------------
 docs/exploring-gnuradio/exploring_gnuradio.dox |   8 +-
 7 files changed, 190 insertions(+), 187 deletions(-)

diff --git a/docs/doxygen/other/build_guide.dox 
b/docs/doxygen/other/build_guide.dox
index e831e8a..e5a1ae3 100644
--- a/docs/doxygen/other/build_guide.dox
+++ b/docs/doxygen/other/build_guide.dox
@@ -98,11 +98,11 @@ 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
+\subsection cmake_options 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_PREFIX_PATH) or set the install prefix
 (-DCMAKE_INSTALL_PREFIX=(dir)).
 
 Components can also be enabled and disabled through the options. For a
@@ -110,7 +110,7 @@ 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.
+by default so long as their dependencies are met.
 
 An example is -DENABLE_PYTHON=False turns off building any Python or
 Swigging components. The result will be the GNU Radio libraries and
@@ -132,7 +132,7 @@ version. Each type sets different flags for different 
purposes. To set
 the build type, use:
 
 \code
--DCMAKE_BUILD_TYPE="Release"|"Debug"
+-DCMAKE_BUILD_TYPE="Release"|"Debug"|"RelWithDebInfo"
 \endcode
 
 If not specified, the "Release" mode is the defaulted to.
@@ -143,6 +143,9 @@ If not specified, the "Release" mode is the defaulted to.
 the optimization to make the libraries easier to debug and step
 through.
 
+"RelWithDebInfo" builds with the release mode optimization of "-O3"
+but also exports debug symbols with "-g".
+
 
 \subsection build_gr_cmake_e100 Building for the E100
 
@@ -157,4 +160,3 @@ cmake -DCMAKE_CXX_FLAGS:STRING="-mcpu=cortex-a8 -mfpu=neon 
-mfloat-abi=softfp -g
 \endcode
 
 */
-
diff --git a/docs/doxygen/other/metadata.dox b/docs/doxygen/other/metadata.dox
index 03ebe59..e29adf3 100644
--- a/docs/doxygen/other/metadata.dox
+++ b/docs/doxygen/other/metadata.dox
@@ -20,7 +20,20 @@ about the item size, data type, if it's complex, the sample 
rate of
 the segment, the time stamp of the first sample of the segment, and
 information regarding the header size and segment size.
 
-Headers have two main tags associated with them:
+The first static portion of the header file contains the following
+information.
+
+- version: (char) version number (usually set to METADATA_VERSION)
+- rx_rate: (double) Stream's sample rate
+- rx_time: (pmt::pmt_t pair - (uint64_t, double)) Time stamp (format from UHD)
+- size: (int) item size in bytes - reflects vector length if any.
+- type: (int) data type (enum below)
+- cplx: (bool) true if data is complex
+- strt: (uint64_t) start of data relative to current header
+- bytes: (uint64_t) size of following data segment in bytes
+
+An optional extra section of the header stores information in any
+received tags. The two main tags associated with tags are:
 
 - rx_rate: the sample rate of the stream.
 - rx_time: the time stamp of the first item in the segment.
diff --git a/docs/doxygen/other/msg_passing.dox 
b/docs/doxygen/other/msg_passing.dox
index 11abf35..882252b 100644
--- a/docs/doxygen/other/msg_passing.dox
+++ b/docs/doxygen/other/msg_passing.dox
@@ -145,6 +145,11 @@ function. When a new message is pushed onto a port's 
message queue,
 it is this function that is used to process the message.
 
 
+\section python_msg_passing Message Passing in Python Blocks
+
+ADD STUFF HERE
+
+
 \section examples Code Examples
 
 The following is snippets of code from blocks current in GNU Radio
diff --git a/docs/doxygen/other/python_blocks.dox 
b/docs/doxygen/other/python_blocks.dox
new file mode 100644
index 0000000..811eb84
--- /dev/null
+++ b/docs/doxygen/other/python_blocks.dox
@@ -0,0 +1,154 @@
+/*! \page page_python_blocks Python Blocks
+
+How to create blocks in Python
+
+\subsection pyblocks_streaming Streaming Data Blocks
+
+We create blocks in Python very much like we would in C++, just with
+more Python. Figure out which type of block you want to create:
+
+\li general block (gr.basic_block)
+\li synchronous block (gr.sync_block)
+\li decimator (gr.sync_decimator)
+\li interpolator (gr.sync_interpolator)
+
+The block class inherits from one of these base classes, and then in
+defining the parent class, we set the I/O signature. However, unlike
+in C++ where we use the gr::io_signature class, here we can just
+create a Python list of the I/O data sizes using numpy data types:
+
+\li numpy.int8
+\li numpy.int16
+\li numpy.int32
+\li numpy.float32
+\li numpy.float64
+
+Like a normal C++ version of the block, we then create and initialize
+any variables in the constructor, define any setters and getters, and
+create the work function. The prototype for the work function is quite
+simple:
+
+\code
+def work(self, input_items, output_items)
+\endcode
+
+The input_items and output_items are lists of lists. The input_items
+contains a vector of input samples for every input stream, and the
+output_items is a vector for each output stream where we can place
+items. Then length of output_items[0] is equivalent to the
+noutput_items concept we are so familiar with from the C++ blocks.
+
+Following is an example Python block that adds two input streams
+together. This block is used in the qa_block_gateway.py test code.
+
+\code
+class add_2_f32_1_f32(gr.sync_block):
+    def __init__(self):
+        gr.sync_block.__init__(
+            self,
+            name = "add 2 f32",
+            in_sig = [numpy.float32, numpy.float32],
+            out_sig = [numpy.float32],
+        )
+
+    def work(self, input_items, output_items):
+        output_items[0][:] = input_items[0] + input_items[1]
+        return len(output_items[0])
+\endcode
+
+The block defines two input floating point streams by setting in_sig
+to "[numpy.float32, numpy.float32]" and a single output float stream
+in out_sig of "[numpy.float32]."
+
+The work function then just adds the two input streams together. The
+streams are input_items[0] and input_items[1]. The block still returns
+the concept of noutput_items like we use in C++, only we get it here
+by getting len(output_items[0]). Because this is a sync_block, we also
+know that the size of the input_items for both streams is the same as
+the size of the output_items vector.
+
+
+
+\subsection pyblocks_tags Using Stream Tags
+
+Python blocks have access to the stream tag system like their C++
+counterparts. The interface is almost identical except they behave
+just a bit more like we would expect in Python.
+
+To add tags to the data stream, we use the add_item_tag function:
+
+\code
+def work(self, input_items, output_items):
+    ....
+    add_item_tag(which_output, abs_offset,
+                 key, value, srcid)
+    ....
+\endcode
+
+The abs_offset is an integer of the sample that the tag is attached
+to, and key and value are both PMTs to set the key:value pair of the
+tag information, and the srcid is an optional PMT to define the source
+of the block that generate the tag.
+
+We then can get tags using either the get_tags_in_range or
+get_tags_in_window. Again, like their C++ counter parts, the
+get_tags_in_range uses the absolute item offset numbering (using
+nitems_read) while the get_tags_in_window uses relative offsets within
+the current window of items available to the work function. The main
+difference from the C++ function is that instead of having the first
+argument be a vector where the tags are stored, the Python version
+just returns a list of tags. We would use it like this:
+
+\code
+def work(self, input_items, output_items):
+    ....
+    tags = get_tags_in_window(which_input, rel_start, rel_end)
+    ....
+\endcode
+
+
+
+\subsection pyblocks_msgs Using Message Passing
+
+Again, like their C++ counterparts, Python blocks can use the
+asynchronous message passing interface. We define output message
+handlers using:
+
+\code
+self.message_port_register_out(pmt.intern("<port name>"))
+\endcode
+
+We can then post messages to this using the message_port_pub function:
+
+\code
+self.message_port_pub(pmt.intern("<port name>"), <pmt message>)
+\endcode
+
+We then register input messages and handlers in similar ways:
+
+\code
+self.message_port_register_in(pmt.intern("<port name>"))
+self.set_msg_handler(pmt.intern("<port name>"), <msg handler function>)
+\endcode
+
+Putting this together below is a very simple example:
+
+\code
+class msg_block(gr.basic_block):
+    def __init__(self):
+        gr.basic_block.__init__(
+            self,
+            name="msg_block",
+            in_sig=None,
+            out_sig=None)
+
+        self.message_port_register_out(pmt.intern('msg_out'))
+        self.message_port_register_in(pmt.intern('msg_in'))
+        self.set_msg_handler(pmt.intern('msg_in'), self.handle_msg)
+
+    def handle_msg(self, msg):
+        self.message_port_pub(pmt.intern('msg_out'),
+                              pmt.intern('message received!'))
+\endcode
+
+*/
\ No newline at end of file
diff --git a/docs/doxygen/other/usage.dox b/docs/doxygen/other/usage.dox
index 90c638e..717f14e 100644
--- a/docs/doxygen/other/usage.dox
+++ b/docs/doxygen/other/usage.dox
@@ -24,6 +24,7 @@ more tutorials on using the software system and examples.
 \li \subpage page_perf_counters
 \li \subpage page_affinity
 \li \subpage page_prefs
+\li \subpage page_python_blocks
 
 <b>Signal Processing and Digital Communications</b>
 
diff --git a/docs/doxygen/other/volk_guide.dox 
b/docs/doxygen/other/volk_guide.dox
index 8fc8c3f..a6a2445 100644
--- a/docs/doxygen/other/volk_guide.dox
+++ b/docs/doxygen/other/volk_guide.dox
@@ -1,170 +1,9 @@
-/*! \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
+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.
+that make use of VOLK.
 
 \section volk_intro Introduction
 
@@ -188,31 +27,20 @@ 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.'
+proto-kernels that are defined for 'generic,' 'avx,' 'sse,' and 'neon'
 
 \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
+    void volk_32f_s32f_multiply_32f_a_neon
 \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
+select this option or the SSE option, depending on which is faster. 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.
diff --git a/docs/exploring-gnuradio/exploring_gnuradio.dox 
b/docs/exploring-gnuradio/exploring_gnuradio.dox
index a322483..78dcfdf 100644
--- a/docs/exploring-gnuradio/exploring_gnuradio.dox
+++ b/docs/exploring-gnuradio/exploring_gnuradio.dox
@@ -1,9 +1,9 @@
 /*! \page page_exploring_gnuradio Exploring GNU Radio
 
-In this page, we will go over two examples that are shipped with GNU
-Radio. We start off with a very simple dial tone generating example
-that is done in Python. The second example uses both GNU Radio
-Companion (GRC) and Python for different stages of the example.
+Let's explore over two examples that are shipped with GNU Radio. We
+start off with a very simple dial tone generating example that is done
+in Python. The second example uses both GNU Radio Companion (GRC) and
+Python for different stages of the example.
 
 In either case, we will be actually working with Python code and the
 modules as they exist in Python. However, in the following discussion,