Define Command

Reference Documentation

Intel® PAC
Napatech SmartNIC
Content Type
Reference Information
Capture Software Version
Link™ Capture Software 12.9
Napatech Software Suite: Define Command

This section specifies the syntax and semantics for the define command.

Supported Options Per Feature Set

Supported Feature Sets

The syntax for define commands is shown below.

<DefineCommand>     ::= 'Define' <Identifier> '=' <DefineSpec>
<DefineSpec>        ::= <DefineSliceSpec> | <DefineHashSpec> | <DefineDescrSpec> |
                        <DefineFilterSpec> | <DefineFieldSpec> | <DefineMacroSpec> |
                        <DefineMaskSpec> | <DefineHstSpec>
<DefineSliceSpec>   ::= 'Slice'          '(' <SliceRecipe> ')'
<DefineHashSpec>    ::= 'Hash'           '(' <HashRecipe> ')'
<DefineDescrSpec>   ::= 'Descriptor'     '(' <DescriptorRecipe> ')'
<DefineCorrSpec>    ::= 'CorrelationKey' '(' <CorrelationKeyRecipe> ')'
<DefineFilterSpec>  ::= 'Filter'         '(' <FilterExpressionSpec> ')'
<DefineFieldSpec>   ::= 'Field'          '(' <ProtocolField> ')'
<DefineMacroSpec>   ::= 'Macro'          '(' <MacroDefinition> ')'
<DefineMaskSpec>    ::= 'Mask'           '(' <MaskRecipe> ')'
<DefineHstSpec>     ::= 'HeaderStripper' '(' <HeaderStripperRecipe> ')'

The <DefineCommand> is used to define reusable elements and give them a name. This name can be used later to refer to the element. Look at the Define Example below and the Balance Tunneled Traffic example to see how the <DefineCommand> can improve the readability and manageability of NTPL expressions. It can replace the use of the Macro Command in many cases. The advantage is that, except for the <DefineMacroSpec>, this command is checked syntactically when entered. The items that you construct can only be used where they fit in the syntax.

Slice Recipe

Defines a position in the packet where the slicing should take place.

The syntax for the slice recipe is shown below.

<SliceRecipe>       ::= <Identifier> | <ProtocolLocation15> | 'NONE'

Using 'Slice=NONE' is equivalent to 'Slice=EndOfFrame[0]' meaning the packets will not be sliced. A slicing resource will however still be allocated.


Slice recipe examples

Hash Recipe

A <HashRecipe> defines how to extract the data into a key that should be used for hashing. The key has 5 fields: 2 four-word fields (128 bits), 2 one-word fields (32 bits) and a 1 byte field. The 4 first fields can be programmed freely to any packet data, but the byte field can only be filled with either the outer or the inner IP protocol field. If a field is not mentioned in the recipe, it will be masked out.

If 'XOR' is 'true' then HashWord0_3 and HashWord4_7 will be xored together. For both HashWord8 and HashWord9, the upper and the lower half will be xored together. This can be used in case traffic in both directions should result in the same hash value.

A 'Swapping' option is not needed, as a hash recipe for each direction should be defined and then combined with appropriate filters.

The syntax for the hash recipe is shown below.

<HashRecipe>        ::= <Identifier> | 'RoundRobin' | 'Random' | <HashKeySpecs>
<HashKeySpecs>      ::= <HashKeySpec> [ ',' <HashKeySpecs> ]
<HashKeySpec>       ::= ( 'HashWord0_3' '=' <FieldAndMask> ) |
                        ( 'HashWord4_7' '=' <FieldAndMask> ) |
                        ( 'HashWord8' '=' <FieldAndMask> ) |
                        ( 'HashWord9' '=' <FieldAndMask> ) |
                        ( 'HashWordP' '=' ( 'IpProtocol' | InnerIpProtocol)) |
                        ( 'XOR' '=' <TrueFalseValue> )
<FieldAndMask>      ::= ( '{' <DataMask> ':' <ProtocolField8> '}' ) |

When specifying the individual hash words, you have the option to specify a mask that will be AND'ed to the value before the hash value is calculated. You can only use mask on field sizes below or equal to 32.


Hash recipe examples

Descriptor Recipe

The descriptor recipe is used in relation to dynamic descriptors.

The dynamic descriptors contain a number of offset fields that point to locations inside a received packet. The locations can be programmed by the user. An offset is formed as the sum of a dynamic part (pointer to internal headers of the decoded packet) and a static part (see Dynamic Descriptors with User-Programmed Offsets).

This can be done in a per filter expression basis.

The syntax for the descriptor recipe is shown below.

<DescriptorRecipe>  ::=  <Descriptor> | <DynamicDescriptor> | <Identifier>
<Descriptor>        ::= 'NT' | 'EXT9' | 'PCAP'
<DynamicDescriptor> ::= ( 'DYN1' | 'DYN2' | 'DYN3' | 'DYN4') [ ',' <DynOptionSpecList> ]
<DynOptionSpecList> ::= <DynOptionSpec> [ ',' <DynOptionSpecList> ]
<DynOptionSpec>     ::= 'Offset0' '=' <ProtocolLocation8> |
                        'Offset1' '=' <ProtocolLocation8> |
                        'Offset2' '=' <ProtocolLocation8> |
                        'Length' '=' <DescriptorLength> |
                        'ColorBits' '=' ( '6' | '8' | '14' | '22' | '32' | 'FlowID' )

When dynamic descriptor parameters are not specified they default to:

  • Offset0: Start of the outer layer 3 header (Layer3Header[0])
  • Offset1: Start of the outer layer 4 header (Layer4Header[0])
  • Offset2: Start of the outer layer 4 payload (Layer4Payload[0])
  • Length: 18 for dynamic descriptor 1, 22 for dynamic descriptors 2 and 3, 24 for descriptor 4
  • ColorBits: 32 for descriptor 4, 14 for the rest

The "Length" parameter specifies how big a received dynamic descriptor should be. The length of the descriptor cannot exceed 64 bytes. If the length is greater than the natural size of the descriptor (18 bytes for dynamic descriptor 1, 22 bytes for dynamic descriptors 2 and 3, 24 bytes for descriptor 4) extra padding will be inserted between the descriptor structure and the start of the packet data. If the length is smaller than the natural size of the descriptor the descriptor will effectively shrink. This is useful for saving PCI bandwidth if the last parts of the descriptor are not used by an application.

The color field(s) in dynamic descriptors 2, 3 and 4 can contain a mix of the color and hash/correlation values. The 'ColorBits' option is used to control how many bits are used for the color value and consequently how many are used for the hash/correlation value.

For dynamic descriptor 2 the 'ColorBits' option accept the following values:

  • 6: Hash value shifted up by 6 ( 6 lower bits are color).
  • 14: Hash value shifted up by 14 (14 lower bits are color).
  • 22: Hash value shifted up by 22 (22 lower bits are color).
  • 32: All bits are color.

For dynamic descriptor 3 the 'ColorBits' option accept the following values:

  • 14: color_lo contains lower 14 bits of color. color_hi contains lower 28 bits of hash.
  • 32: color_lo contains lower 14 bits of color. color_hi contains upper 18 bits of color.

For dynamic descriptor 4 the 'ColorBits' option accept the following values:

  • 8: color0 contains the lower 8 bits of color. color1 contains the correlation key.
  • 32: color0 contains the value of the IP protocol field, the lower 32 bits of color1 contains the color value while the upper 32 bits contain the hash value.
  • FlowID: color0 contains the lower 8 bits of color. color1 contains the id data specified in the flow learn records ( NtFlow_t ).


Descriptor recipe examples

Correlation Key Recipe

The correlation key recipe configures the calculation of correlation keys in the FPGA. The correlation key is a checksum that is calculated over a part of the packet. The correlation key is passed to the application in certain descriptors (e.g. Dyn4) and can be used to identify duplicate packets, or the same packet at different points in a network. It is possible to narrow down which part of the packet the checksum is calculated over. One 32-bit mask is available, for dynamically masking out parts of the packet data, that should be ignored when calculating the checksum. Additionally a number of fixed fields can be masked out.

The syntax for the CorrelationKey recipe is shown below:

<CorrelationKeyRecipe>     ::= <Identifier> | <CorrelationKeyOptions>
<CorrelationKeyOptionSpec> ::= <CorrelationKeyOption> [ ',' <CorrelationKeyOptionSpec> ]
<CorrelationKeyOption>     ::= 'Begin' '=' <ProtocolLocation15> |
                               'End' '=' <ProtocolLocation15> |
                               'KeyLength' '=' <FrameLengthValue> |
                               'Mask1' '=' <LocationAndMask> |
                               'StaticMask' '=' '(' <StaticMaskList> ')' |
                               'DeduplicationGroupID' '=' <DeduplicationGroupNumber>
<LocationAndMask>          ::= '{' <32-bit value> ':' <ProtocolLocation15> '}'
<StaticMaskList>           ::= <OuterStaticMaskList> | <InnerStaticMaskList>
<OuterStaticMaskList>      ::= <OuterStaticMaskElement> [ ',' <OuterStaticMaskList> ]
<InnerStaticMaskList>      ::= <InnerStaticMaskElement> [ ',' <InnerStaticMaskList> ]
<OuterStaticMaskElement>   ::= 'IPTOSDSCP' | 'IPTOSECN' | 'IPID' |
                               'IPTTL' | 'IPFLAGS' | 'IPCHK' |
                               'IPSRC' | 'IPDST' | 'IPFLOW' |
                               'IPHOP' | 'IPTC' | 'IPNXTHDR' |
                               'TCPSEQ' |'TCPSRC' | 'TCPDST' |
                               'TCPCHK' | 'UDPCHK' | 'UDPSRC' |
<InnerStaticMaskElement>   ::= 'InnerIPTOSDSCP' |'InnerIPTOSECN' | 'InnerIPID' |
                               'InnerIPTTL' |'InnerIPFLAGS' | 'InnerIPCHK' |
                               'InnerIPSRC' |'InnerIPDST' |'InnerIPFLOW' |
                               'InnerIPHOP' | 'InnerIPTC' | 'InnerIPNXTHDR' |
                               'InnerTCPSEQ' | 'InnerTCPSRC' |'InnerTCPDST' |
                               'InnerTCPCHK' | 'InnerUDPCHK' | 'InnerUDPSRC' |

The 'Begin' and 'End' options are used to specify which part of the packet to calculate the correlation key over (the window). 'Begin' defaults to "StartOfFrame[0]" and 'End' defaults to "EndOfFrame[-4]". The 'KeyLength' option can be used to clamp the length of the window. This is useful if a packet whose correlation key has been calculated is subsequently fragmented. By limiting the window to the size of the first fragment it will be possible to correlate the unfragmented packet with the first fragment of the packet. The default value of 'KeyLength' is 10000

When calculating the correlation key, it is often desirable to ignore certain parts of the packet, since these will change as the packet moves through the network (eg. TTL in the IP header.) One 32-bit dynamic mask is provided allowing the user to mask away arbitrary parts of a packet. This mask is configured with the 'Mask1' option. In addition to the dynamic mask, a number of predefined fields can be masked out with the 'StaticMask' option. It takes a list of identifiers specifying which fields to ignore when calculating the correlation key. Identifiers exist for both inner (tunneled) and outer fields.

NOTE: It is not possible to mix inner and outer fields in the 'StaticMask' list.


Correlation key recipe examples

Define Examples

An example of defining hash recipes is shown below.

Define HashUp = Hash(HashWord0_3=Layer3Header[12]/32, HashWord4_7=Layer3Header[16]/32)
Define HashDown = Hash(HashWord0_3=Layer3Header[16]/32, HashWord4_7=Layer3Header[12]/32)

Mask Recipe

The Mask recipe will configure up to four byte ranges to be masked out (zero filled) in matching frames.

The syntax for the Mask recipe is shown below:

<MaskRecipe>      ::= <Identifier> | <MaskOptions>
<MaskOptions>     ::= <MaskOption> [ ',' <MaskOptions> ]
<MaskOption>      ::= 'Offset0' '=' <ProtocolLocation15> |
                      'Length0' '=' <MaskLength> |
                      'Offset1' '=' <ProtocolLocation15> |
                      'Length1' '=' <MaskLength> |
                      'Offset2' '=' <ProtocolLocation15> |
                      'Length2' '=' <MaskLength> |
                      'Offset3' '=' <ProtocolLocation15> |
                      'Length3' '=' <MaskLength>

Each OffsetX/LengthX pair will configure a byte range at the specified offset and length to be masked out by the FPGA.


Mask recipe examples

HeaderStripper Recipe

The HeaderStripper can perform two different actions simultaneously:

  • Stripping (removal) of a section in the first 400 bytes of a frame
  • Modification of up to three 2-byte segments.

The syntax for the HeaderStripper recipe is shown below:

<HeaderStripperRecipe>      ::= <Identifier> | <HeaderStripperOptions>
<HeaderStripperOptions>     ::= <HeaderStripperOption> [ ',' <HeaderStripperOptions> ]
<HeaderStripperOption>      ::= 'Begin' '=' <ProtocolLocation15> |
                                'End' '=' <ProtocolLocation15> |
                                'Offset0' '=' <ProtocolLocation15> |
                                'Value0' '=' <16-bit decimal value> |
                                'Cmd0' '=' <HeaderStripperCommand> |
                                'Offset1' '=' <ProtocolLocation15> |
                                'Value1' '=' <16-bit decimal value> |
                                'Cmd1' '=' <HeaderStripperCommand> |
                                'Offset2' '=' <ProtocolLocation15> |
                                'Value2' '=' <16-bit decimal value> |
                                'Cmd2' '=' <HeaderStripperCommand>
<HeaderStripperCommand>     ::= 'Replace2B' | 'Replace1B' | 'Subtract2B' |
                                'Subtract1B' | 'SubtractStripped' | 'OuterEtherType' |

When the EtherType field is stripped, the HeaderStripper will by default replace the two bytes after the stripped entry with correct EtherType deduced from the remaining packet (if it is not corrupted by incorrect stripping). Often this will entail that the NTPL stated will strip two less bytes than intended as the remaining two bytes will be replaced. See the example Removing all VLAN tags.

This behaviour can be modified by using the below commands supported by HeaderStripper:

Cmd Offset Value Description
Replace2B X 0..65535 Replaces two bytes at the provided offset with the value set.
Replace1B X 0..255 Replaces one byte at the provided offset with the value set.
Subtract2B X 0..65535 Subtracts the provided value from two bytes at the set offset.
Subtract1B X 0..255 Subtracts the provided value from one byte at the set offset.
SubtractStripped X - Subtracts the number of stripped bytes (Begin .. End) from two bytes at the set offset.
OuterEtherType X - Replaces two bytes at provided offset with ethertype for the outer IP layer. Requires presence of outer IPv4 or IPv6.
InnerEtherType X - Replaces two bytes at provided offset with ethertype for the inner IP layer. Requires presence of inner IPv4 or IPv6.

'X' indicates that the value is required, while '-' shows that the value is not applicable for the given command.


HeaderStripper recipe examples