diff options
Diffstat (limited to 'share/man/man7')
| -rw-r--r-- | share/man/man7/Makefile | 1 | ||||
| -rw-r--r-- | share/man/man7/arch.7 | 11 | ||||
| -rw-r--r-- | share/man/man7/d.7 | 287 | ||||
| -rw-r--r-- | share/man/man7/intro.7 | 5 | ||||
| -rw-r--r-- | share/man/man7/tracing.7 | 15 |
5 files changed, 306 insertions, 13 deletions
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/arch.7 b/share/man/man7/arch.7 index 91f6953370d9..fe4e8055a8b1 100644 --- a/share/man/man7/arch.7 +++ b/share/man/man7/arch.7 @@ -24,7 +24,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd April 12, 2025 +.Dd July 14, 2025 .Dt ARCH 7 .Os .Sh NAME @@ -67,8 +67,7 @@ and should be avoided. .Pp On some architectures, e.g., -.Dv powerpc -and AIM variants of +AIM variants of .Dv powerpc64 , the kernel uses a separate address space. On other architectures, kernel and a user mode process share a @@ -88,9 +87,6 @@ release to support each architecture. .It aarch64 Ta 11.0 .It amd64 Ta 5.1 .It armv7 Ta 12.0 -.It i386 Ta 1.0 -.It powerpc Ta 6.0 -.It powerpcspe Ta 12.0 .It powerpc64 Ta 9.0 .It powerpc64le Ta 13.0 .It riscv64 Ta 12.0 @@ -104,6 +100,7 @@ Discontinued architectures are shown in the following table. .It armeb Ta 8.0 Ta 11.4 .It armv6 Ta 10.0 Ta 14.x .It ia64 Ta 5.0 Ta 10.4 +.It i386 Ta 1.0 Ta 14.x .It mips Ta 8.0 Ta 13.5 .It mipsel Ta 9.0 Ta 13.5 .It mipselhf Ta 12.0 Ta 13.5 @@ -114,6 +111,8 @@ Discontinued architectures are shown in the following table. .It mips64elhf Ta 12.0 Ta 13.5 .It mips64hf Ta 12.0 Ta 13.5 .It pc98 Ta 2.2 Ta 11.4 +.It powerpc Ta 6.0 Ta 14.x +.It powerpcspe Ta 12.0 Ta 14.x .It riscv64sf Ta 12.0 Ta 13.5 .It sparc64 Ta 5.0 Ta 12.4 .El diff --git a/share/man/man7/d.7 b/share/man/man7/d.7 new file mode 100644 index 000000000000..f4686d98b1d1 --- /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 June 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 diff --git a/share/man/man7/tracing.7 b/share/man/man7/tracing.7 index 0bd64f197084..7085bac78385 100644 --- a/share/man/man7/tracing.7 +++ b/share/man/man7/tracing.7 @@ -3,12 +3,12 @@ .\" .\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> .\" -.Dd June 19, 2025 +.Dd July 12, 2025 .Dt TRACING 7 .Os .Sh NAME .Nm tracing -.Nd introduction to tracing and performance monitoring facilities +.Nd introduction to FreeBSD tracing and performance monitoring .Sh DESCRIPTION .Fx features a large variety of tracing and performance monitoring facilities. @@ -34,7 +34,6 @@ for more details. is a user-friendly wrapper for DTrace. It simplifies common DTrace usage patterns and requires less expert knowledge to operate. -.Pp .Ss Userland Tracing .Xr truss 1 traces system calls. @@ -55,7 +54,8 @@ it asynchronously logs entries to a trace file configured with .Xr ktrace 2 (typically .Pa ktrace.out ) , -and it can log other types of kernel events, such as page faults and name lookups +and it can log other types of kernel events, such as page faults +and name lookups .Po refer to .Fl t in @@ -73,11 +73,14 @@ It comes in handy for some niche purposes during kernel development. It lets kernel programmers log events to a global ring buffer, which can later be dumped using .Xr ktrdump 8 . +.Ss Hardware-Accelerated Tracing +.Xr hwt 4 +is a kernel trace framework providing infrastructure +for hardware-assisted tracing. .Ss Hardware Counters -.Pp .Xr pmcstat 8 , and its kernel counterpart, -.Xr hwmpc 4 , +.Xr hwpmc 4 , is the .Fx facility for conducting performance measurements with hardware counters. |