header_format_default.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_FORMAT_DEFAULT_H
#define INCLUDED_DIGITAL_HEADER_FORMAT_DEFAULT_H

#include <pmt/pmt.h>
#include <gnuradio/digital/api.h>
#include <gnuradio/digital/header_format_base.h>
#include <gnuradio/digital/header_buffer.h>
#include <gnuradio/logger.h>
#include <boost/enable_shared_from_this.hpp>

namespace gr {
  namespace digital {

    /*!
     * \brief Default header formatter for PDU formatting.
     * \ingroup packet_operators_blk
     *
     * \details
     * Used to handle the default packet header.
     *
     * See the parent class header_format_base for details of how
     * these classes operate.
     *
     * The default header created in this base class consists of an
     * access code and the packet length. The length is encoded as a
     * 16-bit value repeated twice:
     *
     * \verbatim
         | access code | hdr | payload |
       \endverbatim
     *
     * Where the access code is <= 64 bits and hdr is:
     *
     * \verbatim
         |  0 -- 15 | 16 -- 31 |
         | pkt len  | pkt len  |
       \endverbatim
     *
     * The access code and header are formatted for network byte order.
     *
     * This header generator does not calculate or append a CRC to the
     * packet. Use the CRC32 Async block for that before adding the
     * header. The header's length will then measure the payload plus
     * the CRC length (4 bytes for a CRC32).
     *
     * The default header parser produces a PMT dictionary that
     * contains the following keys. All formatter blocks MUST produce
     * these two values in any dictionary.
     *
     * \li "payload symbols": the number of symbols in the
     * payload. The payload decoder will have to know how this relates
     * to the number of bits received. This block knows nothing about
     * the payload modulation or the number of bits/symbol. Use the
     * gr::digital::header_format_counter for that purpose.
     *
     * \sa header_format_counter
     * \sa header_format_crc
     * \sa header_format_ofdm
     */
    class DIGITAL_API header_format_default
      : public header_format_base
    {
     public:
      header_format_default(const std::string &access_code, int threshold);
      virtual ~header_format_default();

      /*!
       * Creates a header from the access code and packet length and
       * creates an output header as a PMT vector in the form:
       *
       * \verbatim
           | access code | pkt len | pkt len |
         \endverbatim
       *
       * \param nbytes_in The length (in bytes) of the \p input payload
       * \param input An array of unsigned chars of the packet payload
       * \param output A pmt::u8vector with the new header prepended
       *        onto the input data.
       * \param info A pmt::dict containing meta data and info about
       *        the PDU (generally from the metadata portion of the
       *        input PDU). Data can be extracted from this for the
       *        header formatting or inserted.
       */
      virtual bool format(int nbytes_in,
                          const unsigned char *input,
                          pmt::pmt_t &output,
                          pmt::pmt_t &info);

      /*!
       * Parses a header of the form:
       *
       * \verbatim
           | access code | pkt len | pkt len | payload |
         \endverbatim
       *
       * This is implemented as a state machine that starts off
       * searching for the access code. Once found, the access code is
       * used to find the start of the packet and the following
       * header. This default header encodes the length of the payload
       * a 16 bit integer twice. The state machine finds the header
       * and checks that both payload length values are the same. It
       * then goes into its final state that reads in the payload
       * (based on the payload length) and produces a payload as a PMT
       * u8 vector of packed bytes.
       *
       * \param nbits_in The number of bits in the input array.
       * \param input The input as hard decision bits.
       * \param info A vector of pmt::dicts to hold any meta data or
       *        info about the PDU. When parsing the header, the
       *        formatter can add info from the header into this dict.
       *        Each packet has a single PMT dictionary of info, so
       *        the vector length is the number of packets received
       *        extracted during one call to this parser function.
       * \param nbits_processed Number of input bits actually
       *        processed; If all goes well, this is nbits_in. A
       *        premature return after a bad header could be less than
       *        this.
       */
      virtual bool parse(int nbits_in,
                         const unsigned char *input,
                         std::vector<pmt::pmt_t> &info,
                         int &nbits_processed);

      /*!
       * Returns the length of the formatted header in bits.
       */
      virtual size_t header_nbits() const;

      /*!
       * Updates the access code. Must be a string of 1's and 0's and
       * <= 64 bits.
       */
      bool set_access_code(const std::string &access_code);

      /*!
       * Returns the formatted access code as a 64-bit register.
       */
      unsigned long long access_code() const;

      /*!
       * Sets the threshold for number of access code bits can be in
       * error before detection. Defaults to 0.
       */
      void set_threshold(unsigned int thresh=0);

      /*!
       * Returns threshold value for access code detection.
       */
      unsigned int threshold() const;

      /*!
       * Factory to create an async packet header formatter; returns
       * an sptr to the object.
       *
       * \param access_code An access code that is used to find and
       * synchronize the start of a packet. Used in the parser and in
       * other blocks like a corr_est block that helps trigger the
       * receiver. Can be up to 64-bits long.
       * \param threshold How many bits can be wrong in the access
       * code and still count as correct.
       */
      static sptr make(const std::string &access_code, int threshold);

    protected:
      uint64_t d_access_code;        //!< register to hold the access code
      size_t d_access_code_len;      //!< length in bits of the access code

      unsigned long long d_data_reg; //!< used to look for access_code
      unsigned long long d_mask;     /*!< masks access_code bits (top N bits are set where
                                       N is the number of bits in the access code) */
      unsigned int d_threshold;      //!< how many bits may be wrong in sync vector

      int d_pkt_len;                 //!< Length of the packet to put into the output buffer
      int d_pkt_count;               //!< Number of bytes bits already received

      int d_nbits;                   //!< num bits processed since reset

      //! Access code found, start getting the header
      virtual void enter_have_sync();

      //! Header found, setup for pulling in the hard decision bits
      virtual void enter_have_header(int payload_len);

      //! Verify that the header is valid
      virtual bool header_ok();

      /*! Get info from the header; return payload length and package
       *  rest of data in d_info dictionary.
       */
      virtual int header_payload();
    };

  } // namespace digital
} // namespace gr

#endif /* INCLUDED_DIGITAL_HEADER_FORMAT_DEFAULT_H */