1/*-
2 * SPDX-License-Identifier: Beerware
3 *
4 * ----------------------------------------------------------------------------
5 * "THE BEER-WARE LICENSE" (Revision 42):
6 * <phk@FreeBSD.org> wrote this file.  As long as you retain this notice you
7 * can do whatever you want with this stuff. If we meet some day, and you think
8 * this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
9 * ----------------------------------------------------------------------------
10 *
11 * Copyright (c) 2011 The FreeBSD Foundation
12 * All rights reserved.
13 *
14 * Portions of this software were developed by Julien Ridoux at the University
15 * of Melbourne under sponsorship from the FreeBSD Foundation.
16 *
17 * $FreeBSD$
18 *
19 * The is a FreeBSD version of the RFC 2783 API for Pulse Per Second
20 * timing interfaces.
21 */
22
23#ifndef _SYS_TIMEPPS_H_
24#define _SYS_TIMEPPS_H_
25
26#include <sys/_ffcounter.h>
27#include <sys/ioccom.h>
28#include <sys/time.h>
29
30#define PPS_API_VERS_1	1
31
32typedef int pps_handle_t;
33
34typedef unsigned pps_seq_t;
35
36typedef struct ntp_fp {
37	unsigned int	integral;
38	unsigned int	fractional;
39} ntp_fp_t;
40
41typedef union pps_timeu {
42	struct timespec	tspec;
43	ntp_fp_t	ntpfp;
44	unsigned long	longpad[3];
45} pps_timeu_t;
46
47typedef struct {
48	pps_seq_t	assert_sequence;	/* assert event seq # */
49	pps_seq_t	clear_sequence;		/* clear event seq # */
50	pps_timeu_t	assert_tu;
51	pps_timeu_t	clear_tu;
52	int		current_mode;		/* current mode bits */
53} pps_info_t;
54
55typedef struct {
56	pps_seq_t	assert_sequence;	/* assert event seq # */
57	pps_seq_t	clear_sequence;		/* clear event seq # */
58	pps_timeu_t	assert_tu;
59	pps_timeu_t	clear_tu;
60	ffcounter	assert_ffcount;		/* ffcounter on assert event */
61	ffcounter	clear_ffcount;		/* ffcounter on clear event */
62	int		current_mode;		/* current mode bits */
63} pps_info_ffc_t;
64
65#define assert_timestamp        assert_tu.tspec
66#define clear_timestamp         clear_tu.tspec
67
68#define assert_timestamp_ntpfp  assert_tu.ntpfp
69#define clear_timestamp_ntpfp   clear_tu.ntpfp
70
71typedef struct {
72	int api_version;			/* API version # */
73	int mode;				/* mode bits */
74	pps_timeu_t assert_off_tu;
75	pps_timeu_t clear_off_tu;
76} pps_params_t;
77
78#define assert_offset   assert_off_tu.tspec
79#define clear_offset    clear_off_tu.tspec
80
81#define assert_offset_ntpfp     assert_off_tu.ntpfp
82#define clear_offset_ntpfp      clear_off_tu.ntpfp
83
84#define PPS_CAPTUREASSERT	0x01
85#define PPS_CAPTURECLEAR	0x02
86#define PPS_CAPTUREBOTH		0x03
87
88#define PPS_OFFSETASSERT	0x10
89#define PPS_OFFSETCLEAR		0x20
90
91#define PPS_ECHOASSERT		0x40
92#define PPS_ECHOCLEAR		0x80
93
94#define PPS_CANWAIT		0x100
95#define PPS_CANPOLL		0x200
96
97#define PPS_TSFMT_TSPEC		0x1000
98#define PPS_TSFMT_NTPFP		0x2000
99
100#define	PPS_TSCLK_FBCK		0x10000
101#define	PPS_TSCLK_FFWD		0x20000
102#define	PPS_TSCLK_MASK		0x30000
103
104#define PPS_KC_HARDPPS		0
105#define PPS_KC_HARDPPS_PLL	1
106#define PPS_KC_HARDPPS_FLL	2
107
108struct pps_fetch_args {
109	int tsformat;
110	pps_info_t	pps_info_buf;
111	struct timespec	timeout;
112};
113
114struct pps_fetch_ffc_args {
115	int		tsformat;
116	pps_info_ffc_t	pps_info_buf_ffc;
117	struct timespec	timeout;
118};
119
120struct pps_kcbind_args {
121	int kernel_consumer;
122	int edge;
123	int tsformat;
124};
125
126#define PPS_IOC_CREATE		_IO('1', 1)
127#define PPS_IOC_DESTROY		_IO('1', 2)
128#define PPS_IOC_SETPARAMS	_IOW('1', 3, pps_params_t)
129#define PPS_IOC_GETPARAMS	_IOR('1', 4, pps_params_t)
130#define PPS_IOC_GETCAP		_IOR('1', 5, int)
131#define PPS_IOC_FETCH		_IOWR('1', 6, struct pps_fetch_args)
132#define PPS_IOC_KCBIND		_IOW('1', 7, struct pps_kcbind_args)
133#define	PPS_IOC_FETCH_FFCOUNTER	_IOWR('1', 8, struct pps_fetch_ffc_args)
134
135#ifdef _KERNEL
136
137struct mtx;
138
139#define	KCMODE_EDGEMASK		0x03
140#define	KCMODE_ABIFLAG		0x80000000 /* Internal use: abi-aware driver. */
141
142#define	PPS_ABI_VERSION		1
143
144#define	PPSFLAG_MTX_SPIN	0x01	/* Driver mtx is MTX_SPIN type. */
145
146struct pps_state {
147	/* Capture information. */
148	struct timehands *capth;
149	struct fftimehands *capffth;
150	unsigned	capgen;
151	unsigned	capcount;
152
153	/* State information. */
154	pps_params_t	ppsparam;
155	pps_info_t	ppsinfo;
156	pps_info_ffc_t	ppsinfo_ffc;
157	int		kcmode;
158	int		ppscap;
159	struct timecounter *ppstc;
160	unsigned	ppscount[3];
161	/*
162	 * The following fields are valid if the driver calls pps_init_abi().
163	 */
164	uint16_t	driver_abi;	/* Driver sets before pps_init_abi(). */
165	uint16_t	kernel_abi;	/* Kernel sets during pps_init_abi(). */
166	struct mtx	*driver_mtx;	/* Optional, valid if non-NULL. */
167	uint32_t	flags;
168};
169
170void pps_capture(struct pps_state *pps);
171void pps_event(struct pps_state *pps, int event);
172void pps_init(struct pps_state *pps);
173void pps_init_abi(struct pps_state *pps);
174int pps_ioctl(unsigned long cmd, caddr_t data, struct pps_state *pps);
175void hardpps(struct timespec *tsp, long nsec);
176
177#else /* !_KERNEL */
178
179static __inline int
180time_pps_create(int filedes, pps_handle_t *handle)
181{
182	int error;
183
184	*handle = -1;
185	error = ioctl(filedes, PPS_IOC_CREATE, 0);
186	if (error < 0)
187		return (-1);
188	*handle = filedes;
189	return (0);
190}
191
192static __inline int
193time_pps_destroy(pps_handle_t handle)
194{
195	return (ioctl(handle, PPS_IOC_DESTROY, 0));
196}
197
198static __inline int
199time_pps_setparams(pps_handle_t handle, const pps_params_t *ppsparams)
200{
201	return (ioctl(handle, PPS_IOC_SETPARAMS, ppsparams));
202}
203
204static __inline int
205time_pps_getparams(pps_handle_t handle, pps_params_t *ppsparams)
206{
207	return (ioctl(handle, PPS_IOC_GETPARAMS, ppsparams));
208}
209
210static __inline int
211time_pps_getcap(pps_handle_t handle, int *mode)
212{
213	return (ioctl(handle, PPS_IOC_GETCAP, mode));
214}
215
216static __inline int
217time_pps_fetch(pps_handle_t handle, const int tsformat,
218	pps_info_t *ppsinfobuf, const struct timespec *timeout)
219{
220	int error;
221	struct pps_fetch_args arg;
222
223	arg.tsformat = tsformat;
224	if (timeout == NULL) {
225		arg.timeout.tv_sec = -1;
226		arg.timeout.tv_nsec = -1;
227	} else
228		arg.timeout = *timeout;
229	error = ioctl(handle, PPS_IOC_FETCH, &arg);
230	*ppsinfobuf = arg.pps_info_buf;
231	return (error);
232}
233
234static __inline int
235time_pps_fetch_ffc(pps_handle_t handle, const int tsformat,
236	pps_info_ffc_t *ppsinfobuf, const struct timespec *timeout)
237{
238	struct pps_fetch_ffc_args arg;
239	int error;
240
241	arg.tsformat = tsformat;
242	if (timeout == NULL) {
243		arg.timeout.tv_sec = -1;
244		arg.timeout.tv_nsec = -1;
245	} else {
246		arg.timeout = *timeout;
247	}
248	error = ioctl(handle, PPS_IOC_FETCH_FFCOUNTER, &arg);
249	*ppsinfobuf = arg.pps_info_buf_ffc;
250	return (error);
251}
252
253static __inline int
254time_pps_kcbind(pps_handle_t handle, const int kernel_consumer,
255	const int edge, const int tsformat)
256{
257	struct pps_kcbind_args arg;
258
259	arg.kernel_consumer = kernel_consumer;
260	arg.edge = edge;
261	arg.tsformat = tsformat;
262	return (ioctl(handle, PPS_IOC_KCBIND, &arg));
263}
264
265#endif /* KERNEL */
266
267#endif /* !_SYS_TIMEPPS_H_ */
268