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.Dd August 12, 2015 27.Dt AM335X_DMTPPS 4 28.Os 29.Sh NAME 30.Nm am335x_dmtpps 31.Nd RFC 2783 Pulse Per Second API driver for AM335x systems 32.Sh SYNOPSIS 33.Cd "device am335x_dmtpps" 34.Pp 35Optional in 36.Pa /boot/loader.conf : 37.Cd hw.am335x_dmtpps.input="pin name" 38.\" 39.Sh DESCRIPTION 40The 41.Nm 42device driver provides a system time counter that includes precise 43capture of Pulse Per Second (PPS) signals emitted by GPS receivers 44and other timing devices. 45The 46.Nm 47driver may be compiled into the kernel or loaded as a module. 48.Pp 49The AM335x timer hardware captures the value of the system time counter 50on the leading edge of the PPS pulse. 51Because the capture is done by the hardware there is no interrupt 52latency in the measurement. 53The time counter runs at 24Mhz, providing a measurement resolution 54of 42 nanoseconds. 55.Pp 56To use the PPS timing information provided by this driver with 57.Xr ntpd 8 , 58symlink the 59.Pa /dev/dmtpps 60device to 61.Pa /dev/pps0 62and configure server 63.Va 127.127.22.0 64in 65.Xr ntp.conf 5 66to configure a type 22 (ATOM) refclock. 67.\" 68.Sh DRIVER CONFIGURATION 69The AM335x hardware provides four timer devices with a capture input 70pin, DMTimer4 through DMTimer7. 71Because it also provides the active system time counter, 72only one instance of the 73.Nm 74driver can be active at a time. 75The driver uses system pin configuration to determine which hardware 76timer device to use. 77Configure the timer input pin in the system's FDT data, or by 78supplying the pin name using a tunable variable in 79.Xr loader.conf 5 . 80.Pp 81To use a standard kernel and FDT data, use 82.Xr loader.conf 5 83to load the 84.Nm 85module and set the 86.Va hw.am335x_dmtpps.input 87tunable variable to the name of the input pin, one of the following: 88.Pp 89.Bl -tag -width "GPMC_ADVn_ALE MMMM" -offset MMMM -compact 90.It Em Name 91.Em Hardware 92.It P8-7 93DMTimer4; Beaglebone P8 header pin 7. 94.It P8-8 95DMTimer7; Beaglebone P8 header pin 8. 96.It P8-9 97DMTimer5; Beaglebone P8 header pin 9. 98.It P8-10 99DMTimer6; Beaglebone P8 header pin 10. 100.It GPMC_ADVn_ALE 101DMTimer4. 102.It GPMC_BEn0_CLE 103DMTimer5. 104.It GPMC_WEn 105DMTimer6. 106.It GPMC_OEn_REn 107DMTimer7. 108.El 109.Pp 110To configure the 111.Nm 112driver using FDT data, create a new pinctrl node by referencing the standard 113.Va am33xx_pinmux 114driver node (which is defined in am33xx.dtsi) in your dts file. 115For example: 116.Bd -literal 117 &am33xx_pinmux { 118 timer4_pins: timer4_pins { 119 pinctrl-single,pins = <0x90 (PIN_INPUT | MUX_MODE2)>; 120 }; 121 }; 122.Ed 123.Pp 124Add pinctrl properties referencing 125.Va timer4_pins 126to the standard 127.Va timer4 128device node (also defined in am33xx.dtsi) by referencing it in 129your dts file as follows: 130.Bd -literal 131 &timer4 { 132 pinctrl-names = "default"; 133 pinctrl-0 = <&timer4_pins>; 134 }; 135.Ed 136.\" 137.Sh FILES 138.Bl -tag -width ".Pa /dev/dmtpps" -compact 139.It Pa /dev/dmtpps 140The device providing 141.Xr ioctl 2 142access to the RFC 2783 API. 143.El 144.\" 145.Sh SEE ALSO 146.Xr timecounters 4 , 147.Xr loader.conf 5 , 148.Xr ntp.conf 5 , 149.Xr ntpd 8 150.\" 151.Sh HISTORY 152The 153.Nm 154device driver first appeared in 155.Fx 11.0 . 156.\" 157.Sh AUTHORS 158The 159.Nm 160device driver and this manual page were written by 161.An Ian Lepore Aq Mt ian@FreeBSD.org . 162