diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index c54c3de1bf90..1c7703bdaeb2 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -271,6 +271,7 @@ MAN= aac.4 \ ktls.4 \ ktr.4 \ kue.4 \ + ${_kvmclock.4} \ lagg.4 \ le.4 \ led.4 \ @@ -824,6 +825,7 @@ _igc.4= igc.4 _imcsmb.4= imcsmb.4 _io.4= io.4 _itwd.4= itwd.4 +_kvmclock.4= kvmclock.4 _mgb.4= mgb.4 _nda.4= nda.4 _nfe.4= nfe.4 diff --git a/share/man/man4/kvmclock.4 b/share/man/man4/kvmclock.4 new file mode 100644 index 000000000000..55ee5fc1cb42 --- /dev/null +++ b/share/man/man4/kvmclock.4 @@ -0,0 +1,96 @@ +.\" 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 .