API: Classify Received Frames

Stateful Flow Management

Platform
Napatech SmartNIC
Content Type
User Guide
Capture Software Version
Link™ Capture Software 12.9

Use this example to classify received frames based on the color information.

Packet coloring

Received frames can be classified using the packet coloring feature so that frames can be handled individually in the application. The Color parameter is used in the Network TAP NTPL example and the SPAN port NTPL example. The following Color values are configured in the NTPL examples.
  • Color=0: The flow is found in the flow table (hit).
  • Color=1: The flow is not found in the flow table (missed).
  • Color=2: The lookup was not performed (unhandled).

Dynamic descriptor 4

The 8-bit Color0 field of dynamic packet descriptor 4 contains the color value. Dynamic descriptor 4 is defined as follows:
typedef struct NtDyn4Descr_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 color0:8;     /**< Programmable packet color[8:0].                               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 color1;       /**< Programmable packet color[31:0] and hash[63:32].             128*/
} NtDyn4Descr_t; // descrFormat = 4, default descrLength = 24                         192 bits*/

Classifying RX packets

The following code snippet illustrates how to handle received frames based on the color information.
  int status;
  NtNetStreamRx_t net_stream;
  NtNetBuf_t      net_buffer;
  // Open RX stream
  status = NT_NetRxOpen(&net_stream, "flow_learn NT_NetRxOpen", NT_NET_INTERFACE_PACKET, stream_id, -1);
  handle_error_status(status, "NT_NetRxOpen() failed");
  // Tell main function that this is ready to receive frames, and then start the loop.
  ready->fetch_add(1);
  while (!end_task->load()) {
    // Get next packet or continue.
    status = NT_NetRxGetNextPacket(net_stream, &net_buffer, 100);
    if (status == NT_STATUS_TIMEOUT || status == NT_STATUS_TRYAGAIN) continue;
    handle_error_status(status, "NT_NetRxGetNextPacket() failed");
    // Call a handle function based on the color value.
    const NtDyn4Descr_t* dyn4 = NT_NET_GET_PKT_DESCR_PTR_DYN4(net_buffer);
    switch(dyn4->color0) {
      case 0: handle_hit(net_buffer);       // User-defined function to process known flows.
        break;
      case 1: handle_missed(net_buffer);    // User-defined function to process unknown flows.
        break;
      case 2: handle_unhandled(net_buffer); // User-defined function to process unhandled flows.
        break;
      default:
        count << "Color does not match any case.";
        break;
    }
  }
  // Close the RX stream.
  status = NT_NetRxClose(net_stream);
  handle_error_status(status, "NT_NetRxClose() failed");