a2286a1f46
Reviewed by: pauamma, imp, kib MFC after: 2 weeks Sponsored by: Klara, Inc. Sponsored by: Juniper Networks, Inc. Differential Revision: https://reviews.freebsd.org/D38343
97 lines
3.4 KiB
Groff
97 lines
3.4 KiB
Groff
.\" 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 .
|