svn commit: r212635 - in head/share/man: man4 man7

Wed Sep 15 07:04:15 UTC 2010

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 <mav at FreeBSD.org>
+.\" 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 ,
