[Commit-gnuradio] [gnuradio] 02/03: blocks: Improved docs for repack_bits

[git]

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

jcorgan pushed a commit to branch maint
in repository gnuradio.

commit 7e4527fe9d68c6593eba1a095ea6803ad75febf0
Author: Martin Braun <address@hidden>
Date:   Fri Dec 19 13:36:00 2014 +0100

    blocks: Improved docs for repack_bits
---
 gr-blocks/include/gnuradio/blocks/repack_bits_bb.h | 38 +++++++++++++++++-----
 1 file changed, 29 insertions(+), 9 deletions(-)

diff --git a/gr-blocks/include/gnuradio/blocks/repack_bits_bb.h 
b/gr-blocks/include/gnuradio/blocks/repack_bits_bb.h
index c594966..e094e68 100644
--- a/gr-blocks/include/gnuradio/blocks/repack_bits_bb.h
+++ b/gr-blocks/include/gnuradio/blocks/repack_bits_bb.h
@@ -30,7 +30,7 @@ namespace gr {
   namespace blocks {
 
     /*!
-     * \brief Pack \p k bits from the input stream onto \p l bits of the 
output stream.
+     * \brief Repack \p k bits from the input stream onto \p l bits of the 
output stream.
      * \ingroup byte_operators_blk
      *
      * \details
@@ -38,11 +38,31 @@ namespace gr {
      * On every fresh input byte, it starts reading on the LSB, and starts 
copying
      * to the LSB as well.
      *
-     * If a packet length tag is given, this block assumes a tagged stream.
-     * In this case, the tag with the packet length is updated accordingly.
-     * Also, the number of input bits is padded with zeros if the number of 
input
-     * bits is not an integer multiple of \p l, or bits are truncated from the 
input
-     * if \p align_output is set to true.
+     * When supplying a tag name, this block operates on tagged streams.
+     * In this case, it can happen that the input data or the output data
+     * becomes unaligned when k * input length is not equal to l * output 
length.
+     * In this case, the \p align_output parameter is used to decide which
+     * data packet to align.
+     *
+     * Usually, \p align_output is false for unpacking (k=8, l < 8) and false 
for
+     * reversing that.
+     *
+     * \section gr_blocks_repack_example Example
+     *
+     * Say you're tx'ing 8-PSK and therefore set k=8, l=3 on the transmit side
+     * before the modulator. Now assume you're transmitting a single byte of 
data.
+     * Your incoming tagged stream has length 1, the outgoing has length 3. 
However,
+     * the third item is actually only carrying 2 bits of relevant data, the 
bits
+     * do not align with the boundaries. So you set \p align_output = false,
+     * because the output can be unaligned.
+     *
+     * Now say you're doing the inverse: packing those three items into full
+     * bytes. How do you interpret those three bytes? Without this flag,
+     * you'd have to assume there's 9 relevant bits in there, so you'd end up
+     * with 2 bytes of output data. But in the packing case, you want the
+     * \b output to be aligned; all output bits must be useful. By asserting 
this flag,
+     * the packing algorithm tries to do this and in this case assumes that
+     * since we have alignment after 8 bits, the 9th can be discarded.
      */
     class BLOCKS_API repack_bits_bb : virtual public tagged_stream_block
     {
@@ -52,11 +72,11 @@ namespace gr {
       /*!
        * \param k Number of relevant bits on the input stream
        * \param l Number of relevant bits on the output stream
-       * \param len_tag_key If not empty, this is the key for the length tag.
-       * \param align_output If len_tag_key is given, this controls if the 
input
+       * \param tsb_tag_key If not empty, this is the key for the length tag.
+       * \param align_output If tsb_tag_key is given, this controls if the 
input
        *                     or the output is aligned.
        */
-      static sptr make(int k, int l=8, const std::string &len_tag_key="", bool 
align_output=false);
+      static sptr make(int k, int l=8, const std::string &tsb_tag_key="", bool 
align_output=false);
     };
 
   } // namespace blocks