header_buffer.h

Go to the documentation of this file.

/* -*- c++ -*- */
/* Copyright 2015-2016 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.
 */

#ifndef INCLUDED_DIGITAL_HEADER_BUFFER_H
#define INCLUDED_DIGITAL_HEADER_BUFFER_H

#include <gnuradio/digital/api.h>
#include <vector>
#include <stdint.h>

namespace gr {
  namespace digital {

    /*!
     * \brief Helper class for handling payload headers.
     * \ingroup packet_operators_blk
     *
     * \details
     *
     * This class is used by the header format blocks (e.g.,
     * digital::header_format_default) to make it easier to deal with
     * payload headers. This class functions in two different ways
     * depending on if it is used in a transmitter or receiver. When
     * used in a transmitter, this class helps us build headers out of
     * the fields of the protocol. When used in a receiver, this class
     * helps us parse the received bits into the protocol's fields.
     *
     * This page describes how to work with the different modes,
     * transmit or receive. The class is instructed as to which mode
     * it is in by how the constructor is called. If the constructor
     * is passed a valid array (non NULL), then it is in transmit mode
     * and will pack this buffer with the header fields. If that
     * buffer is NULL, the object is in receive mode.
     *
     * \section header_buffer_tx Transmit Mode
     *
     * When passed a valid buffer in the constructor, this object is in
     * transmit mode. We can then use the add_field[N] functions to
     * add new fields to this header. The buffer MUST be large enough
     * to hold the full header. As this class is meant to work mostly
     * with the digital::header_format_default and child
     * classes, the header length can be read from
     * digital::header_format_default::header_nbytes().
     *
     * Each field is a specific length of 8, 16, 32, or 64 bits that
     * are to be transmitted in network byte order. We can adjust the
     * direction of the bytes by setting the byte-swap flag, \p bs, to
     * true or false.
     *
     * The length argument (\p len) for all add_field[N] calls is the
     * number of bytes actually accounted for in the data
     * structure. Often, we would use the full size of the field,
     * which is sizeof(dtype), and the add_field[N] call defaults to
     * len=N. Occasionally, we may need to use fewer bytes than
     * actually represented by the data type. An example would be the
     * access code used in the header_format_default, which is a
     * uint64_t type but may have fewer bytes used in the actual
     * access code.
     *
     * The function that calls this class is expected to handle the
     * memory handling of the buffer -- both allocating and
     * deallocating.
     *
     * As simple example of using this class in transmit mode:
     *
     * \verbatim
     uint8_t* buffer = (uint8_t*)volk_malloc(header_nbytes(),
                                             volk_get_alignment());

     header_buffer hdr(buffer);
     hdr.add_field64(sync_word, sync_word_len);
     hdr.add_field16(payload_length);
     hdr.add_field8(header_flags);
     hdr.add_field8(header_options);

     // Do something with the header

     volk_free(buffer);
     \endverbatim
     *
     * In this example, the header contains four fields:
     *
     * \verbatim
       |0                           15|16          23|24          31|
       |                          sync word                         |
       |                                                            |
       |           length             |     flags    |   options    |
       \endverbatim
     *
     * The sync word can be up to 64-bits, but the add_field64 is also
     * passed the number of actual bytes in the sync word and so could
     * be fewer.
     *
     * \section header_buffer_rx Receive Mode
     *
     * In receive mode, we build up the header as bits are received by
     * inserting them with insert_bit. We can find out how long the
     * current header is, in bits, using the call to length(). If the
     * header is of the appropriate length, we can then start
     * extracting the fields from it. When we are done with the
     * current header, call clear() to reset the internal buffer to
     * empty, which will mean that length() returns 0.
     *
     * The header fields are extracted using the extract_field[N]
     * functions. Like the add_field[N] functions, we specify the size
     * (in bits) of the field we are extracting. We pass this function
     * the bit-position of the expected field in the received header
     * buffer. The extract_field[N] assumes that the number of bits
     * for the field is N, but we can tell the function to use fewer
     * bits if we want. Setting the length parameter of these
     * functions greater than N is illegal, and it will throw an
     * error.
     *
     * For example, given a header of | length | seq. num. | where the
     * length is 16 bits and the sequence number is 32 bits, we would
     * use:
     *
     * \verbatim
          uint16_t len = d_hdr_reg.extract_field16(0);
          uint32_t seq = d_hdr_reg.extract_field32(16);
       \endverbatim
     *
     * The extract_field functions are specific to data types of the
     * field and the number of bits for each field is inferred by the
     * data type. So extract_field16 assumes we want all 16 bits in
     * the field represented.
     *
     * Some headers have fields that are not standard sizes of
     * integers, like a 1 bit, 4 bit, or even 12 bit fields. We can
     * ask for fewer bits for each field. say:
     *
     * \verbatim
       |0          15|16     19|20          31|
       |     len     |  flags  |   options    |
       \endverbatim
     *
     * We would use the following extraction functions:
     *
     * \verbatim
          uint16_t len   = d_hdr_reg.extract_field16(0);
          uint8_t  flags = d_hdr_reg.extract_field8(16, 4);
          uint16_t opts  = d_hdr_reg.extract_field16(20, 12);
       \endverbatim
     *
     * \sa header_format_default
     * \sa header_format_counter
     * \sa header_format_crc
     */
    class DIGITAL_API header_buffer
    {
    private:
      size_t d_offset;
      uint8_t *d_buffer;

      std::vector<bool> d_input;

    public:
      /*!
       * Create a header buffer object with a pre-allocated buffer, \p
       * buffer, to hold the formatted header data.
       *
       * If \p buffer is set to NULL, then this object is in receive
       * mode meant to receive bits from an incoming data stream and
       * provide the ability to extract fields. In this mode, calls to
       * add_field are invalid and will be nops.
       */
      header_buffer(uint8_t *buffer=NULL);

      /*!
       * Class destructor.
       */
      ~header_buffer();

      /*!
       * Clears the header.
       *
       * In transmit mode, this resets the current offset so new
       * add_field functions start adding data to the start of the
       * buffer.
       *
       * In receive mode, this clears the buffer that we have inserted
       * bits in to.
       */
      void clear();


      /*!
       * In transmit mode, this returns the length of the data in
       * the buffer (not the allocated buffer length).
       *
       * In receiving mode, this returns the current length in bits of
       * the received header.
       */
      size_t length() const;

      /*!
       * Returns a constant pointer to the buffer.
       */
      const uint8_t* header() const;

      /*!
       * Add an 8-bit field to the header.
       *
       * \param data The 8-bit data item.
       * \param len Length (in bits) of \p data.
       * \param bs Set to 'true' to byte swap the data.
       */
      void add_field8(uint8_t data, int len=8, bool bs=false);

      /*!
       * Add an 16-bit field to the header.
       *
       * \param data The 16-bit data item.
       * \param len Length (in bits) of \p data.
       * \param bs Set to 'true' to byte swap the data.
       */
      void add_field16(uint16_t data, int len=16, bool bs=false);

      /*!
       * Add an 32-bit field to the header.
       *
       * \param data The 32-bit data item.
       * \param len Length (in bits) of \p data.
       * \param bs Set to 'true' to byte swap the data.
       */
      void add_field32(uint32_t data, int len=32, bool bs=false);

      /*!
       * Add an 64-bit field to the header.
       *
       * \param data The 64-bit data item.
       * \param len Length (in bits) of \p data.
       * \param bs Set to 'true' to byte swap the data.
       */
      void add_field64(uint64_t data, int len=64, bool bs=false);



      /*****************************************************
       *   Receive mode to build a header from bits        *
       *****************************************************/

      /*!
       * Insert a new bit on the back of the input buffer. This
       * function is used in receive mode to add new bits as they are
       * received for later use of the extract_field functions.
       *
       * \param bit New bit to add.
       */
      void insert_bit(int bit);

      /*!
       * Returns up to an 8-bit field in the packet header.
       *
       * \param pos Bit position of the start of the field.
       * \param len The number of bits in the field.
       * \param bs Set to 'true' to byte swap the data.
       */
      uint8_t extract_field8(int pos, int len=8, bool bs=false);

      /*!
       * Returns up to a 16-bit field in the packet header.
       *
       * \param pos Bit position of the start of the field.
       * \param len The number of bits in the field.
       * \param bs Set to 'true' to byte swap the data.
       */
      uint16_t extract_field16(int pos, int len=16, bool bs=false);

      /*!
       * Returns up to a 32-bit field in the packet header.
       *
       * \param pos Bit position of the start of the field.
       * \param len The number of bits in the field.
       * \param bs Set to 'true' to byte swap the data.
       */
      uint32_t extract_field32(int pos, int len=32, bool bs=false);

      /*!
       * Returns up to a 64-bit field in the packet header.
       *
       * \param pos Bit position of the start of the field.
       * \param len The number of bits in the field.
       * \param bs Set to 'true' to byte swap the data.
       */
      uint64_t extract_field64(int pos, int len=64, bool bs=false);
    };

  } // namespace digital
} // namespace gr

#endif /* INCLUDED_DIGITAL_HEADER_BUFFER_H */