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 February 12, 2016 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 conversion. 69When read as 1, a temperature conversion is in progress. 70When read as 0 and then set to 1, a temperature conversion 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 8-bit i2c address of 114.Nm . 115The default 8-bit address for 116.Nm 117is 0xd0. 118.El 119.Pp 120On a 121.Xr FDT 4 122based system the following properties must be set: 123.Bl -tag -width ".Va compatible" 124.It Va compatible 125Must always be set to "maxim,ds3231". 126.It Va reg 127The 7-bit i2c address of 128.Nm . 129The default 7-bit address for 130.Nm 131is 0x68. 132.El 133.Sh SEE ALSO 134.Xr fdt 4 , 135.Xr iic 4 , 136.Xr iicbus 4 , 137.Xr sysctl 8 138.Sh HISTORY 139The 140.Nm 141driver first appeared in 142.Fx 11.0 . 143.Sh AUTHORS 144.An -nosplit 145The 146.Nm 147driver and this manual page were written by 148.An Luiz Otavio O Souza Aq Mt loos@FreeBSD.org . 149