ptp_clock_kernel.h

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