dtrace_vfs.4: Document the DTrace vfs provider

Reviewed by:	bcr
MFC after:	1 week
Differential Revision:	https://reviews.freebsd.org/D51317

(cherry picked from commit 2020e76450e2705d33d673a3d183c8f0a3910e28)

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 7b80435c03e0..121c87323eba 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
@@ -885,6 +885,7 @@ in
 .Xr dtrace_tcp 4 ,
 .Xr dtrace_udp 4 ,
 .Xr dtrace_udplite 4 ,
+.Xr dtrace_vfs 4 ,
 .Xr elf 5 ,
 .Xr SDT 9
 .Rs
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 5f576c391086..332670598905 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -969,7 +969,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 a269d8d070cf..fcb07afa478d 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_INIT 9 ,