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