header_format_base.h

Go to the documentation of this file.

/* -*- c++ -*- */
/* Copyright 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_BASE_H
#define INCLUDED_DIGITAL_HEADER_FORMAT_BASE_H

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

namespace gr {
  namespace digital {

    /*!
     * \brief Base header formatter class.
     * \ingroup packet_operators_blk
     *
     * \details
     *
     * Creates a base class that other packet formatters will inherit
     * from. The child classes create and parse protocol-specific
     * headers. To add a new protocol processing class, create a class
     * that inherits from this and overload the necessary
     * functions. The main functions to overload are:
     *
     * \li header_format_base::format: takes in a payload and
     * creates a header from it.
     *
     * \li header_format_base::parse: receive bits and extract
     * the header info. These are expected to be hard bits (0 or 1)
     * that have either been sliced or gone through an FEC decoder.
     *
     * \li header_format_base::header_nbits: the number of bits
     * in the full header (including an access code).
     *
     * \li header_format_base::header_ok: checks to see if the
     * received header is ok. Since the header often specifies the
     * length of the frame to decode next, it is important that this
     * information be correct.
     *
     * \li header_format_base::header_payload: unpacks the header
     * register (from the class header_buffer) as a set of bits into
     * its component parts of the header. For example, this may find
     * and extract the frame length field as a 16-bit value and/or
     * flags related to the type of modulation and FEC codes used in
     * the frame's payload.
     *
     * Protected functions of this class that the child class should
     * overload include:
     *
     * \li enter_search
     * \li enter_have_sync
     * \li enter_have_header
     *
     * These three function represent the different states of the
     * parsing state machine. Expected behavior is that the protocol
     * has some known word that we are first looking for the identify
     * the start of the frame. The parsing FSM starts in a state to
     * search for the beginning of the header, normally by looking for
     * a known word (i.e., the access code). Then it changes state to
     * read in the full header. We expect that the protocol provides
     * the length of the header for processing, so the parsing looks
     * pulls in the full length of the header. Then it changes state
     * to the "have header" state for checking and processing. The
     * base class provides the basic functionality for this state
     * machine. However, most likely, each child class must manage
     * these states for themselves.
     *
     * This class is specifically designed to work with packets/frames
     * in the asynchronous PDU architecture of GNU Radio. See the
     * packet_format_async block for formatting the headers onto
     * payloads and packet_parse_b block for parsing headers in a
     * receiver.
     *
     * The Packet Format block takes in a PDU and uses a formatter
     * class derived from this class to add a header onto the
     * packet. The Packet Format blocks takes in the PDU, unpacks the
     * message, and passes it to a formatter class' format function,
     * which builds a header based on the payload. The header is
     * passed back and emitted from formatter block as a separate
     * output. The async format block, packet_format_async, has two
     * message output ports. The 'header' port passes the header out
     * as a PDU and the 'payload' passes the payload out as a PDU. The
     * flowgraph can then separately modulate and combine these two
     * pieces in the follow-on processing.
     *
     * The packet_sync_b block uses the formatter class by calling the
     * 'parse' function to parse the received packet headers. This
     * parser block is a sink for the data stream and emits a message
     * from an 'info' port that contains an PMT dictionary of the
     * information in the header. The formatter class determines the
     * dictionary keys.
     *
     * This is the base class for dealing with formatting headers for
     * different protocols and purposes. For other header formatting
     * behaviors, create a child class from here and overload the
     * format, parse, and parsing state machine functions as
     * necessary.
     *
     * \sa header_format_default
     * \sa header_format_counter
     */
    class DIGITAL_API header_format_base
      : public boost::enable_shared_from_this<gr::digital::header_format_base>
    {
     public:
      typedef boost::shared_ptr<header_format_base> sptr;

      header_format_base();
      virtual ~header_format_base();

      sptr base() { return shared_from_this(); };
      sptr formatter() { return shared_from_this(); };

      /*!
       * Function to creates a header. The child classes overload this
       * function to format the header in the protocol-specific way.
       *
       * \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.
       *
       * MUST be overloaded.
       */
      virtual bool format(int nbytes_in,
                          const unsigned char *input,
                          pmt::pmt_t &output,
                          pmt::pmt_t &info) = 0;

      /*!
       * Parses a header. This function is overloaded in the child
       * class, which knows how to convert the incoming hard bits (0's
       * and 1's) back into a packet header.
       *
       * \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.
       *
       * MUST be overloaded.
       */
      virtual bool parse(int nbits_in,
                         const unsigned char *input,
                         std::vector<pmt::pmt_t> &info,
                         int &nbits_processed) = 0;

      /*!
       * Returns the length of the formatted header in bits.
       * MUST be overloaded.
       */
      virtual size_t header_nbits() const = 0;

      /*!
       * Returns the length of the formatted header in bytes.
       * Auto-calculated from the overloaded header_nbits().
       */
      size_t header_nbytes() const;

    protected:
      enum state_t {STATE_SYNC_SEARCH, STATE_HAVE_SYNC};

      state_t d_state;          //!< state of the state machine
      header_buffer d_hdr_reg;  //!< header_buffer object to hold header bits
      pmt::pmt_t d_info;        //!< info captured from the header

      //! Enter Search state of the state machine to find the access code.
      virtual void enter_search();

      //! 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() = 0;

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

      /*! Used by blocks to access the logger system.
       */
      gr::logger_ptr d_logger;
      gr::logger_ptr d_debug_logger;
    };

  } // namespace digital
} // namespace gr

#endif /* INCLUDED_DIGITAL_HEADER_FORMAT_BASE_H */