1*a2286a1fSMark Johnston.\" SPDX-License-Identifier: BSD-2-Clause 2*a2286a1fSMark Johnston.\" 3*a2286a1fSMark Johnston.\" Copyright (c) 2023 Klara, Inc. 4*a2286a1fSMark Johnston.\" 5*a2286a1fSMark Johnston.\" Redistribution and use in source and binary forms, with or without 6*a2286a1fSMark Johnston.\" modification, are permitted provided that the following conditions 7*a2286a1fSMark Johnston.\" are met: 8*a2286a1fSMark Johnston.\" 1. Redistributions of source code must retain the above copyright 9*a2286a1fSMark Johnston.\" notice, this list of conditions and the following disclaimer. 10*a2286a1fSMark Johnston.\" 2. Redistributions in binary form must reproduce the above copyright 11*a2286a1fSMark Johnston.\" notice, this list of conditions and the following disclaimer in the 12*a2286a1fSMark Johnston.\" documentation and/or other materials provided with the distribution. 13*a2286a1fSMark Johnston.\" 14*a2286a1fSMark Johnston.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15*a2286a1fSMark Johnston.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16*a2286a1fSMark Johnston.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17*a2286a1fSMark Johnston.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18*a2286a1fSMark Johnston.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19*a2286a1fSMark Johnston.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20*a2286a1fSMark Johnston.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21*a2286a1fSMark Johnston.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22*a2286a1fSMark Johnston.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23*a2286a1fSMark Johnston.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24*a2286a1fSMark Johnston.\" SUCH DAMAGE. 25*a2286a1fSMark Johnston.\" 26*a2286a1fSMark Johnston.Dd February 1, 2023 27*a2286a1fSMark Johnston.Dt KVMCLOCK 4 28*a2286a1fSMark Johnston.Os 29*a2286a1fSMark Johnston.Sh NAME 30*a2286a1fSMark Johnston.Nm kvmclock 31*a2286a1fSMark Johnston.Nd Para-virtualized clock driver for x86 KVM guests 32*a2286a1fSMark Johnston.Sh SYNOPSIS 33*a2286a1fSMark JohnstonTo compile this driver into the kernel, 34*a2286a1fSMark Johnstonplace the following line in your 35*a2286a1fSMark Johnstonkernel configuration file: 36*a2286a1fSMark Johnston.Bd -ragged -offset indent 37*a2286a1fSMark Johnston.Cd "device kvm_clock" 38*a2286a1fSMark Johnston.Ed 39*a2286a1fSMark Johnston.Sh DESCRIPTION 40*a2286a1fSMark JohnstonThis driver reads time-keeping information from the para-virtualized clock 41*a2286a1fSMark Johnstondevice provided by the KVM hypervisor on Linux hosts. 42*a2286a1fSMark JohnstonThe 43*a2286a1fSMark Johnston.Nm 44*a2286a1fSMark Johnstondriver is only implemented on i386 and amd64 platforms. 45*a2286a1fSMark JohnstonIt acts as a 46*a2286a1fSMark Johnston.Xr timecounters 4 47*a2286a1fSMark Johnstondevice and is preferred over the Time Stamp Counter (TSC) when available. 48*a2286a1fSMark JohnstonThe driver exports timekeeping information via 49*a2286a1fSMark Johnston.Pa /dev/pvclock , 50*a2286a1fSMark Johnstonenabling the implementation of 51*a2286a1fSMark Johnston.Xr clock_gettime 2 52*a2286a1fSMark Johnstonand related functions without entering the kernel. 53*a2286a1fSMark Johnston.Pp 54*a2286a1fSMark JohnstonThe 55*a2286a1fSMark Johnston.Nm 56*a2286a1fSMark Johnstondriver works by accessing a per-vCPU timekeeping structure maintained by the 57*a2286a1fSMark Johnstonhypervisor. 58*a2286a1fSMark JohnstonIt uses a combination of TSC readings and information from the shared structure 59*a2286a1fSMark Johnstonto produce a high-resolution timecounter which is invariant under hypervisor 60*a2286a1fSMark Johnstonevents such as vCPU migration and live VM migration. 61*a2286a1fSMark Johnston.Sh SYSCTL VARIABLES 62*a2286a1fSMark JohnstonThe following variables are available as both 63*a2286a1fSMark Johnston.Xr sysctl 8 64*a2286a1fSMark Johnstonvariables and 65*a2286a1fSMark Johnston.Xr loader 8 66*a2286a1fSMark Johnstontunables: 67*a2286a1fSMark Johnston.Bl -tag -width indent 68*a2286a1fSMark Johnston.It Va dev.kvmclock.0.vdso_enable_without_rdtscp 69*a2286a1fSMark JohnstonBy default, timekeeping information is exported to userspace only when the 70*a2286a1fSMark Johnston(virtual) CPU announces support for the 71*a2286a1fSMark Johnston.Dq rdtscp 72*a2286a1fSMark Johnstoninstruction. 73*a2286a1fSMark JohnstonSetting this sysctl to 1 overrides this behavior, allowing timekeeping 74*a2286a1fSMark Johnstoninformation to be exported even in the absence of 75*a2286a1fSMark Johnston.Dq rdtscp 76*a2286a1fSMark Johnstonsupport. 77*a2286a1fSMark JohnstonHowever, this breaks compatibility with copies of 78*a2286a1fSMark Johnston.Pa /lib/libc.so.7 79*a2286a1fSMark Johnstonreleased prior to 80*a2286a1fSMark Johnston.Fx 14.0 , 81*a2286a1fSMark Johnstonand statically linked binaries which embed a copy of the system C library. 82*a2286a1fSMark JohnstonThus, this sysctl value should not be changed if the system may execute 83*a2286a1fSMark Johnstonbinaries older than 84*a2286a1fSMark Johnston.Fx 14.0 . 85*a2286a1fSMark Johnston.It Va dev.kvmclock.0.vdso_force_unstable 86*a2286a1fSMark JohnstonMark the timecounter as unstable for userspace consumers. 87*a2286a1fSMark JohnstonThis is mostly useful for debugging the driver and userspace timekeeping code, 88*a2286a1fSMark Johnstonand generally should not be touched. 89*a2286a1fSMark Johnston.El 90*a2286a1fSMark Johnston.Sh SEE ALSO 91*a2286a1fSMark Johnston.Xr timecounters 4 92*a2286a1fSMark Johnston.Sh HISTORY 93*a2286a1fSMark JohnstonThe 94*a2286a1fSMark Johnston.Nm 95*a2286a1fSMark Johnstondriver first appeared in 96*a2286a1fSMark Johnston.Fx 13.1 . 97