git: 3ccb2d9513e6 - main - dtrace_callout_execute.4: Document the DTrace callout_execute provider

The branch main has been updated by 0mp:

URL: https://cgit.FreeBSD.org/src/commit/?id=3ccb2d9513e6a2e046e635c186da68acf8f8498b

commit 3ccb2d9513e6a2e046e635c186da68acf8f8498b
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2025-11-04 11:10:55 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2025-11-04 11:10:55 +0000

    dtrace_callout_execute.4: Document the DTrace callout_execute provider
    
    MFC after:      2 weeks
    Fixes:          91dd9aae1ab8 Add explicit static DTrace tracing to the callout mechanism
    Differential Revision:  https://reviews.freebsd.org/D51397
---
 cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 |  3 +-
 share/man/man4/Makefile                      |  1 +
 share/man/man4/dtrace_callout_execute.4      | 68 ++++++++++++++++++++++++++++
 share/man/man9/callout.9                     |  4 +-
 4 files changed, 74 insertions(+), 2 deletions(-)

diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
index f09cbe1ac27b..456a9e319987 100644
--- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
+++ b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
@@ -20,7 +20,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 3, 2025
+.Dd November 4, 2025
 .Dt DTRACE 1
 .Os
 .Sh NAME
@@ -1292,6 +1292,7 @@ in
 .Xr cpp 1 ,
 .Xr dwatch 1 ,
 .Xr dtrace_audit 4 ,
+.Xr dtrace_callout_execute 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 95618227a010..34edf6ad455d 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1005,6 +1005,7 @@ _ccd.4=		ccd.4
 
 .if ${MK_CDDL} != "no"
 _dtrace_provs=	dtrace_audit.4 \
+		dtrace_callout_execute.4 \
 		dtrace_dtrace.4 \
 		dtrace_fbt.4 \
 		dtrace_io.4 \
diff --git a/share/man/man4/dtrace_callout_execute.4 b/share/man/man4/dtrace_callout_execute.4
new file mode 100644
index 000000000000..1154ed066b97
--- /dev/null
+++ b/share/man/man4/dtrace_callout_execute.4
@@ -0,0 +1,68 @@
+.\"
+.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org>
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd November 4, 2025
+.Dt DTRACE_CALLOUT_EXECUTE 4
+.Os
+.Sh NAME
+.Nm dtrace_callout_execute
+.Nd a DTrace provider for the callout API
+.Sh SYNOPSIS
+.Nm callout_execute Ns Cm :kernel::callout_start
+.Nm callout_execute Ns Cm :kernel::callout_end
+.Sh DESCRIPTION
+The
+.Nm callout_execute
+provider allows for tracing the
+.Xr callout 9
+mechanism.
+.Pp
+The
+.Nm callout_execute Ns Cm :kernel::callout_start
+probe fires just before a callout.
+.Pp
+The
+.Nm callout_execute Ns Cm :kernel::callout_end
+probe fires right after a callout.
+.Pp
+The only argument to the
+.Nm callout_execute
+probes,
+.Fa args[0] ,
+is a callout handler
+.Ft struct callout *
+of the invoked callout.
+.Sh EXAMPLES
+.Ss Example 1: Graph of Callout Execution Time
+The following
+.Xr d 7
+script generates a distribution graph of
+.Xr callout 9
+execution times:
+.Bd -literal -offset 2n
+callout_execute:::callout_start
+{
+    self->cstart = timestamp;
+}
+
+callout_execute:::callout_end
+{
+    @length = quantize(timestamp - self->cstart);
+}
+.Ed
+.Sh SEE ALSO
+.Xr dtrace 1 ,
+.Xr tracing 7 ,
+.Xr callout 9 ,
+.Xr SDT 9
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm callout_execute
+provider was written by
+.An Robert N. M. 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/callout.9 b/share/man/man9/callout.9
index 0e59ef8ab2b1..637049ec1ef5 100644
--- a/share/man/man9/callout.9
+++ b/share/man/man9/callout.9
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd January 22, 2024
+.Dd November 4, 2025
 .Dt CALLOUT 9
 .Os
 .Sh NAME
@@ -789,6 +789,8 @@ and
 functions return a value of one if the callout was still pending when it was
 called, a zero if the callout could not be stopped and a negative one is it
 was either not running or has already completed.
+.Sh SEE ALSO
+.Xr dtrace_callout_execute 4
 .Sh HISTORY
 .Fx
 initially used the long standing