This section specifies the syntax and semantics for the setup command. Supported for all feature sets.
The syntax for setup is shown below.
<SetupAction> ::= 'Setup' [ '[' <SetupOptionSpec> ']' ] '=' <SetupCriteriaSpec> <SetupOptionsSpec> ::= <SetupOption> [ ';' <SetupOptionSpec> ] <SetupOption> ::= ( 'NUMANode' '=' <NUMANode> ) | ( 'minHostBufferSize' '=' <MinHostBufferSize> ) | ( 'State' '=' <State> ) | ( 'TxDescriptor' '=' <TxDescriptor> ) | ( 'TxPorts' '=' <PortNumberSpec> ) | ( 'RxPorts' '=' <PortNumberSpec> ) | ( 'TxPortPos' '=' <32-bit decimal value> ) | ( 'TxIgnorePos' '=' <32-bit decimal value> ) | ( 'RxCRC' '=' <TrueFalseValue> ) | ( 'TxMetaData' '=' 'TimeStamp' ) | ( 'UseWL' '=' <TrueFalseValue> ) <SetupCriteriaSpec> ::= ( 'StreamId' '==' <StreamIdSpec> ) <NUMANode> ::= '0' | '1' | '2' | ... | <Number of NUMA Nodes - 1> <MinHostBufferSize> ::= '16' | '17' | '18' | ... | '131072' <State> ::= 'Active' | 'Inactive' <TxDescriptor> ::= 'PCAP' | 'NT' | 'DYN'
The Setup command defines a set of global properties and state for the given streams. The 'Setup' command should be called before 'Assign' commands as the properties of the stream define how a host buffer is selected and the state of the stream. Calling the Setup command, on a stream which is already assigned, with different NUMA node or increased minimum host buffer size parameters, will throw an error. The NUMA node setting for all streams is reset when issuing a "Delete = All" command. Calling the Setup with different state, to activate or inactivate a stream, can be done both before and after an Assign command.
The Setup command is also used to configure inline transmission, where packets received on a stream, can be re-transmitted out of an adapter. Reception and transmission need not take place on the same adapter. There are two transmission scenarios: static and dynamic. In a static setup, packets are only transmitted on one specific port. In a dynamic setup, a bit-field in the packet specifies which port the packet should be transmitted on. In a similar fashion it is possible to specify the position of a single bit in the packet, that indicates whether or not the packet should be transmitted. In order for inline transmission to work, there needs to be an application attached to the streams, to release the individual packets for transmission.
The following parameters controls the inline transmission behaviour:
- TxDescriptor: The descriptor "class" the incoming packets are prepended with.
- TxPorts: The ports that packets can be transmitted on. If a port range is specified (dynamic inline), all ports must be located on the same physical adapter.
- RxPorts: Ports of the receiving adapter(s). If not specified, it is all adapters.
- TxPortPos: Dynamic transmission port selection field offset.
- TxIgnorePos: Dynamic ignore bit offset.
- RxCRC: Specify whether incoming packets include FCS. Defaults to True.
- TxMetaData: Transmitted packets will have meta-data + a new FCS appended to them.
- UseWL: Specify whether wire-length should be used rather than cap-length for length calculations. Requires a descriptor type containing the wire-length field, such as Std or Dyn3.
A static scenario is configured by only specifying one transmission port. A dynamic scenario is configured by specifying multiple transmission ports (e.g. TxPorts=(1..3)) in conjunction with a port selection field position (e.g. TxPortPos=20). Please note and obey the limitation, that all transmission ports must be located on the same physical adapter for dynamic inline.
The "RxPorts" parameter controls what receiving adapters the transmission applies to. This is mostly useful in a qpi-bypass setup.
When using the 'TxMetaData = TimeStamp' option, the receiving timestamp is appended to the packet along with a new FCS, before inline transmission. The appended timestamp is in native UNIX nanosecond format.
Transmission cannot be configured for a stream on a receiving adapter if the stream is already in use on the receiving adapter. Transmission properties are cleared when the "Delete = All" command.
NOTE: When inline transmission is configured for a set of streams, it directly affects how filters can be assigned. It is not possible to assign a filter that distributes packets to both inline and non-inline streams. This must be done in two separate filters.
The "RxCRC" option will affect the slicing of packets captured by filters that distribute packets to inline streams. If "RxCRC" is set to "True", no slicing is allowed and an error will be thrown, if a filter is assigned with slicing. If set to "False", an implicit slicing recipe to remove the FCS on packets will be configured if not explicitly specified in the assign statement. This is however not true if the Key matcher is used to distribute packets to streams. In this case the user must take care to ensure that slicing is correctly configured.
This section describes some examples of using the setup command.
This section describes an example of setting up the NUMA node to use a specific stream and
setting a stream up to use a minimum host buffer size. The example illustrates how to set up stream 12 to use NUMA node 1.
The 'Setup' NTPL example is shown below.
Setup[NUMANode=1] = StreamId==12
The example illustrates how to set up stream 12 to use a minimum host buffer size of 32 MBytes.
The 'Setup' NTPL example is shown below.
Setup[minhostbuffersize=32] = StreamId==12
The minimum host buffer size used by stream 12 will be the smallest host buffer that is equal or larger than 32 MBytes. If no host buffers are found that fulfill this requirement, the assignment will fail.
By default a stream is active and hence can receive data. This can be changed by changing the stream state. The following example sets stream 12 to 'Inactive' state and hence stops the data reception on that stream.
Setup[State=InActive] = StreamId==12
The stream can later be reactivated again with the following command:
Setup[State=Active] = StreamId==12
This example shows how to set up inline transmission to port 1 of all packets coming in on port 0:
Setup[TxDescriptor=Dyn;TxPorts=1] = StreamId == 42
Assign[StreamId=42;Descriptor=Dyn3] = Port == 0
This example demonstrates how to set up transmission of packets to ports based on a field in the packet descriptor. This field can be set by the application when iterating the incoming packets. Alternatively, by using the color field of a descriptor as port selection field, filters could set the color value to indicate the destination port. This example also uses tail slicing to remove the FCS from incoming packets.
Setup[TxDescriptor=Dyn; TxPorts=(0..3); TxPortPos=128; RxCRC=False] = StreamId == 42
Assign[StreamId=42;Slice=EndOfFrame[-4];Descriptor=Dyn3] = Port == (0..3)
TxPortPos is set to 128 which is the offset in bits to the "color_hi" field in the dynamic descriptor 3. The packet will be transmitted on the port number set in the bits at this offset. Due to the dynamic inline limitation of transmission ports, as described earlier, it is a prerequisite that all the transmission ports, 0 to 3, are located on the same physical adapter and if not, an error is thrown.