1.\" 2.\" Copyright (c) 2015 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 December 10, 2024 26.Dt DS1307 4 27.Os 28.Sh NAME 29.Nm ds1307 30.Nd 64 x 8, serial, i2c real-time clock (RTC) 31.Sh SYNOPSIS 32.Cd "device iic" 33.Cd "device iicbus" 34.Cd "device ds1307" 35.Sh DESCRIPTION 36The 37.Nm 38serial real-time clock (RTC) is a low-power, full binary-coded decimal (BCD) 39clock/calendar plus 56 bytes of NV SRAM. 40.Pp 41The 42.Nm 43has a built-in power-sense circuit that detects power failures and 44automatically switches to the backup supply. 45Timekeeping operation continues while the part operates from the backup supply. 46.Pp 47Access to 48.Nm 49settings is made with the 50.Xr sysctl 8 51interface: 52.Bd -literal 53dev.ds1307.0.%desc: Maxim DS1307 RTC 54dev.ds1307.0.%driver: ds1307 55dev.ds1307.0.%location: addr=0xd0 56dev.ds1307.0.%pnpinfo: name=rtc compat=maxim,ds1307 57dev.ds1307.0.%parent: iicbus1 58dev.ds1307.0.sqwe: 1 59dev.ds1307.0.sqw_freq: 32768 60dev.ds1307.0.sqw_out: 0 61.Ed 62.Bl -tag -width ".Va dev.ds1307.%d.sqw_freq" 63.It Va dev.ds1307.%d.sqwe 64If set to 1, the SQW pin drives a square-wave of 65.Va dev.ds1307.%d.sqw_freq 66frequency. 67If set to 0, the output level of SQW pin is controlled by 68.Va dev.ds1307.%d.sqw_out . 69.It Va dev.ds1307.%d.sqw_freq 70Select the frequency of the SQW pin when the square-wave output is enabled on 71.Va dev.ds1307.%d.sqwe . 72It can be set to 1, 4096, 8192 and 32768. 73.It Va dev.ds1307.%d.sqw_out 74Set the output level of the SQW pin when 75.Va dev.ds1307.%d.sqwe 76is set to 0. 77.El 78.Pp 79Please check the 80.Nm 81datasheet for more details. 82.Pp 83On a 84.Xr device.hints 5 85based system, such as 86.Li MIPS , 87these values are configurable for 88.Nm : 89.Bl -tag -width ".Va hint.ds1307.%d.addr" 90.It Va hint.ds1307.%d.at 91The 92.Xr iicbus 4 93that the 94.Nm 95is connected to. 96.It Va hint.ds1307.%d.addr 97The i2c address of 98.Nm . 99.El 100.Pp 101On a 102.Xr FDT 4 103based system the following properties must be set: 104.Bl -tag -width ".Va compatible" 105.It Va compatible 106Must always be set to "dallas,ds1307" or "maxim,ds1307". 107.It Va reg 108The i2c address of 109.Nm . 110The default address for 111.Nm 112is 0xd0. 113.El 114.Sh SEE ALSO 115.Xr fdt 4 , 116.Xr iic 4 , 117.Xr iicbus 4 , 118.Xr sysctl 8 119.Sh HISTORY 120The 121.Nm 122driver first appeared in 123.Fx 11.0 . 124.Sh AUTHORS 125.An -nosplit 126The 127.Nm 128driver and this manual page were written by 129.An Luiz Otavio O Souza Aq Mt loos@FreeBSD.org . 130