KeyType Command

Reference Documentation

Platform
Intel® PAC
Napatech SmartNIC
Content Type
Reference Information
Capture Software Version
Link™ Capture Software 12.10
Napatech Software Suite: KeyType Command

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

Supported Options Per Feature Set

Supported Feature Sets
N-ANL4 N-ANL5
N-ANL6
N-ANL7
N-ANL8
N-ANL9
N-ANL10
  X

The syntax for the KeyType command is shown below.

<KeyTypeDef>         ::= 'KeyType' '[' <KeyTypeOptionSpec> ']' '=' '{' <FieldSizeSpec> '}'
<KeyTypeOptions>     ::= <KeyTypeOption> [ ';' <KeyTypeOptionSpec> ]
<KeyTypeOption>      ::= ( 'Name' '=' <Identifier> ) |
                         ( 'ColorInfo' '=' <TrueFalseValue> ) |
                         ( 'StreamInfo' '=' <TrueFalseValue> ) |
                         ( 'Access' '=' <AccessValue> ) |
                         ( 'Bank' '=' <BankNo> ) |
                         ( 'Tag' '=' <Identifier> )
<AccessValue>        ::= 'Single' | 'Partial' | 'Full'
<BankNo>             ::= '0' | '1'
<FieldSizeSpec>      ::= <FieldSize> [ ',' <FieldSizeSpec> ]
<FieldSize>          ::= '16' | '32' | '64' | '128' | 'SW_16_16' | 'SW_32_32' | 'SW_128_128'

KeyType command is used for both the Key matcher functionality and Flow matcher functionality; the sections below will specify the similarities and differences.

A KeyType command defines a key type for extraction of fields from received packets and assigns it a unique name. A key type defines the number of fields used to build a key and the size of each field. The key type doesn't define from where in the received packets the individual fields are extracted - it only defines nubmer of fields and field sizes. The location of the field in a packet is defined by a KeyDef Command later on. A single key type may be used by multiple key definition.

Besides fields and their sizes the key type definition also sets a number of properties for keys based on the key type. This is further described below.

Key matcher

  • Name: The name of the key type.
  • ColorInfo: Whether the underlying keys include coloring info.
  • StreamInfo: Whether the underlying keys include stream info.
  • Access: The type of access that will be performed on the underlying keys.
  • Bank: The bank modulus of the underlying keys - explained below.
  • Tag: For a description of the 'Tag' option please refer to Tag Option.
  • FieldSize: '16' | '32' | '64' | '128'

Flow matcher

  • Name: The name of the key type.
  • ColorInfo: Whether the underlying keys include coloring info.
  • StreamInfo: Whether the underlying keys include stream info.
  • Access: N/A
  • Bank: N/A
  • Tag: For a description of the 'Tag' option please refer to Tag Option.
  • FieldSize: '16' | '32' | '64' | '128' | 'SW_16_16' | 'SW_32_32' | 'SW_128_128'

Description of options and fields

Name option

The name option is mandatory and must be a unique name for every key type. The KeyDef Command uses the name as reference to a specific key type.

ColorInfo option

The ColorInfo option specifies that keys using the key type contain color information that should be copied to the packet descriptor when a packet matches.

If not specified ColorInfo defaults to "False".

StreamInfo option

The StreamInfo option specifies that keys using the key type contain information on what stream matching packets should be sent to.

If not specified StreamInfo defaults to "False".

Access option

The type of access the Key matcher will perform on keys affects how they are programmed into the hardware. It is therefore necessary to specify this in the key type. There are three types of accesses:

  • Single: A key is only accessed once per packet.
  • Partial: Two keys of different key type are accessed once each per packet.
  • Full: A key is accessed two times per packet.

A "Single" type access may for example be the source address of an IP header. In this case the source field is extracted from the IP header and a single search is performed in the key database. The other two types of accesses could for example be both the source and destination addresses of an IP header. If the set of source addresses do not overlap significantly with the set of destination addresses, it would be more space efficient to program the two sets into two separate key types and use a "Partial" type access. If however the source and destination addresses can take on values from the same set a "Full" access type should be used. If not specified the access type defaults to "Single".

Bank option

The Bank option is required on key types that use "Partial" access. It is invalid to use it on key types that use "Single" or "Full" access. On adapters that support high packet rates, when performing two partial accesses with two different key types, a key type can only search every other record in the key "database". The Bank option allows one to put keys from one key type into even numbered records and keys from the other key type into odd numbered records and thereby enabling two partial accesses.

Field Size specification

Field size specification is a list of field sizes to define the number of fields and the number of bits in each field. The final key is a concatenation of these fields.

The special FieldSize values 'SW_16_16', 'SW_32_32' and 'SW_128_128' are flow matcher specific.

The value 'SW_16_16' represents a 2x16 = 32 bit field. The flow matcher can be programmed to swap the two 16 bit parts when extracting the field from a packet. This field type is for instance useful for flow matching involving L4 ports.

The value 'SW_32_32' represents a 2x32 = 64 bit field. The flow matcher can be programmed to swap the two 32 bit parts when extracting the field from a packet. This field type is for instance useful for flow matching involving IPv4 addresses.

The value 'SW_128_128' represents a 2x128 = 256 bit field. The flow matcher can be programmed to swap the two 128 bit parts when extracting the field from a packet. This field type is for instance useful for flow matching involving IPv6 addresses.

Sub-field swap is enabled using the FieldAction option in the Key Tests section.

Examples

For examples on how to use the KeyType command please refer to the examples in the Key Tests section.

For Flow matcher specific examples also refer to the Flow matcher feature section and flowmatch/flowmatch_example_main.cpp for a C++ code example.