Packet Descriptors

Feature Set N-ANL9

Napatech SmartNIC
Content Type
Feature Description
Capture Software Version

In this chapter

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


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). 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 value correctly.

Illustration of a packet descriptor

This figure shows frames with different packet descriptors.

Page-1 Process.4 PCAP or Standard Descriptor PCAP or Standard Descriptor Process.6 Frame Frame Sheet.3 Sheet.4 16 bytes 16 bytes Sheet.5 Sheet.6 Sheet.7 Sheet.8 0 - maximum frame size bytes 0 - maximum frame size bytes Sheet.9 Process.10 Dynamic Descriptor 1 Dynamic Descriptor 1 Process.11 Frame Frame Sheet.12 Sheet.13 18 bytes by default 18 bytes by default Sheet.14 Sheet.15 Sheet.16 Sheet.17 0 - maximum frame size bytes 0 - maximum frame size bytes Sheet.18 Process.19 Dynamic Descriptor 2 or 3 Dynamic Descriptor 2 or 3 Process.20 Frame Frame Sheet.21 Sheet.22 22 bytes by default 22 bytes by default Sheet.23 Sheet.24 Sheet.25 Sheet.26 0 - maximum frame size bytes 0 - maximum frame size bytes Sheet.27

Illustration of an extended descriptor

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

Page-1 Process.41 Standard Descriptor Standard Descriptor Process.2 Extended Descriptor 9 Extended Descriptor 9 Process.29 Frame Frame Sheet.4 Sheet.5 16 bytes 16 bytes Sheet.6 Sheet.7 Sheet.8 Sheet.9 Sheet.10 Sheet.11 24 bytes 24 bytes Sheet.12 0 - maximum frame size bytes 0 - maximum frame size bytes Sheet.13

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
  • txNow
  • extensionLength
  • extensionFormat

A correct FCS is always recalculated at TX, and frames are always sent immediately.

Extended descriptors

Extended descriptor 9 is available.

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

Dynamic descriptors

These dynamic descriptors are available:

  • Dynamic descriptor 1
  • Dynamic descriptor 2
  • Dynamic descriptor 3
Note: Dynamic descriptor 3 is not supported for NT200A01-2×100 and NT200A01-2×100/40 running at 2 × 100 Gbit/s.

Among other fields the dynamic packet descriptors contain a number of user-definable offsets, which are specified using NTPL, and which can be used by an application to point to a location in the frames. They also contain one or two color fields. In dynamic packet descriptor 2, only the 14 LSBs (least significant bits) of the color field contain the color, while the 24 MSBs (most significant bits) contain a hash value. See DN-0449 for more details. 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. The first 8 bytes of this descriptor 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.

When specifying a dynamic descriptor in an Assign command, the length of the RX descriptor can be specified as well as the user-definable offsets. This example reduces the length of the RX descriptor:

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

The Length parameter can also be used for adding user data to the RX descriptor when using dynamic descriptor 3. 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 accelerators for packet descriptors with a length smaller than or equal to 20 bytes.

Selecting packet descriptors

Packet descriptors can be set up per filter using NTPL (see DN-0449). A default packet descriptor can be specified per accelerator in the PacketDescriptor parameter in the ntservice.ini file (see DN-0449). 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 the default packet descriptor specified in the ntservice.ini file.
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.
NT Frames are only prepended with a standard packet descriptor. This is the default setting.
Ext9 Frames are prepended with a standard packet descriptor as well as extended packet descriptor 9 (24 bytes).

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 accelerators 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 accelerator merging.
  • The PCAP descriptor uses a 32-bit timeval structure. This must be taken into consideration by 64-bit host applications.