GSoC 2013, New Timestamp and API: Project Design

These data structures and functions will be implemented as a portable library of Linux kernel.

Data structures

First, we need a structure that contains the integral part and fractional part of timestamp, the integral part can be a negative number. This structure should be like:

typedef struct {
    union {
        u_int64 Xf_ui;
        int64 Xf_i;
    } Uf_i;
    u_int64 f_uf;
} f_fp;

Second, we need a structure that contains not only a timestamp but also additional information like error and offset. It should be like:

struct TimeStruct {
    f_fp timestamp;    //timestamp
    f_fp expError;     //expected error
    f_fp maxError;     //maximum expected error
    f_fp expOffset;    //expected offset
    u_int32 timescale; //timescale indicator
    u_int32 version;   //version of timestamp
};

Third, we need a structure that contains the difference of timestamps (such as offsets and arguments that are used to add/subtract to a given timestamp), we can just use the structure f_fp above.

--

We probably need a host+clock ID, and each clock on a host should probably have a "discontinuity counter". For example, each time a laptop goes into "sleep" mode its discontinuity counter should increase.

-- HarlanStenn - 03 Jun 2013

---

Functions

There are functions that called by user application to fetch a timestamp:

int GetNewTimestamp(TimeStruct& ts);

And function that convert a timestamp to timestamp in give timescale:

void ConvertTimestamp(TimeStruct& in, TimeStruct& out);

And function that add a given offset to timestamp:

TimeStruct AddToTimestamp(TimeStruct& ts, TimeDelta& td);

And function that subtract a given offset from timestamp:

TimeStruct SubtractFromTimestamp(TimeStruct& ts, TimeDelta& td);

And function that compare the two given timestamp:

int CompareTimestamp(TimeStruct& t1, TimeStruct& t2);

And function that set the expected offset:

void SetOffset(TimeDelta& td);

GetNewTimestamp and SetOffset should probably take a "clock ID" parameter. One can add or subtract SI time values, add/subtract SI timestamps from other timescale timestamps, and subtract two timescale timstamps and produce an SI result. There are probably other cases.

-- HarlanStenn - 03 Jun 2013

---