share/man/man4/man4.arm/am335x_dmtpps.4

   1 .\"
   2 .\" Copyright (c) 2015 Ian Lepore <ian@freebsd.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd August 12, 2015
  29 .Dt AM335X_DMTPPS 4
  30 .Os
  31 .Sh NAME
  32 .Nm am335x_dmtpps
  33 .Nd RFC 2783 Pulse Per Second API driver for AM335x systems
  34 .Sh SYNOPSIS
  35 .Cd "device am335x_dmtpps"
  36 .Pp
  37 Optional in
  38 .Pa /boot/loader.conf :
  39 .Cd hw.am335x_dmtpps.input="pin name"
  40 .\"
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 device driver provides a system time counter that includes precise
  45 capture of Pulse Per Second (PPS) signals emitted by GPS receivers
  46 and other timing devices.
  47 The
  48 .Nm
  49 driver may be compiled into the kernel or loaded as a module.
  50 .Pp
  51 The AM335x timer hardware captures the value of the system time counter
  52 on the leading edge of the PPS pulse.
  53 Because the capture is done by the hardware there is no interrupt
  54 latency in the measurement.
  55 The time counter runs at 24Mhz, providing a measurement resolution
  56 of 42 nanoseconds.
  57 .Pp
  58 To use the PPS timing information provided by this driver with
  59 .Xr ntpd 8 ,
  60 symlink the
  61 .Pa /dev/dmtpps
  62 device to
  63 .Pa /dev/pps0
  64 and configure server
  65 .Va 127.127.22.0
  66 in
  67 .Xr ntp.conf 5
  68 to configure a type 22 (ATOM) refclock.
  69 .\"
  70 .Sh DRIVER CONFIGURATION
  71 The AM335x hardware provides four timer devices with a capture input
  72 pin, DMTimer4 through DMTimer7.
  73 Because it also provides the active system time counter,
  74 only one instance of the
  75 .Nm
  76 driver can be active at a time.
  77 The driver uses system pin configuration to determine which hardware
  78 timer device to use.
  79 Configure the timer input pin in the system's FDT data, or by
  80 supplying the pin name using a tunable variable in
  81 .Xr loader.conf 5 .
  82 .Pp
  83 To use a standard kernel and FDT data, use
  84 .Xr loader.conf 5
  85 to load the
  86 .Nm
  87 module and set the
  88 .Va hw.am335x_dmtpps.input
  89 tunable variable to the name of the input pin, one of the following:
  90 .Pp
  91 .Bl -tag -width "GPMC_ADVn_ALE MMMM" -offset MMMM -compact
  92 .It Em Name
  93 .Em Hardware
  94 .It P8-7
  95 DMTimer4; Beaglebone P8 header pin 7.
  96 .It P8-8
  97 DMTimer7; Beaglebone P8 header pin 8.
  98 .It P8-9
  99 DMTimer5; Beaglebone P8 header pin 9.
 100 .It P8-10
 101 DMTimer6; Beaglebone P8 header pin 10.
 102 .It GPMC_ADVn_ALE
 103 DMTimer4.
 104 .It GPMC_BEn0_CLE
 105 DMTimer5.
 106 .It GPMC_WEn
 107 DMTimer6.
 108 .It GPMC_OEn_REn
 109 DMTimer7.
 110 .El
 111 .Pp
 112 To configure the
 113 .Nm
 114 driver using FDT data, create a new pinctrl node by referencing the standard
 115 .Va am33xx_pinmux
 116 driver node (which is defined in am33xx.dtsi) in your dts file.
 117 For example:
 118 .Bd -literal
 119    &am33xx_pinmux {
 120       timer4_pins: timer4_pins {
 121          pinctrl-single,pins = <0x90 (PIN_INPUT | MUX_MODE2)>;
 122       };
 123    };
 124 .Ed
 125 .Pp
 126 Add pinctrl properties referencing
 127 .Va timer4_pins
 128 to the standard
 129 .Va timer4
 130 device node (also defined in am33xx.dtsi) by referencing it in
 131 your dts file as follows:
 132 .Bd -literal
 133    &timer4 {
 134       pinctrl-names = "default";
 135       pinctrl-0 = <&timer4_pins>;
 136    };
 137 .Ed
 138 .\"
 139 .Sh FILES
 140 .Bl -tag -width ".Pa /dev/dmtpps" -compact
 141 .It Pa /dev/dmtpps
 142 The device providing
 143 .Xr ioctl 2
 144 access to the RFC 2783 API.
 145 .El
 146 .\"
 147 .Sh SEE ALSO
 148 .Xr timecounters 4 ,
 149 .Xr loader.conf 5 ,
 150 .Xr ntp.conf 5 ,
 151 .Xr ntpd 8
 152 .\"
 153 .Sh HISTORY
 154 The
 155 .Nm
 156 device driver first appeared in
 157 .Fx 11.0 .
 158 .\"
 159 .Sh AUTHORS
 160 The
 161 .Nm
 162 device driver and this manual page were written by
 163 .An Ian Lepore Aq Mt ian@FreeBSD.org .