NL2ClockTestApp Sample

NL2ClockTestApp is a simple example of a Network Link Layer (NL2) application that uses the NL2 Clock APIs to measure the time difference between the CPU clock and a NIC clock and, optionally, synchronize the NIC clock to the CPU clock.

Note: This application is intended for demonstration purposes only. It uses basic smoothing and servo algorithms that are not suitable for production use.

Source Files

File	Description
NL2ClockTestApp.c	The main source file.
CmdOptionsParser.h	The header file for the command line parser.
CmdOptionsParser.c	The command line parser source file.
NL2ClockTestApp_VS2022.sln	The Visual Studio 2022 solution file.
NL2ClockTestApp_VS2022.vcxproj	The Visual Studio 2022 project file.
NL2ClockTestApp_VS2022.vcxproj.filters	The Visual Studio 2022 filters file.

Building the Sample

Build the sample in the RTSSDebug or RTSSRelease configuration (to build NL2ClockTestApp.rtss).

Running the Sample

See Using as a Measurement Tool and Using a Clock Synchronization Tool below.

Expected Results

• Cross-timestamps are printed to the console every second.
• When used as a clock synchronization tool: the NIC's clock is adjusted until a +/-0.1ppm and +/-100ns difference with the CPU's clock.

Using as a Measurement Tool

Below is basic command line usage for running clock measurements on a NIC named "MyNicName":

rtssrun NL2ClockTestApp MyNicName

This starts an infinite loop of measurement cycles, where each cycle:

1. Cross-timestamps the NIC clock and CPU clock, using PTM if available.
2. Prints the values of the measured NIC clock time and CPU clock time.
3. Calculates a smoothed time offset and smoothed rate ratio between the two clocks and prints them.
4. Sleeps for one second.

Notes:

• If the NIC has multiple clocks, the first clock will be used. To specify a different clock, use the /clock command line argument.
• To run the application for a specific number of cycles, use the /cycles command line argument.
• To force the application to use software cross-timestamping instead of PTM, use the /sw command line argument.

Using as a Clock Synchronization Tool

Below is basic command line usage for running clock synchronization on the NIC named "MyNicName":

rtssrun NL2ClockTestApp MyNicName /sync

This starts an infinite loop of synchronization cycles, where each cycle:

1. Cross-timestamps the NIC clock and CPU clock, using PTM if available.
2. Prints the values of the measured NIC clock time and CPU clock time.
3. Performs one of the following actions, depending on the current state of the servo controller, the measured time offset and rate ratio, as well as the previous measurement of time offset and rate ratio:

• Makes a physical adjustment of the NIC Clock time.
• Makes a physical adjustment of the NIC Clock rate.
• Does nothing.

See the source code of the application to get more details about the used servo algorithm.

4. Sleeps for one second.

Notes:

• If the NIC has multiple clocks, the first clock will be used. To specify a different clock, use the /clock command line argument.
• If you want to force the application to use software cross-timestamping instead of PTM, use the /sw command line argument.

Using as a Clock Syntonization Tool

Syntonization refers to adjusting the clock rate only, without making any time adjustments. This can be preferable over synchronization in environments where other applications running on the same system expect the NIC time to be monotonic and continuous.

Use this basic command line to run clock syntonization on the NIC named "MyNicName":

rtssrun NL2ClockTestApp MyNicName /synt

This starts an infinite loop of syntonization cycles, where each cycle:

1. Cross-timestamp the NIC clock and CPU clock, using PTM, if available.
2. Prints the values of the measured NIC clock time and CPU clock time.
3. Depending on the current state of the servo controller, the measured time offset and rate ratio, as well as the previous measurement of time offset and rate ratio, performs one of the following actions:

• Adjusts the software-maintained offset of the NIC Clock time.
• Physically adjusts the NIC Clock rate.
• Does nothing.

See the source code of the application for more details about the used servo algorithm.

4. Sleeps 1 second.

Notes:

• If the NIC has multiple clocks, the first clock will be used. To specify a different clock, use the /clock command line argument.
• To force the application to use software cross-timestamping instead of PTM, use the /sw command line argument.

Command Line Arguments

The first argument passed to the NL2ClockTest application is the name of the network interface to use.

Other arguments:

/clock <number>

Specifies the index of the NIC Clock to use. The default value is 0.

/cycles <number>

Specifies the count of measurement cycles to execute. The default is infinite.

/sw

Instructs to perform software cross-timestamping even if PTM is available. The default is to use PTM.

/sync

Instructs to execute NIC clock synchronization in addition to measurements. The default is to only perform measurements.