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