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