Flow Stream

Reference Documentation

Platform
Intel® PAC
Napatech SmartNIC
Content Type
Reference Information
Napatech Software Suite: Flow Stream

Detailed Description

Flow streams are used to program and delete flows as well as receiving flow status and information records on adapters that support stateful flow tracking.

A flow stream must be opened before flows can be programmed. This is accomplished with the NT_FlowOpen_Attr functions which takes a NtFlowAttr_t attribute structure and returns a handle to the flow stream.

Three types of records can be present in a flow stream:

NtFlow_t records for flow programming using NT_FlowWrite

NtFlowInfo_t records with flow information read using NT_FlowRead. These records are only generated if flow programming sets the gfi bit.

NtFlowStatus_t records with async flow programming result read using NT_FlowStatusRead. Generation of these records depends on ntservice.ini settings.

To ensure optimal performance an application that both wishes to read and write flows should alternate between NT_FlowWrite, NT_FlowRead and NT_FlowStatusRead.

Functions

void NT_FlowOpenAttrInit (NtFlowAttr_t *attr)
 Initialize flow stream attributes. More...
 
void NT_FlowOpenAttrSetAdapterNo (NtFlowAttr_t *attr, uint8_t adapterNo)
 Set adapter number attribute. More...
 
uint8_t NT_FlowOpenAttrGetAdapterNo (NtFlowAttr_t *attr)
 Return the adapter number attribute. More...
 
void NT_FlowOpenAttrSetFlags (NtFlowAttr_t *attr, uint32_t flags)
 Set flow stream flags. More...
 
uint32_t NT_FlowOpenAttrGetFlags (NtFlowAttr_t *attr)
 Get flow stream flags. More...
 
int NT_FlowOpen_Attr (NtFlowStream_t *hStream, const char *name, NtFlowAttr_t *attr)
 Opens a flow programming stream and returns a stream handle. More...
 
int NT_FlowClose (NtFlowStream_t hStream)
 Closes a flow stream. More...
 
int NT_FlowWrite (NtFlowStream_t hStream, NtFlow_t *flow, int timeout)
 Programs a flow into an adapter. More...
 
int NT_FlowRead (NtFlowStream_t hStream, NtFlowInfo_t *info, int timeout)
 Read a flow information record. More...
 
int NT_FlowStatusRead (NtFlowStream_t hStream, NtFlowStatus_t *status)
 Read a flow status record. More...
 

Data Structures

struct  NtFlow_s
 Flow programming structure. More...
 
struct  NtFlowInfo_s
 Flow information structure. More...
 
struct  NtFlowStatus_s
 Flow status structure. More...
 

Macros

#define NT_FLOW_STAT_LDS   0x1 /*< Learn done status flag */
 
#define NT_FLOW_STAT_LFS   0x2 /*< Learn fail status flag */
 
#define NT_FLOW_STAT_LIS   0x4 /*< Learn ignore status flag */
 
#define NT_FLOW_STAT_UDS   0x8 /*< Un-learn done status flag */
 
#define NT_FLOW_STAT_UIS   0x10 /*< Un-learn ignore status flag */
 

Typedefs

typedef struct NtFlowStream_s * NtFlowStream_t
 
typedef struct NtFlow_s NtFlow_t
 Flow programming structure. More...
 
typedef struct NtFlowInfo_s NtFlowInfo_t
 Flow information structure. More...
 
typedef struct NtFlowStatus_s NtFlowStatus_t
 Flow status structure. More...
 

Data Structure Documentation

struct NtFlow_s

Flow programming structure.

This structure is used when programming flows with the NT_FlowWrite function.

Definition at line 88 of file stream_flow.h.

Data Fields

uint8_t keyData [40]
 
uint64_t id
 
uint32_t color
 
uint8_t overwrite:1
 
uint8_t streamId:7
 
uint8_t ipProtocolField
 
uint8_t keyId
 
uint8_t keySetId
 
uint8_t op:4
 
uint8_t gfi:1
 
uint8_t tau:1
 

Field Documentation

uint8_t NtFlow_s::keyData[40]

Raw key data array as defined by the NTPL KeyDef command

Definition at line 89 of file stream_flow.h.

uint64_t NtFlow_s::id

64-bit user defined ID

Definition at line 90 of file stream_flow.h.

uint32_t NtFlow_s::color

32-bit flow color

Definition at line 91 of file stream_flow.h.

uint8_t NtFlow_s::overwrite

Enable overwrite filter action

Definition at line 92 of file stream_flow.h.

uint8_t NtFlow_s::streamId

Marks the stream id if overwrite filter action is enabled. Unused if overwrite is not enabled

Definition at line 93 of file stream_flow.h.

uint8_t NtFlow_s::ipProtocolField

Next-protocol field from the IP header. Can be extracted from outer or inner IP header or not at all (see KeyType NTPL Command)

Definition at line 95 of file stream_flow.h.

uint8_t NtFlow_s::keyId

Key ID as used in the KeyType NTPL Command

Definition at line 98 of file stream_flow.h.

uint8_t NtFlow_s::keySetId

Ket Set id as used in the NTPL filter

Definition at line 99 of file stream_flow.h.

uint8_t NtFlow_s::op

Flow programming operation (1: learn, 0: un-learn)

Definition at line 100 of file stream_flow.h.

uint8_t NtFlow_s::gfi

Generate flow info record (1: generate, 0: do not generate)

Definition at line 101 of file stream_flow.h.

uint8_t NtFlow_s::tau

TCP auto unlearn (1: auto unlearn enable, 0: auto unlearn disable)

Definition at line 102 of file stream_flow.h.

struct NtFlowInfo_s

Flow information structure.

This structure contains state for a particular flow. If flow programming had the gfi bit set, the flow information structure is returned on the flow stream when the flow is terminated or timed out.

Definition at line 112 of file stream_flow.h.

Data Fields

uint64_t packetsA
 
uint64_t octetsA
 
uint64_t packetsB
 
uint64_t octetsB
 
uint64_t ts
 
uint64_t id
 
uint16_t flagsA
 
uint16_t flagsB
 
uint8_t cause
 

Field Documentation

uint64_t NtFlowInfo_s::packetsA

Packet counter for set A

Definition at line 113 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

uint64_t NtFlowInfo_s::octetsA

Byte/octet counter for set A

Definition at line 114 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

uint64_t NtFlowInfo_s::packetsB

Packet counter for set B

Definition at line 115 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

uint64_t NtFlowInfo_s::octetsB

Byte/octet counter for set B

Definition at line 116 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

uint64_t NtFlowInfo_s::ts

Time stamp in UNIX_NS format of last seen packet

Definition at line 117 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

uint64_t NtFlowInfo_s::id

The 64-bit user defined ID from the flow programming operation

Definition at line 118 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

uint16_t NtFlowInfo_s::flagsA

Bitwise OR of TCP flags for packets in set A

Definition at line 119 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

uint16_t NtFlowInfo_s::flagsB

Bitwise OR of TCP flags for packets in set B

Definition at line 120 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

uint8_t NtFlowInfo_s::cause

Unlearn cause (0: Software, 1: Timeout, 2: TCP flow termination

Definition at line 121 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

struct NtFlowStatus_s

Flow status structure.

This structure contains the status for a particular flow (Un-)learning operation. A series of flags indicates whether the operation was successful or not.

Definition at line 138 of file stream_flow.h.

Data Fields

uint64_t id
 
uint32_t flags
 

Field Documentation

uint64_t NtFlowStatus_s::id

Definition at line 139 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

uint32_t NtFlowStatus_s::flags

Definition at line 140 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

Function Documentation

void NT_FlowOpenAttrInit ( NtFlowAttr_t *  attr)

Initialize flow stream attributes.

See NT_FlowOpen_Attr for further description

Parameters
attrPointer to the attributes structure

Referenced by taskReceiverMiss().

void NT_FlowOpenAttrSetAdapterNo ( NtFlowAttr_t *  attr,
uint8_t  adapterNo 
)

Set adapter number attribute.

Parameters
attrPointer to the attributes structure
adapterNoAdapter number the stream should be associated to

Referenced by taskReceiverMiss().

uint8_t NT_FlowOpenAttrGetAdapterNo ( NtFlowAttr_t *  attr)

Return the adapter number attribute.

See NT_FlowOpen_Attr for further description

Returns
The adapter number attribute
void NT_FlowOpenAttrSetFlags ( NtFlowAttr_t *  attr,
uint32_t  flags 
)

Set flow stream flags.

Currently no flags are defined so calls of this function shall be avoided

Parameters
attrPointer to attriute structure
flagsFlow stream flags
uint32_t NT_FlowOpenAttrGetFlags ( NtFlowAttr_t *  attr)

Get flow stream flags.

Parameters
attrPointer to attriute structure
Returns
Flow stream flags
int NT_FlowOpen_Attr ( NtFlowStream_t hStream,
const char *  name,
NtFlowAttr_t *  attr 
)

Opens a flow programming stream and returns a stream handle.

This function opens a flow stream which is used for fast programming of the flow matcher present on adapters that support the flow matching feature. A flow stream should only be opened after all relevant NTPL statements configuring the flow matcher has been executed.

The default sequence for opening a flow stream is:

NtFlowAttr_t attr;

NT_FlowOpenAttrInit(&attr);

NT_FlowOpenAttrSetAdapterNo(&attr, adapter_no);

int status = NT_FlowOpen_Attr(&_stream, "name", &attr);

Parameters
[out]hStreamReference to the NtFlowStream_t stream pointer
[in]nameName of the stream
[in]attrPointer to the flow stream attributes

Referenced by taskReceiverMiss().

int NT_FlowClose ( NtFlowStream_t  hStream)

Closes a flow stream.

This function closes and frees resources belonging to a flow stream

Parameters
[in]hStreamFlow stream handle to be closed
Return values
NT_SUCCESSSuccess
!=NT_SUCCESSError - use NT_ExplainError for an error description

Referenced by taskReceiverMiss().

int NT_FlowWrite ( NtFlowStream_t  hStream,
NtFlow_t flow,
int  timeout 
)

Programs a flow into an adapter.

This function is used to program flows into the adapter associated with the stream handle. The flow data must be written into the NtFlow_t structure by the caller before calling this function.

Returns NT_ERROR_INVALID_PARAMETER if NtFlow_t:

  • tau = 1 and gfi = 0
  • overwrite is set and any of 7 most significant bit in color is set
  • overwrite is not set but streamId is different from 0
Parameters
[in]hStreamThe flow stream handle obtained in NT_FlowOpen_Attr
[in]flowPointer to the flow data structure
[in]timeoutTimeout in ms before failing to program the flow (-1 = retry indefinitely)
Return values
NT_SUCCESSThe flow was successfully programmed
!=NT_SUCCESSError - use NT_ExplainError for an error description

Referenced by taskReceiverMiss().

int NT_FlowRead ( NtFlowStream_t  hStream,
NtFlowInfo_t info,
int  timeout 
)

Read a flow information record.

This function will attempt to read a flow information record. If a record is available in the stream it will be returned in the record pointed to by "info".

Parameters
[in]hStreamThe flow stream handle obtained in NT_FlowOpen_Attr
[out]infoPointer to flow info structure the record is returned in
[in]timeoutTimeout in ms before failing to program the flow (-1 = retry indefinitely)
Return values
NT_SUCCESSA flow information record was successfully read
!=NT_SUCCESSError - use NT_ExplainError for an error description

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

int NT_FlowStatusRead ( NtFlowStream_t  hStream,
NtFlowStatus_t status 
)

Read a flow status record.

This function will attempt to read a flow status record. A status record is an async result response for an NT_FlowWrite. If a record is available in the stream it will be returned in the record pointed to by "status".

There are 5 types of status records:

LearnDone which signals a succesful flow program operation

LearnFail which signals an unsuccesful flow program operation

LearnIgnore which signals an ignored flow program operation (flow already exists)

UnlearnDone which signals a succesful flow unlearn operation

UnlearnIgnore which signals an ignored flow unlearn operation (flow doesn't exists)

Generation of status records can be enabled/disabled individually in ntservice.ini

Parameters
[in]hStreamThe flow stream handle obtained in NT_FlowOpen_Attr
[out]statusPointer to flow status structure the record is returned in
Return values
NT_SUCCESSA flow status record was successfully read
NT_STATUS_TRYAGAINNo flow status records available at this time
!=NT_SUCCESSError - use NT_ExplainError for an error description

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

Macro Definition Documentation

#define NT_FLOW_STAT_LDS   0x1 /*< Learn done status flag */

Definition at line 125 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

#define NT_FLOW_STAT_LFS   0x2 /*< Learn fail status flag */

Definition at line 126 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

#define NT_FLOW_STAT_LIS   0x4 /*< Learn ignore status flag */

Definition at line 127 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

#define NT_FLOW_STAT_UDS   0x8 /*< Un-learn done status flag */

Definition at line 128 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

#define NT_FLOW_STAT_UIS   0x10 /*< Un-learn ignore status flag */

Definition at line 129 of file stream_flow.h.

Referenced by anonymous_namespace{flowmatch_example_receiver.cpp}::printFlowStreamInfo().

Typedef Documentation

typedef struct NtFlowStream_s* NtFlowStream_t

Flow stream handle

Definition at line 71 of file stream_flow.h.

typedef struct NtFlow_s NtFlow_t

Flow programming structure.

This structure is used when programming flows with the NT_FlowWrite function.

typedef struct NtFlowInfo_s NtFlowInfo_t

Flow information structure.

This structure contains state for a particular flow. If flow programming had the gfi bit set, the flow information structure is returned on the flow stream when the flow is terminated or timed out.

Flow status structure.

This structure contains the status for a particular flow (Un-)learning operation. A series of flags indicates whether the operation was successful or not.