Flow ID Update in Flow Management API

In flow stream API version 2, the valid range of the id field in the NtFlow_s structure has been reduced from 64 bits to 32 bits. See the summary of the valid ranges in the following table.

Impact on applications:

• Existing applications using IDs ≤ 4294967295: No changes are required. Applications can run on SmartNICs with the new FPGA images (flow stream API version 2) without modification.
• Existing applications using IDs > 4294967295: Applications that use flow IDs greater than 4294967295 must be updated. The id field in the NtFlow_s structure must be set to values within the valid 32-bit range (0 to 4294967295) to comply with flow stream API version 2. If an application attempts to assign an ID outside of this range, the NT_FlowWrite function will return an error.

The flow ID is typically used when a flow is programmed using the NT_FlowWrite function. See API: Learning a Flow in DN-1227. The id field is included in the NtFlow_s structure. The updated structure is defined as follows:

typedef struct NtFlow_s {
  uint8_t keyData[40];     /*!< Raw key data array as defined by the NTPL KeyDef command */
  uint64_t id;             /*!< User defined ID.
                                Valid range for Flow stream API version 1: 0 to 18446744073709551615 (64 bits).
                                Valid range for Flow stream API version 2: 0 to 4294967295 (32 bits). */
  uint32_t color;          /*!< 32-bit flow color */
  uint8_t overwrite:1;     /*!< Enable overwrite filter action */
  uint8_t streamId:7;      /*!< Marks the stream id if overwrite filter action is enabled.
                               Unused if overwrite is not enabled */
  uint8_t ipProtocolField; /*!< Next-protocol field from the IP header. Can be extracted from
                               outer or inner IP header or not at all
                               (see @ref NtplKeyType "KeyType NTPL Command") */
  uint8_t keyId;           /*!< Key ID as used in the @ref NtplKeyType "KeyType NTPL Command" */
  uint8_t keySetId;        /*!< Ket Set id as used in the NTPL filter */
  uint8_t op:4;            /*!< Flow programming operation (0: Unlearn, 1: Learn, 2: Relearn, 3: Probe) */
  uint8_t gfi:1;           /*!< Generate flow info record (1: Generate, 0: Do not generate) */
  uint8_t tau:1;           /*!< TCP auto unlearn (1: Auto unlearn enable, 0: Auto unlearn disable) */

  uint8_t statProf:3;      /*!< Selects profile for Periodic Statistic.
                                Ignored by Flow stream API version 1 */
  uint8_t reserved_a:1;    /*!< Reserved for future use */

  uint8_t scrubProf:3;     /*!< Selects profile for Flow scrubber.
                                Ignored by Flow stream API version 1 */
  uint8_t reserved_b:1;    /*!< Reserved for future use */

  uint8_t infoSuppress:1;  /*!< When set, no flow info record is generated for the unlearn.
                                Only used for unlearn operations. */
  uint8_t reserved_c:7;    /*!< Reserved for future use */
  uint8_t reserved_d[5];   /*!< Reserved for future use */
} NtFlow_t;

This function is defined as follows:

uint32_t NT_FlowGetVersion(NtFlowStream_t hStream)

The function can be called after the flow stream has been opened as illustrated in the following code example.

uint8_t adapterNo = 0;
NtFlowAttr_t flowAttr;
NtFlowStream_t flowStream;
uint32_t flowApiVersion;
int status;

// Initialize flow stream attributes and set adapter number attribute.
NT_FlowOpenAttrInit(&flowAttr);
NT_FlowOpenAttrSetAdapterNo(&flowAttr, adapterNo);

// Opens a flow programming stream and returns a stream handle (flowStream).
status = NT_FlowOpen_Attr(&flowStream, "open_flow_stream_example", &flowAttr);
if(status != NT_SUCCESS) {
    printf("Failed to open flow stream. Error code: %d\n", status);
    return -1;
}

// Get the flow stream API version
flowApiVersion = NT_FlowGetVersion(flowStream);
printf("Flow stream API version: %” PRIu32 ”\n", flowApiVersion);

NT_FlowGetVersion returns 1 for SmartNICs running old FPGA images and 2 for SmartNICs running new FPGA images.