git: 2020e76450e2 - main - dtrace_vfs.4: Document the DTrace vfs provider

The branch main has been updated by 0mp:

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

commit 2020e76450e2705d33d673a3d183c8f0a3910e28
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2025-11-03 15:54:10 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2025-11-03 15:54:11 +0000

    dtrace_vfs.4: Document the DTrace vfs provider
    
    Reviewed by:    bcr
    MFC after:      1 week
    Differential Revision:  https://reviews.freebsd.org/D51317
---
 cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 |  3 +-
 share/man/man4/Makefile                      |  3 +-
 share/man/man4/dtrace_vfs.4                  | 97 ++++++++++++++++++++++++++++
 share/man/man9/VFS.9                         |  3 +-
 4 files changed, 103 insertions(+), 3 deletions(-)

diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
index e263b936700d..f09cbe1ac27b 100644
--- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
+++ b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
@@ -20,7 +20,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 30, 2025
+.Dd November 3, 2025
 .Dt DTRACE 1
 .Os
 .Sh NAME
@@ -1305,6 +1305,7 @@ in
 .Xr dtrace_tcp 4 ,
 .Xr dtrace_udp 4 ,
 .Xr dtrace_udplite 4 ,
+.Xr dtrace_vfs 4 ,
 .Xr elf 5 ,
 .Xr d 7 ,
 .Xr tracing 7 ,
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index fe744776d9b3..95618227a010 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1017,7 +1017,8 @@ _dtrace_provs=	dtrace_audit.4 \
 		dtrace_sctp.4 \
 		dtrace_tcp.4 \
 		dtrace_udp.4 \
-		dtrace_udplite.4
+		dtrace_udplite.4 \
+		dtrace_vfs.4
 
 MLINKS+=	dtrace_audit.4 dtaudit.4
 .endif
diff --git a/share/man/man4/dtrace_vfs.4 b/share/man/man4/dtrace_vfs.4
new file mode 100644
index 000000000000..528d5da42f3d
--- /dev/null
+++ b/share/man/man4/dtrace_vfs.4
@@ -0,0 +1,97 @@
+.\"
+.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd November 3, 2025
+.Dt DTRACE_VFS 4
+.Os
+.Sh NAME
+.Nm dtrace_vfs
+.Nd a DTrace provider for Virtual File System
+.Sh SYNOPSIS
+.Sm off
+.Nm vfs Cm : fplookup : Ar function Cm : Ar name
+.Nm vfs Cm : namecache : Ar function Cm : Ar name
+.Nm vfs Cm : namei : Ar function Cm : Ar name
+.Nm vfs Cm : vop : Ar function Cm : Ar name
+.Sm on
+.Sh DESCRIPTION
+The DTrace
+.Nm vfs
+provider allows users to trace events in the
+.Xr VFS 9
+layer, the kernel interface for file systems on
+.Fx .
+.Pp
+Run
+.Ql dtrace -l -P vfs
+to list all
+.Nm vfs
+probes.
+Add
+.Fl v
+to generate program stability reports,
+which contain information about the number of probe arguments and their types.
+.Pp
+The
+.Cm fplookup
+module defines a single probe,
+.Fn vfs:fplookup:lookup:done "struct nameidata *ndp" "int line" "bool status_code" ,
+that instruments the fast path lookup code in
+.Xr VFS 9 .
+.Pp
+The
+.Cm namecache
+module provides probes related to the
+.Xr VFS 9
+cache.
+Consult the source code in
+.Pa src/sys/kern/vfs_cache.c
+for more details.
+.Pp
+The
+.Cm namei
+module manages probes related to pathname translation and lookup operations.
+Refer to
+.Xr namei 9
+to learn more.
+.Pp
+The
+.Cm vop
+module contains probes related to the functions responsible for
+.Xr vnode 9
+operations.
+.Sh COMPATIBILITY
+This provider is specific to
+.Fx .
+.Sh EXAMPLES
+Check what lookups failed to be handled in a lockless manner:
+.Bd -literal -offset 2n
+# dtrace -n 'vfs:fplookup:lookup:done { @[arg1, arg2] = count(); }'
+.Ed
+.Sh SEE ALSO
+.Xr dtrace 1 ,
+.Xr d 7 ,
+.Xr SDT 9 ,
+.Xr namei 9 ,
+.Xr VFS 9
+.Rs
+.%A Brendan Gregg
+.%A Jim Mauro
+.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
+.%I Prentice Hall
+.%P pp. 335\(en351
+.%D 2011
+.%U https://www.brendangregg.com/dtracebook/
+.Re
+.Sh AUTHORS
+.An -nosplit
+The
+.Fx
+.Nm vfs
+provider was written by
+.An Robert Watson Aq Mt rwatson@FreeBSD.org .
+.Pp
+This manual page was written by
+.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .
diff --git a/share/man/man9/VFS.9 b/share/man/man9/VFS.9
index a1d0a19bec13..6ea6570bbf6e 100644
--- a/share/man/man9/VFS.9
+++ b/share/man/man9/VFS.9
@@ -26,7 +26,7 @@
 .\" (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 9, 2010
+.Dd November 3, 2025
 .Dt VFS 9
 .Os
 .Sh NAME
@@ -42,6 +42,7 @@ function from
 rather than implementing empty functions or casting to
 .Fa eopnotsupp .
 .Sh SEE ALSO
+.Xr dtrace_vfs 4 ,
 .Xr VFS_CHECKEXP 9 ,
 .Xr VFS_FHTOVP 9 ,
 .Xr VFS_MOUNT 9 ,