.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2023 Klara, Inc.
.\"
.\" 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.
.\"
.Dd February 1, 2023
.Dt KVMCLOCK 4
.Os
.Sh NAME
.Nm kvmclock
.Nd Para-virtualized clock driver for x86 KVM guests
.Sh SYNOPSIS
To compile this driver into the kernel,
place the following line in your
kernel configuration file:
.Bd -ragged -offset indent
.Cd "device kvm_clock"
.Ed
.Sh DESCRIPTION
This driver reads time-keeping information from the para-virtualized clock
device provided by the KVM hypervisor on Linux hosts.
The
.Nm
driver is only implemented on i386 and amd64 platforms.
It acts as a
.Xr timecounters 4
device and is preferred over the Time Stamp Counter (TSC) when available.
The driver exports timekeeping information via
.Pa /dev/pvclock ,
enabling the implementation of
.Xr clock_gettime 2
and related functions without entering the kernel.
.Pp
The
.Nm
driver works by accessing a per-vCPU timekeeping structure maintained by the
hypervisor.
It uses a combination of TSC readings and information from the shared structure
to produce a high-resolution timecounter which is invariant under hypervisor
events such as vCPU migration and live VM migration.
.Sh SYSCTL VARIABLES
The following variables are available as both
.Xr sysctl 8
variables and
.Xr loader 8
tunables:
.Bl -tag -width indent
.It Va dev.kvmclock.0.vdso_enable_without_rdtscp
By default, timekeeping information is exported to userspace only when the
(virtual) CPU announces support for the
.Dq rdtscp
instruction.
Setting this sysctl to 1 overrides this behavior, allowing timekeeping
information to be exported even in the absence of
.Dq rdtscp
support.
However, this breaks compatibility with copies of
.Pa /lib/libc.so.7
released prior to
.Fx 14.0 ,
and statically linked binaries which embed a copy of the system C library.
Thus, this sysctl value should not be changed if the system may execute
binaries older than
.Fx 14.0 .
.It Va dev.kvmclock.0.vdso_force_unstable
Mark the timecounter as unstable for userspace consumers.
This is mostly useful for debugging the driver and userspace timekeeping code,
and generally should not be touched.
.El
.Sh SEE ALSO
.Xr timecounters 4
.Sh HISTORY
The
.Nm
driver first appeared in
.Fx 13.1 .