API: Read Flow Info of an Unlearned Flow

When a flow is unlearned i.e. removed from the flow table in the SmartNIC, information about the flow is generated. See Flow unlearning for more information about how a flow can be unlearned. A flow info record includes the following:

• User-defined flow ID.
• Number of bytes and frames received in the flow.
• RX time stamp of the last frame in the flow.
• Union of all TCP flags observed over the life of the flow.
• Cause of the flow unlearning.

A flow info record can be retrieved using the NT_FlowRead function with the NtFlowInfo_s structure. NtFlowInfo_s is defined as follows:

typedef struct NtFlowInfo_s {
  uint64_t packetsA;/*!< Packet counter for set A */
  uint64_t octetsA; /*!< Byte/octet counter for set A */
  uint64_t packetsB;/*!< Packet counter for set B */
  uint64_t octetsB; /*!< Byte/octet counter for set B */
  uint64_t ts;      /*!< Time stamp in UNIX_NS format of last seen packet */
  uint64_t id;      /*!< The 64-bit user-defined ID from the flow programming operation */
  uint16_t flagsA;  /*!< Bitwise OR of TCP flags for packets in set A */
  uint16_t flagsB;  /*!< Bitwise OR of TCP flags for packets in set B */
  uint8_t cause;    /*!< Unlearn cause (0: Software, 1: Timeout, 2: TCP flow termination */
} NtFlowInfo_t;

Two counter sets, A and B are supported. Two separate counter sets can be utilized handling counters for upstream traffic and downstream traffic individually for example. NtFlowInfo_s contains values for both counter sets. By default counter set A is used. It can be configured which counter set to be used using NTPL as shown in the following example.

Assign[StreamId=(0..3); Color=0; Descriptor=DYN4, ColorBits=FlowID] = Upstream and \\
 Key(kd, KeyID=1, CounterSet=CSA) == 4
Assign[StreamId=(0..3); Color=0; Descriptor=DYN4, ColorBits=FlowID] = Downstream and \\
 Key(kd, KeyID=1, FieldAction=Swap, CounterSet=CSB) == 4

In this example, counter set A is used for upstream traffic and counter set B is used for downstream traffic. See the full NTPL command example and descriptions in Flow Management over Network TAP Configuration.

The cause field contains what caused the flow unlearning operation. The returned value is one of the following:

• 0: Unlearned by NT_FlowWrite in the application.
• 1: Unlearned due to a timeout event because the flow was inactive during the defined period. The time can be configured using the FlowTimeOut parameter in /opt/napatech3/config/ntservice.ini. The default value is 120000 milliseconds as shown in the following example.

  FlowTimeOut = 120000 # 0 .. 4294967295

  Note: Set FlowTimeOut to 0 to disable the timeout feature.
• 2: Unlearned automatically when the TCP session was terminated. This applies to a TCP flow if the tau field of NtFlow_s was set to 1 when the flow was learned. See API: Learn a Flow.

The following code snippet shows how to read flow info records of unlearned flows.

  NtFlowInfo_t   flowInfo;

  // For each element in the flow stream queue, print the flow info record.
  while(NT_FlowRead(flowStream, &flowInfo, 0) == NT_SUCCESS) {
    std::cout << "NT_FlowRead of flow ID " << flowInfo.id << std::endl
      << "CSA: Packages: " << flowInfo.packets_a
      << ", Octets: "      << flowInfo.octets_a << std::endl
      << "CSB: Packages: " << flowInfo.packets_b
      << ", Octets: "      << flowInfo.octets_b << std::endl
      << "Time stamp: "    << flowInfo.ts << std::endl
      << "TCP flags A: "   << flowInfo.flags_a
      << ", TCP flags B: " << flowInfo.flags_b << std::endl;

    switch(flowInfo.cause) {
      case 0:  std::cout << "Unlearn cause: Software"             << std::endl; break;
      case 1:  std::cout << "Unlearn cause: Timeout"              << std::endl; break;
      case 2:  std::cout << "Unlearn cause: TCP flow termination" << std::endl; break;
      default: std::cout << "Unlearn cause: Not supported"        << std::endl; break;
    }
  }

After a flow is unlearned, the SmartNIC delivers the flow info record to the host. Up to 65536 records can be stored in the host memory. If the host memory is full, new records from the SmartNIC will be dropped. It is therefore good practice calling NT_FlowRead until no more records are available as shown in this example.