1  /* SPDX-License-Identifier: GPL-2.0-or-later */
2  /*
3   * PTP 1588 clock support
4   *
5   * Copyright (C) 2010 OMICRON electronics GmbH
6   */
7  
8  #ifndef _PTP_CLOCK_KERNEL_H_
9  #define _PTP_CLOCK_KERNEL_H_
10  
11  #include <linux/device.h>
12  #include <linux/pps_kernel.h>
13  #include <linux/ptp_clock.h>
14  #include <linux/timecounter.h>
15  #include <linux/skbuff.h>
16  
17  #define PTP_CLOCK_NAME_LEN	32
18  /**
19   * struct ptp_clock_request - request PTP clock event
20   *
21   * @type:   The type of the request.
22   *	    EXTTS:  Configure external trigger timestamping
23   *	    PEROUT: Configure periodic output signal (e.g. PPS)
24   *	    PPS:    trigger internal PPS event for input
25   *	            into kernel PPS subsystem
26   * @extts:  describes configuration for external trigger timestamping.
27   *          This is only valid when event == PTP_CLK_REQ_EXTTS.
28   * @perout: describes configuration for periodic output.
29   *	    This is only valid when event == PTP_CLK_REQ_PEROUT.
30   */
31  
32  struct ptp_clock_request {
33  	enum {
34  		PTP_CLK_REQ_EXTTS,
35  		PTP_CLK_REQ_PEROUT,
36  		PTP_CLK_REQ_PPS,
37  	} type;
38  	union {
39  		struct ptp_extts_request extts;
40  		struct ptp_perout_request perout;
41  	};
42  };
43  
44  struct system_device_crosststamp;
45  
46  /**
47   * struct ptp_system_timestamp - system time corresponding to a PHC timestamp
48   * @pre_ts: system timestamp before capturing PHC
49   * @post_ts: system timestamp after capturing PHC
50   * @clockid: clock-base used for capturing the system timestamps
51   */
52  struct ptp_system_timestamp {
53  	struct timespec64 pre_ts;
54  	struct timespec64 post_ts;
55  	clockid_t clockid;
56  };
57  
58  /**
59   * struct ptp_clock_info - describes a PTP hardware clock
60   *
61   * @owner:     The clock driver should set to THIS_MODULE.
62   * @name:      A short "friendly name" to identify the clock and to
63   *             help distinguish PHY based devices from MAC based ones.
64   *             The string is not meant to be a unique id.
65   * @max_adj:   The maximum possible frequency adjustment, in parts per billon.
66   * @n_alarm:   The number of programmable alarms.
67   * @n_ext_ts:  The number of external time stamp channels.
68   * @n_per_out: The number of programmable periodic signals.
69   * @n_pins:    The number of programmable pins.
70   * @pps:       Indicates whether the clock supports a PPS callback.
71   * @pin_config: Array of length 'n_pins'. If the number of
72   *              programmable pins is nonzero, then drivers must
73   *              allocate and initialize this array.
74   *
75   * clock operations
76   *
77   * @adjfine:  Adjusts the frequency of the hardware clock.
78   *            parameter scaled_ppm: Desired frequency offset from
79   *            nominal frequency in parts per million, but with a
80   *            16 bit binary fractional field.
81   *
82   * @adjphase:  Indicates that the PHC should use an internal servo
83   *             algorithm to correct the provided phase offset.
84   *             parameter delta: PHC servo phase adjustment target
85   *                              in nanoseconds.
86   *
87   * @getmaxphase:  Advertises maximum offset that can be provided
88   *                to the hardware clock's phase control functionality
89   *                through adjphase.
90   *
91   * @adjtime:  Shifts the time of the hardware clock.
92   *            parameter delta: Desired change in nanoseconds.
93   *
94   * @gettime64:  Reads the current time from the hardware clock.
95   *              This method is deprecated.  New drivers should implement
96   *              the @gettimex64 method instead.
97   *              parameter ts: Holds the result.
98   *
99   * @gettimex64:  Reads the current time from the hardware clock and optionally
100   *               also the system clock.
101   *               parameter ts: Holds the PHC timestamp.
102   *               parameter sts: If not NULL, it holds a pair of timestamps from
103   *               the system clock. The first reading is made right before
104   *               reading the lowest bits of the PHC timestamp and the second
105   *               reading immediately follows that.
106   *
107   * @getcrosststamp:  Reads the current time from the hardware clock and
108   *                   system clock simultaneously.
109   *                   parameter cts: Contains timestamp (device,system) pair,
110   *                   where system time is realtime and monotonic.
111   *
112   * @settime64:  Set the current time on the hardware clock.
113   *              parameter ts: Time value to set.
114   *
115   * @getcycles64:  Reads the current free running cycle counter from the hardware
116   *                clock.
117   *                If @getcycles64 and @getcyclesx64 are not supported, then
118   *                @gettime64 or @gettimex64 will be used as default
119   *                implementation.
120   *                parameter ts: Holds the result.
121   *
122   * @getcyclesx64:  Reads the current free running cycle counter from the
123   *                 hardware clock and optionally also the system clock.
124   *                 If @getcycles64 and @getcyclesx64 are not supported, then
125   *                 @gettimex64 will be used as default implementation if
126   *                 available.
127   *                 parameter ts: Holds the PHC timestamp.
128   *                 parameter sts: If not NULL, it holds a pair of timestamps
129   *                 from the system clock. The first reading is made right before
130   *                 reading the lowest bits of the PHC timestamp and the second
131   *                 reading immediately follows that.
132   *
133   * @getcrosscycles:  Reads the current free running cycle counter from the
134   *                   hardware clock and system clock simultaneously.
135   *                   If @getcycles64 and @getcyclesx64 are not supported, then
136   *                   @getcrosststamp will be used as default implementation if
137   *                   available.
138   *                   parameter cts: Contains timestamp (device,system) pair,
139   *                   where system time is realtime and monotonic.
140   *
141   * @enable:   Request driver to enable or disable an ancillary feature.
142   *            parameter request: Desired resource to enable or disable.
143   *            parameter on: Caller passes one to enable or zero to disable.
144   *
145   * @verify:   Confirm that a pin can perform a given function. The PTP
146   *            Hardware Clock subsystem maintains the 'pin_config'
147   *            array on behalf of the drivers, but the PHC subsystem
148   *            assumes that every pin can perform every function. This
149   *            hook gives drivers a way of telling the core about
150   *            limitations on specific pins. This function must return
151   *            zero if the function can be assigned to this pin, and
152   *            nonzero otherwise.
153   *            parameter pin: index of the pin in question.
154   *            parameter func: the desired function to use.
155   *            parameter chan: the function channel index to use.
156   *
157   * @do_aux_work:  Request driver to perform auxiliary (periodic) operations
158   *                Driver should return delay of the next auxiliary work
159   *                scheduling time (>=0) or negative value in case further
160   *                scheduling is not required.
161   *
162   * Drivers should embed their ptp_clock_info within a private
163   * structure, obtaining a reference to it using container_of().
164   *
165   * The callbacks must all return zero on success, non-zero otherwise.
166   */
167  
168  struct ptp_clock_info {
169  	struct module *owner;
170  	char name[PTP_CLOCK_NAME_LEN];
171  	s32 max_adj;
172  	int n_alarm;
173  	int n_ext_ts;
174  	int n_per_out;
175  	int n_pins;
176  	int pps;
177  	struct ptp_pin_desc *pin_config;
178  	int (*adjfine)(struct ptp_clock_info *ptp, long scaled_ppm);
179  	int (*adjphase)(struct ptp_clock_info *ptp, s32 phase);
180  	s32 (*getmaxphase)(struct ptp_clock_info *ptp);
181  	int (*adjtime)(struct ptp_clock_info *ptp, s64 delta);
182  	int (*gettime64)(struct ptp_clock_info *ptp, struct timespec64 *ts);
183  	int (*gettimex64)(struct ptp_clock_info *ptp, struct timespec64 *ts,
184  			  struct ptp_system_timestamp *sts);
185  	int (*getcrosststamp)(struct ptp_clock_info *ptp,
186  			      struct system_device_crosststamp *cts);
187  	int (*settime64)(struct ptp_clock_info *p, const struct timespec64 *ts);
188  	int (*getcycles64)(struct ptp_clock_info *ptp, struct timespec64 *ts);
189  	int (*getcyclesx64)(struct ptp_clock_info *ptp, struct timespec64 *ts,
190  			    struct ptp_system_timestamp *sts);
191  	int (*getcrosscycles)(struct ptp_clock_info *ptp,
192  			      struct system_device_crosststamp *cts);
193  	int (*enable)(struct ptp_clock_info *ptp,
194  		      struct ptp_clock_request *request, int on);
195  	int (*verify)(struct ptp_clock_info *ptp, unsigned int pin,
196  		      enum ptp_pin_function func, unsigned int chan);
197  	long (*do_aux_work)(struct ptp_clock_info *ptp);
198  };
199  
200  struct ptp_clock;
201  
202  enum ptp_clock_events {
203  	PTP_CLOCK_ALARM,
204  	PTP_CLOCK_EXTTS,
205  	PTP_CLOCK_EXTOFF,
206  	PTP_CLOCK_PPS,
207  	PTP_CLOCK_PPSUSR,
208  };
209  
210  /**
211   * struct ptp_clock_event - decribes a PTP hardware clock event
212   *
213   * @type:  One of the ptp_clock_events enumeration values.
214   * @index: Identifies the source of the event.
215   * @timestamp: When the event occurred (%PTP_CLOCK_EXTTS only).
216   * @offset:    When the event occurred (%PTP_CLOCK_EXTOFF only).
217   * @pps_times: When the event occurred (%PTP_CLOCK_PPSUSR only).
218   */
219  
220  struct ptp_clock_event {
221  	int type;
222  	int index;
223  	union {
224  		u64 timestamp;
225  		s64 offset;
226  		struct pps_event_time pps_times;
227  	};
228  };
229  
230  /**
231   * scaled_ppm_to_ppb() - convert scaled ppm to ppb
232   *
233   * @ppm:    Parts per million, but with a 16 bit binary fractional field
234   */
scaled_ppm_to_ppb(long ppm)235  static inline long scaled_ppm_to_ppb(long ppm)
236  {
237  	/*
238  	 * The 'freq' field in the 'struct timex' is in parts per
239  	 * million, but with a 16 bit binary fractional field.
240  	 *
241  	 * We want to calculate
242  	 *
243  	 *    ppb = scaled_ppm * 1000 / 2^16
244  	 *
245  	 * which simplifies to
246  	 *
247  	 *    ppb = scaled_ppm * 125 / 2^13
248  	 */
249  	s64 ppb = 1 + ppm;
250  
251  	ppb *= 125;
252  	ppb >>= 13;
253  	return (long)ppb;
254  }
255  
256  /**
257   * diff_by_scaled_ppm - Calculate difference using scaled ppm
258   * @base: the base increment value to adjust
259   * @scaled_ppm: scaled parts per million to adjust by
260   * @diff: on return, the absolute value of calculated diff
261   *
262   * Calculate the difference to adjust the base increment using scaled parts
263   * per million.
264   *
265   * Use mul_u64_u64_div_u64 to perform the difference calculation in avoid
266   * possible overflow.
267   *
268   * Returns: true if scaled_ppm is negative, false otherwise
269   */
diff_by_scaled_ppm(u64 base,long scaled_ppm,u64 * diff)270  static inline bool diff_by_scaled_ppm(u64 base, long scaled_ppm, u64 *diff)
271  {
272  	bool negative = false;
273  
274  	if (scaled_ppm < 0) {
275  		negative = true;
276  		scaled_ppm = -scaled_ppm;
277  	}
278  
279  	*diff = mul_u64_u64_div_u64(base, (u64)scaled_ppm, 1000000ULL << 16);
280  
281  	return negative;
282  }
283  
284  /**
285   * adjust_by_scaled_ppm - Adjust a base increment by scaled parts per million
286   * @base: the base increment value to adjust
287   * @scaled_ppm: scaled parts per million frequency adjustment
288   *
289   * Helper function which calculates a new increment value based on the
290   * requested scaled parts per million adjustment.
291   */
adjust_by_scaled_ppm(u64 base,long scaled_ppm)292  static inline u64 adjust_by_scaled_ppm(u64 base, long scaled_ppm)
293  {
294  	u64 diff;
295  
296  	if (diff_by_scaled_ppm(base, scaled_ppm, &diff))
297  		return base - diff;
298  
299  	return base + diff;
300  }
301  
302  #if IS_ENABLED(CONFIG_PTP_1588_CLOCK)
303  
304  /**
305   * ptp_clock_register() - register a PTP hardware clock driver
306   *
307   * @info:   Structure describing the new clock.
308   * @parent: Pointer to the parent device of the new clock.
309   *
310   * Returns a valid pointer on success or PTR_ERR on failure.  If PHC
311   * support is missing at the configuration level, this function
312   * returns NULL, and drivers are expected to gracefully handle that
313   * case separately.
314   */
315  
316  extern struct ptp_clock *ptp_clock_register(struct ptp_clock_info *info,
317  					    struct device *parent);
318  
319  /**
320   * ptp_clock_unregister() - unregister a PTP hardware clock driver
321   *
322   * @ptp:  The clock to remove from service.
323   */
324  
325  extern int ptp_clock_unregister(struct ptp_clock *ptp);
326  
327  /**
328   * ptp_clock_event() - notify the PTP layer about an event
329   *
330   * @ptp:    The clock obtained from ptp_clock_register().
331   * @event:  Message structure describing the event.
332   */
333  
334  extern void ptp_clock_event(struct ptp_clock *ptp,
335  			    struct ptp_clock_event *event);
336  
337  /**
338   * ptp_clock_index() - obtain the device index of a PTP clock
339   *
340   * @ptp:    The clock obtained from ptp_clock_register().
341   */
342  
343  extern int ptp_clock_index(struct ptp_clock *ptp);
344  
345  /**
346   * ptp_find_pin() - obtain the pin index of a given auxiliary function
347   *
348   * The caller must hold ptp_clock::pincfg_mux.  Drivers do not have
349   * access to that mutex as ptp_clock is an opaque type.  However, the
350   * core code acquires the mutex before invoking the driver's
351   * ptp_clock_info::enable() callback, and so drivers may call this
352   * function from that context.
353   *
354   * @ptp:    The clock obtained from ptp_clock_register().
355   * @func:   One of the ptp_pin_function enumerated values.
356   * @chan:   The particular functional channel to find.
357   * Return:  Pin index in the range of zero to ptp_clock_caps.n_pins - 1,
358   *          or -1 if the auxiliary function cannot be found.
359   */
360  
361  int ptp_find_pin(struct ptp_clock *ptp,
362  		 enum ptp_pin_function func, unsigned int chan);
363  
364  /**
365   * ptp_find_pin_unlocked() - wrapper for ptp_find_pin()
366   *
367   * This function acquires the ptp_clock::pincfg_mux mutex before
368   * invoking ptp_find_pin().  Instead of using this function, drivers
369   * should most likely call ptp_find_pin() directly from their
370   * ptp_clock_info::enable() method.
371   *
372  * @ptp:    The clock obtained from ptp_clock_register().
373  * @func:   One of the ptp_pin_function enumerated values.
374  * @chan:   The particular functional channel to find.
375  * Return:  Pin index in the range of zero to ptp_clock_caps.n_pins - 1,
376  *          or -1 if the auxiliary function cannot be found.
377   */
378  
379  int ptp_find_pin_unlocked(struct ptp_clock *ptp,
380  			  enum ptp_pin_function func, unsigned int chan);
381  
382  /**
383   * ptp_schedule_worker() - schedule ptp auxiliary work
384   *
385   * @ptp:    The clock obtained from ptp_clock_register().
386   * @delay:  number of jiffies to wait before queuing
387   *          See kthread_queue_delayed_work() for more info.
388   */
389  
390  int ptp_schedule_worker(struct ptp_clock *ptp, unsigned long delay);
391  
392  /**
393   * ptp_cancel_worker_sync() - cancel ptp auxiliary clock
394   *
395   * @ptp:     The clock obtained from ptp_clock_register().
396   */
397  void ptp_cancel_worker_sync(struct ptp_clock *ptp);
398  
399  #else
ptp_clock_register(struct ptp_clock_info * info,struct device * parent)400  static inline struct ptp_clock *ptp_clock_register(struct ptp_clock_info *info,
401  						   struct device *parent)
402  { return NULL; }
ptp_clock_unregister(struct ptp_clock * ptp)403  static inline int ptp_clock_unregister(struct ptp_clock *ptp)
404  { return 0; }
ptp_clock_event(struct ptp_clock * ptp,struct ptp_clock_event * event)405  static inline void ptp_clock_event(struct ptp_clock *ptp,
406  				   struct ptp_clock_event *event)
407  { }
ptp_clock_index(struct ptp_clock * ptp)408  static inline int ptp_clock_index(struct ptp_clock *ptp)
409  { return -1; }
ptp_find_pin(struct ptp_clock * ptp,enum ptp_pin_function func,unsigned int chan)410  static inline int ptp_find_pin(struct ptp_clock *ptp,
411  			       enum ptp_pin_function func, unsigned int chan)
412  { return -1; }
ptp_find_pin_unlocked(struct ptp_clock * ptp,enum ptp_pin_function func,unsigned int chan)413  static inline int ptp_find_pin_unlocked(struct ptp_clock *ptp,
414  					enum ptp_pin_function func,
415  					unsigned int chan)
416  { return -1; }
ptp_schedule_worker(struct ptp_clock * ptp,unsigned long delay)417  static inline int ptp_schedule_worker(struct ptp_clock *ptp,
418  				      unsigned long delay)
419  { return -EOPNOTSUPP; }
ptp_cancel_worker_sync(struct ptp_clock * ptp)420  static inline void ptp_cancel_worker_sync(struct ptp_clock *ptp)
421  { }
422  #endif
423  
424  #if IS_BUILTIN(CONFIG_PTP_1588_CLOCK)
425  /*
426   * These are called by the network core, and don't work if PTP is in
427   * a loadable module.
428   */
429  
430  /**
431   * ptp_get_vclocks_index() - get all vclocks index on pclock, and
432   *                           caller is responsible to free memory
433   *                           of vclock_index
434   *
435   * @pclock_index: phc index of ptp pclock.
436   * @vclock_index: pointer to pointer of vclock index.
437   *
438   * return number of vclocks.
439   */
440  int ptp_get_vclocks_index(int pclock_index, int **vclock_index);
441  
442  /**
443   * ptp_convert_timestamp() - convert timestamp to a ptp vclock time
444   *
445   * @hwtstamp:     timestamp
446   * @vclock_index: phc index of ptp vclock.
447   *
448   * Returns converted timestamp, or 0 on error.
449   */
450  ktime_t ptp_convert_timestamp(const ktime_t *hwtstamp, int vclock_index);
451  #else
ptp_get_vclocks_index(int pclock_index,int ** vclock_index)452  static inline int ptp_get_vclocks_index(int pclock_index, int **vclock_index)
453  { return 0; }
ptp_convert_timestamp(const ktime_t * hwtstamp,int vclock_index)454  static inline ktime_t ptp_convert_timestamp(const ktime_t *hwtstamp,
455  					    int vclock_index)
456  { return 0; }
457  
458  #endif
459  
ptp_read_system_prets(struct ptp_system_timestamp * sts)460  static inline void ptp_read_system_prets(struct ptp_system_timestamp *sts)
461  {
462  	if (sts) {
463  		switch (sts->clockid) {
464  		case CLOCK_REALTIME:
465  			ktime_get_real_ts64(&sts->pre_ts);
466  			break;
467  		case CLOCK_MONOTONIC:
468  			ktime_get_ts64(&sts->pre_ts);
469  			break;
470  		case CLOCK_MONOTONIC_RAW:
471  			ktime_get_raw_ts64(&sts->pre_ts);
472  			break;
473  		default:
474  			break;
475  		}
476  	}
477  }
478  
ptp_read_system_postts(struct ptp_system_timestamp * sts)479  static inline void ptp_read_system_postts(struct ptp_system_timestamp *sts)
480  {
481  	if (sts) {
482  		switch (sts->clockid) {
483  		case CLOCK_REALTIME:
484  			ktime_get_real_ts64(&sts->post_ts);
485  			break;
486  		case CLOCK_MONOTONIC:
487  			ktime_get_ts64(&sts->post_ts);
488  			break;
489  		case CLOCK_MONOTONIC_RAW:
490  			ktime_get_raw_ts64(&sts->post_ts);
491  			break;
492  		default:
493  			break;
494  		}
495  	}
496  }
497  
498  #endif
499