1.\" 2.\" Copyright (c) 2014 Luiz Otavio O Souza <loos@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.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.Dd February 12, 2016 26.Dt DS3231 4 27.Os 28.Sh NAME 29.Nm ds3231 30.Nd Extremely Accurate i2c-integrated RTC/TCXO/Crystal 31.Sh SYNOPSIS 32.Cd "device iic" 33.Cd "device iicbus" 34.Cd "device ds3231" 35.Sh DESCRIPTION 36The 37.Nm 38is a low-cost, extremely accurate I2C realtime clock (RTC) with an 39integrated temperature-compensated crystal oscillator (TCXO) and crystal. 40.Pp 41The device incorporates a battery input and maintains accurate timekeeping 42when main power to the device is interrupted. 43.Pp 44Access to 45.Nm 46data is made with the 47.Xr sysctl 8 48interface: 49.Bd -literal 50dev.ds3231.0.%desc: Maxim DS3231 RTC 51dev.ds3231.0.%driver: ds3231 52dev.ds3231.0.%location: addr=0xd0 53dev.ds3231.0.%pnpinfo: name=rtc compat=maxim,ds3231 54dev.ds3231.0.%parent: iicbus1 55dev.ds3231.0.temperature: 23.2C 56dev.ds3231.0.temp_conv: 0 57dev.ds3231.0.bbsqw: 0 58dev.ds3231.0.sqw_freq: 8192 59dev.ds3231.0.sqw_mode: interrupt 60dev.ds3231.0.32khz_enable: 1 61.Ed 62.Bl -tag -width ".Va dev.ds3231.%d.temperature" 63.It Va dev.ds3231.%d.temperature 64The read-only value of the current temperature read by the RTC. 65.It Va dev.ds3231.%d.temp_conv 66Start a new temperature conversion. 67When read as 1, a temperature conversion is in progress. 68When read as 0 and then set to 1, a temperature conversion is started. 69The temperature conversion runs automatically on power up and once every 64 70seconds afterward. 71.It Va dev.ds3231.%d.bbsqw 72If set to 1 and 73.Va dev.ds3231.%d.sqw_mode 74is set to square-wave, battery-backed square-wave output is enabled. 75If set to 0, the SQW pin will be set to high impendance when the RTC is 76being powered by battery. 77.It Va dev.ds3231.%d.sqw_freq 78Select the frequency of the SQW pin when the square-wave output is enabled on 79.Va dev.ds3231.%d.sqw_mode . 80It can be set to 1, 1024, 4096, and 8192. 81.It Va dev.ds3231.%d.sqw_mode 82Set the operation mode for the SQW pin. 83It can be set to 'interrupt' (default) or 'square-wave'. 84In interrupt mode, the SQW pin is used to generate interrupts for the RTC 85alarms. 86In square-wave mode, the SQW pin drives a square-wave of 87.Va dev.ds3231.%d.sqw_freq 88frequency. 89.It Va dev.ds3231.%d.32khz_enable 90Enable the 32kHz output. 91.El 92.Pp 93Please check the 94.Nm 95datasheet for more details. 96.Pp 97On a 98.Xr device.hints 5 99based system, such as 100.Li MIPS , 101these values are configurable for 102.Nm : 103.Bl -tag -width ".Va hint.ds3231.%d.addr" 104.It Va hint.ds3231.%d.at 105The 106.Xr iicbus 4 107that the 108.Nm 109is connected to. 110.It Va hint.ds3231.%d.addr 111The 8-bit i2c address of 112.Nm . 113The default 8-bit address for 114.Nm 115is 0xd0. 116.El 117.Pp 118On a 119.Xr FDT 4 120based system the following properties must be set: 121.Bl -tag -width ".Va compatible" 122.It Va compatible 123Must always be set to "maxim,ds3231". 124.It Va reg 125The 7-bit i2c address of 126.Nm . 127The default 7-bit address for 128.Nm 129is 0x68. 130.El 131.Sh SEE ALSO 132.Xr fdt 4 , 133.Xr iic 4 , 134.Xr iicbus 4 , 135.Xr sysctl 8 136.Sh HISTORY 137The 138.Nm 139driver first appeared in 140.Fx 11.0 . 141.Sh AUTHORS 142.An -nosplit 143The 144.Nm 145driver and this manual page were written by 146.An Luiz Otavio O Souza Aq Mt loos@FreeBSD.org . 147