Defining Key Match

The KeyType, KeyDef and KeyList commands are used to define key match. This NTPL example configures the SmartNIC to observe the IPv4 source address field. If the IP address of a frame is contained in one of the IP address lists (IP_List0 or IP_List1), the frame is delivered to the corresponding stream.

// Macros for KeySet identifiers.
Define IP_list0 = Macro("3")
Define IP_list1 = Macro("4")

// IPv4 protocol filter.
Define isIPv4 = Filter(Layer3Protocol==IPv4)
// Source IPv4 field.
Define IPv4SrcField = Field(Layer3Header[12]/32)

KeyType[Name=KT_IPv4] = {32}
KeyDef[Name=IPv4Src; KeyType=KT_IPv4] = (IPv4SrcField)

Assign[StreamId=0] = isIPv4 AND Key(IPv4Src)==IP_list0
Assign[StreamId=1] = isIPv4 AND Key(IPv4Src)==IP_list1

// Add IP addresses to IP list 0.
KeyList[KeySet=IP_list0; KeyType=KT_IPv4] = ( [192.168.0.2] ), \\
( [192.168.0.3] ), ( [192.168.0.4] )

// Add IP addresses to IP list 1.
KeyList[KeySet=IP_list1; KeyType=KT_IPv4] = ( [192.168.1.20] ), \\
( [192.168.1.21] ), ( [192.168.1.24] ), ({[ff.ff.ff.00]:[192.168.2.2]})

Configure key match using the KeyType, KeyDef and KeyList commands.

• KeyType: Defines number of fields and their lengths. Supported lengths are 16, 32, 64 and 128 bytes. One 32-byte field is defined in this example.
• KeyDef: Defines the location of fields. The IPv4 source address field is defined in this example.
• KeyList: Configures values for key match.
  • Two macros for two lists (IP_List0 and IP_List1) are defined.
  • KeySet=IP_List0 with a list of IPv4 addresses and KeySet=IP_List1 with another list of IPv4 addresses are configured.
    Note: Supported values for KeySet are 1 to 15 where 1 is reserved for IPv4 addresses, and 2 is reserved for IPv6 addresses.
  • A mask can also be used to match a range of IP addresses as shown in this example, ({[ff.ff.ff.00]:[192.168.2.2]}).

The first Assign command configures the SmartNIC to deliver frames to stream 0 if the IP address is contained in one of IP_List0. The second Assign command indicates that frames are delivered to stream 1 if the IP address of the frames is contained in one of IP_List1.

// Macros for KeySet identifiers.
Define IP_list0 = Macro("3")
Define IP_list1 = Macro("4")

// IPv4 protocol filter.
Define isIPv4 = Filter(Layer3Protocol==IPv4)
// Source IPv4 field.
Define IPv4SrcField = Field(Layer3Header[12]/32)

KeyType[Name=KT_IPv4; ColorInfo=True] = {32}
KeyDef[Name=IPv4Src; KeyType=KT_IPv4] = (IPv4SrcField)

Assign[StreamId=0; Descriptor=DYN2; ColorBits=6] = isIPv4 AND Key(IPv4Src)==IP_list0
Assign[StreamId=1; Descriptor=DYN2; ColorBits=6] = isIPv4 AND Key(IPv4Src)==IP_list1

KeyList[KeySet=IP_list0; Color=23; KeyType = KT_IPv4] = ( [192.168.0.2] ), \\
( [192.168.0.3] ), ( [192.168.0.4];Color=24 )

KeyList[KeySet=IP_list1; Color=25; KeyType = KT_IPv4] = ( [192.168.1.20] ), \\
 ( [192.168.1.21] ), ( [192.168.1.24];Color=26 ), ({[ff.ff.ff.00]:[192.168.2.2]})

The color information is included in the dynamic descriptor of each frame. The descriptor type is configured in the /opt/napatech3/config/ntservice.ini file and can be changed dynamically using NTPL. In this example, dynamic descriptor 2 is selected, and the lower 6 bits of the color field is used for the color information. By default, the lower 14 bits of the color field are used if dynamic descriptor 2 is selected. See the Descriptor Recipe section in Define Command for more information on the supported values of the ColorBits parameter. Dynamic descriptor 2 is defined as follows:

typedef struct NtDyn2Descr_s {
  uint64_t capLength:14;    /**< The length of the packet incl. descriptor.                         */ /*  0*/
  uint64_t offset0:10;      /**< Programmable offset into the packet. Default is outer L3.          */ /* 14*/
  uint64_t offset1:10;      /**< Programmable offset into the packet. Default is outer L4.          */ /* 24*/
  uint64_t ipProtocol:8;    /**< Select-able IP protocol. Default is outer IP Protocol field.       */ /* 34*/
  uint64_t rxPort:6;        /**< The port that received the frame.                                  */ /* 42*/
  uint64_t descrFormat:8;   /**< The descriptor type.                                               */ /* 48*/
  uint64_t descrLength:6;   /**< The length of the descriptor in bytes.                             */ /* 56*/
  uint64_t tsColor:1;       /**< Timestamp color. Reserved for future use.                          */ /* 62*/
  uint64_t ntDynDescr:1;    /**< Set to 1 to identify this descriptor as a dynamic descriptor.      */ /* 63*/
  uint64_t timestamp;       /**< The time of arrival of the packet.                                 */ /* 64*/
  uint64_t offset2:10;      /**< Programmable offset into the packet. Default is outer L4 payload.  */ /*128*/
  uint64_t color:38;        /**< 32 bit hash and 6 bit traditional color.                           */ /*138*/
} NtDyn2Descr_t; // descrFormat = 2, descrLength = 22 /*176 bits*/

StreamInfo=True in the KeyType command enables the SmartNICs to forward matching frames to the streams which are configured in the KeyList command as shown in the following example.

// Define a filter for IPv4 traffic.
Define isIPv4 = Filter(Layer3Protocol == IPv4)

// Observe the source IP address field. 
KeyType[name=KT_IPv4; ColorInfo=True; StreamInfo=True] = {32}
KeyDef[Name=SrcIPv4; KeyType=KT_IPv4] = (Layer3Header[12]/32)

// Set up filters.
Assign[StreamId=Key; Descriptor=DYN2; Priority=0] = isIPv4 AND Key(SrcIPv4)==3

// Add IP addresses with stream ID.
KeyList[KeySet=3; Color=23; StreamId=4; KeyType=KT_IPv4] = ( [192.168.0.2] ), \\
( [192.168.0.3] ), ( [192.168.0.4];StreamId=5 )

StreamId=Key in the first Assign command indicates that the filtered frames are delivered to the stream which is specified in the KeyList. It is also possible to configure a stream ID for individual IP addresses as shown in this example, ([192.168.0.4]; StreamId=5). The stream information is stored in the upper 7 bits of the color field in the descriptor of each frame. Dynamic descriptor 2 is selected in this example. See Dynamic descriptor 2 structure.

Various header fields can be selected for key match. This example shows how to select the first and second VLAN ID fields as well as the source and destination IP address fields.

// Define fields for the first/second VLAN IDs and source/destination IP addresses.
Define VlanId1 = Field(FirstVLAN[2]/16)
Define VlanId2 = Field(FirstVLAN[6]/16)
Define IPv4Src = Field(Layer3Header[12]/32)
Define Ipv4Dst = Field(Layer3Header[16]/32)

KeyType[name=KT_4tuple; ColorInfo=True] = {16, 16, 32, 32}
KeyDef[name=KD_4tuple; KeyType=KT_4tuple] = ({0xFFF:VlanId1}, {0xFFF:VlanId2}, IPv4Src, IPv4Dst)

Assign[StreamId=0; Descriptor=DYN2] = Key(KD_4tuple)==4

KeyList[KeySet=4; Color=100; KeyType=KT_4tuple] = ( 3, 15, [192.168.0.2], [10.100.1.2])

In the following example, the source and destination MAC address fields are used for key match.

// Define fields for destination and source MAC addresses.
Define MacDsc = Field(Layer2Header[0]/64)
Define MacSrc = Field(Layer2Header[6]/64)

KeyType[name=KT_L2; ColorInfo=True] = {64, 64}
KeyDef[name=KD_L2; KeyType=KT_L2] = ({0xFFFFFFFFFFFF0000:MacDsc}, {0xFFFFFFFFFFFF0000:MacSrc})

Assign[StreamId=0; Descriptor=DYN2] = Key(KD_L2)==4

KeyList[KeySet=4; Color=101; KeyType=KT_L2] = ( 0x000f3d53482d, 0x90b11c3ddada)