Loading...
Searching...
No Matches
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
*
* SPDX-License-Identifier: GPL-3.0-or-later
*
*/
#ifndef INCLUDED_DIGITAL_HEADER_FORMAT_BASE_H
#define INCLUDED_DIGITAL_HEADER_FORMAT_BASE_H
#include <gnuradio/digital/api.h>
#include <gnuradio/digital/header_buffer.h>
#include <gnuradio/logger.h>
#include <pmt/pmt.h>
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 std::enable_shared_from_this<gr::digital::header_format_base>
{
public:
typedef std::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 */
gr::digital::header_buffer
Helper class for handling payload headers.
Definition header_buffer.h:154
gr::digital::header_format_base::d_info
pmt::pmt_t d_info
info captured from the header
Definition header_format_base.h:184
gr::digital::header_format_base::d_debug_logger
gr::logger_ptr d_debug_logger
Definition header_format_base.h:206
gr::digital::header_format_base::header_ok
virtual bool header_ok()=0
Verify that the header is valid.
gr::digital::header_format_base::d_logger
gr::logger_ptr d_logger
Definition header_format_base.h:205
gr::digital::header_format_base::d_hdr_reg
header_buffer d_hdr_reg
header_buffer object to hold header bits
Definition header_format_base.h:183
gr::digital::header_format_base::header_nbits
virtual size_t header_nbits() const =0
gr::digital::header_format_base::enter_have_sync
virtual void enter_have_sync()
Access code found, start getting the header.
gr::digital::header_format_base::format
virtual bool format(int nbytes_in, const unsigned char *input, pmt::pmt_t &output, pmt::pmt_t &info)=0
gr::digital::header_format_base::header_payload
virtual int header_payload()=0
gr::digital::header_format_base::base
sptr base()
Definition header_format_base.h:119
gr::digital::header_format_base::d_state
state_t d_state
state of the state machine
Definition header_format_base.h:182
gr::digital::header_format_base::state_t
state_t
Definition header_format_base.h:180
gr::digital::header_format_base::STATE_SYNC_SEARCH
@ STATE_SYNC_SEARCH
Definition header_format_base.h:180
gr::digital::header_format_base::STATE_HAVE_SYNC
@ STATE_HAVE_SYNC
Definition header_format_base.h:180
gr::digital::header_format_base::sptr
std::shared_ptr< header_format_base > sptr
Definition header_format_base.h:114
gr::digital::header_format_base::enter_have_header
virtual void enter_have_header(int payload_len)
Header found, setup for pulling in the hard decision bits.
gr::digital::header_format_base::enter_search
virtual void enter_search()
Enter Search state of the state machine to find the access code.
gr::digital::header_format_base::~header_format_base
virtual ~header_format_base()
gr::digital::header_format_base::formatter
sptr formatter()
Definition header_format_base.h:120
gr::digital::header_format_base::header_format_base
header_format_base()
gr::digital::header_format_base::header_nbytes
size_t header_nbytes() const
gr::digital::header_format_base::parse
virtual bool parse(int nbits_in, const unsigned char *input, std::vector< pmt::pmt_t > &info, int &nbits_processed)=0
api.h
DIGITAL_API
#define DIGITAL_API
Definition gr-digital/include/gnuradio/digital/api.h:18
header_buffer.h
logger.h
gr::digital
Definition adaptive_algorithm.h:22
gr
GNU Radio logging wrapper.
Definition basic_block.h:29
gr::logger_ptr
std::shared_ptr< logger > logger_ptr
Definition logger.h:250
pmt::pmt_t
std::shared_ptr< pmt_base > pmt_t
typedef for shared pointer (transparent reference counting).
Definition pmt.h:83
pmt.h