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 StoreFBClockData(fd uintptr, d Data) error
- func Uint32AsFloat(val uint32) float64
- func Uint64ToUint32(val uint64) uint32
- type Data
- 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 StoreFBClockData ¶
StoreFBClockData 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 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 (*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 OpenFBClockShmCustom ¶
OpenFBClockShmCustom returns opened POSIX shared mem used by fbclock, with custom path
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