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  */
  49 struct ptp_system_timestamp {
  50         struct timespec64 pre_ts;
  51         struct timespec64 post_ts;
  52 };
  53
  54 /**
  55  * struct ptp_clock_info - describes a PTP hardware clock
  56  *
  57  * @owner:     The clock driver should set to THIS_MODULE.
  58  * @name:      A short "friendly name" to identify the clock and to
  59  *             help distinguish PHY based devices from MAC based ones.
  60  *             The string is not meant to be a unique id.
  61  * @max_adj:   The maximum possible frequency adjustment, in parts per billon.
  62  * @n_alarm:   The number of programmable alarms.
  63  * @n_ext_ts:  The number of external time stamp channels.
  64  * @n_per_out: The number of programmable periodic signals.
  65  * @n_pins:    The number of programmable pins.
  66  * @pps:       Indicates whether the clock supports a PPS callback.
  67  * @pin_config: Array of length 'n_pins'. If the number of
  68  *              programmable pins is nonzero, then drivers must
  69  *              allocate and initialize this array.
  70  *
  71  * clock operations
  72  *
  73  * @adjfine:  Adjusts the frequency of the hardware clock.
  74  *            parameter scaled_ppm: Desired frequency offset from
  75  *            nominal frequency in parts per million, but with a
  76  *            16 bit binary fractional field.
  77  *
  78  * @adjfreq:  Adjusts the frequency of the hardware clock.
  79  *            This method is deprecated.  New drivers should implement
  80  *            the @adjfine method instead.
  81  *            parameter delta: Desired frequency offset from nominal frequency
  82  *            in parts per billion
  83  *
  84  * @adjphase:  Adjusts the phase offset of the hardware clock.
  85  *             parameter delta: Desired change in nanoseconds.
  86  *
  87  * @adjtime:  Shifts the time of the hardware clock.
  88  *            parameter delta: Desired change in nanoseconds.
  89  *
  90  * @gettime64:  Reads the current time from the hardware clock.
  91  *              This method is deprecated.  New drivers should implement
  92  *              the @gettimex64 method instead.
  93  *              parameter ts: Holds the result.
  94  *
  95  * @gettimex64:  Reads the current time from the hardware clock and optionally
  96  *               also the system clock.
  97  *               parameter ts: Holds the PHC timestamp.
  98  *               parameter sts: If not NULL, it holds a pair of timestamps from
  99  *               the system clock. The first reading is made right before
 100  *               reading the lowest bits of the PHC timestamp and the second
 101  *               reading immediately follows that.
 102  *
 103  * @getcrosststamp:  Reads the current time from the hardware clock and
 104  *                   system clock simultaneously.
 105  *                   parameter cts: Contains timestamp (device,system) pair,
 106  *                   where system time is realtime and monotonic.
 107  *
 108  * @settime64:  Set the current time on the hardware clock.
 109  *              parameter ts: Time value to set.
 110  *
 111  * @enable:   Request driver to enable or disable an ancillary feature.
 112  *            parameter request: Desired resource to enable or disable.
 113  *            parameter on: Caller passes one to enable or zero to disable.
 114  *
 115  * @verify:   Confirm that a pin can perform a given function. The PTP
 116  *            Hardware Clock subsystem maintains the 'pin_config'
 117  *            array on behalf of the drivers, but the PHC subsystem
 118  *            assumes that every pin can perform every function. This
 119  *            hook gives drivers a way of telling the core about
 120  *            limitations on specific pins. This function must return
 121  *            zero if the function can be assigned to this pin, and
 122  *            nonzero otherwise.
 123  *            parameter pin: index of the pin in question.
 124  *            parameter func: the desired function to use.
 125  *            parameter chan: the function channel index to use.
 126  *
 127  * @do_aux_work:  Request driver to perform auxiliary (periodic) operations
 128  *                Driver should return delay of the next auxiliary work
 129  *                scheduling time (>=0) or negative value in case further
 130  *                scheduling is not required.
 131  *
 132  * Drivers should embed their ptp_clock_info within a private
 133  * structure, obtaining a reference to it using container_of().
 134  *
 135  * The callbacks must all return zero on success, non-zero otherwise.
 136  */
 137
 138 struct ptp_clock_info {
 139         struct module *owner;
 140         char name[PTP_CLOCK_NAME_LEN];
 141         s32 max_adj;
 142         int n_alarm;
 143         int n_ext_ts;
 144         int n_per_out;
 145         int n_pins;
 146         int pps;
 147         struct ptp_pin_desc *pin_config;
 148         int (*adjfine)(struct ptp_clock_info *ptp, long scaled_ppm);
 149         int (*adjfreq)(struct ptp_clock_info *ptp, s32 delta);
 150         int (*adjphase)(struct ptp_clock_info *ptp, s32 phase);
 151         int (*adjtime)(struct ptp_clock_info *ptp, s64 delta);
 152         int (*gettime64)(struct ptp_clock_info *ptp, struct timespec64 *ts);
 153         int (*gettimex64)(struct ptp_clock_info *ptp, struct timespec64 *ts,
 154                           struct ptp_system_timestamp *sts);
 155         int (*getcrosststamp)(struct ptp_clock_info *ptp,
 156                               struct system_device_crosststamp *cts);
 157         int (*settime64)(struct ptp_clock_info *p, const struct timespec64 *ts);
 158         int (*enable)(struct ptp_clock_info *ptp,
 159                       struct ptp_clock_request *request, int on);
 160         int (*verify)(struct ptp_clock_info *ptp, unsigned int pin,
 161                       enum ptp_pin_function func, unsigned int chan);
 162         long (*do_aux_work)(struct ptp_clock_info *ptp);
 163 };
 164
 165 struct ptp_clock;
 166
 167 enum ptp_clock_events {
 168         PTP_CLOCK_ALARM,
 169         PTP_CLOCK_EXTTS,
 170         PTP_CLOCK_PPS,
 171         PTP_CLOCK_PPSUSR,
 172 };
 173
 174 /**
 175  * struct ptp_clock_event - decribes a PTP hardware clock event
 176  *
 177  * @type:  One of the ptp_clock_events enumeration values.
 178  * @index: Identifies the source of the event.
 179  * @timestamp: When the event occurred (%PTP_CLOCK_EXTTS only).
 180  * @pps_times: When the event occurred (%PTP_CLOCK_PPSUSR only).
 181  */
 182
 183 struct ptp_clock_event {
 184         int type;
 185         int index;
 186         union {
 187                 u64 timestamp;
 188                 struct pps_event_time pps_times;
 189         };
 190 };
 191
 192 /**
 193  * scaled_ppm_to_ppb() - convert scaled ppm to ppb
 194  *
 195  * @ppm:    Parts per million, but with a 16 bit binary fractional field
 196  */
 197 static inline long scaled_ppm_to_ppb(long ppm)
 198 {
 199         /*
 200          * The 'freq' field in the 'struct timex' is in parts per
 201          * million, but with a 16 bit binary fractional field.
 202          *
 203          * We want to calculate
 204          *
 205          *    ppb = scaled_ppm * 1000 / 2^16
 206          *
 207          * which simplifies to
 208          *
 209          *    ppb = scaled_ppm * 125 / 2^13
 210          */
 211         s64 ppb = 1 + ppm;
 212
 213         ppb *= 125;
 214         ppb >>= 13;
 215         return (long)ppb;
 216 }
 217
 218 #if IS_ENABLED(CONFIG_PTP_1588_CLOCK)
 219
 220 /**
 221  * ptp_clock_register() - register a PTP hardware clock driver
 222  *
 223  * @info:   Structure describing the new clock.
 224  * @parent: Pointer to the parent device of the new clock.
 225  *
 226  * Returns a valid pointer on success or PTR_ERR on failure.  If PHC
 227  * support is missing at the configuration level, this function
 228  * returns NULL, and drivers are expected to gracefully handle that
 229  * case separately.
 230  */
 231
 232 extern struct ptp_clock *ptp_clock_register(struct ptp_clock_info *info,
 233                                             struct device *parent);
 234
 235 /**
 236  * ptp_clock_unregister() - unregister a PTP hardware clock driver
 237  *
 238  * @ptp:  The clock to remove from service.
 239  */
 240
 241 extern int ptp_clock_unregister(struct ptp_clock *ptp);
 242
 243 /**
 244  * ptp_clock_event() - notify the PTP layer about an event
 245  *
 246  * @ptp:    The clock obtained from ptp_clock_register().
 247  * @event:  Message structure describing the event.
 248  */
 249
 250 extern void ptp_clock_event(struct ptp_clock *ptp,
 251                             struct ptp_clock_event *event);
 252
 253 /**
 254  * ptp_clock_index() - obtain the device index of a PTP clock
 255  *
 256  * @ptp:    The clock obtained from ptp_clock_register().
 257  */
 258
 259 extern int ptp_clock_index(struct ptp_clock *ptp);
 260
 261 /**
 262  * ptp_find_pin() - obtain the pin index of a given auxiliary function
 263  *
 264  * The caller must hold ptp_clock::pincfg_mux.  Drivers do not have
 265  * access to that mutex as ptp_clock is an opaque type.  However, the
 266  * core code acquires the mutex before invoking the driver's
 267  * ptp_clock_info::enable() callback, and so drivers may call this
 268  * function from that context.
 269  *
 270  * @ptp:    The clock obtained from ptp_clock_register().
 271  * @func:   One of the ptp_pin_function enumerated values.
 272  * @chan:   The particular functional channel to find.
 273  * Return:  Pin index in the range of zero to ptp_clock_caps.n_pins - 1,
 274  *          or -1 if the auxiliary function cannot be found.
 275  */
 276
 277 int ptp_find_pin(struct ptp_clock *ptp,
 278                  enum ptp_pin_function func, unsigned int chan);
 279
 280 /**
 281  * ptp_find_pin_unlocked() - wrapper for ptp_find_pin()
 282  *
 283  * This function acquires the ptp_clock::pincfg_mux mutex before
 284  * invoking ptp_find_pin().  Instead of using this function, drivers
 285  * should most likely call ptp_find_pin() directly from their
 286  * ptp_clock_info::enable() method.
 287  *
 288  */
 289
 290 int ptp_find_pin_unlocked(struct ptp_clock *ptp,
 291                           enum ptp_pin_function func, unsigned int chan);
 292
 293 /**
 294  * ptp_schedule_worker() - schedule ptp auxiliary work
 295  *
 296  * @ptp:    The clock obtained from ptp_clock_register().
 297  * @delay:  number of jiffies to wait before queuing
 298  *          See kthread_queue_delayed_work() for more info.
 299  */
 300
 301 int ptp_schedule_worker(struct ptp_clock *ptp, unsigned long delay);
 302
 303 /**
 304  * ptp_cancel_worker_sync() - cancel ptp auxiliary clock
 305  *
 306  * @ptp:     The clock obtained from ptp_clock_register().
 307  */
 308 void ptp_cancel_worker_sync(struct ptp_clock *ptp);
 309
 310 #else
 311 static inline struct ptp_clock *ptp_clock_register(struct ptp_clock_info *info,
 312                                                    struct device *parent)
 313 { return NULL; }
 314 static inline int ptp_clock_unregister(struct ptp_clock *ptp)
 315 { return 0; }
 316 static inline void ptp_clock_event(struct ptp_clock *ptp,
 317                                    struct ptp_clock_event *event)
 318 { }
 319 static inline int ptp_clock_index(struct ptp_clock *ptp)
 320 { return -1; }
 321 static inline int ptp_find_pin(struct ptp_clock *ptp,
 322                                enum ptp_pin_function func, unsigned int chan)
 323 { return -1; }
 324 static inline int ptp_schedule_worker(struct ptp_clock *ptp,
 325                                       unsigned long delay)
 326 { return -EOPNOTSUPP; }
 327 static inline void ptp_cancel_worker_sync(struct ptp_clock *ptp)
 328 { }
 329 #endif
 330
 331 #if IS_BUILTIN(CONFIG_PTP_1588_CLOCK)
 332 /*
 333  * These are called by the network core, and don't work if PTP is in
 334  * a loadable module.
 335  */
 336
 337 /**
 338  * ptp_get_vclocks_index() - get all vclocks index on pclock, and
 339  *                           caller is responsible to free memory
 340  *                           of vclock_index
 341  *
 342  * @pclock_index: phc index of ptp pclock.
 343  * @vclock_index: pointer to pointer of vclock index.
 344  *
 345  * return number of vclocks.
 346  */
 347 int ptp_get_vclocks_index(int pclock_index, int **vclock_index);
 348
 349 /**
 350  * ptp_convert_timestamp() - convert timestamp to a ptp vclock time
 351  *
 352  * @hwtstamps:    skb_shared_hwtstamps structure pointer
 353  * @vclock_index: phc index of ptp vclock.
 354  */
 355 void ptp_convert_timestamp(struct skb_shared_hwtstamps *hwtstamps,
 356                            int vclock_index);
 357 #else
 358 static inline int ptp_get_vclocks_index(int pclock_index, int **vclock_index)
 359 { return 0; }
 360 static inline void ptp_convert_timestamp(struct skb_shared_hwtstamps *hwtstamps,
 361                                          int vclock_index)
 362 { }
 363
 364 #endif
 365
 366 static inline void ptp_read_system_prets(struct ptp_system_timestamp *sts)
 367 {
 368         if (sts)
 369                 ktime_get_real_ts64(&sts->pre_ts);
 370 }
 371
 372 static inline void ptp_read_system_postts(struct ptp_system_timestamp *sts)
 373 {
 374         if (sts)
 375                 ktime_get_real_ts64(&sts->post_ts);
 376 }
 377
 378 #endif