152 lines
4.4 KiB
Groff
152 lines
4.4 KiB
Groff
.\" $NetBSD: tsc.9,v 1.3 2011/03/13 04:57:21 jruoho Exp $
|
|
.\"
|
|
.\" Copyright (c) 2011 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Jukka Ruohonen.
|
|
.\"
|
|
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
|
|
.\"
|
|
.Dd March 13, 2011
|
|
.Dt TSC 9 x86
|
|
.Os
|
|
.Sh NAME
|
|
.Nm tsc
|
|
.Nd Time Stamp Counter
|
|
.Sh SYNOPSIS
|
|
.In x86/x86/tsc.h
|
|
.Ft void
|
|
.Fn tsc_tc_init "void"
|
|
.Ft void
|
|
.Fn tsc_sync_ap "struct cpu_info *ci"
|
|
.Ft void
|
|
.Fn tsc_sync_bp "struct cpu_info *ci"
|
|
.Ft void
|
|
.Fn tsc_sync_drift "int64_t drift"
|
|
.Sh DESCRIPTION
|
|
The time stamp counter
|
|
.Pq Tn TSC
|
|
is a hardware counter found in all contemporary x86 processors.
|
|
The counter is implemented as a 64-bit model-specific register
|
|
.Pq Tn MSR
|
|
that is incremented at every clock cycle.
|
|
The
|
|
.Tn RDTSC
|
|
.Pq Dq read time stamp counter
|
|
register has been present since the original Pentium.
|
|
.Pp
|
|
Already because of the access method,
|
|
.Tn TSC
|
|
has traditionally provided a low-overhead and high-resolution
|
|
way to obtain
|
|
.Tn CPU
|
|
timing information.
|
|
Recently, however, this reliability has been undermined by
|
|
such factors as system sleep states,
|
|
.Tn CPU
|
|
.Dq hotplugging ,
|
|
.Dq hibernation ,
|
|
and
|
|
.Tn CPU
|
|
frequency scaling.
|
|
.Pp
|
|
These potential new sources of unreliability are easily understandable
|
|
when one recalls that the counter measures cycles and not
|
|
.Dq time .
|
|
Comparing the cycle counts only makes sense when the clock frequency
|
|
is stable; to convert the cycle counts to time units, a general equation
|
|
would be:
|
|
.Dq seconds = cycles / frequency in Hz .
|
|
The use of
|
|
.Tn TSC
|
|
as a source of high-resolution timing can be thus discouraged.
|
|
But the basic premise is still guaranteed:
|
|
.Tn TSC
|
|
is a monotonically increasing counter.
|
|
.Sh FUNCTIONS
|
|
.Bl -tag -width abcd
|
|
.It Fn tsc_tc_init ""
|
|
The
|
|
.Fn tsc_tc_init
|
|
function initializes the
|
|
.Tn TSC
|
|
as a
|
|
.Xr timecounter 9 .
|
|
The function is called early in the boot process when the processors attach.
|
|
.It Fn tsc_sync_ap "ci"
|
|
The
|
|
.Fn tsc_sync_ap
|
|
function synchronizes the counter for the boot processor
|
|
.Pq Tn BP .
|
|
The supplied
|
|
.Fa ci
|
|
must refer to the
|
|
.Tn BP
|
|
itself.
|
|
The
|
|
.Nm
|
|
interface takes internally care of such issues as out-of-order execution,
|
|
where instructions are not necessarily performed in the order of execution,
|
|
possibly causing a misleading cycle count.
|
|
.It Fn tsc_sync_bp "ci"
|
|
The
|
|
.Fn tsc_sync_bp
|
|
function synchronize the counter for the application processor
|
|
.Fa ci .
|
|
Interrupts must be off at machine-level when the function is called.
|
|
.Pp
|
|
It is necessary to call both
|
|
.Fn tsc_sync_ap
|
|
and
|
|
.Fn tsc_sync_bp
|
|
during the boot, but additional synchronization
|
|
may be required also during runtime.
|
|
As an example, the
|
|
.Tn TSC
|
|
needs to be synchronized for all processors when the system resumes from an
|
|
.Xr acpi 4
|
|
sleep state.
|
|
.It Fn tsc_sync_drift "drift"
|
|
Finally, the
|
|
.Fn tsc_sync_drift
|
|
function records
|
|
.Fa drift ,
|
|
measured in clock cycles.
|
|
This is called when the
|
|
.Tn APs
|
|
attach.
|
|
.El
|
|
.\"
|
|
.\" Some references that are not worth adding to the actual page:
|
|
.\"
|
|
.\" http://lwn.net/Articles/209101/
|
|
.\" http://lwn.net/Articles/388188/
|
|
.\" http://lkml.org/lkml/2005/11/4/173
|
|
.\" http://www.ccsl.carleton.ca/~jamuir/rdtscpm1.pdf
|
|
.\"
|
|
.Sh SEE ALSO
|
|
.Xr gettimeofday 2 ,
|
|
.Xr hpet 4 ,
|
|
.Xr hz 9 ,
|
|
.Xr timecounter 9
|