The NL2TransmitTestApp sample provides a simple Network Link Layer (NL2) sample application that demonstrates various NL2 APIs for packet transmission. It provides a flexible framework for testing your network setup or customizing to experiment with different aspects of the NL2 and the NIC drivers.
By default, when only the mandatory /etype parameter is provided, the application uses the first Physical Transmit Queue on the specified interface. It transmits packets from that queue as quickly as possible to minimize the gap between consecutive packets. It also prints statistics about the achieved transmission throughput during the process.
Setup Considerations
By default, this sample runs on the system default RTSS processor with a default priority, which is CPU intensive. On wRTOS systems, if the system default RTSS processor is the first processor, and if this processor is occupied by another application, communication between Windows and RTSS—occurring at a lower priority—may starve, causing the system to appear hung.
To avoid this, do the following:
- Open wRTOS Settings and navigate to the Network Link Layer (NL2) page.
- Change the Management thread core value to a different core.
Typical Usage
To continuously transmit as fast as possible, use the following command line:
rtssrun NL2TransmitTestApp MyNicName /q 1 /mac 00:11:22:33:44:55 /etype 0x1234 /pktlen 60 /p 7 /y 40 /report 20000
This instructs NL2TransmitTestApp to continuously transmit packets through Physical Transmit Queue 1 of interface MyNicName. The packets are sent from a thread running on processor 7 with priority 40. All transmitted packets use 00:11:22:33:44:55 as the Destination MAC Address, 0x1234 as the EtherType, and have a length of 60 bytes, including the 14-byte Ethernet header but excluding the 4-byte FCS. Every 20,000 packets transmitted, the application prints a report with the achieved throughput and the observed intervals between Transmit events.
Details:
MyNicName
The name of the NIC to be used by the application.
/q 1
Specifies the Physical Transmit Queue to be used.
/mac 00:11:22:33:44:55 S
Specifies the Destination MAC Address of the packets to be transmitted
/etype 0x1234
Specifies the EtherType of the packets to be transmitted.
/pktlen 60
Specifies the length of the packets to be transmitted (this includes the 14-byte Ethernet header but not the 4-byte FCS).
/p 7
Specifies the ideal processor used by the Transmit thread.
/y 40
Specifies the priority of the Transmit thread.
/report 20000
Specifies that the application shall print a report every 20000 packets transmitted.
Transmitting Frames with a VLAN Tag
By default, the application transmits untagged Ethernet frames. You can ask it to transmit 802.1Q-tagged frames using this command:
rtssrun NL2TransmitTestApp MyNicName /etype 0x1234 /vid 2 /dei 0 /pcp 3
This instructs NL2TransmitTestApp to continuously transmit packets through Physical Transmit Queue 0 (default) of interface MyNicName. The packets are sent from a thread running on the system default real-time processor (default) with 0 (default). All transmitted packets use ff:ff:ff:ff:ff:ff (default) as Destination MAC Address, 0x1234 as EtherType, and have a length of 1514 bytes (default, which includes the 14-byte Ethernet header and the payload, but not the 4-byte VLAN Tag and not the 4-byte FCS). The 4-byte VLAN Tag is inserted on the fly in every transmitted packet by the hardware. Every 100000 packets transmitted (default), the application prints a report with the achieved throughput and with the observed intervals between Transmit events.
Details:
MyNicName
The name of the NIC to be used by the application.
/etype 0x1234
The EtherType of the packets to be transmitted
/vid 2
Specifies the value of the VLAN ID field in the inserted VLAN Tags.
/dei 0
Specifies the value of the DEI field in the inserted VLAN Tags
/pcp 3
Specifies the value of the PCP field in the inserted VLAN Tags
Note: VLAN Tags are inserted in the transmitted frames if, and only if, at least one of the three parameters /vid, /dei, or /pcp is specified on the command line.
Transmitting Frames at a Rate Determined by the Credit-Based Shaper
If transmitting through a Physical Transmit Queue that uses the Credit-Based Shaper, you can specify the amount of bandwidth to allocate to that queue, as follows:
rtssrun NL2TransmitTestApp MyNicName /etype 0x1234 /bw 50000
This instructs NL2TransmitTestApp to continuously transmit packets through Physical Transmit Queue 0 (default) of interface MyNicName. The packets are sent from a thread running on the system default real-time processor (default) with 0 (default). All transmitted packets use ff:ff:ff:ff:ff:ff (default) as Destination MAC Address, 0x1234 as EtherType, and have a length of 1514 bytes (default, which includes the 14-byte Ethernet header and the payload, but not the 4-byte FCS). The hardware ensures that no more than 50000 Kbps (50 Mbps) is used by the acquired Physical Transmit Queue. Every 100000 packets transmitted (default), the application prints a report with the achieved throughput and with the observed intervals between Transmit events.
Details:
MyNicName
The name of the NIC to be used by the application.
/etype 0x1234
Specifies the EtherType of the packets to be transmitted.
/bw 50000
Specifies the bandwidth allocated to the Physical Transmit Queue, in Kbps.
Note: The /bw value must be calculated to account for all Ethernet overhead, including the 20-byte gap between frames. This 20-byte gap is not accounted for in the throughput reports printed by the application. As a result, you will observe a reported throughput that is lower than the specified /bw value.
Transmitting Bursts at Regular Intervals
Instead of transmitting continuously, you can have the application send fixed-length bursts at regular intervals:
rtssrun NL2TransmitTestApp MyNicName /etype 0x1234 /burstlen 50000 /burstdelay 1000
This instructs NL2TransmitTestApp to transmit bursts of 50,000 packets, with each consecutive burst spaced by a 1,000 ms interval. The application uses Physical Transmit Queue 0 (default) of interface MyNicName. The packets are sent from a thread running on the system default real-time processor (default) with priority 0 (default). All transmitted packets use the broadcast address ff:ff:ff:ff:ff:ff (default) as the Destination MAC Address, 0x1234 as the EtherType, and have a length of 1514 bytes (default). Every 100,000 packets transmitted (default), the application prints a report with the achieved throughput.
Note: The application doesn't print observed intervals between Transmit events when transmitting non-continuously.
Details:
MyNicName
The name of the NIC to be used by the application.
/etype 0x1234
Specifies the EtherType of the packets to be transmitted.
/burstlen 50000
Specifies the number of packets to be transmitted in each burst.
/burstdelay 1000
Specifies the interval between consecutive bursts, in milliseconds.
Transmitting over a Logical Transmit Queue
All use cases described above also work with Logical Transmit Queues:
rtssrun NL2TransmitTestApp MyNicName /logical /q 1 /logqlen 50 /etype 0x1234
This instructs NL2TransmitTestApp to create a Logical Transmit Queue on top of Physical Transmit Queue 1 of interface MyNicName and to continuously transmit packets through that Logical Transmit Queue. The created Logical Transmit Queue has a length of 50 buffers, meaning that when the underlying Physical Transmit Queue is already full, the Logical Transmit Queue can store the content of up to 50 pending frames before overflowing. The packets are sent from a thread running on the system default real-time processor (default) with priority 0 (default). All transmitted packets use the broadcast address ff:ff:ff:ff:ff:ff as the Destination MAC Address (default), 0x1234 as the EtherType, and have a length of 1514 bytes (default). Every 100,000 packets transmitted (default), the application prints a report with the achieved throughput.
Note: There is no Transmit event when transmitting through a Logical Transmit Queue.
Details:
MyNicName
The name of the NIC to be used by the application.
/logical
Specifies that the Logical Queue API shall be used instead of the Physical Queue API.
/q 1
Specifies the Physical Transmit Queue to be used to create a Logical Transmit Queue.
/logqlen 50
Specifies the number of buffers in the Logical Transmit Queue.
/etype 0x1234
Specifies the EtherType of the packets to be transmitted.
Transmitting a Specified Amount of Frames
All examples above transmit frames indefinitely. You can limit the total amount of transmitted frames as follows:
rtssrun NL2TransmitTestApp MyNicName /etype 0x1234 /frames 750000
This instructs NL2TransmitTestApp to continuously transmit 750,000 packets through Physical Transmit Queue 0 (default) of interface MyNicName and then terminate the application. The packets are sent from a thread running on the system default real-time processor (default) with priority 0 (default). All transmitted packets use the broadcast address ff:ff:ff:ff:ff:ff (default) as the Destination MAC Address, 0x1234 as the EtherType, and have a length of 1514 bytes (default). Every 10,000 packets transmitted (default), the application prints a report with the achieved throughput and the observed intervals between Transmit events.
Details:
MyNicName
The name of the NIC to be used by the application.
/etype 0x1234
Specifies the EtherType of the packets to be transmitted.
/frames 750000
Specifies the total number of packets to be transmitted.
Transmitting and Timestamping
By default, the application doesn't request the NL2 to timestamp the transmitted frames. You can request to timestamp one frame every given number of transmitted frames as follows:
rtssrun NL2TransmitTestApp MyNicName /etype 0x1234 /ts 100000
This instructs NL2TransmitTestApp to continuously transmit packets through Physical Transmit Queue 0 (default) of interface MyNicName and to request timestamping of one frame every 100,000. The packets are sent from a thread running on the system default real-time processor (default) with priority 0 (default). All transmitted packets use the broadcast address ff:ff:ff:ff:ff:ff (default) as the Destination MAC Address, 0x1234 as the EtherType, and have a length of 1,514 bytes (default). Every 10,000 packets transmitted (default), the application prints a report with the achieved throughput and the observed intervals between Transmit events.
Details:
MyNicName
The name of the NIC to be used by the application.
/etype 0x1234
Specifies the EtherType of the packets to be transmitted.
/ts 100000
Specifies the interval between two timestamped frames.
Note: Please ensure that you specify a sufficiently large value for /ts. If the previous timestamp hasn't been retrieved, the NL2 will refuse to timestamp a new frame for a given queue.
Timestamping also works with Logical Transmit Queues, and with burst-mode transmission:
rtssrun NL2TransmitTestApp MyNicName /logical /etype 0x1234 /burstlen 1 /burstdelay 1000 /ts 1 /beep
This instructs NL2TransmitTestApp to create a Logical Transmit Queue on top of Physical Transmit Queue 0 (default) of interface MyNicName and to transmit 1 packet every 1,000 ms through that Logical Transmit Queue. The created Logical Transmit Queue has a default length of 200 buffers, meaning that when the underlying Physical Transmit Queue is already full, the Logical Transmit Queue can store the content of up to 200 pending frames before overflowing. The application requests the NL2 to timestamp every transmitted packet and makes an audio beep every time it extracts a timestamp. The packets are sent from a thread running on the system default real-time processor (default) with priority 0 (default). All transmitted packets use the broadcast address ff:ff:ff:ff:ff:ff as the Destination MAC Address (default), 0x1234 as the EtherType, and have a length of 1,514 bytes (default).
Details:
MyNicName
The name of the NIC to be used by the application.
/logical
Specifies that the Logical Queue API shall be used instead of the Physical Queue API.
/etype 0x1234
Specifies the EtherType of the packets to be transmitted.
/burstlen 1
Specifies the number of packets to be transmitted in each burst.
/burstdelay 1000
Specifies the interval between consecutive bursts, in milliseconds.
/ts 1
Specifies the interval between two timestamped frames.
/beep
Specifies that the application shall make an audio beep every time it extracts a timestamp.
Note: The /beep option can be used with Physical Transmit Queues and Logical Transmit Queues. Physical Transmit Queues make a short beep every time a timestamp is successfully extracted. For Logical Transmit Queues, a short beep is emitted every time a timestamp is successfully extracted, and a long beep is emitted if timestamping fails, which typically occurs when the link is down. The /beep option is useful when you don't have access to the console output of the application, such as during a system shutdown.
