.\"
.\" Copyright (c) 2015 Ian Lepore <ian@freebsd.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 12, 2015
.Dt AM335X_DMTPPS 4
.Os
.Sh NAME
.Nm am335x_dmtpps
.Nd RFC 2783 Pulse Per Second API driver for AM335x systems
.Sh SYNOPSIS
.Cd "device am335x_dmtpps"
.Pp
Optional in
.Pa /boot/loader.conf :
.Cd hw.am335x_dmtpps.input="pin name"
.\"
.Sh DESCRIPTION
The
.Nm
device driver provides a system time counter that includes precise
capture of Pulse Per Second (PPS) signals emitted by GPS receivers
and other timing devices.
The
.Nm
driver may be compiled into the kernel or loaded as a module.
.Pp
The AM335x timer hardware captures the value of the system time counter
on the leading edge of the PPS pulse.
Because the capture is done by the hardware there is no interrupt
latency in the measurement.
The time counter runs at 24Mhz, providing a measurement resolution
of 42 nanoseconds.
.Pp
To use the PPS timing information provided by this driver with
.Xr ntpd 8 ,
symlink the
.Pa /dev/dmtpps
device to
.Pa /dev/pps0
and configure server
.Va 127.127.22.0
in
.Xr ntp.conf 5
to configure a type 22 (ATOM) refclock.
.\"
.Sh DRIVER CONFIGURATION
The AM335x hardware provides four timer devices with a capture input
pin, DMTimer4 through DMTimer7.
Because it also provides the active system time counter,
only one instance of the
.Nm
driver can be active at a time.
The driver uses system pin configuration to determine which hardware
timer device to use.
Configure the timer input pin in the system's FDT data, or by
supplying the pin name using a tunable variable in
.Xr loader.conf 5 .
.Pp
To use a standard kernel and FDT data, use
.Xr loader.conf 5
to load the
.Nm
module and set the
.Va hw.am335x_dmtpps.input
tunable variable to the name of the input pin, one of the following:
.Pp
.Bl -tag -width "GPMC_ADVn_ALE MMMM" -offset MMMM -compact
.It Em Name
.Em Hardware
.It P8-7
DMTimer4; Beaglebone P8 header pin 7.
.It P8-8
DMTimer7; Beaglebone P8 header pin 8.
.It P8-9
DMTimer5; Beaglebone P8 header pin 9.
.It P8-10
DMTimer6; Beaglebone P8 header pin 10.
.It GPMC_ADVn_ALE
DMTimer4.
.It GPMC_BEn0_CLE
DMTimer5.
.It GPMC_WEn
DMTimer6.
.It GPMC_OEn_REn
DMTimer7.
.El
.Pp
To configure the
.Nm
driver using FDT data, create a new pinctrl node by referencing the standard
.Va am33xx_pinmux
driver node (which is defined in am33xx.dtsi) in your dts file.
For example:
.Bd -literal
   &am33xx_pinmux {
      timer4_pins: timer4_pins {
         pinctrl-single,pins = <0x90 (PIN_INPUT | MUX_MODE2)>;
      };
   };
.Ed
.Pp
Add pinctrl properties referencing
.Va timer4_pins
to the standard
.Va timer4
device node (also defined in am33xx.dtsi) by referencing it in
your dts file as follows:
.Bd -literal
   &timer4 {
      pinctrl-names = "default";
      pinctrl-0 = <&timer4_pins>;
   };
.Ed
.\"
.Sh FILES
.Bl -tag -width ".Pa /dev/dmtpps" -compact
.It Pa /dev/dmtpps
The device providing
.Xr ioctl 2
access to the RFC 2783 API.
.El
.\"
.Sh SEE ALSO
.Xr timecounters 4 ,
.Xr loader.conf 5 ,
.Xr ntp.conf 5 ,
.Xr ntpd 8
.\"
.Sh HISTORY
The
.Nm
device driver first appeared in
.Fx 11.0 .
.\"
.Sh AUTHORS
The
.Nm
device driver and this manual page were written by
.An Ian Lepore Aq Mt ian@FreeBSD.org .