Rtnl2AdjustClockTime

Rtnl2AdjustClockTime adjusts the time of a clock by applying an offset to the current counter value.

Syntax

BOOL Rtnl2AdjustClockTime(
    [in] RTNL2_HCLOCK Clock, 
    [in] const RTNL2_TIMESTAMP *pTimeOffset
);

Parameters

[in] Clock

A handle to the clock object (see RTNL2_HCLOCK).

[in] pTimeOffset

The offset (positive or negative) to apply.

Return Value

If the function succeeds, it returns TRUE. If the function fails, it returns FALSE. Call GetLastError to obtain an error code.

Possible error codes:

Remarks

Depending on the hardware capabilities, the NL2 will use one of the two following methods:

• Method 1 (preferred, if available): provide the offset directly to the hardware and let the hardware apply the offset. This is a very precise method but it generally works with small offset values only. See RTNL2_INTERFACE_FEATURES.ClockTimeFineOffsetMax and RTNL2_INTERFACE_FEATURES.ClockTimeFineOffsetMin.
• Method 2: read the current counter value, add the offset to it, and write the new counter value. This method is much less precise because reading and writing hardware registers takes a non-negligible and variable amount of time.

IMPORTANT: Modifying the clock time is a disruptive operation that should be done with the greatest care. Whenever possible, it is preferable to maintain a logical time offset in software rather than modifying the hardware clock time.

IMPORTANT: If this clock is currently used by another application (typically PTP for Ethernet packet ingress/egress timestamping), that application should be made aware of the modification by some means outside of the NL2. Otherwise, it may wrongly interpret invalid timestamps and behave incorrectly.

IMPORTANT: Hardware clocks generally use a hardware register to record the value of their counter (e.g. a 32-bit register for the number of seconds and another 32-bit register for the number of nanoseconds, or a single 64-bit register for the number of nanoseconds). The size of this(these) register(s) is normally sufficient to avoid counter overflow for a very long time (e.g. 136 years for a 32-bit seconds register). However, if the application modifies the clock time by applying a large offset, it may cause the counter to overflow, which results in the clock time wrapping around. The NL2 does not prevent this from happening. It’s the application’s responsibility to either make sure it doesn’t happen or handle it correctly if it does. A similar problem occurs when applying a large negative time offset (counter underflow). See RTNL2_INTERFACE_FEATURES.ClockTimeRange for the range of possible values for the hardware clock time.

Characteristics

Requirements

See Also:

• RTNL2_HCLOCK
• RTNL2_INTERFACE_FEATURES