NL2ReceiveTestApp provides a simple Network Link Layer (NL2) application example that uses various NL2 APIs to receive packets in different approaches. 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 no optional parameter is passed, the application acquires the first Physical Receive Queue of the specified interface and extracts packets received through that queue as soon as possible to minimize receive latency. It also prints statistics about the achieved reception 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 receive with minimum latency, use the following command line:
rtssrun NL2ReceiveTestApp MyNicName /q 1 /p 7 /y 40 /report 20000
This instructs NL2ReceiveTestApp to use the Receive event to extract packets received through Physical Receive Queue 1 of interface MyNicName as soon as possible. The packets are extracted from a thread running on processor 7 with priority 40. Every 20,000 received packets, the application prints a report with the achieved throughput and the observed intervals between Receive events.
Details:
MyNicName
The name of the NIC to be used by the application.
/q 1
Specifies the Physical Receive Queue to be used.
/p 7
Specifies the ideal processor used by the Receive thread.
/y 40
Specifies the priority of the Receive thread.
/report 20000
Specifies that the application shall print a report every 20,000 received packets.
Extracting Received Packets Cyclically
Instead of extracting packets based on a notification from the NL2 (the Receive event), you can have the application extract multiple packets at regular intervals:
rtssrun NL2ReceiveTestApp MyNicName /burstlen 50000 /burstdelay 1000
This instructs NL2ReceiveTestApp to extract 50,000 packets, wait 1,000 ms, then extract again, and repeat the process indefinitely. The application uses Physical Receive Queue 0 (default) of interface MyNicName. The packets are extracted from a thread running on the system default real-time processor (default) with priority 0 (default). Every 100,000 received packets (default), the application prints a report with the achieved throughput.
Note: The application doesn't print the observed intervals between Receive events when receiving cyclically.
Details:
MyNicName
The name of the NIC to be used by the application.
/burstlen 50000
Specifies the number of packets to be extracted in each iteration.
/burstdelay 1000
Specifies the interval between iterations, in milliseconds.
Receiving through a Logical Receive Queue
Both use cases described above also work with Logical Receive Queues:
rtssrun NL2ReceiveTestApp MyNicName /logical /q 1 /logqlen 100 /buflen 512
This instructs NL2ReceiveTestApp to create a Logical Receive Queue on top of Physical Receive Queue 1 of interface MyNicName and to extract packets received through that Logical Receive Queue as soon as possible. The created Logical Receive Queue has a length of 100 buffers, meaning it can store up to 100 received, unextracted frames before overflowing. The buffers used to store incoming packets have a length of 512 bytes, so any incoming larger packet gets truncated to 512 bytes. The packets are extracted from a thread running on the system default real-time processor (default) with priority 0 (default). Every 100,000 received packets (default), the application prints a report with the achieved throughput and the observed intervals between Receive events.
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 Receive Queue to be used to create a Logical Receive Queue.
/logqlen 100
Specifies the number of buffers in the Logical Receive Queue.
/buflen 512
Specifies the length of the buffers used to store the incoming packets in the Logical Receive Queue.
Receiving a Specified Number of Frames
All examples above receive frames indefinitely. You can limit the total number of frames to receive as follows:
rtssrun NL2ReceiveTestApp MyNicName /frames 750000 /beep
This instructs NL2ReceiveTestApp to use the Receive event to extract 750,000 packets received through Physical Receive Queue 0 (default) of interface MyNicName as soon as possible. The packets are extracted from a thread running on the system default real-time processor (default) with priority 0 (default). Every 100,000 received packets (default), the application prints a report with the achieved throughput and the observed intervals between Receive events and makes an audio beep.
Details:
MyNicName
The name of the NIC to be used by the application.
/frames 750,000
Specifies the total number of packets to be received.
/beep
Specifies that the application shall make an audio beep every time it prints a report.
Note: The /beep option is useful when you don't have access to the application's console output, such as during a system shutdown.
Specifying a Receive Mode
For Physical Receive Queues and Logical Receive Queues, you can enable specific Receive modes as follows:
rtssrun NL2ReceiveTestApp MyNicName /promiscuous /passbadframes
This instructs NL2ReceiveTestApp to enable the Promiscuous and PassBadFrames modes on Physical Receive Queue 0 (default) of interface MyNicName and use the Receive event to extract packets received through that queue as soon as possible. The packets are extracted from a thread running on the system default real-time processor (default) with priority 0 (default). Every 100,000 received packets (default), the application prints a report with the achieved throughput and the observed intervals between Receive events.
Details:
MyNicName
The name of the NIC to be used by the application.
/promiscuous
Specifies that the application shall enable the Promiscuous mode on the queue.
/passbadframes
Specifies that the application shall enable the PassBadFrames mode on the queue.
Specifying a Multicast Filter
For Physical Receive Queues and Logical Receive Queues, you can specify a list of multicast addresses to be accepted or even set the queue in PassAllMulticast mode.
To specify a list of multicast addresses:
rtssrun NL2ReceiveTestApp MyNicName /mcast 11:22:33:44:55:66 11:22:33:44:55:67 11:22:33:44:55:68
This instructs NL2ReceiveTestApp to set up a multicast filter with three Multicast MAC Addresses on Physical Receive Queue 0 (default) of interface MyNicName and use the Receive event to extract packets received through that queue as soon as possible. The packets are extracted from a thread running on the system default real-time processor (default) with priority 0 (default). Every 100,000 received packets (default), the application prints a report with the achieved throughput and the observed intervals between Receive events.
Details:
MyNicName
The name of the NIC to be used by the application.
/mcast
Specifies a list of Multicast MAC Addresses to add to the multicast filter of the queue.
Note: When used with Physical Receive Queues, the multicast filter is imperfect because it may pass Multicast MAC Addresses which were not specified but have the same hash as the specified ones. In contrast, when used with Logical Receive Queues, the multicast filter is perfect as it passes only the specified Multicast MAC Addresses.
To enable the PassAllMulticast mode:
rtssrun NL2ReceiveTestApp MyNicName /mcastall
Specifying an EtherType Filter (for Logical Receive Queues only)
When using a Logical Receive Queue, you can specify a list of EtherTypes that the queue accepts:
rtssrun NL2ReceiveTestApp MyNicName /logical /etype 0x1234 0x1235 0x1236
This instructs NL2ReceiveTestApp to create a Logical Receive Queue on top of Physical Receive Queue 0 (default) of interface MyNicName, set up an EtherType filter with three EtherType values, and extract packets received through that Logical Receive Queue as soon as possible. The created Logical Receive Queue has a length of 200 buffers (default). The buffers used to store incoming packets have a default length of 1,514 bytes. The packets are extracted from a thread running on the system default real-time processor (default) with priority 0 (default). Every 100,000 received packets (default), the application prints a report with the achieved throughput and the observed intervals between Receive events.
Note: The EtherType filter is perfect as it passes only the specified EtherTypes.
Note: When the /etype parameter is not used, the default is to accept all EtherTypes (no filter).
Enabling Ingress Timestamping
For Physical Receive Queues and Logical Receive Queues, you can enable ingress timestamping as follows:
rtssrun NL2ReceiveTestApp MyNicName /ts
This instructs NL2ReceiveTestApp to enable the timestamping logic on Physical Receive Queue 0 (default) of interface MyNicName and use the Receive event to extract packets received through that queue as soon as possible. The packets are extracted from a thread running on the system default real-time processor (default) with priority 0 (default). Every 100,000 received packets (default), the application prints a report with the achieved throughput and the observed intervals between Receive events.
Details:
MyNicName
The name of the NIC to be used by the application.
/ts
To enable ingress timestamping on the queue.
