In this chapter
This chapter describes the packet descriptors used in the interaction between the host and the SmartNIC.
Introduction
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.
Illustration of an extended descriptor 9
This figure shows a frame with a standard packet descriptor and an extended descriptor 9.
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
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
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 or id data specified in flow learn records. See DN-0449 for more details.
Restrictions on the standard descriptor
- TCPCsumOk
- UDPCsumOk
- IPCsumOk
- crcError
- txCrcOverride
- cvError
- txSetClock
- frameSliced
- extensionLength
- extensionFormat
A correct FCS is always recalculated at TX.
Restrictions on the extended descriptor 9
- decodeError
- innerDecodeError
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.