From nobody Mon Jul 14 13:02:19 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4bgjCJ0SXMz61k1d; Mon, 14 Jul 2025 13:02:20 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4bgjCH4TfBz3G7X; Mon, 14 Jul 2025 13:02:19 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1752498139; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=p9XLN5FLrhGWfEUlkhsP0Bpf07JPEOPn/ffGS1K51kE=; b=W4RNNGW+50zcLSy2tWLqv7v/F05m80mpTauWy0rx6ViMDpzprtZDeu11sPy16tCpGn4VPW cw99NMrbysKmk2kx7VAFg8kknQounqMgkT2HgqNBFJPZjNbIyALssvJ6XlzzXBQxCwBhlK uK2gu/Xrs3RKtfoKxQTp5fW/4s45gFiKPZADBdYRlj57l0MCo3xTpq2ZYCrA7bcnV1pQIz qn9HUwr/a6NXJLZIEoTGd6yv30MOm3u7vKEKC6mDsM91GEcWEfPL297PUfu0DXJ8qPAiMt G6VF++bDnZdD1Rlx0SX175kmQ9eOPsx1znCDXzq97QfT1JJOksZTJMHHVrPgSg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1752498139; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=p9XLN5FLrhGWfEUlkhsP0Bpf07JPEOPn/ffGS1K51kE=; b=F9SI3fTtKqSAbwnRjMwjkhGBpNDKP9ISdXGdI/GyWTEBfkgMJQ5lkEQI2yoofiJd11sXss zcYtYYTITnYF81+hBzfDL+TLdW6FTTpHr5/mweos3UUGPhQEWCVkcji8oaw2Z7WizE9kNF 1Syk1J48la34RcZdfP9I3WHyTj+U0BKjyx7JDFtEYfi9hkdlVg4vUgeKe2dixIcSyq/3pD aqwbDBsYGOyHq04gXjiZikpB+jpiP+07+LEflA5SZCOvnZiHGuTblIs2ynvZK6iAA7TRXV dwXp4lDE3CgSrmjkP+GL1xjQNCdfK96Ug+LeSw6q/abSy/KLkq1ZQR2rJwCT+Q== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1752498139; a=rsa-sha256; cv=none; b=M3+f1X8Jb/5WQAKbPYFc1cD037dQ/fKqqzx4Hvq/K/JNU1KFGZS0UPdKVBUXDbqxT1Ghvy onG0yMPxenI2E72ZpHb9inoXqHNPo1vaLuWooDwzfQz3XmEosLaN4VNm1RaBg1GlIk9X8I a3ZH6YUgpQ8nk55fOwjPMGWzvyvKSPyAwmB3lSzmt08Fg646BiXlmhFcFajlbiO/9aIfpC VgyE3B6i4G8Dfqe3E+BpLhilauYN3BprUk1HAo6ECMpCWdmmkfEFRd/qg9fYBjdajZM7L1 7FFKMC2idVvaZJeb/wkb5Nksyx8FLjp66xWwVIaQYbh88ePRSssyIrNrAZyWVw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4bgjCH44gwzw4D; Mon, 14 Jul 2025 13:02:19 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 56ED2JW4049364; Mon, 14 Jul 2025 13:02:19 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 56ED2JbT049361; Mon, 14 Jul 2025 13:02:19 GMT (envelope-from git) Date: Mon, 14 Jul 2025 13:02:19 GMT Message-Id: <202507141302.56ED2JbT049361@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Mateusz Piotrowski <0mp@FreeBSD.org> Subject: git: 193f2289fc9a - main - d.7: Document the DTrace scripting language List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: 0mp X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 193f2289fc9a5c7464b460e1e61c2c0ac8c9f57d Auto-Submitted: auto-generated The branch main has been updated by 0mp: URL: https://cgit.FreeBSD.org/src/commit/?id=193f2289fc9a5c7464b460e1e61c2c0ac8c9f57d commit 193f2289fc9a5c7464b460e1e61c2c0ac8c9f57d Author: Mateusz Piotrowski <0mp@FreeBSD.org> AuthorDate: 2025-07-11 18:10:58 +0000 Commit: Mateusz Piotrowski <0mp@FreeBSD.org> CommitDate: 2025-07-14 13:01:51 +0000 d.7: Document the DTrace scripting language Reviewed by: bcr, christos, ziaee Event: Berlin Hackathon 202507 Relnotes: yes Differential Revision: https://reviews.freebsd.org/D51268 --- cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 | 3 +- share/man/man7/Makefile | 1 + share/man/man7/d.7 | 287 +++++++++++++++++++++++++++ share/man/man7/intro.7 | 5 +- 4 files changed, 294 insertions(+), 2 deletions(-) diff --git a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 index 10a6922d79db..f3d7a49e0e78 100644 --- a/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 +++ b/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 @@ -20,7 +20,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 12, 2025 +.Dd June 14, 2025 .Dt DTRACE 1 .Os .Sh NAME @@ -1235,6 +1235,7 @@ Invalid command line options or arguments were specified. .Xr dtrace_udp 4 , .Xr dtrace_udplite 4 , .Xr elf 5 , +.Xr d 7 , .Xr tracing 7 , .Xr SDT 9 .Rs diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile index 7daa0ffed8ea..1e50242a1754 100644 --- a/share/man/man7/Makefile +++ b/share/man/man7/Makefile @@ -6,6 +6,7 @@ MAN= arch.7 \ bsd.snmpmod.mk.7 \ build.7 \ c.7 \ + d.7 \ clocks.7 \ crypto.7 \ development.7 \ diff --git a/share/man/man7/d.7 b/share/man/man7/d.7 new file mode 100644 index 000000000000..30efb0249a77 --- /dev/null +++ b/share/man/man7/d.7 @@ -0,0 +1,287 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd July 14, 2025 +.Dt D 7 +.Os +.Sh NAME +.Nm D +.Nd DTrace scripting language overview +.Sh SYNOPSIS +.Sm off +.Ar provider Cm \&: +.Ar module Cm \&: +.Ar function Cm \&: +.Ar name +.Sm on +.Sm off +.Oo +.Cm / +.Ar predicate +.Cm / +.Sm on +.Oc +.Op Cm \&{ Ns Ar action Ns Cm \&} +.Sh DESCRIPTION +.Nm D +is the +.Xr dtrace 1 +scripting language. +This manual provides a brief reference of the +.Nm +language and scripting. +.Pp +This manual page serves as a short reference of the language. +Refer to books listed in +.Sx SEE ALSO +for a complete reference. +.Sh PROBE'S DESCRIPTION +A probe's description consists of four elements: +.Sm off +.D1 Ar provider Ns Cm \&: Ns Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on +.Pp +The exact meaning of +.Ar module , +.Ar function , +and +.Ar name +depends on +.Ar provider . +.Sh USER-DEFINED VARIABLE TYPES +.Bl -column "thread-local" "Syntax" +.It Sy Type Ta Sy Syntax +.It global Ta Va variable_name +.It thread-local Ta Sy self-> Ns Va variable_name +.It clause-local Ta Sy this-> Ns Va variable_name +.It aggregate Ta Sy @ Ns Va variable_name +.El +.Pp +.Em Tips : +.Bl -dash -compact +.It +Always use the variable type with the smallest scope +to minimize processing overhead. +.It +Use aggregate variables instead of global variables when possible. +Aggregate variables are multi-CPU safe in contrast to global variables. +.El +.Sh BUILT-IN VARIABLES +.Ss Probe Arguments +.Bl -tag -width "arg0, ..., arg9" +.It Va args[] +The array of typed probe arguments. +.It Va arg0 , ... , arg9 +The untyped probe arguments represented as 64-bit unsigned integers. +Only the first ten arguments are available this way. +.El +.Ss Probe Information +.Bl -tag -width probeprov +.It Va epid +The enabled probe ID which uniquely identifies an enabled probe. +An enabled probe is defined by its probe ID, its predicates, and its actions. +.It Va id +The probe ID which uniquely identifies a probe available to DTrace. +.It Va probeprov +The +.Ar provider +in the probe's description +.Sm off +.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on . +.It Va probemod +The +.Ar module +in the probe's description +.Sm off +.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on . +.It Va probefunc +The +.Ar function +in the probe's description +.Sm off +.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on . +.It Va probename +The +.Ar name +in the probe's description +.Sm off +.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on . +.El +.Ss Process Information +.Bl -tag -width execname +.It Va execargs +The process arguments. +Effectively, +.Ql curthread->td_proc->p_args . +.It Va execname +The name of the current process. +Effectively, +.Ql curthread->td_proc->p_comm . +.It Va gid +The group ID of the current process. +.It Va pid +The process ID of the current process. +.It Va ppid +The parent process ID of the current process. +.It Va uid +The user ID of the current process. +.El +.Ss Thread Information +.Bl -tag -width curlwpsinfo +.It Va uregs[] +The saved user-mode register values. +.It Va cpu +The ID of the current CPU. +.It Va stackdepth +The kernel stack frame depth. +.It Va ustackdepth +The userspace counterpart of +.Va stackdepth . +.It Va tid +The thread ID. +Depending on the context, +this can be either the ID of a kernel thread or a thread in a user process. +.It Va errno +The +.Xr errno 2 +value of the last system call performed by the current thread. +.It Va curlwpsinfo +A pointer to the +.Vt lwpsinfo_t +representation of the current thread. +Refer to +.Xr dtrace_proc 4 +for more details. +.It Va curpsinfo +A pointer to the +.Vt psinfo_t +representation of the current process. +Refer to +.Xr dtrace_proc 4 +for more details. +.It Va curthread +A pointer to the thread struct that is currently on-CPU. +E.g., +.Ql curthread->td_name +returns the thread name. +The +.In sys/proc.h +header documents all members of +.Vt struct thread . +.It Va caller +The address of the kernel thread instruction at the time of execution +of the current probe. +.It Va ucaller +The userspace counterpart of +.Va caller . +.El +.Ss Timestamps +.Bl -tag -width walltimestamp +.It Va timestamp +The number of nanoseconds since boot. +Suitable for calculating relative time differences of elapsed time and latency. +.It Va vtimestamp +The number of nanoseconds that the current thread spent on CPU. +The counter is not increased during handling of a fired DTrace probe. +Suitable for calculating relative time differences of on-CPU time. +.It Va walltimestamp +The number of nanoseconds since the Epoch +.Pq 1970-01-01T00+00:00 . +Suitable for timestamping logs. +.El +.Sh BUILT-IN FUNCTIONS +.Ss Aggregation Functions +.Bl -tag -compact -width "llquantize(value, factor, low, high, nsteps)" +.It Fn avg value +Average +.It Fn count +Count +.It Fn llquantize value factor low high nsteps +Log-linear quantization +.It Fn lquantize value low high nsteps +Linear quantization +.It Fn max value +Maximum +.It Fn min value +Minimum +.It Fn quantize value +Power-of-two frequency distribution +.It Fn stddev value +Standard deviation +.It Fn sum value +Sum +.El +.Ss Kernel Destructive Functions +By default, +.Xr dtrace 1 +does not permit the use of destructive actions. +.Bl -tag -width "chill(nanoseconds)" +.It Fn breakpoint +Set a kernel breakpoint and transfer control to +the +.Xr ddb 4 +kernel debugger. +.It Fn chill nanoseconds +Spin on the CPU for the specified number of +.Fa nanoseconds . +.It Fn panic +Panic the kernel. +.El +.Sh FILES +.Bl -tag -width /usr/share/dtrace +.It Pa /usr/share/dtrace +DTrace scripts shipped with +.Fx +base. +.El +.Sh SEE ALSO +.Xr awk 1 , +.Xr dtrace 1 , +.Xr tracing 7 +.Rs +.%B The illumos Dynamic Tracing Guide +.%D 2008 +.%U https://illumos.org/books/dtrace/ +.Re +.Rs +.%A Brendan Gregg +.%A Jim Mauro +.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD +.%I Prentice Hall +.%D 2011 +.%U https://www.brendangregg.com/dtracebook/ +.Re +.Rs +.%A George Neville-Neil +.%A Jonathan Anderson +.%A Graeme Jenkinson +.%A Brian Kidney +.%A Domagoj Stolfa +.%A Arun Thomas +.%A Robert N. M. Watson +.%C Cambridge, United Kingdom +.%D August 2018 +.%T Univeristy of Cambridge Computer Laboratory +.%R OpenDTrace Specification version 1.0 +.%U https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf +.Re +.Sh HISTORY +This manual page first appeared in +.Fx 15.0 . +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . +.Sh BUGS +The +.Va cwd +variable which typically provides the current working directory is +not supported on +.Fx +at the moment. diff --git a/share/man/man7/intro.7 b/share/man/man7/intro.7 index d889c2dd299f..43e48de87bc5 100644 --- a/share/man/man7/intro.7 +++ b/share/man/man7/intro.7 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd June 23, 2025 +.Dd July 14, 2025 .Dt INTRO 7 .Os .Sh NAME @@ -49,6 +49,9 @@ system timekeeping clocks available in .It Xr crypto 7 cryptographic algorithms provided by OpenCrypto in .Fx +.It Xr d 7 +.Xr dtrace 1 +scripting language overview .It Xr development 7 development introduction to .Fx