GSoC 2013 New Timestamp and API: Key Parts

Key parts of this new timestamp API and their realizations


This was originally expected to be the system time, as maintained by the system clock. As each system will likely have multiple clocks, this value more properly means the time of the clock we are querying. Some of these clocks will be "absolute" clocks and some will be "relative" clocks. When the system boots, for example, that may start a relative clock starting at 0.0 seconds. This means the timestamp structure will need a host ID that includes a clock ID as a subfield. When ready, the system will present an absolute clock and we can "tie" events against the low-level boot clock to this absolute clock and figure out when the system was booted (by working backwards). IE, if the absolute clock reads 2:15:00 and the boot clock says 0:0:15, that means the system was actually booted at 2:14:45.

-- HarlanStenn - 03 Jun 2013

Canonic timescale

Our new timestamp API needs a canonic timescale as standard. All conversion will be based on this canonic timescale.

Canonic timescale can be one of existing timescales as well as a whole new timescale.

For example, we can choose GPS timescale as canonic timescale, if we want to convert a timestamp in UTC timescale to TAI timescale, we need to first convert the UTC timestamp into GPS timescale, and then convert the GPS timestamp into TAI timescale.

Our new timestamp format will be including two 64-bit values. The first 64-bit value is the fractional part of timestamp, and the second 64-bit value is the integral part of timestamp. This format can support up to about 585 billion years and far more accurate than picosecond resolution.

64-bit number may cause problem in embedded systems, for they have very limited memory space. In that case, we can choose a smaller number instead.


Probable error and maximum expected error

There will always be accidents to affect the validity of system time, e.g. network delay and inaccuracy of hardware clock. The NTPd maintains an expected error value that increased by 15 microseconds per second if it does not talk to a trusted time source. When this expected error value exceed 1.5 second, other NTP server and client will consider this NTP server as invalid.

But this error value can only be used by other NTP module, and are not exposed to user applications. It will be great if we can add this part to our new timestamp API and share the error value to more applications.

Currently two errors will be considered in our design: probable error and maximum expected error.

Both of them will accumulate over time, and will be reset when the system talk to a trusted time source.

The former is the value that represents the error level in expected case, while the latter represents the greatest possible error level.

For example, when user application calls the API, it will get a timestamp and two error value (supposing the expected error is 50000 microsecond), but it requires this value to be under 30000 microsecond, so it can refuse to use the timestamp. In the meantime, other applications that have looser requirements can continue using this timestamp.


Expected offset

Excepted offset is a value that indicates the difference between system time and standard time. When application like NTPd needs to change the system time, it is not necessary to change itself, the application can simply write offset using our new timestamp API, so that system will later call functions like adjfreq() and adjtimex() to apply the offset adjustment smoothly.

  • This field is only useful for absolute clocks, right? -- HarlanStenn - 27 Jun 2013

Boot counter (may not be needed now)

Boot counter is an indicator that indicates whether the system has been rebooted. Our new timestamp API will record information like current timestamp and unapplied offset to disk. When system starts again, the data will be recovered and applied offset adjustment. If the system occasionally step backward after rebooting, that time skew will also be added to unapplied offset and have the current system time increasing very slowly until there is no more offset is left.

When our new timestamp API finds that the system has been rebooted, it will set maximum expected error to infinite, so the user application will know that this timestamp is not reliable. As described above, the maximum expected error will be reset when the system talks to a trusted time source.

The "Boot Counter" may need to be renamed "Clock Discontinuity Counter" and we may also need a "Host ID" that has a subfield for "Clock ID". On a given host, there may be a CMOS/RTC clock, several other clock sources, and then some "more processed clocks" that the OS maintains internally.

-- HarlanStenn - 03 Jun 2013

Interface function

The most important part of this new timestamp API is the interface that called by user applications to get the current timestamp in our unified format.

This function is embedded into Linux/BSD kernel. When user application calls it, it generates a timestamp using systemís time, along with the timescale indicator. Then it returns a series of data including the timestamp, two errors and timescale indicator to user application.

There will be other operations to be implemented, e.g. addition, subtraction, comparison between two or more timestamps.

A timestamp may contain an absolute timestamp (a timescale of, say, TAI) or a scalar timestamp (with a timescale of, say SI seconds). If we subtract two TAI timestamps we get an SI result. We can add or subtract two timestamps with SI timescales and get an SI timescale result.

-- HarlanStenn - 03 Jun 2013

Topic revision: r6 - 08 Feb 2014, HarlanStenn

This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Network Time Foundation Community Wiki? Send feedback