git: 9fe88e550323 - main - dtrace_pid.4: Document the DTrace PID provider

The branch main has been updated by 0mp:

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

commit 9fe88e5503239cb65e503e3b2b7344933a888644
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2025-11-06 22:40:41 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2025-11-06 22:40:41 +0000

    dtrace_pid.4: Document the DTrace PID provider
    
    MFC after:      2 weeks
    Differential Revision:  https://reviews.freebsd.org/D51287
---
 cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 |  3 +-
 share/man/man4/Makefile                      |  1 +
 share/man/man4/dtrace_pid.4                  | 99 ++++++++++++++++++++++++++++
 3 files changed, 102 insertions(+), 1 deletion(-)

diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
index 456a9e319987..ea28f051cc6f 100644
--- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
+++ b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
@@ -20,7 +20,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 4, 2025
+.Dd November 6, 2025
 .Dt DTRACE 1
 .Os
 .Sh NAME
@@ -1299,6 +1299,7 @@ in
 .Xr dtrace_ip 4 ,
 .Xr dtrace_kinst 4 ,
 .Xr dtrace_lockstat 4 ,
+.Xr dtrace_pid 4 ,
 .Xr dtrace_proc 4 ,
 .Xr dtrace_profile 4 ,
 .Xr dtrace_sched 4 ,
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 34edf6ad455d..fe1d285aec96 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1012,6 +1012,7 @@ _dtrace_provs=	dtrace_audit.4 \
 		dtrace_ip.4 \
 		dtrace_kinst.4 \
 		dtrace_lockstat.4 \
+		dtrace_pid.4 \
 		dtrace_proc.4 \
 		dtrace_profile.4 \
 		dtrace_sched.4 \
diff --git a/share/man/man4/dtrace_pid.4 b/share/man/man4/dtrace_pid.4
new file mode 100644
index 000000000000..1acbdd097ba8
--- /dev/null
+++ b/share/man/man4/dtrace_pid.4
@@ -0,0 +1,99 @@
+.\"
+.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd November 6, 2025
+.Dt DTRACE_PID 4
+.Os
+.Sh NAME
+.Nm dtrace_pid
+.Nd a DTrace provider for dynamic userspace tracing based on function boundary instrumentation
+.Sh SYNOPSIS
+.Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry
+.\" XXX: For some reason Op renders here in bold, so use literal square
+.\"      brackets instead.
+.Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&: Ns No \&[ Ns Ar offset Ns No \&]
+.Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return
+.Sh DESCRIPTION
+The
+.Nm pid
+provider implements userspace dynamic tracing
+by instrumenting the entry and return of functions in userspace programs.
+Refer to
+.Xr dtrace_fbt 4
+for more details about function boundary instrumentation.
+.Pp
+The
+.Nm pid
+provider provides the following probes:
+.Bl -inset
+.It Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry
+instruments the entry of the
+.Ar function .
+.It Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&: Ns Op Ar offset
+instruments the instruction within the
+.Ar function
+located at
+.Ar offset
+bytes (expressed as a hexadecimal integer).
+.It Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return
+instruments the return from the
+.Ar function .
+.El
+.Ss Probe Arguments
+The arguments of the entry probe
+.Pq Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry
+are the arguments of the traced function call.
+.Bl -column -offset indent "Entry Probe Argument" "Definition"
+.It Sy Entry Probe Argument Ta Sy Definition
+.It Ft uint64_t Fa arg0  Ta Function's first argument
+.It Ft uint64_t Fa arg1  Ta Function's second argument
+.It Ft uint64_t Fa arg2  Ta Function's third argument
+.It Fa ...      Ta ...
+.El
+.Pp
+The offset probes
+.Pq Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&: Ns Op Ar offset
+do not define any arguments.
+Use
+.Va uregs[]
+to inspect the registers.
+.Pp
+The arguments of the return probe
+.Pq Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return
+are the program counter and the function's return value.
+.Bl -column -offset indent "Return Probe Argument" "Definition"
+.It Sy Return Probe Argument Ta Sy Definition
+.It Ft uint64_t Fa arg0  Ta Program counter
+.It Ft uint64_t Fa arg1  Ta Function's return value
+.El
+.Pp
+Note that all probe arguments within the
+.Nm pid
+provider are of type
+.Ft uint64_t .
+.Sh SEE ALSO
+.Xr dtrace 1 ,
+.Xr dtrace_fbt 4 ,
+.Xr dtrace_kinst 4 ,
+.Xr elf 5 ,
+.Xr d 7 ,
+.Xr tracing 7
+.Rs
+.%A Brendan Gregg
+.%A Jim Mauro
+.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
+.%I Prentice Hall
+.%D 2011
+.%U https://www.brendangregg.com/dtracebook/
+.Re
+.Rs
+.%B The illumos Dynamic Tracing Guide
+.%O Chapter pid Provider
+.%D 2008
+.%U https://illumos.org/books/dtrace/chp-pid.html
+.Re
+.Sh AUTHORS
+This manual page was written by
+.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .