diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/CMakeLists.txt | 50 | ||||
| -rw-r--r-- | docs/doxygen/CMakeLists.txt | 52 | ||||
| -rw-r--r-- | docs/doxygen/Doxyfile.in | 39 | ||||
| -rw-r--r-- | docs/doxygen/Makefile.am | 2 | ||||
| -rw-r--r-- | docs/doxygen/images/gnuradio-logo.png | bin | 0 -> 5223 bytes | |||
| -rw-r--r-- | docs/doxygen/other/build_guide.dox | 135 | ||||
| -rw-r--r-- | docs/doxygen/other/group_defs.dox | 16 | ||||
| -rw-r--r-- | docs/doxygen/other/main_page.dox | 31 | ||||
| -rw-r--r-- | docs/doxygen/other/pfb_intro.dox | 82 |
9 files changed, 361 insertions, 46 deletions
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 000000000..45f9b0102 --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,50 @@ +# Copyright 2011 Free Software Foundation, Inc. +# +# This file is part of GNU Radio +# +# GNU Radio is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3, or (at your option) +# any later version. +# +# GNU Radio is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with GNU Radio; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 51 Franklin Street, +# Boston, MA 02110-1301, USA. + +######################################################################## +# Setup dependencies +######################################################################## +find_package(Doxygen) + +######################################################################## +# Register component +######################################################################## +include(GrComponent) +GR_REGISTER_COMPONENT("doxygen" ENABLE_DOXYGEN DOXYGEN_FOUND) + +######################################################################## +# Begin conditional configuration +######################################################################## +if(ENABLE_DOXYGEN) + +######################################################################## +# Setup CPack components +######################################################################## +include(GrPackage) +CPACK_COMPONENT("docs" + DISPLAY_NAME "Documentation" + DESCRIPTION "Doxygen generated documentation" +) + +######################################################################## +# Add subdirectories +######################################################################## +add_subdirectory(doxygen) + +endif(ENABLE_DOXYGEN) diff --git a/docs/doxygen/CMakeLists.txt b/docs/doxygen/CMakeLists.txt new file mode 100644 index 000000000..532b09d7f --- /dev/null +++ b/docs/doxygen/CMakeLists.txt @@ -0,0 +1,52 @@ +# Copyright 2011 Free Software Foundation, Inc. +# +# This file is part of GNU Radio +# +# GNU Radio is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3, or (at your option) +# any later version. +# +# GNU Radio is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with GNU Radio; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 51 Franklin Street, +# Boston, MA 02110-1301, USA. + +######################################################################## +# Create the doxygen configuration file +######################################################################## +file(TO_NATIVE_PATH ${CMAKE_SOURCE_DIR} top_srcdir) +file(TO_NATIVE_PATH ${CMAKE_BINARY_DIR} top_builddir) +file(TO_NATIVE_PATH ${CMAKE_SOURCE_DIR} abs_top_srcdir) +file(TO_NATIVE_PATH ${CMAKE_BINARY_DIR} abs_top_builddir) + +set(HAVE_DOT ${DOXYGEN_DOT_FOUND}) +set(enable_html_docs YES) +set(enable_latex_docs NO) +set(enable_xml_docs YES) + +configure_file( + ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in + ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile +@ONLY) + +set(BUILT_DIRS ${CMAKE_CURRENT_BINARY_DIR}/xml ${CMAKE_CURRENT_BINARY_DIR}/html) + +######################################################################## +# Make and install doxygen docs +######################################################################## +add_custom_command( + OUTPUT ${BUILT_DIRS} + COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + COMMENT "Generating documentation with doxygen" +) + +add_custom_target(doxygen_target ALL DEPENDS ${BUILT_DIRS}) + +install(DIRECTORY ${BUILT_DIRS} DESTINATION ${GR_PKG_DOC_DIR} COMPONENT "docs") diff --git a/docs/doxygen/Doxyfile.in b/docs/doxygen/Doxyfile.in index 1f544e5bd..d5614d90c 100644 --- a/docs/doxygen/Doxyfile.in +++ b/docs/doxygen/Doxyfile.in @@ -587,7 +587,6 @@ EXCLUDE = @abs_top_builddir@/docs/doxygen/html \ @abs_top_builddir@/docs/doxygen/xml-swig \ @abs_top_builddir@/docs/doxygen/other/doxypy.py \ @abs_top_builddir@/dtools \ - @abs_top_srcdir@/gcell/ibm \ @abs_top_builddir@/gnuradio-core/src/lib/bug_work_around_6.cc \ @abs_top_builddir@/gnuradio-core/src/lib/filter/assembly.h \ @abs_top_builddir@/gnuradio-core/src/lib/filter/generate_all.py \ @@ -626,49 +625,22 @@ EXCLUDE = @abs_top_builddir@/docs/doxygen/html \ @abs_top_builddir@/gr-audio-alsa/src/audio-alsa.py \ @abs_top_builddir@/gr-audio-oss/src/audio_oss.py \ @abs_top_builddir@/gr-audio-osx/src/test_audio_loop.py \ - @abs_top_builddir@/gr-cvsd-vocoder/src/lib/cvsd_vocoder.py \ - @abs_top_builddir@/gr-cvsd-vocoder/src/python/encdec.py \ @abs_top_builddir@/gr-gsm-fr-vocoder/src/lib/gsm \ @abs_top_builddir@/gr-gsm-fr-vocoder/src/lib/gsm_full_rate.py \ @abs_top_builddir@/gr-gsm-fr-vocoder/src/python/encdec.py \ @abs_top_builddir@/gr-howto-write-a-block \ - @abs_top_builddir@/gr-msdd6000/src/msdd.py \ @abs_top_builddir@/gr-pager/src/pager_swig.py \ @abs_top_builddir@/gr-qtgui \ - @abs_top_builddir@/gr-radar-mono/src/python/usrp_radar_mono.py \ - @abs_top_builddir@/gr-radio-astronomy/src/lib/ra.py \ - @abs_top_builddir@/gr-radio-astronomy/src/python \ - @abs_top_builddir@/gr-sounder/src/python/usrp_sounder.py \ @abs_top_builddir@/gr-trellis/doc \ @abs_top_builddir@/gr-trellis/src/lib/generate_all.py \ @abs_top_builddir@/gr-trellis/src/lib/generate_trellis.py \ @abs_top_builddir@/gr-trellis/src/lib/trellis.py \ - @abs_top_builddir@/gr-usrp/src/usrp1.py \ - @abs_top_builddir@/gr-usrp2/src/usrp2.py \ @abs_top_builddir@/gr-video-sdl/src/video_sdl.py \ @abs_top_builddir@/gr-wxgui/src/python \ @abs_top_builddir@/grc \ - @abs_top_builddir@/usrp/doc \ - @abs_top_builddir@/usrp/firmware \ - @abs_top_builddir@/usrp/fpga \ - @abs_top_builddir@/usrp/host/apps \ - @abs_top_builddir@/usrp/host/apps-inband \ - @abs_top_builddir@/usrp/host/lib/inband \ - @abs_top_builddir@/usrp/host/lib/legacy/ad9862.h \ - @abs_top_builddir@/usrp/host/lib/legacy/check_data.py \ - @abs_top_builddir@/usrp/host/lib/legacy/circular_buffer.h \ - @abs_top_builddir@/usrp/host/lib/legacy/circular_linked_list.h \ - @abs_top_builddir@/usrp/host/lib/legacy/db_wbx.h \ - @abs_top_builddir@/usrp/host/lib/legacy/db_wbx.cc \ - @abs_top_builddir@/usrp/host/lib/legacy/dump_data.py \ - @abs_top_builddir@/usrp/host/lib/legacy/gen_usrp_dbid.py \ - @abs_top_builddir@/usrp/host/lib/legacy/usrp_dbid.py \ - @abs_top_builddir@/usrp/host/misc \ - @abs_top_builddir@/usrp/host/swig \ - @abs_top_builddir@/usrp2/firmware \ - @abs_top_srcdir@/usrp2/firmware \ - @abs_top_builddir@/usrp2/fpga \ - @abs_top_srcdir@/usrp2/fpga + @abs_top_builddir@/_CPack_Packages \ + @abs_top_srcdir@/cmake \ + @abs_top_srcdir@/gr-qtgui/lib # The EXCLUDE_SYMLINKS tag can be used select whether or not files or # directories that are symbolic links (a Unix filesystem feature) are excluded @@ -701,7 +673,6 @@ EXCLUDE_PATTERNS = */.deps/* \ EXCLUDE_SYMBOLS = ad9862 \ numpy \ - usrpm \ *swig* \ *Swig* \ *my_top_block* \ @@ -745,7 +716,7 @@ EXAMPLE_RECURSIVE = NO # directories that contain image that are included in the documentation (see # the \image command). -IMAGE_PATH = +IMAGE_PATH = @abs_top_srcdir@/docs/doxygen/images/ # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program @@ -1308,7 +1279,7 @@ SEARCH_INCLUDES = YES # contain include files that are not input files but should be processed by # the preprocessor. -INCLUDE_PATH = +INCLUDE_PATH = @abs_top_builddir@/gruel/src/lib/pmt/ # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the diff --git a/docs/doxygen/Makefile.am b/docs/doxygen/Makefile.am index 3a67fb6d4..f763f6f79 100644 --- a/docs/doxygen/Makefile.am +++ b/docs/doxygen/Makefile.am @@ -34,6 +34,8 @@ docs: prep html/index.html html/index.html: @DOXYGEN@ +EXTRA_DIST = images/gnuradio-logo.png + prep: $(MKDIR_P) html $(MKDIR_P) xml diff --git a/docs/doxygen/images/gnuradio-logo.png b/docs/doxygen/images/gnuradio-logo.png Binary files differnew file mode 100644 index 000000000..ec4db23fc --- /dev/null +++ b/docs/doxygen/images/gnuradio-logo.png diff --git a/docs/doxygen/other/build_guide.dox b/docs/doxygen/other/build_guide.dox new file mode 100644 index 000000000..207f553a1 --- /dev/null +++ b/docs/doxygen/other/build_guide.dox @@ -0,0 +1,135 @@ +/*! \page page_build 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. + +\subsection dep_global Global Dependencies +\li git http://code.google.com/p/msysgit +\li cmake 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 +\li gsl (>= 1.10) http://gnuwin32.sourceforge.net/packages/gsl.htm + +\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_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 + +\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_shd shd: The Symplex Hardware Driver Interface +\li shd (>= 3.0.0) + +\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/ + + + +\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. + +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. + + +\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 + + +\section build_old_autotools Building Using Old Autotools Method + +As of version 3.5, we have moved to using Cmake as the default, +preferred build system. If for some reason, Cmake fails on your +system, GNU Radio still includes the old autotools build process as a +parallel build method. To build: + +\code +$ cd $(srcdir) +$ ./bootstrap // only if not building from a tarball +$ cd $(builddir) +$ $(srcdir)/configure [options] +$ make [-jN] +$ make check +$ sudo make install +\endcode + +*/ diff --git a/docs/doxygen/other/group_defs.dox b/docs/doxygen/other/group_defs.dox index 6f2e1ac7f..b0b1994ff 100644 --- a/docs/doxygen/other/group_defs.dox +++ b/docs/doxygen/other/group_defs.dox @@ -27,6 +27,11 @@ /*! \defgroup misc_blk Miscellaneous Blocks */ /*! \defgroup slicedice_blk Slicing and Dicing Streams */ /*! \defgroup vocoder_blk Voice Encoders and Decoders */ +/*! \defgroup digital Digital Modulation Blocks */ +/*! \defgroup qtgui_blk QT Graphical Interfaces */ +/*! \defgroup uhd_blk UHD Interface */ +/*! \defgroup audio_blk Audio Interface */ +/*! \defgroup pfb_blk Polyphase Filterbank */ /*! * \defgroup base_blk Base classes for GR Blocks @@ -63,15 +68,4 @@ /*! @} */ -/*! \defgroup usrp USRP */ -/*! \defgroup usrp2 USRP2 */ - -/*! - * \defgroup gcell gcell: Cell Broadband Engine SPE Scheduler & RPC Mechanism - * - * For additional information please see the - * <a href="http://gnuradio.org/trac/wiki/Gcell">gcell wiki page</a> - * and <a href="http://comsec.com/papers/gcell-sdrf-2008.pdf">gcell-sdrf-2008.pdf</a>. - */ - /*! \defgroup hardware Misc Hardware Control */ diff --git a/docs/doxygen/other/main_page.dox b/docs/doxygen/other/main_page.dox index 43fcbf67a..0caa0b20f 100644 --- a/docs/doxygen/other/main_page.dox +++ b/docs/doxygen/other/main_page.dox @@ -1,12 +1,41 @@ /*! \mainpage +\image html gnuradio-logo.png + Welcome to GNU Radio! -For a list of all GNU Radio C++ blocks, please see <a href="modules.html">C++ Blocks</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://gnuradio.squarespace.com" target="_blank"><b>GNU Radio blog</b></a>. + + +\section build Building GNU Radio + +See the \ref page_build page for details about the project's +dependencies and build process. + + +\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 +\li \ref page_pfb */ diff --git a/docs/doxygen/other/pfb_intro.dox b/docs/doxygen/other/pfb_intro.dox new file mode 100644 index 000000000..8b82d96d7 --- /dev/null +++ b/docs/doxygen/other/pfb_intro.dox @@ -0,0 +1,82 @@ +/*! \page page_pfb Polyphase Filterbanks + +\section Introduction + +Polyphase filterbanks (PFB) are a very powerful set of filtering tools +that can efficiently perform many multi-rate signal processing +tasks. GNU Radio has a set of polyphase filterbank blocks to be used +in all sorts of applications. These blocks and their documentation can +be found in \ref pfb_blk. + +\section Usage + +See the documentation for the individual blocks for details about what +they can do and how they should be used. Furthermore, there are +examples for these blocks in <b>gnuradio-examples/python/pfb</b>. + +The main issue when using the PFB blocks is defining the prototype +filter, which is passed to all of the blocks as a vector of \p +taps. The taps from the prototype filter which get partitioned among +the \p N channels of the channelizer. + +An example of creating a set of filter taps for a PFB channelizer is +found on line 49 of <b>gnuradio-examples/python/pfb/channelizer.py</b> +and reproduced below. Notice that the sample rate is the sample rate +at the input to the channelizer while the bandwidth and transition +width are defined for the channel bandwidths. This makes a fairly long +filter that is then split up between the \p N channels of the PFB. + +\code + self._fs = 9000 # input sample rate + self._M = 9 # Number of channels to channelize + + self._taps = gr.firdes.low_pass_2(1, self._fs, 475.50, 50, + attenuation_dB=100, + window=gr.firdes.WIN_BLACKMAN_hARRIS) +\endcode + +In this example, the signal into the channelizer is sampled at 9 ksps +(complex, so 9 kHz of bandwidth). The filter uses 9 channels, so each +output channel will have a bandwidth and sample rate of 1 kHz. We want +to pass most of the channel, so we define the channel bandwidth to be +a low pass filter with a bandwidth of 475.5 Hz and a transition +bandwidth of 50 Hz, but we have defined this using a sample rate of +the original 9 kHz. The prototype filter has 819 taps to be divided up +between the 9 channels, so each channel uses 91 taps. This is probably +over-kill for a channelizer, and we could reduce the amount of taps +per channel to a couple of dozen with no ill effects. + +The basic rule when defining a set of taps for a PFB block is to think +about the filter running at the highest rate it will see while the +bandwidth is defined for the size of the channels. In the channelizer +case, the highest rate is defined as the rate of the incoming signal, +but in other PFB blocks, this is not so obvious. + +Two very useful blocks to use are the arbitrary resampler and the +clock synchronizer (for PAM signals). These PFBs are defined with a +set number of filters based on the fidelity required from them, not +the rate changes. By default, the \p filter_size is set to 32 for +these blocks, which is a reasonable default for most tasks. Because +the PFB uses this number of filters in the filterbank, the maximum +rate of the bank is defined from this (see the theory of a polyphase +interpolator for a justification of this). So the prototype filter is +defined to use a sample rate of \p filter_size times the signal's +sampling rate. + +A helpful wrapper for the arbitrary resampler is found in +<b>gnuradio-core/src/python/gnuradio/blks2impl/pfb_arb_resampler.py</b>, +which is exposed in Python as <b>blks2.pfb_arb_resampler_ccf</b> and +<b>blks2.pfb_arb_resampler_fff</b>. This block is set up so that the +user only needs to pass it the real number \p rate as the resampling +rate. With just this information, this hierarchical block +automatically creates a filter that fully passes the signal bandwidth +being resampled but does not pass any out-of-band noise. See the code +for this block for details of how the filter is constructed. + +Of course, a user can create his or her own taps and use them in the +arbitrary resampler for more specific requirements. Some of the UHD +examples (<b>gr-uhd/examples</b>) use this ability to create a +received matched filter or channel filter that also resamples the +signal. + +*/ |
