Utility Programs

Table of Contents

Simulator Program

The kern.c simulator program linked with the ktime.c and micro.c subroutines in the distribution can be used to run a validation test suite in order to confirm that the kernel modifications work correctly in a particular architecture. The simulator can initialize state variables from the command line and write the feedback loop impulse response to the standard output. Alternately, the simulator can read input phase offset values from a data file and write the response to the standard output. See the source and header files for further details. Following is a list of command line flags interpreted by the program.

Option Description
a use alternate output format
c specify PPS mode and averaging time (shift)
d specify debug mode (trace on every tick/PPS interrupt
f frequency specify initial frequency transient (PPM)
F file specify file name for data input
l poll specify FLL mode and interval between polls (shift)
m min specify minimum simulation time (s) for trace
p usec specify initial phase transient (ms)
r random specify random walk frequency parameter
s run specify maximum simulation time (s)
t tc specify PLL mode and time constant (shift)
w hex specify status word (not used here)
z hz specify tick interrupt frequency (Hz)

In use, the kern.sh script should be run and the output compared with the model kern.out file in the distribution. Following is an example of the normal output format produced by the simulator.

start 0 s, stop 4000 s
state 0, status 2001, poll 64 s, phase 1000 us, freq 0 PPM
hz = 100 Hz, tick 10000000 ns

time offset   freq  _offset          _freq            _adj
0    1000.000 0.000 000f424000000000 0000000000000000 3b9aca0000000000

The program generates trace data lines in the format

time offset frequency hex_offset hex_frequency hex_adjustment

The first three fields are the simulation time in seconds, phase error in microseconds and frequency error in PPM in decimal, and the last three fields are the corresponding time_offset, time_freq and time_adj state variables of the clock discipline loop in hexadecimal. In comparing the output of one architecture with another, minor differences may occur in the least significant digits. This is due to minor differences in input and output conversion routines, roundoff error, etc., and should not be considered significant.

An alternate output file format can be selected with the -a command line switch. This format consists of three fields corresponding to the first three fields of the standard format and in the same units. This format is intended for analysis and display programs like Matlab. In this format no header lines are produced.

As an alternative to producing the impulse response of the feedback loop, an input data file can be specified using the -F command line option. The input file format consists of one update per line, where each line consists of two fields, the observation time in seconds and the phase offset in microseconds.

Histogram Program

The jitter.c program in the distribution can be used to generate a histogram of execution times for the ntp_gettime() system call, which involves a call on the nano_time() routine, an example of which is in kern.c. This is useful to determine the expected running time, as well as to look for anomalies, such as monotonic violations, etc. When operating properly, the histogram should show a sharp peak about 50 ms for a Sun IPC, 20 ms for a DEC 5000/240, 10 ms for a DEC 3000 Alpha, 8 ms for a HP 9000/735 and 2 ms for a Digital 433au. There should be no samples much below the peak; if samples of 1 ms or less are found (the silly thing coredumps if less than zero), there is probably a bug in the implementation or the local clock has been set backward when the ntpd daemon is running while the program is running.