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 \
|
ktls.4 \
|
||||||
ktr.4 \
|
ktr.4 \
|
||||||
kue.4 \
|
kue.4 \
|
||||||
|
${_kvmclock.4} \
|
||||||
lagg.4 \
|
lagg.4 \
|
||||||
le.4 \
|
le.4 \
|
||||||
led.4 \
|
led.4 \
|
||||||
@ -824,6 +825,7 @@ _igc.4= igc.4
|
|||||||
_imcsmb.4= imcsmb.4
|
_imcsmb.4= imcsmb.4
|
||||||
_io.4= io.4
|
_io.4= io.4
|
||||||
_itwd.4= itwd.4
|
_itwd.4= itwd.4
|
||||||
|
_kvmclock.4= kvmclock.4
|
||||||
_mgb.4= mgb.4
|
_mgb.4= mgb.4
|
||||||
_nda.4= nda.4
|
_nda.4= nda.4
|
||||||
_nfe.4= nfe.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