Commit | Line | Data |
---|---|---|
a75244c3 PO |
1 | /* |
2 | * Utility code which helps transforming between two different time | |
3 | * bases, called "source" and "target" time in this code. | |
4 | * | |
5 | * Source time has to be provided via the timecounter API while target | |
6 | * time is accessed via a function callback whose prototype | |
7 | * intentionally matches ktime_get() and ktime_get_real(). These | |
8 | * interfaces where chosen like this so that the code serves its | |
9 | * initial purpose without additional glue code. | |
10 | * | |
11 | * This purpose is synchronizing a hardware clock in a NIC with system | |
12 | * time, in order to implement the Precision Time Protocol (PTP, | |
13 | * IEEE1588) with more accurate hardware assisted time stamping. In | |
14 | * that context only synchronization against system time (= | |
15 | * ktime_get_real()) is currently needed. But this utility code might | |
16 | * become useful in other situations, which is why it was written as | |
17 | * general purpose utility code. | |
18 | * | |
19 | * The source timecounter is assumed to return monotonically | |
20 | * increasing time (but this code does its best to compensate if that | |
21 | * is not the case) whereas target time may jump. | |
22 | * | |
23 | * The target time corresponding to a source time is determined by | |
24 | * reading target time, reading source time, reading target time | |
25 | * again, then assuming that average target time corresponds to source | |
26 | * time. In other words, the assumption is that reading the source | |
27 | * time is slow and involves equal time for sending the request and | |
28 | * receiving the reply, whereas reading target time is assumed to be | |
29 | * fast. | |
30 | * | |
31 | * Copyright (C) 2009 Intel Corporation. | |
32 | * Author: Patrick Ohly <patrick.ohly@intel.com> | |
33 | * | |
34 | * This program is free software; you can redistribute it and/or modify it | |
35 | * under the terms and conditions of the GNU General Public License, | |
36 | * version 2, as published by the Free Software Foundation. | |
37 | * | |
38 | * This program is distributed in the hope it will be useful, but WITHOUT | |
39 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
40 | * FITNESS FOR A PARTICULAR PURPOSE. * See the GNU General Public License for | |
41 | * more details. | |
42 | * | |
43 | * You should have received a copy of the GNU General Public License along with | |
44 | * this program; if not, write to the Free Software Foundation, Inc., | |
45 | * 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. | |
46 | */ | |
47 | #ifndef _LINUX_TIMECOMPARE_H | |
48 | #define _LINUX_TIMECOMPARE_H | |
49 | ||
50 | #include <linux/clocksource.h> | |
51 | #include <linux/ktime.h> | |
52 | ||
53 | /** | |
54 | * struct timecompare - stores state and configuration for the two clocks | |
55 | * | |
56 | * Initialize to zero, then set source/target/num_samples. | |
57 | * | |
58 | * Transformation between source time and target time is done with: | |
59 | * target_time = source_time + offset + | |
60 | * (source_time - last_update) * skew / | |
61 | * TIMECOMPARE_SKEW_RESOLUTION | |
62 | * | |
63 | * @source: used to get source time stamps via timecounter_read() | |
64 | * @target: function returning target time (for example, ktime_get | |
65 | * for monotonic time, or ktime_get_real for wall clock) | |
66 | * @num_samples: number of times that source time and target time are to | |
67 | * be compared when determining their offset | |
68 | * @offset: (target time - source time) at the time of the last update | |
69 | * @skew: average (target time - source time) / delta source time * | |
70 | * TIMECOMPARE_SKEW_RESOLUTION | |
71 | * @last_update: last source time stamp when time offset was measured | |
72 | */ | |
73 | struct timecompare { | |
74 | struct timecounter *source; | |
75 | ktime_t (*target)(void); | |
76 | int num_samples; | |
77 | ||
78 | s64 offset; | |
79 | s64 skew; | |
80 | u64 last_update; | |
81 | }; | |
82 | ||
83 | /** | |
84 | * timecompare_transform - transform source time stamp into target time base | |
85 | * @sync: context for time sync | |
86 | * @source_tstamp: the result of timecounter_read() or | |
87 | * timecounter_cyc2time() | |
88 | */ | |
89 | extern ktime_t timecompare_transform(struct timecompare *sync, | |
90 | u64 source_tstamp); | |
91 | ||
92 | /** | |
93 | * timecompare_offset - measure current (target time - source time) offset | |
94 | * @sync: context for time sync | |
95 | * @offset: average offset during sample period returned here | |
96 | * @source_tstamp: average source time during sample period returned here | |
97 | * | |
98 | * Returns number of samples used. Might be zero (= no result) in the | |
99 | * unlikely case that target time was monotonically decreasing for all | |
100 | * samples (= broken). | |
101 | */ | |
102 | extern int timecompare_offset(struct timecompare *sync, | |
103 | s64 *offset, | |
104 | u64 *source_tstamp); | |
105 | ||
106 | extern void __timecompare_update(struct timecompare *sync, | |
107 | u64 source_tstamp); | |
108 | ||
109 | /** | |
110 | * timecompare_update - update offset and skew by measuring current offset | |
111 | * @sync: context for time sync | |
112 | * @source_tstamp: the result of timecounter_read() or | |
113 | * timecounter_cyc2time(), pass zero to force update | |
114 | * | |
115 | * Updates are only done at most once per second. | |
116 | */ | |
117 | static inline void timecompare_update(struct timecompare *sync, | |
118 | u64 source_tstamp) | |
119 | { | |
120 | if (!source_tstamp || | |
121 | (s64)(source_tstamp - sync->last_update) >= NSEC_PER_SEC) | |
122 | __timecompare_update(sync, source_tstamp); | |
123 | } | |
124 | ||
125 | #endif /* _LINUX_TIMECOMPARE_H */ |