dtrace_dtmalloc.4: Document the DTrace dtmalloc provider

MFC after:	1 week
Discussed with:	christos, markj, ziaee
Differential Revision:	https://reviews.freebsd.org/D51396

cddl/contrib/opensolaris/cmd/dtrace/dtrace.1

@@ -20,7 +20,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 7, 2026
+.Dd May 12, 2026
 .Dt DTRACE 1
 .Os
 .Sh NAME
@@ -1298,6 +1298,7 @@ in
 .Xr dtrace_audit 4 ,
 .Xr dtrace_callout_execute 4 ,
 .Xr dtrace_cam 4 ,
+.Xr dtrace_dtmalloc 4 ,
 .Xr dtrace_dtrace 4 ,
 .Xr dtrace_fbt 4 ,
 .Xr dtrace_io 4 ,

share/man/man4/Makefile

@@ -1017,6 +1017,7 @@ _ccd.4=		ccd.4
 _dtrace_provs=	dtrace_audit.4 \
 		dtrace_callout_execute.4 \
 		dtrace_cam.4 \
+		dtrace_dtmalloc.4 \
 		dtrace_dtrace.4 \
 		dtrace_fbt.4 \
 		dtrace_io.4 \

share/man/man4/dtrace_dtmalloc.4

@@ -0,0 +1,132 @@
+.\"
+.\" Copyright (c) 2025-2026 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd May 12, 2026
+.Dt DTRACE_DTMALLOC 4
+.Os
+.Sh NAME
+.Nm dtrace_dtmalloc
+.Nd a DTrace provider for tracing kernel memory allocations by type
+.Sh SYNOPSIS
+.Nm dtmalloc Ns Cm :: Ns Ar function Ns Cm :malloc
+.Nm dtmalloc Ns Cm :: Ns Ar function Ns Cm :free
+.Sh DESCRIPTION
+The
+.Nm dtmalloc
+provider instruments
+.Xr malloc 9
+and
+.Xr free 9
+kernel functions to trace memory allocations by type.
+Refer to
+.Xr malloc 9
+for more details about malloc types.
+.Pp
+The
+.Nm dtmalloc Ns Cm :: Ns Ar function Ns Cm :malloc
+probe fires upon a successful allocation.
+Its probe arguments are:
+.Bl -column -offset indent "malloc Probe Argument" "Definition"
+.It Sy Probe Argument Ta Sy Definition
+.It Fa args[0]  Ta Ft struct malloc_type *mtp
+.It Fa args[1]  Ta Ft struct malloc_type_internal *mtip
+.It Fa args[2]  Ta Ft struct malloc_type_stats *mtsp
+.It Fa args[3]  Ta Ft unsigned long size
+.It Fa args[4]  Ta Ft int zindx
+.El
+.Pp
+The
+.Nm dtmalloc Ns Cm :: Ns Ar function Ns Cm :free
+probe fires upon a free operation.
+Its probe arguments are:
+.Bl -column -offset indent "free Probe Argument" "Definition"
+.It Sy free Probe Argument Ta Sy Definition
+.It Fa args[0]  Ta Ft struct malloc_type *mtp
+.It Fa args[1]  Ta Ft struct malloc_type_internal *mtip
+.It Fa args[2]  Ta Ft struct malloc_type_stats *mtsp
+.It Fa args[3]  Ta Ft unsigned long size
+.It Fa args[4]  Ta Always 0
+.El
+.Pp
+The first three arguments for each probe
+.Po i.e.,
+.Fa mtp , mtip ,
+and
+.Fa mtsp Pc
+provide references to the
+.Xr malloc 9
+type internals;
+.Fa size
+is the size of the allocation;
+.Fa zindx
+is the index into the
+.Va kmemzones[]
+array used for the allocation.
+In practice,
+.Fa size
+is the most useful parameter to trace.
+.Sh IMPLEMENTATION NOTES
+The
+.Ar function
+part of the probe description in the
+.Nm dtmalloc
+provider is the
+.Xr malloc 9
+type short description with all whitespace characters replaced
+with underscores.
+For example, a malloc type defined by
+.Bd -literal -offset indent
+MALLOC_DEFINE(M_FOO_BAR, "foo bar", "FooBar subsystem");
+.Ed
+.Pp
+will have probes called
+.Bd -literal -offset indent
+dtmalloc::foo_bar:
+.Ed
+.Sh FILES
+.Bl -tag -width "<sys/malloc.h>"
+.It In sys/malloc.h
+The header where
+.Vt struct malloc_type
+is defined.
+.El
+.Sh EXAMPLES
+.Ss Example 1 : Counting Successful Memory Allocations by Type
+.Bd -literal -offset 2n
+# dtrace -n 'dtmalloc:::malloc {@[stringof args[0]->ks_shortdesc] = count()}'
+dtrace: description 'dtmalloc:::malloc ' matched 480 probes
+^C
+  80211node                                                         1
+  CAM CCB                                                           1
+  CAM periph                                                        1
+  ioctlops                                                          1
+  netlink                                                           1
+  soname                                                            4
+  sysctltmp                                                         4
+  solaris                                                           5
+  acpica                                                           16
+  temp                                                             36
+  lkpikmalloc                                                      44
+  iov                                                             100
+  selfd                                                           648
+.Ed
+.Sh SEE ALSO
+.Xr dtrace 1 ,
+.Xr tracing 7 ,
+.Xr malloc 9
+.Sh AUTHORS
+.An -nosplit
+.Nm
+was written by
+.An John Birrell Aq Mt jb@FreeBSD.org .
+.Pp
+This manual page was written by
+.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .
+.Sh CAVEATS
+The
+.Nm dtmalloc
+provider does not trace
+.Xr uma 9
+allocations.

share/man/man9/malloc.9

@@ -28,7 +28,7 @@
 .\"
 .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
 .\"
-.Dd August 4, 2024
+.Dd May 12, 2026
 .Dt MALLOC 9
 .Os
 .Sh NAME
@@ -394,6 +394,7 @@ functions.
 Failing consistency checks will cause a panic or a system console
 message.
 .Sh SEE ALSO
+.Xr dtrace_dtmalloc 4 ,
 .Xr numa 4 ,
 .Xr vmstat 8 ,
 .Xr contigmalloc 9 ,