.\" $NetBSD: tsc.9,v 1.8 2017/02/19 11:54:59 wiz 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 February 17, 2017
.Dt TSC 9 x86
.Os
.Sh NAME
.Nm tsc
.Nd Time Stamp Counter
.Sh SYNOPSIS
.In x86/x86/tsc.h
.Ft uint64_t
.Fn rdtsc "void"
.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
provides a low-overhead and high-resolution
way to obtain
.Tn CPU
timing information.
This traditional premise was violated when such factors as
system sleep states,
.Tn CPU
.Dq hotplugging ,
.Dq hibernation ,
and
.Tn CPU
frequency scaling
were introduced to the x86 lineage.
This was however mainly a short abruption:
in many new x86
.Tn CPUs
the time stamp counter is again invariant with
respect to the stability of the clock frequency.
Care should be however taken in implementations that rely on this assumption.
.Sh FUNCTIONS
.Bl -tag -width abcd
.It Fn rdtsc ""
The
.Fn rdtsc
function returns the value read from
.Dv RDTSC .
.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_bp "ci"
The
.Fn tsc_sync_bp
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_ap "ci"
The
.Fn tsc_sync_ap
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 ,
.Xr x86/rdmsr 9