git: 5675bb582985 - main - tslog.4: Document TSLOG

The branch main has been updated by 0mp (doc, ports committer):

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

commit 5675bb582985654b172a4c1dd191e2b3bb8e78bb
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2022-03-04 19:33:22 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2022-03-04 19:37:19 +0000

    tslog.4: Document TSLOG
    
    Based on commit messages and Colin Percival's presentation
    from BSDCan 2018 [1].
    
    [1]: https://papers.freebsd.org/2018/bsdcan/percival-Profiling_the_FreeBSD_kernel_boot.files/percival-Profiling_the_FreeBSD_kernel_boot.pdf
    
    Reviewed by:    cperciva, debdrup
    MFC after:      1 week
    Differential Revision:  https://reviews.freebsd.org/D34430
---
 share/man/man4/Makefile |   1 +
 share/man/man4/tslog.4  | 135 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 136 insertions(+)

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 1b28736082b2..7e847065994b 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -554,6 +554,7 @@ MAN=	aac.4 \
 	ti.4 \
 	timecounters.4 \
 	${_tpm.4} \
+	tslog.4 \
 	tty.4 \
 	tun.4 \
 	twe.4 \
diff --git a/share/man/man4/tslog.4 b/share/man/man4/tslog.4
new file mode 100644
index 000000000000..7d36898a6533
--- /dev/null
+++ b/share/man/man4/tslog.4
@@ -0,0 +1,135 @@
+.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
+.\"
+.\" Copyright (c) 2022 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\"
+.\" 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 March 4, 2022
+.Dt TSLOG 4
+.Os
+.Sh NAME
+.Nm tslog
+.Nd Boot-time event tracing facility
+.Sh SYNOPSIS
+To compile this boot-time event tracing facility into the kernel,
+place the following line in the kernel configuration file:
+.Bd -ragged -offset indent
+.Cd "option TSLOG"
+.Ed
+.Sh DESCRIPTION
+.Nm
+is a boot-time event tracing facility.
+Its purpose is to ease diagnosing and reducing the overall
+.Fx
+boot time by generating detailed timing information.
+.Pp
+.Nm
+is able to trace the boot loader, kernel initialization, and userland processes.
+.Pp
+In userland, it records the following details for each process ID:
+.Bl -dash
+.It
+The timestamp of the
+.Xr fork 2
+which creates the given process ID and the parent process ID.
+.It
+The path passed to
+.Xr execve 2 ,
+if any.
+.It
+The first path resolved by
+.Xr namei 9 ,
+if any.
+.It
+The timestamp of the
+.Xr exit 3
+which terminates the process.
+.El
+.Sh SYSCTL VARIABLES
+The following
+.Xr sysctl 8
+variables are available:
+.Bl -tag -width indent
+.It Va debug.tslog
+Dump the
+.Nm
+buffer of recorded loader and kernel event timestamps.
+.It Va debug.tslog_user
+Dump the
+.Nm
+buffer
+of recorded userland event timestamps.
+.El
+.Sh FLAMEGRAPHS
+The
+.Nm
+buffer dumps
+can be used to generate flamegraphs of the
+.Fx
+boot process for visual analysis.
+See
+.Lk https://github.com/cperciva/freebsd-boot-profiling
+for more information.
+.Sh SEE ALSO
+.Xr dtrace 1 ,
+.Xr boottrace 4 ,
+.Xr ktr 4
+.Sh HISTORY
+.Nm
+first appeared in
+.Fx 12.0 .
+Support for tracing boot loaders and userland process
+was added in
+.Fx 14.0 .
+.Ss TSLOG vs. Boottrace
+.Nm
+is oriented towards system developers while
+.Xr boottrace 4
+is meant to be easy to use by system administrators.
+Both faciliities provide an overview of timing and resource usage of the boot
+process.
+.Ss TSLOG vs. DTrace
+.Xr dtrace 1
+is not always the right tool for profiling early kernel initialization.
+The reason is it requires some kernel subroutines
+which are not yet available early in the boot process, e.g.:
+traps, memory allocation, or thread schedulling.
+.Nm
+depends on fewer kernel subroutines than
+.Xr dtrace 1
+and because of that can trace early kernel initialization.
+.Ss TSLOG vs. KTR
+.Xr ktr 4
+has a couple of limitations which prevent it from
+being able to run at the start of the boot process.
+In contrast,
+.Nm
+is designed for logging timestamped events for boot
+profiling.
+.Sh AUTHORS
+.An -nosplit
+.Nm
+was written by
+.An Colin Percival Aq Mt cperciva@FreeBSD.org .
+.Pp
+This manual page was written by
+.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .