From owner-svn-src-all@FreeBSD.ORG Tue Dec 20 17:10:35 2011 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 7B720106567C; Tue, 20 Dec 2011 17:10:35 +0000 (UTC) (envelope-from mav@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 649E38FC12; Tue, 20 Dec 2011 17:10:35 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id pBKHAZxa026189; Tue, 20 Dec 2011 17:10:35 GMT (envelope-from mav@svn.freebsd.org) Received: (from mav@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id pBKHAZli026183; Tue, 20 Dec 2011 17:10:35 GMT (envelope-from mav@svn.freebsd.org) Message-Id: <201112201710.pBKHAZli026183@svn.freebsd.org> From: Alexander Motin Date: Tue, 20 Dec 2011 17:10:35 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r228741 - head/share/man/man4 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 20 Dec 2011 17:10:35 -0000 Author: mav Date: Tue Dec 20 17:10:34 2011 New Revision: 228741 URL: http://svn.freebsd.org/changeset/base/228741 Log: Add timecounters(4) man page alike to eventtimers(4). Added: head/share/man/man4/timecounters.4 (contents, props changed) Modified: head/share/man/man4/Makefile head/share/man/man4/attimer.4 head/share/man/man4/eventtimers.4 head/share/man/man4/hpet.4 Modified: head/share/man/man4/Makefile ============================================================================== --- head/share/man/man4/Makefile Tue Dec 20 15:50:54 2011 (r228740) +++ head/share/man/man4/Makefile Tue Dec 20 17:10:34 2011 (r228741) @@ -445,6 +445,7 @@ MAN= aac.4 \ termios.4 \ textdump.4 \ ti.4 \ + timecounters.4 \ tl.4 \ tnt4882.4 \ ${_tpm.4} \ Modified: head/share/man/man4/attimer.4 ============================================================================== --- head/share/man/man4/attimer.4 Tue Dec 20 15:50:54 2011 (r228740) +++ head/share/man/man4/attimer.4 Tue Dec 20 17:10:34 2011 (r228741) @@ -73,4 +73,5 @@ Event timer provided by the driver is ir .Xr apic 4 , .Xr atrtc 4 , .Xr eventtimers 4 , -.Xr hpet 4 +.Xr hpet 4 , +.Xr timecounters 4 Modified: head/share/man/man4/eventtimers.4 ============================================================================== --- head/share/man/man4/eventtimers.4 Tue Dec 20 15:50:54 2011 (r228740) +++ head/share/man/man4/eventtimers.4 Tue Dec 20 17:10:34 2011 (r228741) @@ -149,4 +149,5 @@ always generating. .Xr atrtc 4 , .Xr attimer 4 , .Xr hpet 4 , +.Xr timecounters 4 , .Xr eventtimers 9 Modified: head/share/man/man4/hpet.4 ============================================================================== --- head/share/man/man4/hpet.4 Tue Dec 20 15:50:54 2011 (r228740) +++ head/share/man/man4/hpet.4 Tue Dec 20 17:10:34 2011 (r228741) @@ -97,7 +97,8 @@ of these comparators has own unsharable .Xr apic 4 , .Xr atrtc 4 , .Xr attimer 4 , -.Xr eventtimers 4 +.Xr eventtimers 4 , +.Xr timecounters 4 .Sh HISTORY The .Nm Added: head/share/man/man4/timecounters.4 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man4/timecounters.4 Tue Dec 20 17:10:34 2011 (r228741) @@ -0,0 +1,105 @@ +.\" Copyright (c) 2011 Alexander Motin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 20, 2011 +.Dt TIMECOUNTERS 4 +.Os +.Sh NAME +.Nm timecounters +.Nd kernel time counters subsystem +.Sh SYNOPSIS +Kernel uses several types of time-related devices, such as: real time clocks, +time counters and event timers. +Real time clocks responsible for tracking real world time, mostly when system +is down. +Time counters are responsible for tracking purposes, when system is running. +Event timers are responsible for generating interrupts at specified time or +periodically, to run different time-based events. +This page is about the second. +.Sh DESCRIPTION +Time counters are the lowest level of time tracking in kernel. +They provide monotonically increasing timestamps with known width and +update frequency. +They can overflow, drift, etc and so in raw form used only in very limited +performance-critical places like process scheduler. +.Pp +More usable time is created by scaling the values read from the selected +time counter and combining it with some offset, regularly updated by +.Fn tc_windup +on +.Fn hardclock +invocation. +.Pp +Different platforms provide different kinds of timer hardware. +The goal of the time counters subsystem is to provide unified way to access +that hardware. +.Pp +Each driver implementing time counters, registers them at the subsystem. +It is possible to see the list of present time counters, like this, via +.Va kern.timecounter +sysctl: +.Bd -literal +kern.timecounter.choice: TSC-low(-100) HPET(950) i8254(0) ACPI-fast(900) dummy(-1000000) +kern.timecounter.tc.ACPI-fast.mask: 16777215 +kern.timecounter.tc.ACPI-fast.counter: 13467909 +kern.timecounter.tc.ACPI-fast.frequency: 3579545 +kern.timecounter.tc.ACPI-fast.quality: 900 +kern.timecounter.tc.i8254.mask: 65535 +kern.timecounter.tc.i8254.counter: 62692 +kern.timecounter.tc.i8254.frequency: 1193182 +kern.timecounter.tc.i8254.quality: 0 +kern.timecounter.tc.HPET.mask: 4294967295 +kern.timecounter.tc.HPET.counter: 3013495652 +kern.timecounter.tc.HPET.frequency: 14318180 +kern.timecounter.tc.HPET.quality: 950 +kern.timecounter.tc.TSC-low.mask: 4294967295 +kern.timecounter.tc.TSC-low.counter: 4067509463 +kern.timecounter.tc.TSC-low.frequency: 11458556 +kern.timecounter.tc.TSC-low.quality: -100 +.Ed +.Pp +where: +.Bl -inset +.It Va kern.timecounter.tc. Ns Ar X Ns Va .mask +is a bitmask, defining valid counter bits, +.It Va kern.timecounter.tc. Ns Ar X Ns Va .counter +is a present counter value, +.It Va kern.eventtimer.tc. Ns Ar X Ns Va .frequency +is a counter update frequency, +.It Va kern.eventtimer.tc. Ns Ar X Ns Va .quality +is an integral value, defining how good is this time counter, +comparing to others. +Negative value means that this time counter is broken and should not be used. +.El +.Pp +Time management code of the kernel chooses one time counter from that list. +Current choice can be read and affected via +.Va kern.timecounter.hardware +tunable/sysctl. +.Sh SEE ALSO +.Xr attimer 4 , +.Xr eventtimers 4 , +.Xr hpet 4