README
¶
fbclock
Client C library and stateful Go daemon to provide true time API based on PTP time.
fbclock doesn't just provide a single timestamp, instead it provides an [Earliest, Latest] values that incorporate calculated Window of Uncertainty.
The idea is using the math based on observed PTP client metrics like offset/path delay/frequency adjustments that allows estimating the level of uncertainty for current time taken from the NIC PHC.
Then on each request to the fbclock API the client gets a tuple of [Earliest, Latest] values, with 6-9s guarantee that 'true time' lies withing this range.
C API
// what customers get
typedef struct fbclock_truetime {
uint64_t earliest_ns;
uint64_t latest_ns;
} fbclock_truetime;
// methods we provide
int fbclock_init(fbclock_lib* lib, const char* shm_path);
int fbclock_destroy(fbclock_lib* lib);
int fbclock_gettime(fbclock_lib* lib, fbclock_truetime* truetime);
Usage
As a preprequisite, you need working PTP client set up with ptp4l, using hardware timestamps. This requires a NIC with PHC support.
- build the daemon
go build github.com/facebook/time/fbclock/daemon - run it as root (it needs permissions to talk to ptp4l, and get frequency from PHC)
- build the example client CLI (
cd cmd/fbclock-bin && make), use it to exercise the API and get the current PHC time
C API can be used to build a client in any language. Clients don't need special permissions except for read access to SHM path and PHC device.
Math
fbclock-daemon uses 3 formulas to provide accurate [Earliest, Latest] values.
- M is the measurement, based on N recent values we obtain from ptp4l, such as offset, path delay, or GM clock accuracy
- W is the error bound before it's adjusted for holdover, based on recent values of
M - Drift is the estimation of local oscillator drift during the holdover, based on changes in PHC frequency adjustments.
This all comes together when real WOU is calculated for each API call, when client part of the code uses W and Drift values received from fbclock-daemon and adjusts W based on how far in the past the latest synchronization with GM happened.
Architecture
Documentation
¶
Index ¶
- Constants
- func FloatAsUint32(val float64) uint32
- func MmapShmpData(fd uintptr) (unsafe.Pointer, error)
- func MmapShmpDataV2(fd uintptr) (unsafe.Pointer, error)
- func StoreFBClockData(fd uintptr, d Data) error
- func StoreFBClockDataV2(fd uintptr, d DataV2) error
- func Uint32AsFloat(val uint32) float64
- func Uint64ToUint32(val uint64) uint32
- type Data
- type DataV2
- type FBClock
- type Shm
- type Stats
- type StatsCollector
- type TrueTime
Constants ¶
const PTPPath = C.FBCLOCK_PTPPATH
PTPPath is the path we set for PTP device
Variables ¶
This section is empty.
Functions ¶
func FloatAsUint32 ¶
FloatAsUint32 stores float as multiplier of 2**16. Effectively this means we can store max 65k like this.
func MmapShmpData ¶
MmapShmpData mmaps open file as fbclock shared memory. Used in tests only.
func MmapShmpDataV2 ¶
MmapShmpDataV2 mmaps open file as fbclock shared memory. Used in tests only.
func StoreFBClockData ¶
StoreFBClockData will store fbclock data in shared mem, fd param should be open file descriptor of that shared mem.
func StoreFBClockDataV2 ¶
StoreFBClockDataV2 will store fbclock data in shared mem, fd param should be open file descriptor of that shared mem.
func Uint32AsFloat ¶
Uint32AsFloat restores float that was stored as a multiplier of 2**16.
func Uint64ToUint32 ¶
Uint64ToUint32 converts uint64 to uint32, handling the overflow. If the uint64 value is more than MaxUint32, result is set to MaxUint32.
Types ¶
type Data ¶
type Data struct {
IngressTimeNS int64
ErrorBoundNS uint64
HoldoverMultiplierNS float64 // float stored as multiplier of 2**16
SmearingStartS uint64 // Smearing starts before the Leap Second Event Time (midnight on June-30 or Dec-31)
SmearingEndS uint64 // Smearing ends after the Leap Second Event Time (midnight on June-30 or Dec-31)
UTCOffsetPreS int32 // UTC Offset before Leap Second Event
UTCOffsetPostS int32 // UTC Offset after Leap Second Event
}
Data is a Go equivalent of what we want to store in shared memory for fbclock to use
type DataV2 ¶
type DataV2 struct {
IngressTimeNS int64
ErrorBoundNS uint64
HoldoverMultiplierNS float64 // float stored as multiplier of 2**16
SmearingStartS uint64 // Smearing starts before the Leap Second Event Time (midnight on June-30 or Dec-31)
UTCOffsetPreS int16 // UTC Offset before Leap Second Event
UTCOffsetPostS int16 // UTC Offset after Leap Second Event
ClockID uint32 // Clock ID of SysclockTimeNS (MONOTONIC_RAW or REALTIME)
PHCTimeNS int64 // Periodically updated PHC time used to calculate real PHC time
SysclockTimeNS int64 // Periodically updated system clock time (MONOTONIC_RAW or REALTIME) received with PHC time
CoefPPB int64 // Coefficient of the approximation of the PHC time
}
DataV2 is a Go equivalent of what we want to store in shared memory for fbclock to use
type FBClock ¶
type FBClock struct {
// contains filtered or unexported fields
}
FBClock wraps around fbclock C lib
func NewFBClockCustom ¶
NewFBClockCustom returns new FBClock wrapper with custom path
func NewFBClockV2 ¶
NewFBClockV2 returns new FBClock wrapper using v2 data structure
func (*FBClock) GetTimeUTC ¶
GetTimeUTC returns TrueTime in UTC
type Shm ¶
Shm is POSIX shared memory
func OpenFBClockSHM ¶
OpenFBClockSHM returns opened POSIX shared mem used by fbclock
func OpenFBClockSHMv2 ¶
OpenFBClockSHMv2 returns opened POSIX shared mem used by fbclock
func OpenFBClockShmCustom ¶
OpenFBClockShmCustom returns opened POSIX shared mem used by fbclock, with custom path and version specified
func OpenFBClockShmCustomVer ¶
OpenFBClockShmCustomVer returns opened POSIX shared mem used by fbclock, with custom path and version specified
type Stats ¶
type Stats struct {
Requests int64
Errors int64
WOUAvg int64
WOUMax int64
WOUlt10us int64
WOUlt100us int64
WOUlt1000us int64
WOUge1000us int64
}
Stats aggregate stats for fbclock GetTime results
type StatsCollector ¶
type StatsCollector struct {
// contains filtered or unexported fields
}
StatsCollector collects stats based on GetTime results
func (*StatsCollector) Update ¶
func (s *StatsCollector) Update(tt *TrueTime, err error)
Update processes result of GetTime call and updates Stats
Source Files
Directories