// $Id$ // // Copyright (C) 2008 // Fraunhofer Institute for Open Communication Systems (FOKUS) // Competence Center NETwork research (NET), St. Augustin, GERMANY // Stefan Bund // // This program 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 2 of the License, or // (at your option) any later version. // // This program 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 this program; if not, write to the // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. /** \mainpage HowTo: Defining and using a new 'libPacket' Packet Type This howto will introduce the facilities needed to define a new packet type. As example, the \c GREPacket type is defined. \autotoc \section howto_newpacket_start Getting started Before starting with the implementation, we look at the specification of the GRE packet. This is found in RFC 2784 in Section 2.1: 
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |C|       Reserved0       | Ver |         Protocol Type         |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |      Checksum (optional)      |       Reserved1 (Optional)    |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Using this protocol definition, we can decide the first important question: Whether the packet header is fixed size or dynamically sized. As we see above, the header incorporates optional fields. Therefore it must be dynamically sized. The RFC further details, that if the \a Checksum \a Present bit \a C is set, both \a Checksum and \a Reserved1 are present, otherwise they must both be omitted. Another information we take from the RFC is, that the \a Protocol \a Type is used to define the type of payload which directly follows the GRE header. This value is an ETHERTYPE value. To allow the packet library to automatically parse the GRE payload data, we need to tell the packet library which ETHERTYPE represents which packet type. This association already exists in form of the senf::EtherTypes registry. Our GRE packet will therefore utilize this registry. To summarize, we have gathered the following information: \li The GRE packet header is a dynamically sized header. \li The GRE packet header utilizes the senf::EtherTypes registry for next-header selection \section howto_newpacket_parser Implementing the GRE Parser The next step in creating a new packet type is to implement the parser. The parser is responsible for turning a bunch of bytes into an interpreted header with specific fields. The parser will later be constructed with an iterator (pointer) to the first byte to be interpreted as a GRE header and will provide member functions to access the header fields. You can implement these members manually but the SENF library provides a large set of helper macros which simplify this task considerably. \subsection howto_newpacket_parser_skeleton The PacketParser skeleton \code struct GREPacketParser : public senf::PacketParser { # include SENF_PARSER() // Define fields SENF_PARSER_FINALIZE(GREPacketParser); }; \endcode This is the standard skeleton of any parser class: We need to inherit senf::PacketParser and start out by including either \ref SENF_PARSER() or \ref SENF_FIXED_PARSER(). Which, depends on whether we define a fixed size or a dynamically sized parser. As \c GREPacketParser is dynamically sized, we include \ref SENF_PARSER(). After the fields are defined, we need to call the \ref SENF_PARSER_FINALIZE() macro to close of the parser definition. This call takes the name of the parser being defined as it's sole argument. This is already a valid parser, albeit not a very usable one since it defines no fields. We now go back to define the parser fields and begin with the simple part: Those fields which are always present. \subsection howto_newpacket_parser_simple Simple field definitions \code SENF_PARSER_BITFIELD ( checksumPresent, 1, bool ); SENF_PARSER_SKIP_BITS ( 12 ); SENF_PARSER_BITFIELD ( version, 3, unsigned ); SENF_PARSER_BITFIELD ( protocolType, 16, unsigned ); \endcode This is a direct transcript of the field definition above. There are quite a number of macros which may be used to define fields. All these macros are documented in '\ref packetparsermacros'. This is a correct \c GREPacket header definition but we can optimize a little bit: Since the \a protocolType field is aligned on a byte boundary, instead of defining it as a bitfield, we can define it as a UInt16 field: \code SENF_PARSER_BITFIELD ( checksumPresent, 1, bool ); SENF_PARSER_SKIP_BITS ( 12 ); SENF_PARSER_BITFIELD ( version, 3, unsigned ); SENF_PARSER_FIELD ( protocolType, senf::UInt16Parser ); \endcode Whereas \ref SENF_PARSER_BITFIELD can define only bit-fields, \ref SENF_PARSER_FIELD can define almost arbitrary field types. The type is specified by passing the name of another parser to \ref SENF_PARSER_FIELD. It is important to understand, that the accessors do \e not return the parsed field value. They return another \e parser which is used to further interpret the value. This is the inherent recursive nature of the SENF packet parsers. This allows to define wildly complex header formats if needed. Of course, at some point we need the real value. This is, what the so called value parsers do: They interpret some bytes or bits and return the value of that field (not a parser). Examples are the bitfield parsers returned by the accessors generated by SENF_PARSER_BITFIELD (like senf::UIntFieldParser) or the senf::UInt16Parser. What happens in the above macros? Most of the macros define an accessor for a specific field: \a checksumPresent() or \a protocolType(). They also manage a current Offset. This value is advanced according to the field size whenever a new field is defined (and since this parser is defined as a dynamically sized parser, this offset is not a constant, it is an expression which calculates the offset of a field depending on the preceding data). \subsection howto_newpacket_parser_variant Defining optional fields: The 'variant' parser We now come to the optional fields. Since there are two fields which need to be disabled/enabled together, we first need to define an additional sub-parser which combines those two fields. After this parser is defined, we can use \ref SENF_PARSER_VARIANT() to add this parser as an optional parser to the GRE header. \code struct GREPacketParser_OptFields : public senf::PacketParser { # include SENF_FIXED_PARSER() SENF_PARSER_FIELD ( checksum, senf::UInt16Parser ); SENF_PARSER_SKIP ( 2 ); SENF_PARSER_FINALIZE(GREPacketParser_OptFields); }; \endcode This parser only parses the two optional fields of which the reserved field is just skipped. The parser this time is a fixed size parser. We can now use this parser to continue the \c GREPacketParser implementation: \code SENF_PARSER_BITFIELD ( checksumPresent, 1, bool ); SENF_PARSER_SKIP_BITS ( 12 ); SENF_PARSER_BITFIELD ( version, 3, unsigned ); SENF_PARSER_FIELD ( protocolType, senf::UInt16Parser ); SENF_PARSER_VARIANT ( optionalFields, checksumPresent, (senf::VoidPacketParser) (GREPacketParser_OptFields) ); \endcode For a variant parser, two things need to be specified: A selector and a list of variant parsers. The selector is another parser field which is used to decide, which variant to choose. In this simple case, the field must be an unsigned integer (more precisely a value parser which returns a value which is implicitly convertible to \c unsigned). This value is used as index into the list of variant types. So in our case, 0 is associated with senf::VoidPacketParser whereas 1 is associated with \c GREPacketParser_OptFields. (senf::VoidPacketParser is a special empty parser which is used in a Variant to denote cases in which the variant parser should not parse anything) This parser will work, it is however not very safe and not very usable. If \a p is a GREPacketParser instance, than we access the fields via: \code p.checksumPresent() = true; p.version() = 4u; p.protocolType() = 0x86dd; p.optionalFields().get<1>().checksum() = 12345u; \endcode There are two problems here: \li accessing the checksum field is quite unwieldy \li changing the checksumPresent() value will break the parser The reason for the second problem lies in the fact, that the variant parser needs to be informed whenever the selector (here \a checksumPresent) is changed since the variant parser must ensure, that the header data stays consistent. In this example, whenever the checksumPresent field is enabled, the variant parser needs to insert additional 4 bytes of data and remove those bytes, when the checksumPresent field is disabled. \subsection howto_newpacket_parser_fixvariant Fixing access by providing custom accessor members Since we don't want to allow che \a checksumPresent() field to be changed directly, we mark this field as read-only: \code SENF_PARSER_BITFIELD_RO ( checksumPresent, 1, bool ); \endcode To change the \a checksumPresent() value, the variant parser provides special members to change the currently selected variant: \code p.optionalFields().init<0>(); p.optionalFields().init<1>(); \endcode These statements also change the selector field (in this case \a checksumPresent()) to the correct value: The first statements switches to the first variant and therefore in this case disables the checksum field. The second statement will switch to the second variant and enable the checksum field. Again, these statements are relatively complex. So we complete the parser by providing simple additional members which wrap these complicated calls. While doing this, we also mark the variant as a private field so it is not directly accessible any more (since we now have the additional helpers which are used to access the variant, we don't want anyone to mess around with it directly). Here the final \c GREPacketParser \code struct GREPacketParser_OptFields : public senf::PacketParser { # include SENF_FIXED_PARSER() SENF_PARSER_FIELD ( checksum, senf::UInt16Parser ); SENF_PARSER_SKIP ( 2 ); SENF_PARSER_FINALIZE(GREPacketParser_OptFields); }; struct GREPacketParser : public senf::PacketParser { # include SENF_PARSER() SENF_PARSER_BITFIELD_RO ( checksumPresent, 1, bool ); SENF_PARSER_SKIP_BITS ( 12 ); SENF_PARSER_BITFIELD ( version, 3, unsigned ); SENF_PARSER_FIELD ( protocolType, senf::UInt16Parser ); SENF_PARSER_PRIVATE_VARIANT ( optionalFields_, checksumPresent, (senf::VoidPacketParser) (GREPacketParser_OptFields) ); typedef GREPacketParser_OptFields::checksum_t checksum_t; checksum_t checksum() const { return optionalFields_().get<1>().checksum(); } void enableChecksum() const { optionalFields_().init<1>(); } void disableChecksum() const { optionalFields_().init<0>(); } SENF_PARSER_FINALIZE(GREPacketParser); }; \endcode Above code has one other twist we need to discuss: the \a checksum_t typedef. This is added as a convenience to the user of this parser. The \c SENF_PARSER_* macros which define a field all define some additional symbols providing further information about the field. Of these additional symbols, the most important is field_t, which is the (parser) type returned by the field. This helps to work with a parser in more complex situations (e.g. when using \ref parsecollection) since it allows to access the parser type without exact knowledge of this type (which may become quite complex if templates are involved) as long as the field name is known. Since we provide an accessor for the \a checksum field, we also provide the \a checksum_t typedef for this accessor. The \c GREPacketParser is now simple and safe to use. The only responsibility of the user now is to only access \a checksum() if the \a checksumPresent() field is set. Otherwise, the behavior is undefined (in debug builds, the parser will terminate the application with an assert). \section howto_newpacket_type Defining the packet type After we have implemented the \c GREPacketParser we need now to build the packet type. This is done by providing a special policy class called the 'packet type'. This class encapsulates all the information the packet library needs to know about a packet: \subsection howto_newpacket_type_skeleton The packet type skeleton For every type of packet, the 'packet type' class will look roughly the same. If the packet utilizes a registry and is not hopelessly complex, the packet type will almost always look like this: \code struct GREPacketType : public senf::PacketTypeBase, public senf::PacketTypeMixin { typedef senf::PacketTypeMixin mixin; typedef senf::ConcretePacket packet; typedef senf::GREPacketParser parser; using mixin::nextPacketRange; using mixin::nextPacketType; using mixin::init; using mixin::initSize; // Define members here }; \endcode We note, that \c GREPacketType derives from two classes: senf::PacketTypeBase and senf::PacketTypeMixin. senf::PacketTypeBase must be inherited by every packet type class. the senf::PacketTypeMixin provides default implementations for some members which are useful for most kinds of packets. If a packet type is very complex and these defaults don't work, the mixin class can and should be left out. Of the typedefs, only \a parser is mandatory. It defines the packet parser to use to interpret this type of packet. \a mixin and \a packet are defined to simplify the following definitions (More on \a packet and senf::ConcretePacket later). The next block of statements imports all the default implementations provided by the mixin class: \li \a nextPacketRange provides information about where the next packet lives within the GRE packet. \li \a nextPacketType provides the type of the next packet from information in the GRE packet. \li \a init is called to initialize a new GRE packet. This call is forwarded to \c GREPacketparser::init. \li \a initSize is called to find the size of an empty (newly create) GRE packet. This is also provided by GREPacketParser. With these default implementations provided by the mixin, only a few additional members are needed to complete the \c GREPacketType: \a nextPacketKey, \a finalize, and \a dump \subsection howto_newpacket_type_registry Utilizing the packet registry We want the GRE packet to utilize the senf::EtherTypes registry to find the type of packet contained in the GRE payload. A registry maps an arbitrary key value to a packet type represented by a packet factory instance. The details have already been taken care of by the senf::PacketTypeMixin (it provides the \a nextPacketType member). However, to lookup the packet in the registry, the mixin needs to know the key value. To this end, we implement \a nextPacketKey(), which is very simple: \code static key_t nextPacketKey(packet p) { return p->protocolType(); } \endcode All \c GREPacketType members are static. They are passed the packet in question as an argument. \a nextPacketKey() just needs to return the value of the correct packet field. And since the \c parser type (as defined as a typedef) allows direct access to the packet parser using the -> operator, we can simply access that value. The \c key_t return type is a typedef provided by the mixin class it is taken from the type of registry, in this case it is senf::EtherTypes::key_t (which is defined as a 16 bit unsigned integer value). With this information, the packet library can now find out the type of packet needed to parse the GRE payload -- as long as the protocolType() is registered with the senf::EtherTypes registry. If this is not the case, the packet library will not try to interpret the payload, it will return a senf::DataPacket. One special case of GRE encapsulation occurs when layer 2 frames and especially ethernet frames are carried in the GRE payload. The ETHERTYPE registry normally only contains layer 3 protocols (like IP or IPX) however for this special case, the value 0x6558 has been added to the ETHERTYPE registry. So we need to add this value to inform the packet library to parse the payload as an ethernet packet if the \a protocolType() is 0x6558. This happens in the implementation file (the \c .cc file): \code SENF_PACKET_REGISTRY_REGISTER( senf::EtherTypes, 0x6558, senf::EthernetPacket ); \endcode This macro registers the value 0x6558 in the senf::EtherTypes registry and associates it with the packet type senf::EthernetPacket. This macro declares an anonymous static variable, it therefore must always be placed in the implementation file and \e never in an include file. Additionally, we want the GRE packet to be parsed when present as an IP payload. Therefore we additionally need to register GRE in the senf::IpTypes registry. Looking at the IP protocol numbers, we find that GRE has been assigned the value 47: \code SENF_PACKET_REGISTRY_REGISTER( senf::IpTypes, 47, GREPacket ); \endcode But wait -- what is \c GREPacket ? This question is answered a few section farther on. \fixme Document the needed \c \#include files \fixme Provide an advanced section with additional info: How to ensure, that the first 5 bits in reserver0 are not set. How to enforce version == 0 (that is, make version() read-only and return no_factory for the next packet type if any of the conditions is violated) */ // Local Variables: // mode: c++ // fill-column: 100 // comment-column: 40 // c-file-style: "senf" // indent-tabs-mode: nil // ispell-local-dictionary: "american" // compile-command: "scons -u doc" // mode: flyspell // mode: auto-fill // End: