History log of /freebsd-head/sys/sys/clock.h
Revision Date Author Comments
74f072217c40efdb995453ab6c01bf669f7e2d93 12-Mar-2019 imp <imp@FreeBSD.org> Kill tz_minuteswest and tz_dsttime.

Research Unix, 7th Edition introduced TIMEZONE and DSTFLAG
compile-time constants in sys/param.h to communicate these values for
the machine. 4.2BSD moved from the compile-time to run-time and
introduced these variables and used for localtime() to return the
right offset from UTC (sometimes referred to as GMT, for this purpose
is the same). 4.4BSD migrated to using the tzdata code/database and
these variables were basically unused.

FreeBSD removed the real need for these with adjkerntz in
1995. However, some RTC clocks continued to use these variables,
though they were largely unused otherwise. Later, phk centeralized
most of the uses in utc_offset, but left it using both tz_minuteswest
and adjkerntz.

POSIX (IEEE Std 1003.1-2017) states in the gettimeofday specification
"If tzp is not a null pointer, the behavior is unspecified" so there's
no standards reason to retain it anymore. In fact, gettimeofday has
been marked as obsolecent, meaning it could be removed from a future
release of the standard. It is the only interface defined in POSIX
that references these two values. All other references come from the
tzdata database via tzset().

These were used to more faithfully implement early unix ABIs which
have been removed from FreeBSD. NetBSD has completely eliminated
these variables years ago. Linux has migrated to tzdata as well,
though these variables technically still exist for compatibility
with unspecified older programs.

So, there's no real reason to have them these days. They are a
historical vestige that's no longer used in any meaningful way.

Reviewed By: jhb@, brooks@
Differential Revision: https://reviews.freebsd.org/D19550
e5909c170bde83b730e6d056e9081199d9f7d69d 12-Feb-2018 ian <ian@FreeBSD.org> Add a set of convenience routines for RTC drivers to use for debug output,
and a debug.clock_show_io sysctl to control debugging output.
19e2991d59ea760ebd16f2cded2b0a828ed4436c 12-Feb-2018 ian <ian@FreeBSD.org> Replace the existing print_ct() private debugging function with a set of
three public functions to format and print the three major data structures
used by realtime clock drivers (clocktime, bcd_clocktime, and timespec).
7f4e81c4934c99b6ea37410b3491e9d05cef4d74 06-Feb-2018 ian <ian@FreeBSD.org> Use const pointers for input data not modified by clock utility functions.
9c7cac637a203f2f966a501fda4ef0e84bff09c0 14-Jan-2018 ian <ian@FreeBSD.org> Add RTC clock conversions for BCD values, with non-panic validation.

RTC clock hardware frequently uses BCD numbers. Currently the low-level
bcd2bin() and bin2bcd() functions will KASSERT if given out-of-range BCD
values. Every RTC driver must implement its own code for validating the
unreliable data coming from the hardware to avoid a potential kernel panic.

This change introduces two new functions, clock_bcd_to_ts() and
clock_ts_to_bcd(). The former validates its inputs and returns EINVAL if any
values are out of range. The latter guarantees the returned data will be
valid BCD in a known format (4-digit years, etc).

A new bcd_clocktime structure is used with the new functions. It is similar
to the original clocktime structure, but defines the fields holding BCD
values as uint8_t (uint16_t for year), and adds a PM flag for handling hours
using AM/PM mode.

PR: 224813
Differential Revision: https://reviews.freebsd.org/D13730 (no reviewers)
d8596f6f687a64b994b065f3058155405dfc39db 27-Nov-2017 pfg <pfg@FreeBSD.org> sys/sys: further adoption of SPDX licensing ID tags.

Mainly focus on files that use BSD 2-Clause license, however the tool I
was using misidentified many licenses so this was mostly a manual - error
prone - task.

The Software Package Data Exchange (SPDX) group provides a specification
to make it easier for automated tools to detect and summarize well known
opensource licenses. We are gradually adopting the specification, noting
that the tags are considered only advisory and do not, in any way,
superceed or replace the license texts.
4b1f61b07349416374d891828e69dc6bacff4d5b 31-Jul-2017 ian <ian@FreeBSD.org> Add clock_schedule(), a feature that allows realtime clock drivers to
request that their clock_settime() methods be called at a given offset
from top-of-second. This adds a timeout_task to the rtc_instance so that
each clock can be separately added to taskqueue_thread with the scheduling
it prefers, instead of looping through all the clocks at once with a
single task on taskqueue_thread. If a driver doesn't call clock_schedule()
the default is the old behavior: clock_settime() is queued immediately.

The motivation behind this is that I was on the path of adding identical
code to a third RTC driver to figure out a delta to top-of-second and
sleep for that amount of time because writing the the RTC registers resets
the hardware's concept of top-of-second. (Sometimes it's not top-of-second,
some RTC clocks tick over a half second after you set their time registers.)
Worst-case would be to sleep for almost a full second, which is a rude thing
to do on a shared task queue thread.
91f22a6f6a8c11e173cac44d7953378d9b3615d6 12-Jul-2017 ian <ian@FreeBSD.org> Support multiple realtime clocks, and remove locking/sleeping restrictions
on clock drivers.

This tracks multiple concurrent realtime clock drivers in a list sorted by
clock resolution. When system time changes (and periodically) the
clock_settime() methods of all registered clocks are invoked.

To initialize system time, each driver is tried in turn from best to worst
resolution, until one succesfully returns a valid time.

The code no longer holds a mutex while calling the clock_settime() and
clock_gettime() methods of the registered clocks. This allows clock drivers
to do whatever kind of locking or sleeping is necessary (this is especially
important for i2c clock chips since i2c drivers often need to sleep).

A new clock_register_flags() function allows the clock driver to pass
flags. The flags currently defined help support drivers that use their own
techniques to avoid roundoff errors (prevents the 4/5 rounding done by the
subr_rtc code). A driver which may need to wait for resources (such as bus
ownership) may pass a flag to indicate that it will obtain system time for
itself after waiting for resources; this is merely an optimization to avoid
the common code retrieving a timespec that will never get used.

Relnotes: yes
Differential Revision: https://reviews.freebsd.org/D11484
a9f3b66feea94839f311e80d9b0fe2a00d776f18 21-Sep-2016 kib <kib@FreeBSD.org> Make resettodr_lock accessible outside subr_rtc.c. Protect
CLOCK_GETTIME() with the lock.

Now all time-related accesses to the CMOS for RTC should be under the
lock. This is needed to allow upcoming EFI Runtime Services support
to provide required execution environment for the firmware calls.

Sponsored by: The FreeBSD Foundation
MFC after: 1 week
00d578928eca75be320b36d37543a7e2a4f9fbdb 27-May-2016 grehan <grehan@FreeBSD.org> Create branch for bhyve graphics import.
eb1a5f8de9f7ea602c373a710f531abbf81141c4 21-Feb-2014 gjb <gjb@FreeBSD.org> Move ^/user/gjb/hacking/release-embedded up one directory, and remove
^/user/gjb/hacking since this is likely to be merged to head/ soon.

Sponsored by: The FreeBSD Foundation
6b01bbf146ab195243a8e7d43bb11f8835c76af8 27-Dec-2013 gjb <gjb@FreeBSD.org> Copy head@r259933 -> user/gjb/hacking/release-embedded for initial
inclusion of (at least) arm builds with the release.

Sponsored by: The FreeBSD Foundation
09f9c897d33c41618ada06fbbcf1a9b3812dee53 19-Oct-2010 jamie <jamie@FreeBSD.org> A new jail(8) with a configuration file, to replace the work currently done
by /etc/rc.d/jail.
f1216d1f0ade038907195fc114b7e630623b402c 19-Mar-2010 delphij <delphij@FreeBSD.org> Create a custom branch where I will be able to do the merge.
2e980c4bcf447bd8ccd284e972342df981d9b51b 03-Mar-2010 joel <joel@FreeBSD.org> The NetBSD Foundation has granted permission to remove clause 3 and 4 from
the software.

Obtained from: NetBSD
19b6af98ec71398e77874582eb84ec5310c7156f 22-Nov-2008 dfr <dfr@FreeBSD.org> Clone Kip's Xen on stable/6 tree so that I can work on improving FreeBSD/amd64
performance in Xen's HVM mode.
cf5320822f93810742e3d4a1ac8202db8482e633 19-Oct-2008 lulf <lulf@FreeBSD.org> - Import the HEAD csup code which is the basis for the cvsmode work.
8d647da1edcc4aad93660da8a41dc09f628eb53c 22-Apr-2008 phk <phk@FreeBSD.org> Now that all platforms use genclock, shuffle things around slightly
for better structure.

Much of this is related to <sys/clock.h>, which should really have
been called <sys/calendar.h>, but unless and until we need the name,
the repocopy can wait.

In general the kernel does not know about minutes, hours, days,
timezones, daylight savings time, leap-years and such. All that
is theoretically a matter for userland only.

Parts of kernel code does however care: badly designed filesystems
store timestamps in local time and RTC chips almost universally
track time in a YY-MM-DD HH:MM:SS format, and sometimes in local
timezone instead of UTC. For this we have <sys/clock.h>

<sys/time.h> on the other hand, deals with time_t, timeval, timespec
and so on. These know only seconds and fractions thereof.

Move inittodr() and resettodr() prototypes to <sys/time.h>.
Retain the names as it is one of the few surviving PDP/VAX references.

Move startrtclock() to <machine/clock.h> on relevant platforms, it
is a MD call between machdep.c/clock.c. Remove references to it
elsewhere.

Remove a lot of unnecessary <sys/clock.h> includes.

Move the machdep.disable_rtc_set sysctl to subr_rtc.c where it belongs.
XXX: should be kern.disable_rtc_set really, it's not MD.
e74f0ab1401b205bfe9ee22d26d1800157598185 24-Oct-2006 phk <phk@FreeBSD.org> Better naming of fattime conversion functions, they do convert to timespec
after all.

Add 'utc' argument to control if fattimestamps are on UTC or local timezone
calendar.
cc74fcabb418a714919dc9abc75e57e47b0a058c 22-Oct-2006 phk <phk@FreeBSD.org> Add two new functions to convert FAT filesystem format timestamps
to and from struct timespec, to replace the crummy conversion
function which have been copy&pasted into three different
filesystems already.

Apart from general crummyness as indicated by code like:

for (year = 1970;; year++) {
inc = year & 0x03 ? 365 : 366;
if (days < inc)
break;
days -= inc;
}

They also contain specialized crummyness which tries to compensate
for the general crummyness by caching recent conversion results,
with no regard for locking or consistency.

These replacement functions are smaller, O(1) and handle the Y2.1K
leap-year correctly.

Ideally, these functions should live in a module of their own,
which the three offending filesystems would depend on, but the
size is 877 bytes of code (on i386), so that would be false
economy.
638e020bc6857faa5fda80000dcd6c68e81077b3 02-Oct-2006 phk <phk@FreeBSD.org> Use utc_offset() where applicable, and hide the internals of it
as static variables.
52fd27550447035a972590168c4734a6af58cb1e 02-Oct-2006 phk <phk@FreeBSD.org> Introduce utc_offset() to capture a calculation currently done all over the
place.
50c81b8a9a184590a45c87eace5798a2055cee48 02-Oct-2006 phk <phk@FreeBSD.org> First part of a little cleanup in the calendar/timezone/RTC handling.

Move relevant variables to <sys/clock.h> and fix #includes as necessary.

Use libkern's much more time- & spamce-efficient BCD routines.
6bce57cdf3aa5590392d13ac04cd7dfc37cf032f 24-Mar-2006 imp <imp@FreeBSD.org> The year field is the 4 digit year (eg, 2006), not 'year - 1900' (eg
106). Fix the comment to reflect this.
91f571835acb430a421ab7ec0fa5a8fff635b0c8 04-Apr-2002 tmm <tmm@FreeBSD.org> Add a generic implementation of inittodr() and resettodr(), as well as
a set of helper routines to deal with real-time clocks. The generic
functions access the clock diver using a kobj interface. This is intended
to reduce code reduplication and make it easy to support more than one
clock model on a single architecture.

This code is currently only used on sparc64, but it is planned to convert
the code of the other architectures to it later.