git: 03bc95b060a9 - main - dtrace_dtmalloc.4: Document the DTrace dtmalloc provider
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Tue, 12 May 2026 18:12:09 UTC
The branch main has been updated by 0mp:
URL: https://cgit.FreeBSD.org/src/commit/?id=03bc95b060a91ed9d410270d00d1dd4f8edcdcc7
commit 03bc95b060a91ed9d410270d00d1dd4f8edcdcc7
Author: Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2025-07-17 20:55:49 +0000
Commit: Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2026-05-12 18:03:11 +0000
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 | 3 +-
share/man/man4/Makefile | 1 +
share/man/man4/dtrace_dtmalloc.4 | 132 +++++++++++++++++++++++++++
share/man/man9/malloc.9 | 3 +-
4 files changed, 137 insertions(+), 2 deletions(-)
diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
index e78b6e1875ae..ad639f337a72 100644
--- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
+++ b/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 ,
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index b9c441e97597..4f067f3ef757 100644
--- a/share/man/man4/Makefile
+++ b/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 \
diff --git a/share/man/man4/dtrace_dtmalloc.4 b/share/man/man4/dtrace_dtmalloc.4
new file mode 100644
index 000000000000..97b4ffd8a057
--- /dev/null
+++ b/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.
diff --git a/share/man/man9/malloc.9 b/share/man/man9/malloc.9
index 06f5ed4ef360..269a766e6168 100644
--- a/share/man/man9/malloc.9
+++ b/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 ,