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 37Optional in 38.Pa /boot/loader.conf : 39.Cd hw.am335x_dmtpps.input="pin name" 40.\" 41.Sh DESCRIPTION 42The 43.Nm 44device driver provides a system time counter that includes precise 45capture of Pulse Per Second (PPS) signals emitted by GPS receivers 46and other timing devices. 47The 48.Nm 49driver may be compiled into the kernel or loaded as a module. 50.Pp 51The AM335x timer hardware captures the value of the system time counter 52on the leading edge of the PPS pulse. 53Because the capture is done by the hardware there is no interrupt 54latency in the measurement. 55The time counter runs at 24Mhz, providing a measurement resolution 56of 42 nanoseconds. 57.Pp 58To use the PPS timing information provided by this driver with 59.Xr ntpd 8 , 60symlink the 61.Pa /dev/dmtpps 62device to 63.Pa /dev/pps0 64and configure server 65.Va 127.127.22.0 66in 67.Xr ntp.conf 5 68to configure a type 22 (ATOM) refclock. 69.\" 70.Sh DRIVER CONFIGURATION 71The AM335x hardware provides four timer devices with a capture input 72pin, DMTimer4 through DMTimer7. 73Because it also provides the active system time counter, 74only one instance of the 75.Nm 76driver can be active at a time. 77The driver uses system pin configuration to determine which hardware 78timer device to use. 79Configure the timer input pin in the system's FDT data, or by 80supplying the pin name using a tunable variable in 81.Xr loader.conf 5 . 82.Pp 83To use a standard kernel and FDT data, use 84.Xr loader.conf 5 85to load the 86.Nm 87module and set the 88.Va hw.am335x_dmtpps.input 89tunable 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 95DMTimer4; Beaglebone P8 header pin 7. 96.It P8-8 97DMTimer7; Beaglebone P8 header pin 8. 98.It P8-9 99DMTimer5; Beaglebone P8 header pin 9. 100.It P8-10 101DMTimer6; Beaglebone P8 header pin 10. 102.It GPMC_ADVn_ALE 103DMTimer4. 104.It GPMC_BEn0_CLE 105DMTimer5. 106.It GPMC_WEn 107DMTimer6. 108.It GPMC_OEn_REn 109DMTimer7. 110.El 111.Pp 112To configure the 113.Nm 114driver using FDT data, create a new pinctrl node by referencing the standard 115.Va am33xx_pinmux 116driver node (which is defined in am33xx.dtsi) in your dts file. 117For 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 126Add pinctrl properties referencing 127.Va timer4_pins 128to the standard 129.Va timer4 130device node (also defined in am33xx.dtsi) by referencing it in 131your 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 142The device providing 143.Xr ioctl 2 144access 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 154The 155.Nm 156device driver first appeared in 157.Fx 11.0 . 158.\" 159.Sh AUTHORS 160The 161.Nm 162device driver and this manual page were written by 163.An Ian Lepore Aq Mt ian@FreeBSD.org . 164