[thirdparty/linux.git] / include / linux / ptp_clock_kernel.h

/* SPDX-License-Identifier: GPL-2.0-or-later */
/*
 * PTP 1588 clock support
 *
 * Copyright (C) 2010 OMICRON electronics GmbH
 */

#ifndef _PTP_CLOCK_KERNEL_H_
#define _PTP_CLOCK_KERNEL_H_

#include <linux/device.h>
#include <linux/pps_kernel.h>
#include <linux/ptp_clock.h>


struct ptp_clock_request {
	enum {
		PTP_CLK_REQ_EXTTS,
		PTP_CLK_REQ_PEROUT,
		PTP_CLK_REQ_PPS,
	} type;
	union {
		struct ptp_extts_request extts;
		struct ptp_perout_request perout;
	};
};

struct system_device_crosststamp;

/**
 * struct ptp_system_timestamp - system time corresponding to a PHC timestamp
 */
struct ptp_system_timestamp {
	struct timespec64 pre_ts;
	struct timespec64 post_ts;
};

/**
 * struct ptp_clock_info - decribes a PTP hardware clock
 *
 * @owner:     The clock driver should set to THIS_MODULE.
 * @name:      A short "friendly name" to identify the clock and to
 *             help distinguish PHY based devices from MAC based ones.
 *             The string is not meant to be a unique id.
 * @max_adj:   The maximum possible frequency adjustment, in parts per billon.
 * @n_alarm:   The number of programmable alarms.
 * @n_ext_ts:  The number of external time stamp channels.
 * @n_per_out: The number of programmable periodic signals.
 * @n_pins:    The number of programmable pins.
 * @pps:       Indicates whether the clock supports a PPS callback.
 * @pin_config: Array of length 'n_pins'. If the number of
 *              programmable pins is nonzero, then drivers must
 *              allocate and initialize this array.
 *
 * clock operations
 *
 * @adjfine:  Adjusts the frequency of the hardware clock.
 *            parameter scaled_ppm: Desired frequency offset from
 *            nominal frequency in parts per million, but with a
 *            16 bit binary fractional field.
 *
 * @adjfreq:  Adjusts the frequency of the hardware clock.
 *            This method is deprecated.  New drivers should implement
 *            the @adjfine method instead.
 *            parameter delta: Desired frequency offset from nominal frequency
 *            in parts per billion
 *
 * @adjtime:  Shifts the time of the hardware clock.
 *            parameter delta: Desired change in nanoseconds.
 *
 * @gettime64:  Reads the current time from the hardware clock.
 *              This method is deprecated.  New drivers should implement
 *              the @gettimex64 method instead.
 *              parameter ts: Holds the result.
 *
 * @gettimex64:  Reads the current time from the hardware clock and optionally
 *               also the system clock.
 *               parameter ts: Holds the PHC timestamp.
 *               parameter sts: If not NULL, it holds a pair of timestamps from
 *               the system clock. The first reading is made right before
 *               reading the lowest bits of the PHC timestamp and the second
 *               reading immediately follows that.
 *
 * @getcrosststamp:  Reads the current time from the hardware clock and
 *                   system clock simultaneously.
 *                   parameter cts: Contains timestamp (device,system) pair,
 *                   where system time is realtime and monotonic.
 *
 * @settime64:  Set the current time on the hardware clock.
 *              parameter ts: Time value to set.
 *
 * @enable:   Request driver to enable or disable an ancillary feature.
 *            parameter request: Desired resource to enable or disable.
 *            parameter on: Caller passes one to enable or zero to disable.
 *
 * @verify:   Confirm that a pin can perform a given function. The PTP
 *            Hardware Clock subsystem maintains the 'pin_config'
 *            array on behalf of the drivers, but the PHC subsystem
 *            assumes that every pin can perform every function. This
 *            hook gives drivers a way of telling the core about
 *            limitations on specific pins. This function must return
 *            zero if the function can be assigned to this pin, and
 *            nonzero otherwise.
 *            parameter pin: index of the pin in question.
 *            parameter func: the desired function to use.
 *            parameter chan: the function channel index to use.
 *
 * @do_aux_work:  Request driver to perform auxiliary (periodic) operations
 *                Driver should return delay of the next auxiliary work
 *                scheduling time (>=0) or negative value in case further
 *                scheduling is not required.
 *
 * Drivers should embed their ptp_clock_info within a private
 * structure, obtaining a reference to it using container_of().
 *
 * The callbacks must all return zero on success, non-zero otherwise.
 */

struct ptp_clock_info {
	struct module *owner;
	char name[16];
	s32 max_adj;
	int n_alarm;
	int n_ext_ts;
	int n_per_out;
	int n_pins;
	int pps;
	struct ptp_pin_desc *pin_config;
	int (*adjfine)(struct ptp_clock_info *ptp, long scaled_ppm);
	int (*adjfreq)(struct ptp_clock_info *ptp, s32 delta);
	int (*adjtime)(struct ptp_clock_info *ptp, s64 delta);
	int (*gettime64)(struct ptp_clock_info *ptp, struct timespec64 *ts);
	int (*gettimex64)(struct ptp_clock_info *ptp, struct timespec64 *ts,
			  struct ptp_system_timestamp *sts);
	int (*getcrosststamp)(struct ptp_clock_info *ptp,
			      struct system_device_crosststamp *cts);
	int (*settime64)(struct ptp_clock_info *p, const struct timespec64 *ts);
	int (*enable)(struct ptp_clock_info *ptp,
		      struct ptp_clock_request *request, int on);
	int (*verify)(struct ptp_clock_info *ptp, unsigned int pin,
		      enum ptp_pin_function func, unsigned int chan);
	long (*do_aux_work)(struct ptp_clock_info *ptp);
};

struct ptp_clock;

enum ptp_clock_events {
	PTP_CLOCK_ALARM,
	PTP_CLOCK_EXTTS,
	PTP_CLOCK_PPS,
	PTP_CLOCK_PPSUSR,
};

/**
 * struct ptp_clock_event - decribes a PTP hardware clock event
 *
 * @type:  One of the ptp_clock_events enumeration values.
 * @index: Identifies the source of the event.
 * @timestamp: When the event occurred (%PTP_CLOCK_EXTTS only).
 * @pps_times: When the event occurred (%PTP_CLOCK_PPSUSR only).
 */

struct ptp_clock_event {
	int type;
	int index;
	union {
		u64 timestamp;
		struct pps_event_time pps_times;
	};
};

#if IS_REACHABLE(CONFIG_PTP_1588_CLOCK)

/**
 * ptp_clock_register() - register a PTP hardware clock driver
 *
 * @info:   Structure describing the new clock.
 * @parent: Pointer to the parent device of the new clock.
 *
 * Returns a valid pointer on success or PTR_ERR on failure.  If PHC
 * support is missing at the configuration level, this function
 * returns NULL, and drivers are expected to gracefully handle that
 * case separately.
 */

extern struct ptp_clock *ptp_clock_register(struct ptp_clock_info *info,
					    struct device *parent);

/**
 * ptp_clock_unregister() - unregister a PTP hardware clock driver
 *
 * @ptp:  The clock to remove from service.
 */

extern int ptp_clock_unregister(struct ptp_clock *ptp);

/**
 * ptp_clock_event() - notify the PTP layer about an event
 *
 * @ptp:    The clock obtained from ptp_clock_register().
 * @event:  Message structure describing the event.
 */

extern void ptp_clock_event(struct ptp_clock *ptp,
			    struct ptp_clock_event *event);

/**
 * ptp_clock_index() - obtain the device index of a PTP clock
 *
 * @ptp:    The clock obtained from ptp_clock_register().
 */

extern int ptp_clock_index(struct ptp_clock *ptp);

/**
 * scaled_ppm_to_ppb() - convert scaled ppm to ppb
 *
 * @ppm:    Parts per million, but with a 16 bit binary fractional field
 */

extern s32 scaled_ppm_to_ppb(long ppm);

/**
 * ptp_find_pin() - obtain the pin index of a given auxiliary function
 *
 * The caller must hold ptp_clock::pincfg_mux.  Drivers do not have
 * access to that mutex as ptp_clock is an opaque type.  However, the
 * core code acquires the mutex before invoking the driver's
 * ptp_clock_info::enable() callback, and so drivers may call this
 * function from that context.
 *
 * @ptp:    The clock obtained from ptp_clock_register().
 * @func:   One of the ptp_pin_function enumerated values.
 * @chan:   The particular functional channel to find.
 * Return:  Pin index in the range of zero to ptp_clock_caps.n_pins - 1,
 *          or -1 if the auxiliary function cannot be found.
 */

int ptp_find_pin(struct ptp_clock *ptp,
		 enum ptp_pin_function func, unsigned int chan);

/**
 * ptp_find_pin_unlocked() - wrapper for ptp_find_pin()
 *
 * This function acquires the ptp_clock::pincfg_mux mutex before
 * invoking ptp_find_pin().  Instead of using this function, drivers
 * should most likely call ptp_find_pin() directly from their
 * ptp_clock_info::enable() method.
 *
 */

int ptp_find_pin_unlocked(struct ptp_clock *ptp,
			  enum ptp_pin_function func, unsigned int chan);

/**
 * ptp_schedule_worker() - schedule ptp auxiliary work
 *
 * @ptp:    The clock obtained from ptp_clock_register().
 * @delay:  number of jiffies to wait before queuing
 *          See kthread_queue_delayed_work() for more info.
 */

int ptp_schedule_worker(struct ptp_clock *ptp, unsigned long delay);

/**
 * ptp_cancel_worker_sync() - cancel ptp auxiliary clock
 *
 * @ptp:     The clock obtained from ptp_clock_register().
 */
void ptp_cancel_worker_sync(struct ptp_clock *ptp);

#else
static inline struct ptp_clock *ptp_clock_register(struct ptp_clock_info *info,
						   struct device *parent)
{ return NULL; }
static inline int ptp_clock_unregister(struct ptp_clock *ptp)
{ return 0; }
static inline void ptp_clock_event(struct ptp_clock *ptp,
				   struct ptp_clock_event *event)
{ }
static inline int ptp_clock_index(struct ptp_clock *ptp)
{ return -1; }
static inline int ptp_find_pin(struct ptp_clock *ptp,
			       enum ptp_pin_function func, unsigned int chan)
{ return -1; }
static inline int ptp_schedule_worker(struct ptp_clock *ptp,
				      unsigned long delay)
{ return -EOPNOTSUPP; }
static inline void ptp_cancel_worker_sync(struct ptp_clock *ptp)
{ }

#endif

static inline void ptp_read_system_prets(struct ptp_system_timestamp *sts)
{
	if (sts)
		ktime_get_real_ts64(&sts->pre_ts);
}

static inline void ptp_read_system_postts(struct ptp_system_timestamp *sts)
{
	if (sts)
		ktime_get_real_ts64(&sts->post_ts);
}

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