share/man/man4/kvmclock.4

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