API: Read Flow Learn/Unlearn Result

Stateful Flow Management

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

Use this example to handle a flow status record.

NtFlowStatus_s structure

Whenever NT_FlowWrite is called, the SmartNIC delivers information whether the learning/unlearning operation is successful, failed or ignored. This information can be retrieved calling the NT_FlowStatusRead function with the NtFlowStatus_s structure. NtFlowStatus_s is defined as follows:
typedef struct NtFlowStatus_s {
  uint64_t id;    /*< 64-bit  user-defined flow id */
  uint32_t flags; /*< Flags indicating the status of the operation */
} NtFlowStatus_t;
You can identify the associated flow using the id field which is programmed when learning the flow. See Programming Key ID, key set ID and flow ID.

Learning/unlearning status

The flags field of NtFlowStatus_s indicates one of the following status:
  • LearnDone: The learning operation is successful.
  • LearnFail: The learning operation is failed.
  • LearnIgnore: The learning operation is ignored because the flow already exists in the flow table.
  • UnlearnDone: The unlearning operation is successful.
  • UnlearnIgnore: The unlearning operation is ignored because the flow doesn't exists in the flow table.
Generating each status can be enabled/disabled individually in the /opt/napatech3/config/ntservice.ini file. The following configuration shows the available parameters and the default values in the ntservice.ini file.
FlowStatusLearnDone = false              # true/false
FlowStatusLearnFail = true               # true/false
FlowStatusLearnIgnore = true             # true/false
FlowStatusUnlearnDone = false            # true/false
FlowStatusUnlearnIgnore = true           # true/false
See DN-0449 for detailed information about the parameters in the ntservice.ini file.

Read flow learning/unlearning result

The following code snippet shows how to read the flow learning/unlearning status. A returned status is an asynchronous result for an NT_FlowWrite.
  NtFlowStatus_t flowStatus;

  // For each element in the flow stream queue, print the flow status record.
  while(NT_FlowStatusRead(flowStream, &flowStatus) == NT_SUCCESS) {
    std::cout << "Flow status for ID " << flowStatus.id;

    // The flags returned from NT_FlowStatusRead depend on ntservice.ini settings.
    switch(flowStatus.flags) {
      case NT_FLOW_STAT_LDS: std::cout << " Flow learn successfully done." << std::endl; break;
      case NT_FLOW_STAT_LFS: std::cout << " Flow learn failed." << std::endl; break;
      case NT_FLOW_STAT_LIS: std::cout << " Flow learn ignored. Flow already exists." << std::endl; break;
      case NT_FLOW_STAT_UDS: std::cout << " Flow unlearn successfully done." << std::endl; break;
      case NT_FLOW_STAT_UIS: std::cout << " Flow unlearn ignored. Flow does not exists." << std::endl; break;
      default:               std::cout << " Unknown flag"     << std::endl; break;
    }
  }
Up to 256 records can be stored in the host memory. If 256 records are full and standing by to be read by the application, new records from the SmartNIC will be dropped. It is therefore good practice calling NT_FlowStatusRead until no more records are available as shown in this example.
Note: If receiving the flow status records is not needed, it is recommended to disable in ntservice.ini.
Note: Flow status records are read from the same flow stream that originally learned the flows.