From owner-svn-src-all@FreeBSD.ORG Wed Sep 15 07:04:15 2010 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 47A0E106567A; Wed, 15 Sep 2010 07:04:15 +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 379988FC1A; Wed, 15 Sep 2010 07:04:15 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id o8F74FSQ024732; Wed, 15 Sep 2010 07:04:15 GMT (envelope-from mav@svn.freebsd.org) Received: (from mav@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id o8F74Fca024727; Wed, 15 Sep 2010 07:04:15 GMT (envelope-from mav@svn.freebsd.org) Message-Id: <201009150704.o8F74Fca024727@svn.freebsd.org> From: Alexander Motin Date: Wed, 15 Sep 2010 07:04:15 +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: r212635 - in head/share/man: man4 man7 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: Wed, 15 Sep 2010 07:04:15 -0000 Author: mav Date: Wed Sep 15 07:04:14 2010 New Revision: 212635 URL: http://svn.freebsd.org/changeset/base/212635 Log: Add eventtimers(7) man page, briefly describing event timers subsystem functionality and configuration options. Added: head/share/man/man7/eventtimers.7 (contents, props changed) Modified: head/share/man/man4/hpet.4 head/share/man/man7/Makefile head/share/man/man7/tuning.7 Modified: head/share/man/man4/hpet.4 ============================================================================== --- head/share/man/man4/hpet.4 Wed Sep 15 05:32:10 2010 (r212634) +++ head/share/man/man4/hpet.4 Wed Sep 15 07:04:14 2010 (r212635) @@ -95,7 +95,7 @@ group is bound to specific CPU core. Thi of these comparators has own unsharable IRQ. .Sh SEE ALSO .Xr acpi 4 , -.Xr eventtimer 4 +.Xr eventtimers 7 .Sh HISTORY The .Nm Modified: head/share/man/man7/Makefile ============================================================================== --- head/share/man/man7/Makefile Wed Sep 15 05:32:10 2010 (r212634) +++ head/share/man/man7/Makefile Wed Sep 15 07:04:14 2010 (r212635) @@ -10,6 +10,7 @@ MAN= adding_user.7 \ c99.7 \ development.7 \ environ.7 \ + eventtimers.7 \ ffs.7 \ firewall.7 \ hier.7 \ Added: head/share/man/man7/eventtimers.7 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man7/eventtimers.7 Wed Sep 15 07:04:14 2010 (r212635) @@ -0,0 +1,131 @@ +.\" Copyright (c) 2010 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 September 15, 2010 +.Dt eventtimers 4 +.Os +.Sh NAME +.Nm eventtimers +.Nd kernel event timers 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 generation of monotonically increasing +timestamps for precise uptime 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 last. +.Sh DESCRIPTION +Kernel uses time-based events for many different purposes: scheduling, +statistics, time keeping, profiling and many other things, based on +.Xr callout 9 +mechanism. +These purposes now grouped into three main callbacks: +.Bl -tag +.It hardclock() +.Xr callout 9 +and timekeeping events entry. Called with frequency defined by hz variable, +usually 1000Hz. +.It statclock() +statistics and scheduler events entry. Called with frequency about 128Hz. +.It profclock() +profiler events entry. When enabled, called with frequency about 8KHz. +.El +Different platforms provide different kinds of timer hardware. +The goal of the event timers subsystem is to provide unified way to control +that hardware, and to use it, supplying kernel with all required time-based +events. +.Pp +Each driver implementing event timers, registers them at the subsystem. +It is possible to see the list of present event timers, like this, via +.Va kern.eventtimer +sysctl: +.Bd -literal +kern.eventtimer.choice: HPET(550) LAPIC(400) i8254(100) RTC(0) +kern.eventtimer.et.LAPIC.flags: 15 +kern.eventtimer.et.LAPIC.frequency: 0 +kern.eventtimer.et.LAPIC.quality: 400 +kern.eventtimer.et.i8254.flags: 1 +kern.eventtimer.et.i8254.frequency: 1193182 +kern.eventtimer.et.i8254.quality: 100 +kern.eventtimer.et.RTC.flags: 17 +kern.eventtimer.et.RTC.frequency: 32768 +kern.eventtimer.et.RTC.quality: 0 +kern.eventtimer.et.HPET.flags: 7 +kern.eventtimer.et.HPET.frequency: 14318180 +kern.eventtimer.et.HPET.quality: 550 +.Ed +, where: +.Bl -tag +.It Va kern.eventtimer.et. Ns Ar X Ns Va .flags +bitmask, defining event timer capabilities: +.Bl -tag -compact +.It 1 +periodic mode supported, +.It 2 +one-shot mode supported, +.It 4 +timer is per-CPU, +.It 8 +timer may stop when CPU goes to sleep state, +.It 16 +timer supports only power-of-2 divisors. +.El +.It Va kern.eventtimer.et. Ns Ar X Ns Va .frequency +timer base frequency, +.It Va kern.eventtimer.et. Ns Ar X Ns Va .quality +integral value, defining how good is this timer, comparing to others. +.El +.Pp +Timers management code of the kernel chooses one timer from that list. +Current choice can be read and affected via +.Va kern.eventtimer.timer +tunable/sysctl. +Several other tunables/sysctls are affecting how exactly this timer is used: +.Bl -tag +.It Va kern.eventtimer.periodic +allows to choose periodic and one-shot operation mode. +In periodic mode, periodic interrupts from timer hardware are taken as the +only source of time for time events. +One-shot mode instead uses currently selected time counter to precisely +schedule all needed events and programs event timer to generate interrupt +exactly in specified time. +Default value depends of chosen timer capabilities, but one-shot mode is +preferred, until other is forced by user or hardware. +.It Va kern.eventtimer.singlemul +in periodic mode specifies how much times higher timer frequency should be, +to not strictly alias hardclock() and statclock() events. Default values are +1, 2 or 4, depending on configured HZ value. +.It Va kern.eventtimer.idletick +makes each CPU to receive every timer interrupt independently of whether they +busy or not. By default this options is disabled. If chosen timer is per-CPU +and runs in periodic mode, this option has no effect - all interrupts are +always generating. +.El +.Sh SEE ALSO +.Xr hpet 4 Modified: head/share/man/man7/tuning.7 ============================================================================== --- head/share/man/man7/tuning.7 Wed Sep 15 05:32:10 2010 (r212634) +++ head/share/man/man7/tuning.7 Wed Sep 15 07:04:14 2010 (r212635) @@ -1019,6 +1019,7 @@ over services you export from your box ( .Xr rc.conf 5 , .Xr sysctl.conf 5 , .Xr firewall 7 , +.Xr eventtimers 7 , .Xr hier 7 , .Xr ports 7 , .Xr boot 8 ,