[Commit-gnuradio] [gnuradio] 02/06: digital: Updated HPD documentation

[git]

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

jcorgan pushed a commit to branch maint
in repository gnuradio.

commit 383d94736c03e2a48cf6a4f042d69d96e0a92b16
Author: Martin Braun <address@hidden>
Date:   Thu Jun 11 14:27:28 2015 -0700

    digital: Updated HPD documentation
---
 .../gnuradio/digital/header_payload_demux.h        | 71 ++++++++++++++++------
 1 file changed, 52 insertions(+), 19 deletions(-)

diff --git a/gr-digital/include/gnuradio/digital/header_payload_demux.h 
b/gr-digital/include/gnuradio/digital/header_payload_demux.h
index d68c4ab..303bebb 100644
--- a/gr-digital/include/gnuradio/digital/header_payload_demux.h
+++ b/gr-digital/include/gnuradio/digital/header_payload_demux.h
@@ -33,11 +33,20 @@ namespace gr {
      * \ingroup packet_operators_blk
      *
      * \details
-     * This block is designed to handle packets from a bursty transmission.
-     * Input 0 takes a continuous transmission of samples.
-     * If used, input 1 is a trigger signal. In this case, a 1 on input 1
-     * is a trigger. Otherwise, a tag with the key specified in \p 
trigger_tag_key
-     * is used as a trigger (its value is irrelevant).
+     * This block is designed to demultiplex packets from a bursty 
transmission.
+     * The typical application for this block is the case when you are 
receiving
+     * packets with yet-to-determine length. This block will pass the header
+     * section to other blocks for demodulation. Using the information from the
+     * demodulated header, it will then output the payload. The beginning of 
the
+     * header needs to be identified by a trigger signal (see below).
+     *
+     * \section hpd_theory_of_ops Theory of Operation
+     *
+     * Input 0 takes a continuous transmission of samples (items).
+     * Input 1 is an optional input for the trigger signal (mark beginning of
+     * packets). In this case, a non-zero value on input 1 identifies the 
beginning of a packet.
+     * Otherwise, a tag with the key specified in \p trigger_tag_key is used 
as a
+     * trigger (its value is irrelevant).
      *
      * Until a trigger signal is detected, all samples are dropped onto the 
floor.
      * Once a trigger is detected, a total of \p header_len items are copied 
to output 0.
@@ -49,9 +58,33 @@ namespace gr {
      * and taken as the payload length. The payload, together with the header 
data
      * as tags, is then copied to output 1.
      *
+     * \section hpd_item_sizes Symbols, Items and Item Sizes
+     *
+     * To generically and transparently handle different kinds of modulations,
+     * including OFDM, this block distinguises between \b symbols and \b items.
+     *
+     * Items are what are consumed at the input. Anything that uses complex 
samples
+     * will therefore use an itemsize of `sizeof(gr_complex)`. Symbols are a 
way of
+     * grouping items. In OFDM, we usually don't care about individual 
samples, but
+     * we do care about full OFDM symbols, so we set \p items_per_symbol to the
+     * IFFT / FFT length of the OFDM modulator / demodulator.
+     * For most single-carrier modulations, this value can be set to 1 (the 
default
+     * value).
      * If specified, \p guard_interval items are discarded before every symbol.
      * This is useful for demuxing bursts of OFDM signals.
      *
+     * On the output, we can deal with symbols directly by setting \p 
output_symbols
+     * to true. In that case, the output item size is the <em>symbol size</em>.
+     *
+     * \b Example: OFDM with 48 sub-carriers, using a length-64 IFFT on the 
modulator,
+     * and a cyclic-prefix length of 16 samples. In this case, the itemsize is
+     * `sizeof(gr_complex)`, because we're receiving complex samples. One OFDM 
symbol
+     * has 64 samples, hence \p items_per_symbol is set to 64, and \p 
guard_interval to
+     * 16. The header length is specified in number of OFDM symbols. Because 
we want to
+     * deal with full OFDM symbols, we set \p output_symbols to true.
+     *
+     * \section hpd_tag_handling Tag Handling
+     *
      * Any tags on the input stream are copied to the corresponding output 
*if* they're
      * on an item that is propagated. Note that a tag on the header items is 
copied to the
      * header stream; that means the header-parsing block must handle these 
tags if they
@@ -59,12 +92,12 @@ namespace gr {
      * A special case are tags on items that make up the guard interval. These 
are copied
      * to the first item of the following symbol.
      * If a tag is situated very close to the end of the payload, it might be 
unclear if
-     * it belongs to this packet or the following. In this case, the tag might 
be propagated
-     * twice.
+     * it belongs to this packet or the following. In this case, it is 
possible that the
+     * tag might be propagated twice.
      *
      * Tags outside of packets are generally discarded. If this information is 
important,
      * there are two additional mechanisms to preserve the tags:
-     * - Timing tags might be relevant to know <em>when</em> a packet was 
received. By
+     * - Timing tags might be relevant to know \b when a packet was received. 
By
      *   specifying the name of a timestamp tag and the sample rate at this 
block, it
      *   keeps track of the time and will add the time to the first item of 
every packet.
      *   The name of the timestamp tag is usually 'rx_time' (see 
gr::uhd::usrp_source::make()).
@@ -90,19 +123,19 @@ namespace gr {
        * \param itemsize Item size (bytes per item)
        * \param timing_tag_key The name of the tag with timing information, 
usually 'rx_time' or empty (this means timing info is discarded)
        * \param samp_rate Sampling rate at the input. Necessary to calculate 
the rx time of packets.
-       * \param special_tags A vector of strings denoting tags which shall be 
preserved.
+       * \param special_tags A vector of strings denoting tags which shall be 
preserved (see \ref hpd_tag_handling)
        */
       static sptr make(
-       int header_len,
-       int items_per_symbol,
-       int guard_interval=0,
-       const std::string &length_tag_key="frame_len",
-       const std::string &trigger_tag_key="",
-       bool output_symbols=false,
-       size_t itemsize=sizeof(gr_complex),
-       const std::string &timing_tag_key="",
-       const double samp_rate=1.0,
-       const std::vector<std::string> &special_tags=std::vector<std::string>()
+          int header_len,
+          int items_per_symbol=1,
+          int guard_interval=0,
+          const std::string &length_tag_key="frame_len",
+          const std::string &trigger_tag_key="",
+          bool output_symbols=false,
+          size_t itemsize=sizeof(gr_complex),
+          const std::string &timing_tag_key="",
+          const double samp_rate=1.0,
+          const std::vector<std::string> 
&special_tags=std::vector<std::string>()
       );
     };