[Commit-gnuradio] [gnuradio] 09/11: docs: Updated uhd to reflect tag changes.

[git]

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

jcorgan pushed a commit to branch master
in repository gnuradio.

commit bfd518302421731fbdf074554d9a573f2d23a6b5
Author: Martin Braun <address@hidden>
Date:   Mon Apr 7 16:59:18 2014 +0200

    docs: Updated uhd to reflect tag changes.
---
 gr-uhd/doc/uhd.dox                      |  5 ++-
 gr-uhd/include/gnuradio/uhd/usrp_sink.h | 77 ++++++++++++++-------------------
 2 files changed, 36 insertions(+), 46 deletions(-)

diff --git a/gr-uhd/doc/uhd.dox b/gr-uhd/doc/uhd.dox
index 4cd30a8..538c98c 100644
--- a/gr-uhd/doc/uhd.dox
+++ b/gr-uhd/doc/uhd.dox
@@ -1,3 +1,4 @@
+// vim: set ft=doxygen:
 /*! \page page_uhd UHD Interface
 
 \section Introduction
@@ -27,12 +28,12 @@ Ettus Research keeps the comprehensive documentation to the 
underlying UHD drive
 
     http://files.ettus.com/uhd_docs/manual/html/
 
-The UHD Doxygen page is located:
+The UHD Doxygen page is located at:
 
     http://files.ettus.com/uhd_docs/doxygen/html/index.html
 
 
-\section Typical Setup
+\section Configuring a UHD object
 
 A typical option parser setup for a UHD device looks like
 
diff --git a/gr-uhd/include/gnuradio/uhd/usrp_sink.h 
b/gr-uhd/include/gnuradio/uhd/usrp_sink.h
index cac3e01..273ee4c 100644
--- a/gr-uhd/include/gnuradio/uhd/usrp_sink.h
+++ b/gr-uhd/include/gnuradio/uhd/usrp_sink.h
@@ -60,49 +60,12 @@ namespace gr {
       typedef boost::shared_ptr<usrp_sink> sptr;
 
       /*!
-       * \brief Make a new USRP sink block.
+       * \brief DEPRECATED Make a new USRP sink block using the deprecated 
io_type_t.
        * \ingroup uhd_blk
-       *
-       * The USRP sink block reads a stream and transmits the samples.
-       * The sink block also provides API calls for transmitter settings.
-       *
-       * TX Stream tagging:
-       *
-       * The following tag keys will be consumed by the work function:
-       *  - pmt::string_to_symbol("tx_sob")
-       *  - pmt::string_to_symbol("tx_eob")
-       *  - pmt::string_to_symbol("tx_time")
-       *  - pmt::string_to_symbol("tx_freq")
-       *  - pmt::string_to_symbol(length_tag_name)
-       *
-       * The sob and eob (start and end of burst) tag values are pmt booleans.
-       * When present, burst tags should be set to true (pmt::PMT_T).
-       *
-       * If length_tag_name is not an empty string, all "tx_sob" and "tx_eob"
-       * tags will be ignored.
-       *
-       * The length tag value should be a pmt long specifying the number
-       * of samples contained in the corresponding tagged stream.
-       *
-       * The timstamp tag value is a pmt tuple of the following:
-       * (uint64 seconds, and double fractional seconds).
-       *
-       * The tx_freq tag has to be a double, and will re-tune the USRP to the 
given frequency,
-       * if possible.
-       *
-       * See the UHD manual for more detailed documentation:
-       * http://code.ettus.com/redmine/ettus/projects/uhd/wiki
-       *
-       * \param device_addr the address to identify the hardware (e.g. 
"type=b200", "addr=192.168.10.2")
-       * \param io_type the desired input data type
-       * \param num_channels number of stream from the device
-       * \param length_tag_name the name of the tag identifying tagged stream 
length
-       * \return a new USRP sink block object
        */
       static sptr make(const ::uhd::device_addr_t &device_addr,
                        const ::uhd::io_type_t &io_type,
-                       size_t num_channels,
-                       const std::string &length_tag_name = "");
+                       size_t num_channels);
 
       /*!
        * \brief Make a new USRP sink block.
@@ -110,30 +73,56 @@ namespace gr {
        * The USRP sink block reads a stream and transmits the samples.
        * The sink block also provides API calls for transmitter settings.
        *
-       * TX Stream tagging:
+       * \section uhd_tx_tagging TX Stream tagging
        *
        * The following tag keys will be consumed by the work function:
        *  - pmt::string_to_symbol("tx_sob")
        *  - pmt::string_to_symbol("tx_eob")
        *  - pmt::string_to_symbol("tx_time")
        *  - pmt::string_to_symbol("tx_freq")
+       *  - pmt::string_to_symbol("tx_command")
        *  - pmt::string_to_symbol(length_tag_name)
        *
+       * Any other tag will be ignored.
+       *
        * The sob and eob (start and end of burst) tag values are pmt booleans.
        * When present, burst tags should be set to true (pmt::PMT_T).
        *
        * If length_tag_name is not an empty string, all "tx_sob" and "tx_eob"
-       * tags will be ignored.
-       *
-       * The length tag value should be a pmt long specifying the number
+       * tags will be ignored, and the input is assumed to a tagged stream,
+       * as described in \ref page_tagged_stream_blocks.
+       * The length tag value should be a PMT long specifying the number
        * of samples contained in the corresponding tagged stream.
        *
-       * The timstamp tag value is a pmt tuple of the following:
+       * If sob/eob tags or length tags are used, this block understands that
+       * the data is bursty, and will configure the USRP to make sure there's
+       * no underruns etc.
+       *
+       * The timestamp tag value is a PMT tuple of the following:
        * (uint64 seconds, and double fractional seconds).
        *
        * The tx_freq tag has to be a double, and will re-tune the USRP to the 
given frequency,
        * if possible.
        *
+       * The command tag can carry a PMT command. See the following section.
+       *
+       * \section uhd_commands Command interface
+       *
+       * There are two ways of passing commands to this block:
+       * 1) tx_command tag. The command is attached to a sample, and will 
executed
+       *    before the sample is transmitted, and after the previous sample.
+       * 2) 'command' message interface. The command is executed 
asynchronously,
+       *    as soon as possible.
+       *
+       * In both cases, the payload of the command is a PMT pair, with the 
first
+       * item ('car') being the command name, and second ('cdr') the command 
value.
+       *
+       * Command name | Command value
+       * 
-------------|--------------------------------------------------------------------------
+       * `freq`       | Tuple: (chan, new_freq). Requests a tune to `new_freq` 
on channel `chan`.
+       * `lo_offset`  | Tuple: (chan, lo_offset). Adds a LO offset on channel 
`chan`.
+       * `gain`       | Tuple: (chan, gain). Requests a gain change to `gain` 
on channel `chan`.
+       *
        * See the UHD manual for more detailed documentation:
        * http://code.ettus.com/redmine/ettus/projects/uhd/wiki
        *