Packet Descriptors

Feature Set N-ANL11

Intel® PAC
Napatech SmartNIC
Feature Description

In this chapter

This chapter describes the packet descriptors used in the interaction between the host and the SmartNIC.


Captured frames are always prepended with a packet descriptor, which can be either a standard descriptor, a dynamic descriptor or a PCAP descriptor (see Illustration of a packet descriptor). If the packet descriptor is a standard descriptor, the frame can also be prepended with an extended descriptor 9 (see Illustration of an extended descriptor 9). Packet descriptors are described in detail in DN-0449.

The standard and extended descriptors contain predefined fields with protocol-specific information. RX information from these packet descriptors can be retrieved and TX parameters can be set using HAL (hardware abstraction layer) macros (see DN-0449).

The dynamic descriptors contain no predefined protocol-specific information. A number of configurable fields contain dynamic offsets into the captured packet, and one or two color fields can be used to classify the packet and otherwise store any useful information about the packet. The application retrieves RX information directly from the packet descriptor, and it is up to the application to use the offsets and interpret the color values correctly.

Illustration of a packet descriptor

This figure shows frames with different packet descriptors.

Frame with PCAP / standard descriptor or dynamic descriptors

Illustration of an extended descriptor 9

This figure shows a frame with a standard packet descriptor and an extended descriptor 9.

Frame with a standard descriptor and extended descriptor

Selecting packet descriptors

Packet descriptors can be set up per filter in NTPL using descriptor recipes (see DN-0449). This is an example of an Assign command for a port filter:

Assign[StreamId = 42; Descriptor = Dyn3] = Port == 0
If a packet descriptor is specified for a filter, matching frames that are captured by the filter are prepended with this descriptor. Other frames are prepended with a default packet descriptor specified per SmartNIC in the PacketDescriptor parameter in the ntservice.ini file (see DN-0449).
Note: Dynamic packet descriptors can only be specified per filter and not as default.

This table shows the values the PacketDescriptor parameter can take.

Value Description
PCAP Frames are only prepended with a PCAP packet descriptor by default.
NT Frames are only prepended with a standard packet descriptor by default. This is the default setting.
Ext9 Frames are prepended with a standard packet descriptor as well as extended packet descriptor 9 (24 bytes) by default.

Specifying dynamic packet descriptors

For dynamic packet descriptors a number of user-definable offsets, a number of color bits and the length of the descriptor can be defined in the descriptor recipe. The offsets are contained in the dynamic packet descriptors and can be used by an application to point to a location in the frames. The number of color bits can be used for controlling how many bits in the color fields of the dynamic packet descriptors are actually used for a color value and how many bits are available for a hash value or for a correlation value. The Length parameter can be used both for reducing the length of the RX descriptor as well as for adding user data to the RX descriptor.

This example reduces the length of the RX descriptor:

Assign[StreamId = 42; Descriptor = Dyn3, Length = 16] = Port == 0

This example adds 4 bytes to the descriptor, which can be used, for instance, for inserting a VLAN ID in the frame (see In-Line Functionality):

Assign[StreamId = 42; Descriptor = Dyn3, Length = 26] = Port == 0

The Length parameter can take values from 16 to 62 bytes. Line rate transfer is guaranteed for all supported SmartNICs for packet descriptors with a length smaller than or equal to 20 bytes.

Dynamic descriptor types

These dynamic descriptors are available:

  • Dynamic descriptor 1
  • Dynamic descriptor 2
  • Dynamic descriptor 3
  • Dynamic descriptor 4
Note: Dynamic descriptor 4 is not supported for NT40A01-4×10/1-SLB.

Dynamic descriptors 1 and 2 are especially suitable for netflow and IDS (intrusion detection system) applications, while dynamic descriptor 3 is especially suitable for TX applications, and dynamic descriptor 4 is especially suitable for packet correlation applications.

The first 8 bytes of dynamic descriptor 3 contains the wire length of the frame and 4 color bits, while the next 8 bytes contain the time stamp. This enables applications to reduce the frame size before TX by modifying the wire length and to reduce the descriptor length to 16 bytes while retaining the time stamp as well as the possibility of encoding TX flags into the color bits, for instance for the frame to ignore TX.

In dynamic packet descriptor 2, the 32, 24 or 16 MSBs (most significant bits) of the color field may optionally contain a hash value. In dynamic packet descriptor 3, the color_hi field may optionally contain a hash value. In dynamic packet descriptor 4, the color1 field may optionally contain a 64-bit correlation key value. See DN-0449 for more details.

Restrictions on the standard descriptor

Note: These fields in the standard descriptor are 1 if a frame matches the protocol in question irregardless of whether the checksum is correct, since IP, UDP and TCP checksum verification is not supported:
  • TCPCsumOk
  • UDPCsumOk
  • IPCsumOk
Note: These fields in the standard descriptor are ignored at TX:
  • crcError
  • txCrcOverride
  • cvError
  • txSetClock
  • frameSliced
  • extensionLength
  • extensionFormat

A correct FCS is always recalculated at TX.

Restrictions on the extended descriptor 9

Note: These RX fields in the extended descriptor 9 are always 0, since the associated features are not supported:
  • decodeError
  • innerDecodeError
Note: No TX fields are supported.

Restrictions on the PCAP packet descriptor

Use of PCAP packet descriptors is restricted as follows:

  • PCAP descriptors are supported on the segment-based interface only. If PCAP is selected in the PacketDescriptor parameter (see Selecting packet descriptors), the packet-based interface will fail. As a consequence, the osmode tool and the latency tool will fail (see DN-0449).
  • The throughput tool (see DN-0449) only works when executed with the --pcap argument.
  • When PCAP is selected in the PacketDescriptor parameter, TimestampFormat in the ntservice.ini file (see DN-0449) must be set to PCAP or PCAP_NS, and vice versa. This means that all or no SmartNICs must have PacketDescriptor set to PCAP, since the TimestampFormat parameter is a global parameter.
    Note: A consequence of using PCAP or PCAP_NS time stamp format is that there is no support for SmartNIC merging.
  • The PCAP descriptor uses a 32-bit timeval structure. This must be taken into consideration by 64-bit host applications.