ProtoSpecs XML Writing Guidelines

for AiroPeek or AiroPeek NX 2.0 or higher

Doc version 5.1.0.1
Last revised 05/05/2003

The file of interest for adding protocols to the ProtoSpec protocol hierarchy is PSpecs.xml. This file is located in a language specific folder (by language ID, for instance the 1033 folder for the English version) in the program's installation folder--the default location is C:\Program Files\WildPackets\[product].

Before opening or modifying these files, it is recommended that you make a backup copy of the PSpecs.xml file, in case your modified copy becomes unusable by your Peek application.

In order to add a protocol to the ProtoSpec hierarchy, you will need to add specifically formatted information to the PSpecs.xml file. This PSpecs.xml file must remain in the language specific folder depending on your system's language settings.

Once you have made a backup copy of the PSpecs.xml file, familiarize yourself with the format of a ProtoSpec item by examining the XML file.

General format of PSpecs.xml:

	<PSpec Name="IEEE 802.3">
		<PSpecID>1</PSpecID>
		<LName>IEEE 802.3 CSMA/CD Ethernet</LName>
		<SName>802.3</SName>
		<Desc>802.3 is a comprehensive standard for Local Area Networks employing the Carrier Sense Multiple Access with Collision Detection 
			(CSMA/CD) access method. Under the International Standards Organization (ISO) the 10 megabits per second transmission speed 
			is specified by ISO/DIS 8802/3. The definition of Ethernet under 802.3 supersedes the previous Ethernet standard known as 
			Ethernet Type 2. In terms of data bytes in the protocol stack, 802.3 uses bytes 13 and 14 as a length field, whereas the 
			earlier standard used these bytes as a protocol definition field.</Desc>
		<Color>color_1</Color>
		<CondExp><![CDATA[ MLD16[12] <= 1500 ]]></CondExp>
		<NextLayer>
			<Exp><![CDATA[    14    ]]></Exp>
		</NextLayer>
		<Link Name="802.2 LLC"/>
	</PSpec>

Each PSpec element block is made up of the following items:

PSpec - starts a new ProtoSpec node. This element can contain the following attributes:
- Name - Hierarchical name for the ProtoSpec.
- Type - used at the root level only. Type="CommonTable" implies that this node contains common elements for sharing with other nodes.
- Sort - Setting Sort="First" forces this element to be created first in the protocol list. Sort="Last" does the opposite. No attribute implies to use the given order
PSpecID - a 16-bit identifier for the ProtoSpec, in most cases a unique number throughout the file. This may be shared between different definitions when the definitions should be considered the same protocol. See the IPv6 definitions for an example.
LName - Long name of the protocol.
SName - Short name of the protocol.
Desc - [optional] Description for the protocol.
DescID - [optional] Protocol ID from which to obtain the description.
Color - [optional] Color for the protocol. If not specified the application will use the parent's color.
CondExp - [optional] A conditional expression to evaluate if a packet matches this protocol definition. The expression is evaluated to true (or != 0) or false (== 0). See the description of expressions below for more details.
NextLayer - [optional] An element with the following children:
- Exp - A numeric expression used to determine the size of the protocol's header. See the description of expressions below for more details
Definitions - [optional] An element with the following children:
- Define - Defines a literal substitution for sub protocol expressions, much like a C #define. Define has 2 children:
  - Name - The name of the definition
  - Value - The expression to substitute for in expressions containing Name.
NotChild - [optional] used to prevent recursive protocol defnitions. This element can contain the following attribute:
- Name - the hierarchical name of the protocol to not include as a subprotocol.
Link - [optional] An element with the following children:
- Name - the hierarchical name of a CommonTable to include as children of this protocol.

Expressions

Expressions are C style mathematical expressions geared toward analyzing packets. In addition to C style mathematical operators (+, -, <, etc.), there are special operations that examine packet data:

PLDX[Y] - ParentLayerData; starting from the header layer of the parent protocol, examine "X" bits at byte offset Y in network byte order. Possible values for X are 8, 16, 24, and 32. For example, PLD8[3] evaluates to the value of the byte at offset 3 from the start of the parent layer's header.
MLDX[Y] - MyLayerData; starting from the payload layer of the parent protocol, examine "X" bits at byte offset Y in network byte order. Possible values for X are 8, 16, 24, and 32. For example, MLD8[3] evaluates to the value of the byte at offset 3 from the start of the parent layer's payload.

ProtoSpec Tree Generation

The ProtoSpec tree is generated from the XML by walking the tree from each root element and adding each element, element's children, and the children of any links included in any element. A 32-bit ProtoSpec instance ID is generated for each element in the tree; the lower 16 bits consist of the PSpecID value, and the upper 16 bits are an instance counter, incremented for each time an element is included in the tree. All ProtoSpec IDs passed to plugins are 32 bit instance IDs. Plugins generally examine the lower 16 bits to determine the actual protocol, and list the 16 bit PSpecIDs in the Supported ProtoSpecs array. The 32 bit ID is used for determining the parent protocol list, determining the header and payload locations for each protocol, etc.