1 files changed, 10 insertions, 493 deletions
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"
 
 */