contrib/ntp/include/timepps-Solaris.h

   1 /***********************************************************************
   2  *                                                                     *
   3  * Copyright (c) David L. Mills 1999-2000                              *
   4  *                                                                     *
   5  * Permission to use, copy, modify, and distribute this software and   *
   6  * its documentation for any purpose and without fee is hereby         *
   7  * granted, provided that the above copyright notice appears in all    *
   8  * copies and that both the copyright notice and this permission       *
   9  * notice appear in supporting documentation, and that the name        *
  10  * University of Delaware not be used in advertising or publicity      *
  11  * pertaining to distribution of the software without specific,        *
  12  * written prior permission. The University of Delaware makes no       *
  13  * representations about the suitability this software for any         *
  14  * purpose. It is provided "as is" without express or implied          *
  15  * warranty.                                                           *
  16  *                                                                     *
  17  ***********************************************************************
  18  *                                                                     *
  19  * This header file complies with "Pulse-Per-Second API for UNIX-like  *
  20  * Operating Systems, Version 1.0", rfc2783. Credit is due Jeff Mogul  *
  21  * and Marc Brett, from whom much of this code was shamelessly stolen. *
  22  *                                                                     *
  23  * this modified timepps.h can be used to provide a PPSAPI interface   *
  24  * to a machine running Solaris (2.6 and above).                       *
  25  *                                                                     *
  26  ***********************************************************************
  27  *                                                                     *
  28  * A full PPSAPI interface to the Solaris kernel would be better, but  *
  29  * this at least removes the necessity for special coding from the NTP *
  30  * NTP drivers.                                                        *
  31  *                                                                     *
  32  ***********************************************************************
  33  *                                                                     *
  34  * Some of this include file                                           *
  35  * Copyright (c) 1999 by Ulrich Windl,                                 *
  36  *      based on code by Reg Clemens <reg@dwf.com>                     *
  37  *              based on code by Poul-Henning Kamp <phk@FreeBSD.org>   *
  38  *                                                                     *
  39  ***********************************************************************
  40  *                                                                     *
  41  * "THE BEER-WARE LICENSE" (Revision 42):                              *
  42  * <phk@FreeBSD.org> wrote this file.  As long as you retain this      *
  43  * notice you can do whatever you want with this stuff. If we meet some*
  44  * day, and you think this stuff is worth it, you can buy me a beer    *
  45  * in return.   Poul-Henning Kamp                                      *
  46  *                                                                     *
  47  **********************************************************************/
  48
  49 /* Solaris version, TIOCGPPSEV and TIOCSPPS assumed to exist. */
  50
  51 #ifndef _SYS_TIMEPPS_H_
  52 #define _SYS_TIMEPPS_H_
  53
  54 #include <termios.h>    /* to get TOCGPPSEV and TIOCSPPS */
  55
  56 /* Implementation note: the logical states ``assert'' and ``clear''
  57  * are implemented in terms of the UART register, i.e. ``assert''
  58  * means the bit is set.
  59  */
  60
  61 /*
  62  * The following definitions are architecture independent
  63  */
  64
  65 #define PPS_API_VERS_1  1               /* API version number */
  66 #define PPS_JAN_1970    2208988800UL    /* 1970 - 1900 in seconds */
  67 #define PPS_NANOSECOND  1000000000L     /* one nanosecond in decimal */
  68 #define PPS_FRAC        4294967296.     /* 2^32 as a double */
  69
  70 #define PPS_NORMALIZE(x)        /* normalize timespec */ \
  71         do { \
  72                 if ((x).tv_nsec >= PPS_NANOSECOND) { \
  73                         (x).tv_nsec -= PPS_NANOSECOND; \
  74                         (x).tv_sec++; \
  75                 } else if ((x).tv_nsec < 0) { \
  76                         (x).tv_nsec += PPS_NANOSECOND; \
  77                         (x).tv_sec--; \
  78                 } \
  79         } while (0)
  80
  81 #define PPS_TSPECTONTP(x)       /* convert timespec to l_fp */ \
  82         do { \
  83                 double d_temp; \
  84         \
  85                 (x).integral += (unsigned int)PPS_JAN_1970; \
  86                 d_temp = (x).fractional * PPS_FRAC / PPS_NANOSECOND; \
  87                 if (d_temp >= PPS_FRAC) \
  88                         (x).integral++; \
  89                 (x).fractional = (unsigned int)d_temp; \
  90         } while (0)
  91
  92 /*
  93  * Device/implementation parameters (mode)
  94  */
  95
  96 #define PPS_CAPTUREASSERT       0x01    /* capture assert events */
  97 #define PPS_CAPTURECLEAR        0x02    /* capture clear events */
  98 #define PPS_CAPTUREBOTH         0x03    /* capture assert and clear events */
  99
 100 #define PPS_OFFSETASSERT        0x10    /* apply compensation for assert ev. */
 101 #define PPS_OFFSETCLEAR         0x20    /* apply compensation for clear ev. */
 102 #define PPS_OFFSETBOTH          0x30    /* apply compensation for both */
 103
 104 #define PPS_CANWAIT             0x100   /* Can we wait for an event? */
 105 #define PPS_CANPOLL             0x200   /* "This bit is reserved for */
 106
 107 /*
 108  * Kernel actions (mode)
 109  */
 110
 111 #define PPS_ECHOASSERT          0x40    /* feed back assert event to output */
 112 #define PPS_ECHOCLEAR           0x80    /* feed back clear event to output */
 113
 114 /*
 115  * Timestamp formats (tsformat)
 116  */
 117
 118 #define PPS_TSFMT_TSPEC         0x1000  /* select timespec format */
 119 #define PPS_TSFMT_NTPFP         0x2000  /* select NTP format */
 120
 121 /*
 122  * Kernel discipline actions (not used in Solaris)
 123  */
 124
 125 #define PPS_KC_HARDPPS          0       /* enable kernel consumer */
 126 #define PPS_KC_HARDPPS_PLL      1       /* phase-lock mode */
 127 #define PPS_KC_HARDPPS_FLL      2       /* frequency-lock mode */
 128
 129 /*
 130  * Type definitions
 131  */
 132
 133 typedef unsigned long pps_seq_t;        /* sequence number */
 134
 135 typedef struct ntp_fp {
 136         unsigned int    integral;
 137         unsigned int    fractional;
 138 } ntp_fp_t;                             /* NTP-compatible time stamp */
 139
 140 typedef union pps_timeu {               /* timestamp format */
 141         struct timespec tspec;
 142         ntp_fp_t        ntpfp;
 143         unsigned long   longpad[3];
 144 } pps_timeu_t;                          /* generic data type to represent time stamps */
 145
 146 /*
 147  * Timestamp information structure
 148  */
 149
 150 typedef struct pps_info {
 151         pps_seq_t       assert_sequence;        /* seq. num. of assert event */
 152         pps_seq_t       clear_sequence;         /* seq. num. of clear event */
 153         pps_timeu_t     assert_tu;              /* time of assert event */
 154         pps_timeu_t     clear_tu;               /* time of clear event */
 155         int             current_mode;           /* current mode bits */
 156 } pps_info_t;
 157
 158 #define assert_timestamp        assert_tu.tspec
 159 #define clear_timestamp         clear_tu.tspec
 160
 161 #define assert_timestamp_ntpfp  assert_tu.ntpfp
 162 #define clear_timestamp_ntpfp   clear_tu.ntpfp
 163
 164 /*
 165  * Parameter structure
 166  */
 167
 168 typedef struct pps_params {
 169         int             api_version;    /* API version # */
 170         int             mode;           /* mode bits */
 171         pps_timeu_t assert_off_tu;      /* offset compensation for assert */
 172         pps_timeu_t clear_off_tu;       /* offset compensation for clear */
 173 } pps_params_t;
 174
 175 #define assert_offset           assert_off_tu.tspec
 176 #define clear_offset            clear_off_tu.tspec
 177
 178 #define assert_offset_ntpfp     assert_off_tu.ntpfp
 179 #define clear_offset_ntpfp      clear_off_tu.ntpfp
 180
 181 /*
 182  * The following definitions are architecture-dependent
 183  */
 184
 185 #define PPS_CAP (PPS_CAPTUREASSERT | PPS_OFFSETASSERT | PPS_TSFMT_TSPEC | PPS_TSFMT_NTPFP)
 186 #define PPS_RO  (PPS_CANWAIT | PPS_CANPOLL | PPS_TSFMT_TSPEC | PPS_TSFMT_NTPFP)
 187
 188 typedef struct {
 189         int filedes;            /* file descriptor */
 190         pps_params_t params;    /* PPS parameters set by user */
 191 } pps_unit_t;
 192
 193 typedef pps_unit_t* pps_handle_t; /* pps handlebars */
 194
 195 /*
 196  *------ Here begins the implementation-specific part! ------
 197  */
 198
 199 #include <errno.h>
 200
 201 /*
 202  * create PPS handle from file descriptor
 203  */
 204
 205 static inline int
 206 time_pps_create(
 207         int filedes,            /* file descriptor */
 208         pps_handle_t *handle    /* returned handle */
 209         )
 210 {
 211         int one = 1;
 212
 213         /*
 214          * Check for valid arguments and attach PPS signal.
 215          */
 216
 217         if (!handle) {
 218                 errno = EFAULT;
 219                 return (-1);    /* null pointer */
 220         }
 221
 222         if (ioctl(filedes, TIOCSPPS, &one) < 0) {
 223                 perror("refclock_ioctl: TIOCSPPS failed:");
 224                 return (-1);
 225         }
 226
 227         /*
 228          * Allocate and initialize default unit structure.
 229          */
 230
 231         *handle = malloc(sizeof(pps_unit_t));
 232         if (!(*handle)) {
 233                 errno = EBADF;
 234                 return (-1);    /* what, no memory? */
 235         }
 236
 237         memset(*handle, 0, sizeof(pps_unit_t));
 238         (*handle)->filedes = filedes;
 239         (*handle)->params.api_version = PPS_API_VERS_1;
 240         (*handle)->params.mode = PPS_CAPTUREASSERT | PPS_TSFMT_TSPEC;
 241         return (0);
 242 }
 243
 244 /*
 245  * release PPS handle
 246  */
 247
 248 static inline int
 249 time_pps_destroy(
 250         pps_handle_t handle
 251         )
 252 {
 253         /*
 254          * Check for valid arguments and detach PPS signal.
 255          */
 256
 257         if (!handle) {
 258                 errno = EBADF;
 259                 return (-1);    /* bad handle */
 260         }
 261         free(handle);
 262         return (0);
 263 }
 264
 265 /*
 266  * set parameters for handle
 267  */
 268
 269 static inline int
 270 time_pps_setparams(
 271         pps_handle_t handle,
 272         const pps_params_t *params
 273         )
 274 {
 275         int     mode, mode_in;
 276         /*
 277          * Check for valid arguments and set parameters.
 278          */
 279
 280         if (!handle) {
 281                 errno = EBADF;
 282                 return (-1);    /* bad handle */
 283         }
 284
 285         if (!params) {
 286                 errno = EFAULT;
 287                 return (-1);    /* bad argument */
 288         }
 289
 290         /*
 291          * There was no reasonable consensu in the API working group.
 292          * I require `api_version' to be set!
 293          */
 294
 295         if (params->api_version != PPS_API_VERS_1) {
 296                 errno = EINVAL;
 297                 return(-1);
 298         }
 299
 300         /*
 301          * only settable modes are PPS_CAPTUREASSERT and PPS_OFFSETASSERT
 302          */
 303
 304         mode_in = params->mode;
 305
 306         /* turn off read-only bits */
 307
 308         mode_in &= ~PPS_RO;
 309
 310         /* test remaining bits, should only have captureassert and/or offsetassert */
 311
 312         if (mode_in & ~(PPS_CAPTUREASSERT | PPS_OFFSETASSERT)) {
 313                 errno = EOPNOTSUPP;
 314                 return(-1);
 315         }
 316
 317         /*
 318          * ok, ready to go.
 319          */
 320
 321         mode = handle->params.mode;
 322         memcpy(&handle->params, params, sizeof(pps_params_t));
 323         handle->params.api_version = PPS_API_VERS_1;
 324         handle->params.mode = mode | mode_in;
 325         return (0);
 326 }
 327
 328 /*
 329  * get parameters for handle
 330  */
 331
 332 static inline int
 333 time_pps_getparams(
 334         pps_handle_t handle,
 335         pps_params_t *params
 336         )
 337 {
 338         /*
 339          * Check for valid arguments and get parameters.
 340          */
 341
 342         if (!handle) {
 343                 errno = EBADF;
 344                 return (-1);    /* bad handle */
 345         }
 346
 347         if (!params) {
 348                 errno = EFAULT;
 349                 return (-1);    /* bad argument */
 350         }
 351
 352         memcpy(params, &handle->params, sizeof(pps_params_t));
 353         return (0);
 354 }
 355
 356 /* (
 357  * get capabilities for handle
 358  */
 359
 360 static inline int
 361 time_pps_getcap(
 362         pps_handle_t handle,
 363         int *mode
 364         )
 365 {
 366         /*
 367          * Check for valid arguments and get capabilities.
 368          */
 369
 370         if (!handle) {
 371                 errno = EBADF;
 372                 return (-1);    /* bad handle */
 373         }
 374
 375         if (!mode) {
 376                 errno = EFAULT;
 377                 return (-1);    /* bad argument */
 378         }
 379         *mode = PPS_CAP;
 380         return (0);
 381 }
 382
 383 /*
 384  * Fetch timestamps
 385  */
 386
 387 static inline int
 388 time_pps_fetch(
 389         pps_handle_t handle,
 390         const int tsformat,
 391         pps_info_t *ppsinfo,
 392         const struct timespec *timeout
 393         )
 394 {
 395         struct ppsclockev {
 396                 struct timeval tv;
 397                 u_int serial;
 398         } ev;
 399
 400         pps_info_t infobuf;
 401
 402         /*
 403          * Check for valid arguments and fetch timestamps
 404          */
 405
 406         if (!handle) {
 407                 errno = EBADF;
 408                 return (-1);    /* bad handle */
 409         }
 410
 411         if (!ppsinfo) {
 412                 errno = EFAULT;
 413                 return (-1);    /* bad argument */
 414         }
 415
 416         /*
 417          * nb. PPS_CANWAIT is NOT set by the implementation, we can totally
 418          * ignore the timeout variable.
 419          */
 420
 421         memset(&infobuf, 0, sizeof(infobuf));
 422
 423         /*
 424          * if not captureassert, nothing to return.
 425          */
 426
 427         if (!handle->params.mode & PPS_CAPTUREASSERT) {
 428                 memcpy(ppsinfo, &infobuf, sizeof(pps_info_t));
 429                 return (0);
 430         }
 431
 432         if (ioctl(handle->filedes, TIOCGPPSEV, (caddr_t) &ev) < 0) {
 433                 perror("time_pps_fetch:");
 434                 errno = EOPNOTSUPP;
 435                 return(-1);
 436         }
 437
 438         /*
 439          * Apply offsets as specified. Note that only assert timestamps
 440          * are captured by this interface.
 441          */
 442
 443         infobuf.assert_sequence = ev.serial;
 444         infobuf.assert_timestamp.tv_sec = ev.tv.tv_sec;
 445         infobuf.assert_timestamp.tv_nsec = ev.tv.tv_usec * 1000;
 446
 447         if (handle->params.mode & PPS_OFFSETASSERT) {
 448                 infobuf.assert_timestamp.tv_sec  += handle->params.assert_offset.tv_sec;
 449                 infobuf.assert_timestamp.tv_nsec += handle->params.assert_offset.tv_nsec;
 450                 PPS_NORMALIZE(infobuf.assert_timestamp);
 451         }
 452
 453         /*
 454          * Translate to specified format
 455          */
 456
 457         switch (tsformat) {
 458         case PPS_TSFMT_TSPEC:
 459                 break;           /* timespec format requires no translation */
 460
 461         case PPS_TSFMT_NTPFP:   /* NTP format requires conversion to fraction form */
 462                 PPS_TSPECTONTP(infobuf.assert_timestamp_ntpfp);
 463                 break;
 464
 465         default:
 466                 errno = EINVAL;
 467                 return (-1);
 468         }
 469
 470         infobuf.current_mode = handle->params.mode;
 471         memcpy(ppsinfo, &infobuf, sizeof(pps_info_t));
 472         return (0);
 473 }
 474
 475 /*
 476  * specify kernel consumer
 477  */
 478
 479 static inline int
 480 time_pps_kcbind(
 481         pps_handle_t handle,
 482         const int kernel_consumer,
 483         const int edge, const int tsformat
 484         )
 485 {
 486         /*
 487          * Check for valid arguments and bind kernel consumer
 488          */
 489         if (!handle) {
 490                 errno = EBADF;
 491                 return (-1);    /* bad handle */
 492         }
 493         if (geteuid() != 0) {
 494                 errno = EPERM;
 495                 return (-1);    /* must be superuser */
 496         }
 497         errno = EOPNOTSUPP;
 498         return(-1);
 499 }
 500
 501 #endif /* _SYS_TIMEPPS_H_ */