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.\" $FreeBSD$ 26.\" 27.Dd March 6, 2015 28.Dt DS3231 4 29.Os 30.Sh NAME 31.Nm ds3231 32.Nd Extremely Accurate i2c-integrated RTC/TCXO/Crystal 33.Sh SYNOPSIS 34.Cd "device iic" 35.Cd "device iicbus" 36.Cd "device ds3231" 37.Sh DESCRIPTION 38The 39.Nm 40is a low-cost, extremely accurate I2C realtime clock (RTC) with an 41integrated temperature-compensated crystal oscillator (TCXO) and crystal. 42.Pp 43The device incorporates a battery input and maintains accurate timekeeping 44when main power to the device is interrupted. 45.Pp 46Access to 47.Nm 48data is made with the 49.Xr sysctl 8 50interface: 51.Bd -literal 52dev.ds3231.0.%desc: Maxim DS3231 RTC 53dev.ds3231.0.%driver: ds3231 54dev.ds3231.0.%location: addr=0xd0 55dev.ds3231.0.%pnpinfo: name=rtc compat=maxim,ds3231 56dev.ds3231.0.%parent: iicbus1 57dev.ds3231.0.temperature: 23.2C 58dev.ds3231.0.temp_conv: 0 59dev.ds3231.0.bbsqw: 0 60dev.ds3231.0.sqw_freq: 8192 61dev.ds3231.0.sqw_mode: interrupt 62dev.ds3231.0.32khz_enable: 1 63.Ed 64.Bl -tag -width ".Va dev.ds3231.%d.temperature" 65.It Va dev.ds3231.%d.temperature 66The read-only value of the current temperature read by the RTC. 67.It Va dev.ds3231.%d.temp_conv 68Start a new temperature convertion. 69When read as 1, a temperature conversion is in progress. 70When read as 0 and then set to 1, a temperature convertion is started. 71The temperature conversion runs automatically on power up and once every 64 72seconds afterward. 73.It Va dev.ds3231.%d.bbsqw 74If set to 1 and 75.Va dev.ds3231.%d.sqw_mode 76is set to square-wave, battery-backed square-wave output is enabled. 77If set to 0, the SQW pin will be set to high impendance when the RTC is 78being powered by battery. 79.It Va dev.ds3231.%d.sqw_freq 80Select the frequency of the SQW pin when the square-wave output is enabled on 81.Va dev.ds3231.%d.sqw_mode . 82It can be set to 1, 1024, 4096, and 8192. 83.It Va dev.ds3231.%d.sqw_mode 84Set the operation mode for the SQW pin. 85It can be set to 'interrupt' (default) or 'square-wave'. 86In interrupt mode, the SQW pin is used to generate interrupts for the RTC 87alarms. 88In square-wave mode, the SQW pin drives a square-wave of 89.Va dev.ds3231.%d.sqw_freq 90frequency. 91.It Va dev.ds3231.%d.32khz_enable 92Enable the 32kHz output. 93.El 94.Pp 95Please check the 96.Nm 97datasheet for more details. 98.Pp 99On a 100.Xr device.hints 5 101based system, such as 102.Li MIPS , 103these values are configurable for 104.Nm : 105.Bl -tag -width ".Va hint.ds3231.%d.addr" 106.It Va hint.ds3231.%d.at 107The 108.Xr iicbus 4 109that the 110.Nm 111is connected to. 112.It Va hint.ds3231.%d.addr 113The i2c address of 114.Nm . 115.El 116.Pp 117On a 118.Xr FDT 4 119based system the following properties must be set: 120.Bl -tag -width ".Va compatible" 121.It Va compatible 122Must always be set to "maxim,ds3231". 123.It Va reg 124The i2c address of 125.Nm . 126The default address for 127.Nm 128is 0xd0. 129.El 130.Sh SEE ALSO 131.Xr fdt 4 , 132.Xr iic 4 , 133.Xr iicbus 4 , 134.Xr sysctl 8 135.Sh HISTORY 136The 137.Nm 138driver first appeared in 139.Fx 11.0 . 140.Sh AUTHORS 141.An -nosplit 142The 143.Nm 144driver and this manual page were written by 145.An Luiz Otavio O Souza Aq Mt loos@FreeBSD.org . 146