git: a2286a1f4651 - main - man4: Add a manual page for kvmclock

The branch main has been updated by markj:

URL: https://cgit.FreeBSD.org/src/commit/?id=a2286a1f4651f9369cacb82bb1777920f5a86fdc

commit a2286a1f4651f9369cacb82bb1777920f5a86fdc
Author:     Mark Johnston <markj@FreeBSD.org>
AuthorDate: 2023-02-03 15:54:50 +0000
Commit:     Mark Johnston <markj@FreeBSD.org>
CommitDate: 2023-02-03 16:48:25 +0000

    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
---
 share/man/man4/Makefile   |  2 +
 share/man/man4/kvmclock.4 | 96 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+)

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 .