man4: Add a manual page for kvmclock
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
This commit is contained in:
parent
2bed14192c
commit
a2286a1f46
@ -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
|
||||
|
96
share/man/man4/kvmclock.4
Normal file
96
share/man/man4/kvmclock.4
Normal file
@ -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 .
|
Loading…
Reference in New Issue
Block a user