diff options
Diffstat (limited to 'share/man')
-rw-r--r-- | share/man/man4/Makefile | 9 | ||||
-rw-r--r-- | share/man/man4/dtrace_dtrace.4 | 191 | ||||
-rw-r--r-- | share/man/man4/dtrace_fbt.4 | 332 | ||||
-rw-r--r-- | share/man/man4/dtrace_kinst.4 | 12 | ||||
-rw-r--r-- | share/man/man4/dtrace_profile.4 | 129 | ||||
-rw-r--r-- | share/man/man4/gif.4 | 154 | ||||
-rw-r--r-- | share/man/man4/hwt.4 | 3 | ||||
-rw-r--r-- | share/man/man4/md.4 | 4 | ||||
-rw-r--r-- | share/man/man4/mtw.4 | 78 | ||||
-rw-r--r-- | share/man/man4/sa.4 | 3 | ||||
-rw-r--r-- | share/man/man4/snd_uaudio.4 | 36 | ||||
-rw-r--r-- | share/man/man4/ufshci.4 | 181 | ||||
-rw-r--r-- | share/man/man5/pf.conf.5 | 17 | ||||
-rw-r--r-- | share/man/man5/rc.conf.5 | 6 | ||||
-rw-r--r-- | share/man/man5/src.conf.5 | 36 | ||||
-rw-r--r-- | share/man/man5/style.Makefile.5 | 8 | ||||
-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 | 6 | ||||
-rw-r--r-- | share/man/man8/nanobsd.8 | 8 | ||||
-rw-r--r-- | share/man/man9/vnode.9 | 4 |
23 files changed, 1423 insertions, 98 deletions
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 7c8a8f3afc45..505e83a67369 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -594,6 +594,7 @@ MAN= aac.4 \ tws.4 \ udp.4 \ udplite.4 \ + ${_ufshci.4} \ unionfs.4 \ ure.4 \ vale.4 \ @@ -746,7 +747,6 @@ MLINKS+=lge.4 if_lge.4 MLINKS+=lo.4 loop.4 MLINKS+=lp.4 plip.4 MLINKS+=malo.4 if_malo.4 -MLINKS+=md.4 vn.4 MLINKS+=mem.4 kmem.4 MLINKS+=mfi.4 mfi_linux.4 \ mfi.4 mfip.4 @@ -938,6 +938,10 @@ MLINKS+=hwt.4 spe.4 .endif .endif +.if ${MACHINE_CPUARCH} == "amd64" || ${MACHINE_CPUARCH} == "aarch64" +_ufshci.4= ufshci.4 +.endif + .if ${MACHINE_CPUARCH} == "amd64" || ${MACHINE_CPUARCH} == "i386" || \ ${MACHINE_CPUARCH} == "aarch64" _gve.4= gve.4 @@ -980,11 +984,14 @@ _ccd.4= ccd.4 .if ${MK_CDDL} != "no" _dtrace_provs= dtrace_audit.4 \ + dtrace_dtrace.4 \ + dtrace_fbt.4 \ dtrace_io.4 \ dtrace_ip.4 \ dtrace_kinst.4 \ dtrace_lockstat.4 \ dtrace_proc.4 \ + dtrace_profile.4 \ dtrace_sched.4 \ dtrace_sctp.4 \ dtrace_tcp.4 \ diff --git a/share/man/man4/dtrace_dtrace.4 b/share/man/man4/dtrace_dtrace.4 new file mode 100644 index 000000000000..b8c31005b47e --- /dev/null +++ b/share/man/man4/dtrace_dtrace.4 @@ -0,0 +1,191 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd July 14, 2025 +.Dt DTRACE_DTRACE 4 +.Os +.Sh NAME +.Nm dtrace_dtrace +.Nd a DTrace provider for BEGIN, END, and ERROR probes +.Sh SYNOPSIS +.Nm dtrace Ns Cm :::BEGIN +.Nm dtrace Ns Cm :::END +.Nm dtrace Ns Cm :::ERROR +.Sh DESCRIPTION +The +.Nm dtrace +provider implements three special probes related to the life cycle of the +DTrace program itself. +.Ss dtrace:::BEGIN +The +.Nm dtrace Ns Cm :::BEGIN +probe fires at the beginning of a +.Xr dtrace 1 , +program before tracing has begun. +It provides a convenient place for initializing variables +and printing column headers. +.Pp +Variables such as +.Va stack +or +.Va execname +cannot be relied upon in the execution context of the +.Nm dtrace Ns Cm :::BEGIN +probe. +.Ss dtrace:::END +The +.Nm dtrace Ns Cm :::END +probe fires at the end of a +.Xr dtrace 1 +program, when all tracing has stopped. +.Ss dtrace:::ERROR +The +.Nm dtrace Ns Cm :::ERROR +probe fires when an unexpected runtime error occurs in another probe. +.Pp +The following table describes the arguments to +.Nm dtrace Ns Cm :::ERROR . +.Bl -column -offset indent "Argument" "Definition" +.It Sy Argument Ta Sy Definition +.It Fa arg1 Ta Enabled probe identifier (EPID) +of the probe where the runtime error occurred +.It Fa arg2 Ta Index of the action statement that caused the error +.It Fa arg3 Ta DIF offset into the action if available (otherwise -1) +.It Fa arg4 Ta Fault type +.It Fa arg5 Ta Accessed address (or 0 if not applicable) when +.Va arg4 +is of fault type +.Dv DTRACEFLT_BADADDR , DTRACEFLT_BADALIGN , DTRACEFLT_KPRIV , +or +.Dv DTRACEFLT_UPRIV +.El +.Pp +The fault types are: +.Bl -tag -offset indent -width "DTRACEFLT_NOSCRATCH" -compact +.It Dv DTRACEFLT_UNKNOWN +Unknown fault +.It Dv DTRACEFLT_BADADDR +Bad address +.It Dv DTRACEFLT_BADALIGN +Bad alignment +.It Dv DTRACEFLT_ILLOP +Illegal operation +.It Dv DTRACEFLT_DIVZERO +Divide-by-zero +.It Dv DTRACEFLT_NOSCRATCH +Out of scratch space +.It Dv DTRACEFLT_KPRIV +Illegal kernel access +.It Dv DTRACEFLT_UPRIV +Illegal user access +.It Dv DTRACEFLT_TUPOFLOW +Tuple stack overflow +.It Dv DTRACEFLT_BADSTACK +Bad stack +.El +.Sh FILES +.Bl -tag -width '<sys/dtrace.h>' +.It In sys/dtrace.h +The header file containing the definitions of DTrace fault types. +.El +.Sh EXAMPLES +.Ss Example 1 : Custom Column Headers +The following script uses the +.Nm dtrace Ns Cm :::BEGIN +probe to print column headers. +Note the pragma line setting the +.Ql quiet +option to disable the default column headers. +.Bd -literal -offset 2n +#pragma D option quiet + +dtrace:::BEGIN +{ + printf(" %12s %-20s %-20s %s\en", + "DELTA(us)", "OLD", "NEW", "TIMESTAMP"); +} +.Ed +.Ss Example 2 : Handling Runtime Errors with dtrace:::ERROR +The following script causes a runtime error by dereferencing a pointer +on address +.Ad 19930908 +in the +.Cm BEGIN +probe. +As a result, the +.Cm ERROR +probe fires and prints out +.Dq Oops +along with the probe arguments. +At that point, the program ends and fires the +.Cm END +probe. +.\" It might look weird to define ERROR first, but that is on purpose. +.\" This way the probe IDs and EPIDs are a bit more mixed up +.\" and are easier to understand. +.Bd -literal -offset 2n +ERROR +{ + printf("Oops\en"); + printf("EPID (arg1): %d\en", arg1); + printf("Action index (arg2): %d\en", arg2); + printf("DIF offset (arg3): %d\en", arg3); + printf("Fault type (arg4): %d\en", arg4); + printf("Accessed address (arg5): %X\en", arg5); + exit(1); +} +BEGIN +{ + *(int *)0x19931101; +} +END { + printf("Bye"); +} +.Ed +.Pp +This script will result in the following output: +.Bd -literal -offset 2n +CPU ID FUNCTION:NAME + 2 3 :ERROR Oops +EPID (arg1): 2 +Action index (arg2): 1 +DIF offset (arg3): 16 +Fault type: 1 +arg5: 19931101 + +dtrace: error on enabled probe ID 2 (ID 1: dtrace:::BEGIN): invalid address (0x19931101) in action #1 at DIF offset 16 + 2 2 :END Bye +.Ed +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr tracing 7 +.Rs +.%B The illumos Dynamic Tracing Guide +.%O Chapter dtrace Provider +.%D 2008 +.%U https://illumos.org/books/dtrace/chp-dtrace.html +.Re +.Sh AUTHORS +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . +.Sh CAVEATS +The +.Nm dtrace Ns Cm :::ERROR +probe arguments cannot be accessed through the typed +.Va args[] +array. +.Pp +.Xr dtrace 1 +will not fire the +.Nm dtrace Ns Cm :::ERROR +probe recursively. +If an error occurs in one of the action statements of the +.Nm dtrace Ns Cm :::ERROR , +then +.Xr dtrace 1 +will abort further processing of +the +.Nm dtrace Ns Cm :::ERROR +probe's actions. diff --git a/share/man/man4/dtrace_fbt.4 b/share/man/man4/dtrace_fbt.4 new file mode 100644 index 000000000000..3e35bb8c5bbc --- /dev/null +++ b/share/man/man4/dtrace_fbt.4 @@ -0,0 +1,332 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd July 16, 2025 +.Dt DTRACE_FBT 4 +.Os +.Sh NAME +.Nm dtrace_fbt +.Nd a DTrace provider for dynamic kernel tracing based on function boundaries +.Sh SYNOPSIS +.Nm fbt Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry +.Nm fbt Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return +.Sh DESCRIPTION +The Function Boundary Tracing +.Pq Nm fbt +provider instruments the entry and return of almost every kernel function +corresponding to an +.Xr elf 5 +symbol in the kernel and loaded kernel modules. +.Pp +.Nm fbt Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry +fires whenever the +.Ar function +is called. +.Nm fbt Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return +fires when the +.Ar function +returns. +.Pp +The +.Ar module +in the probe description is either the name of the loaded kernel module +or +.Ql kernel +for functions compiled into the kernel. +.Ss Function Boundary Instrumentation +The +.Nm fbt +will always instrument a function's entry, but +its return will be intsrumented so long as it can find a +.Ql ret +instruction. +.Pp +In some cases, +.Nm fbt +cannot instrument a function's entry and/or return. +Refer to subsection +.Sx Frame Pointer +for more details. +.Ss Probe Arguments +The arguments of the entry probe +.Pq Nm fbt Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry +are the arguments of the traced function call. +.Bl -column -offset indent "Entry Probe Argument" "Definition" +.It Sy Entry Probe Argument Ta Sy Definition +.It Fa args[0] Ta Function's first argument, typed +.Pq e.g., Xr malloc 9 Ap s Ft size_t Fa size +.It Fa args[1] Ta Function's second argument, typed +.Pq e.g., Xr malloc 9 Ap s Ft struct malloc_type Fa *type +.It Fa args[2] Ta Function's third argument, typed +.Pq e.g., Xr malloc 9 Ap s Ft int Fa flags +.It Fa ... Ta ... +.El +.Pp +The arguments of the return probe +.Pq Nm fbt Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return +are +.Fa args[0] +.Po +the offset of the firing return instruction within the function; +useful to tell apart two different return statements in a single function +.Pc +and +.Fa args[1] +.Pq the return value, if any . +.Bl -column -offset indent "Return Probe Argument" "Definition" +.It Sy Return Probe Argument Ta Sy Definition +.It Fa args[0] Ta Offset of the traced return instruction +.It Fa args[1] Ta Function's return value +.Po e.g., a kernel virtual address if returning from a successful +.Xr malloc 9 +.Pc +.El +.Pp +Subsection +.Sx Example 2 : Getting Details About Probe's Arguments +shows how to get probe's argument count and types directly with +.Xr dtrace 1 +without having to resort to the reading function's source code +or documentation. +.Sh EXAMPLES +.Ss Example 1 : Listing Available FBT Probes +The following example shows how to list all the available +.Nm fbt +probes. +.Bd -literal -offset 2n +# dtrace -l -P fbt + ID PROVIDER MODULE FUNCTION NAME +[...] +31868 fbt kernel hammer_time entry +31869 fbt kernel hammer_time return +[...] +.Ed +.Pp +Since +.Fn hammer_time +is a part of the kernel and not a separate loaded module, the +.Ar module +column displays +.Ql kernel . +.Ss Example 2 : Getting Details About Probe's Arguments +The following example shows how to generate a program stability report of +.Xr malloc 9 Ap s +entry and return probes. +Those reports are useful to view +the probe's number of arguments and their types. +.Bd -literal -offset 2n +# dtrace -l -v -n fbt::malloc:entry +[...] + Argument Types + args[0]: size_t + args[1]: struct malloc_type * + args[2]: int +.Ed +.Pp +The count and types of +.Nm fbt Ns Cm \&::malloc:entry +arguments +match the function signature of +.Xr malloc 9 : +.Va args[0] +is +.Ft size_t , +.Va args[1] +is +.Ft "struct malloc_type *" , +and +.Va "args[2]" +is +.Ft int . +.Bd -literal -offset 2n +# dtrace -l -v -n fbt::malloc:return +[...] + Argument Types + args[0]: int + args[1]: void * +.Ed +.Pp +The +.Cm return +probe reports two arguments and their types: +the return instruction offset +.Pq the usual Ft int +and the function's return value, which in this case is +.Ft void * , +as +.Xr malloc 9 +returns a kernel virtual address. +.Ss Example 3 : Counting Kernel Slab Memory Allocation by Function +.Bd -literal -offset 2n +# dtrace -n 'fbt::kmem*:entry { @[probefunc] = count(); }' +dtrace: description 'fbt::kmem*:entry ' matched 47 probes +^C + kmem_alloc_contig 1 + kmem_alloc_contig_domainset 1 + kmem_cache_reap_active 1 + kmem_alloc_contig_pages 2 + kmem_free 2 + kmem_std_destructor 19 + kmem_std_constructor 26 + kmem_cache_free 151 + kmem_cache_alloc 181 +.Ed +.Ss Example 4 : Counting Kernel Slab Memory Allocation by Calling Function +.Bd -literal -offset 2n +# dtrace -q -n 'fbt::kmem*:entry { @[caller] = count(); } END { printa("%40a %@16d\en", @); }' +^C + kernel`contigmalloc+0x33 1 + kernel`free+0xd3 1 + kernel`kmem_alloc_contig+0x29 1 +kernel`kmem_alloc_contig_domainset+0x19a 1 + zfs.ko`arc_reap_cb_check+0x16 1 +.Ed +.Ss Example 5 : Counting Kernel malloc()'s by Calling Function +.Bd -literal -offset 2n +# dtrace -q -n 'fbt::malloc:entry { @[caller] = count(); } END { printa("%45a %@16d\en", @); }' +^C + kernel`devclass_get_devices+0xa8 1 + kernel`sys_ioctl+0xb7 1 + dtrace.ko`dtrace_ioctl+0x15c1 1 + dtrace.ko`dtrace_ioctl+0x972 2 + dtrace.ko`dtrace_dof_create+0x35 2 + kernel`kern_poll_kfds+0x2f0 4 + kernel`kern_poll_kfds+0x28a 19 +.Ed +.Ss Example 6 : Counting Kernel malloc()'s by Kernel Stack Trace +.Bd -literal -offset 2n +# dtrace -q -n 'fbt::malloc:entry { @[stack()] = count(); }' +^C + dtrace.ko`dtrace_dof_create+0x35 + dtrace.ko`dtrace_ioctl+0x827 + kernel`devfs_ioctl+0xd1 + kernel`VOP_IOCTL_APV+0x2a + kernel`vn_ioctl+0xb6 + kernel`devfs_ioctl_f+0x1e + kernel`kern_ioctl+0x286 + kernel`sys_ioctl+0x12f + kernel`amd64_syscall+0x169 + kernel`0xffffffff81092b0b + 2 +.Ed +.Ss Example 7 : Summarizing vmem_alloc()'s by Arena Name and Size Distribution +.Bd -literal -offset 2n +# dtrace -q -n 'fbt::vmem_alloc:entry { @[args[0]->vm_name] = quantize(arg1); }' +^C + + kernel arena dom + value ------------- Distribution ------------- count + 2048 | 0 + 4096 |@@@@@@@@@@@@@@@@@@@@@@@@@@@ 4 + 8192 |@@@@@@@@@@@@@ 2 + 16384 | 0 +.Ed +.Ss Example 8 : Measuring Total Time Spent Executing a Function +This DTrace script measures the total time spent in +.Fn vm_page* +kernel functions. +The +.Fn quantize +aggregation organizes the measurements into power-of-two buckets, +providing a time distribution in nanoseconds for each function. +.Bd -literal -offset 2n +fbt::vm_page*:entry { + self->start = timestamp; +} + +fbt::vm_page*:return /self->start/ { + @[probefunc] = quantize(timestamp - self->start); + self->start = 0; +} +.Ed +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace_kinst 4 , +.Xr tracing 7 +.Rs +.%A Brendan Gregg +.%A Jim Mauro +.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD +.%I Prentice Hall +.%P pp. 898\(en903 +.%D 2011 +.%U https://www.brendangregg.com/dtracebook/ +.Re +.Rs +.%B The illumos Dynamic Tracing Guide +.%O Chapter fbt Provider +.%D 2008 +.%U https://illumos.org/books/dtrace/chp-fbt.html#chp-fbt +.Re +.Sh AUTHORS +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . +.Sh CAVEATS +.Ss Stability and Portability +.Nm fbt +probes are by definition tightly coupled to kernel code; if the code underlying +a script changes, the script may fail to run or may produce incorrect results. +Scripts written for one version of +.Fx +might not work on others, +and almost certainly will not work on other operating systems. +.Pp +Individual +.Nm fbt +probes often do not correspond nicely to logical system events. +For example, consider a DTrace script which prints the destination +address of every IP packet as the kernel hands them over +to the network card driver (NIC). +An +.Nm fbt Ns -based +implementation of such a script is a discouragingly difficult task: +it involves instrumenting at least four different functions in different parts +of the IPv4 and IPv6 code. +At the same time, with the +.Xr dtrace_ip 4 +provider the script is a simple one-liner: +.Dl dtrace -n 'ip:::send {printf("%s", args[2]->ip_daddr);}' +.Pp +Make sure to review available +.Xr dtrace 1 +providers first +before implementing a custom script with the +.Nm fbt +provider. +If none of the DTrace providers offer the desired probes, +consider adding new statically-defined tracing probes +.Pq Xr SDT 9 . +.Ss Frame Pointer +Inline functions are not instrumentable by +.Nm fbt +as they lack a frame pointer. +A developer might explicitly disable inlining by adding the +.Ql __noinline +attribute to a function definition, +but of course this requires a recompilation of the kernel. +Building the kernel with +.Fl fno-omit-frame-pointer +is another way of preserving frame pointers. +Note, that sometimes compilers will omit the frame pointer in leaf functions, +even when configured with +.Fl fno-omit-frame-pointer . +.Pp +Function returns via a tail call are also not instrumentable by +.Nm fbt . +As a result, +a function might have an entry probe +and a mix of instrumented and uninstrumentable returns. +.Pp +Use +.Xr dtrace_kinst 4 +to trace arbitrary instructions inside kernel functions +and work around some of the +limitations +of +.Nm fbt . +.Ss Tracing DTrace +The +.Nm fbt +provider cannot attach to functions inside DTrace provider kernel modules. diff --git a/share/man/man4/dtrace_kinst.4 b/share/man/man4/dtrace_kinst.4 index 9debbc1bd106..c2187689749b 100644 --- a/share/man/man4/dtrace_kinst.4 +++ b/share/man/man4/dtrace_kinst.4 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd February 27, 2023 +.Dd July 16, 2025 .Dt DTRACE_KINST 4 .Os .Sh NAME @@ -43,10 +43,13 @@ creates probes on-demand, meaning it searches for and parses the function's instructions each time .Xr dtrace 1 is run, and not at module load time. -This is in contrast to FBT's load-time parsing, since +This is in contrast to +.Xr dtrace_fbt 4 Ap s +load-time parsing, since .Nm kinst can potentially create thousands of probes for just a single function, instead -of up to two (entry and return) in the case of FBT. +of up to two (entry and return) in the case of +.Xr dtrace_fbt 4 . A result of this is that .Cm dtrace -l -P kinst will not match any probes. @@ -79,7 +82,8 @@ Trace all instructions in # dtrace -n 'kinst::amd64_syscall:' .Ed .Sh SEE ALSO -.Xr dtrace 1 +.Xr dtrace 1 , +.Xr dtrace_fbt 4 .Sh HISTORY The .Nm kinst diff --git a/share/man/man4/dtrace_profile.4 b/share/man/man4/dtrace_profile.4 new file mode 100644 index 000000000000..07f86663d60a --- /dev/null +++ b/share/man/man4/dtrace_profile.4 @@ -0,0 +1,129 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd July 14, 2025 +.Dt DTRACE_PROFILE 4 +.Os +.Sh NAME +.Nm dtrace_profile +.Nd a DTrace provider for firing probes at a given time interval +.Sh SYNOPSIS +.Nm profile Ns Cm :::profile- Ns Ar rate Ns Op Ar unit +.Nm profile Ns Cm :::tick- Ns Ar rate Ns Op Ar unit +.Sh DESCRIPTION +The +.Nm profile +provider implements three special probes related to the life cycle of the +DTrace program itself. +.Ss Probes +The +.Nm profile Ns Cm :::profile +probes fire on all CPUs and are suitable for measuring the whole system +periodically. +.Pp +The +.Nm profile Ns Cm :::tick +probes fire on a single CPU, potentially a different one every time. +They are useful, e.g., for printing partial results periodically. +.Ss Rate and Time Units +The +.Nm profile +provider probes will fire at the specified +.Ar rate . +.Pp +The default unit is +.Cm hz . +The +.Nm profile +provider supports the following time units: +.Bl -column -offset indent "ns, nsec" "Definition" +.It Sy Time Unit Ta Sy Definition +.It Cm ns , nsec Ta nanoseconds +.It Cm us , usec Ta microseconds +.It Cm ms , msec Ta milliseconds +.It Cm s , sec Ta seconds +.It Cm m , min Ta minutes +.It Cm h , hour Ta hours +.It Cm d , day Ta days +.It Cm hz Ta Hertz (frequency per second) +.El +.Ss Probe Arguments +The arguments of the +.Nm profile +provider probes +are: +.Bl -tag -width arg0 +.It Va arg0 +The PC (program counter) in the kernel when the probe triggered, +or 0 if the process was not in the kernel at that time. +.It Va arg1 +The PC in the user process when the probe triggered, +or 0 if the process was in the kernel when the probe triggered. +.El +.Pp +Use arguments +.Va arg0 +and +.Va arg1 +to tell if the +.Nm profile +provider probe fired in the kernel or in the userspace context. +.Sh IMPLEMENTATION NOTES +The +.Xr sysctl 8 +variable +.Va kern.dtrace.profile.aframes +controls the number of skipped artificial frames for +the +.Nm profile +provider. +.Sh EXAMPLES +.Ss Example 1 : Profiling On-CPU Kernel Stack Traces +The following DTrace one-liner uses the +.Nm profile +provider to collect stack traces over 60 seconds. +.\" XXX: Keep on one line for easier copy-pasting. +.Bd -literal -offset indent +dtrace -x stackframes=100 -n 'profile-197 /arg0/ {@[stack()] = count();} tick-60s {exit(0);} +.Ed +.Pp +The system is profiled at the 197 Hz to avoid sampling in lockstep +with other periodic activities. +This unnatural frequency minimizes the chance of overlapping with other events. +.Pp +Option +.Fl x Cm stackframes=100 +increases the maximum number of kernel stack frames to unwind during +.Fn stack . +.Pp +Checking if +.Ar arg0 +is not zero makes sure that profiling happens +when the program is in the kernel context. +.Pp +Refer to +.Lk https://www.brendangregg.com/flamegraphs.html +to learn about generating flame graphs from the obtained stack traces. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr tracing 7 +.Rs +.%B The illumos Dynamic Tracing Guide +.%O Chapter profile Provider +.%D 2008 +.%U https://www.illumos.org/books/dtrace/chp-profile.html +.Re +.Rs +.%A Brendan Gregg +.%A Jim Mauro +.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD +.%I Prentice Hall +.%P pp. 24\(en25 +.%D 2011 +.%U https://www.brendangregg.com/dtracebook/ +.Re +.Sh AUTHORS +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/share/man/man4/gif.4 b/share/man/man4/gif.4 index 959510451011..ad33d5d21e81 100644 --- a/share/man/man4/gif.4 +++ b/share/man/man4/gif.4 @@ -1,6 +1,7 @@ .\" $KAME: gif.4,v 1.28 2001/05/18 13:15:56 itojun Exp $ .\" .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. +.\" Copyright (C) 2024 Hiroki Sato <hrs@FreeBSD.org> .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -27,7 +28,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd October 21, 2018 +.Dd July 14, 2025 .Dt GIF 4 .Os .Sh NAME @@ -67,8 +68,8 @@ variable in .Pp To use .Nm , -the administrator needs to configure the protocol and addresses used for the outer -header. +the administrator needs to configure the protocol and addresses used for +the outer header. This can be done by using .Xr ifconfig 8 .Cm tunnel , @@ -79,8 +80,7 @@ The administrator also needs to configure the protocol and addresses for the inner header, with .Xr ifconfig 8 . Note that IPv6 link-local addresses -(those that start with -.Li fe80:: ) +.Pq those that start with Li fe80\&:\&: will be automatically configured whenever possible. You may need to remove IPv6 link-local addresses manually using .Xr ifconfig 8 , @@ -89,12 +89,139 @@ if you want to disable the use of IPv6 as the inner header Finally, you must modify the routing table to route the packets through the .Nm interface. +.Ss MTU Configuration and Path MTU Discovery +The +.Nm +interface uses the fixed length, +.Li 1280 , +to determine whether the outgoing IPv6 packets are split. +This means the MTU value configured on the interface will be ignored +when the outer protocol is IPv6. +When the +.Dv NOCLAMP +interface flag is set, +.Nm +uses the same configured value as IPv4 communications. +This behavior prevents potential issues when the path MTU is +smaller than the interface MTU. +This section describes the reason why the default behavior is different. +The +.Dv NOCLAMP +interface flag can be set using the following command: +.Pp +.Dl ifconfig Ar gif0 Cm noclamp +.Pp +and clear the flag using the following: +.Pp +.Dl ifconfig Ar gif0 Cm -noclamp +.Pp +where +.Ar gif0 +is the actual interface name. +.Pp +A tunnel interface always has an implicit smaller MTU for the inner protocol +than the outer protocol because of the additional header. +Note that the interface MTU on a +.Nm +interface, +the default value is +.Li 1280 , +is used as MTU for the outer protocol. +This means that the MTU for the inner protocol varies depending on the +outer protocol header length. +If an outgoing packet bigger than the inner protocol MTU arrives at a +.Nm +interface for encapsulation, +it will be split into fragments. +Specifically, +if IPv4 is used as the outer protocol, +the inner is 20 octets smaller than the interface MTU. +In the case of the default interface MTU, +.Li 1280 , +inner packets bigger than +.Li 1260 +will be fragmented. +In the case of IPv6, +the inner is 40 octets smaller than the outer. +.Pp +This fragmentation is not harmful though it can degrade the +performance. +Note that while an increased MTU on +.Nm +interface helps to mitigate this reduced performance issue, +it can also cause packet losses on the intermediate narrowest path +between the two communication endpoints in IPv6. +IPv6 allows fragmentation only on the sender, +not on the routers in the communication path. +A big outgoing packet will be dropped on a router with a smaller MTU. .Pp +In normal IPv6 communication, +an ICMPv6 Packet Too Big error will be sent back to the sender, +who can adjust the packet length and re-send it. +This process is performed in the upper protocols than L3, +such as TCP, +and makes the packet length shorter so that packets go through +the path without fragmentation. +This behavior is known as path MTU discovery. +.Pp +When using a +.Nm +interface, +the Packet Too Big message is generated for the outer protocol. +Since the +.Nm +interface does not translate this error to the inner protocol, +the inner protocol sees it just as a packet loss with no useful +information to adjust the length of the next packets. +In this situation, +path MTU discovery does not work, +and communications of the inner protocol +become stalled. +.Pp +In order to avoid this, +a +.Nm +interface silently splits a packet of over 1240 octets into fragments to make +the outer protocol packets equal or shorter than 1280 octets, +even when the interface MTU is configured as larger than 1280. +Note that this occurs only when the outer protocol is IPv6. +.Li 1280 +is the smallest MTU in IPv6 and guarantees no packet loss occurs +on intermediate routers. +.Pp +As mentioned earlier, +the performance is sub-optimal if the actual path MTU is larger than +.Li 1280 . +A typical confusing scenario is as follows. The .Nm -device can be configured to be ECN friendly. -This can be configured by -.Dv IFF_LINK1 . +interface can have Ethernet, +whose MTU is usually 1500, +as the inner protocol. +It is called an EtherIP tunnel, +and can be configured by adding the +.Nm +interface as a member of +.Xr if_bridge 4 +interface. +The +.Xr if_bridge 4 +interface forcibly changes the MTU of the +.Nm +interface with those for the other member interfaces, +which are likely 1500. +In this case, +a situation in which the MTU of the +.Nm +interface is 1500 but fragmentation in 1280 octets always occurs. +.Pp +The default behavior is most conservative to prevent confusing packet loss. +Depending on the network configuration, +enabling the +.Dv NOCLAMP +interface flag might be helpful for better performance. +It is crucial to ensure that the path MTU is equal to or larger than +the interface MTU when enabling this flag. .Ss ECN friendly behavior The .Nm @@ -169,6 +296,7 @@ variable to the desired level of nesting. .Sh SEE ALSO .Xr gre 4 , +.Xr if_bridge 4 , .Xr inet 4 , .Xr inet6 4 , .Xr ifconfig 8 @@ -199,7 +327,8 @@ There are many tunnelling protocol specifications, all defined differently from each other. The .Nm -device may not interoperate with peers which are based on different specifications, +device may not interoperate with peers which are based on different +specifications, and are picky about outer header fields. For example, you cannot usually use .Nm @@ -219,11 +348,14 @@ to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4. .Pp The .Nm -device does not translate ICMP messages for the outer header into the inner header. +device does not translate ICMP messages for the outer header into the inner +header. .Pp In the past, .Nm had a multi-destination behavior, configurable via -.Dv IFF_LINK0 +.Dv NOCLAMP flag. The behavior is obsolete and is no longer supported. +This flag is now used to determine whether performing fragmentation when +the outer protocol is IPv6. diff --git a/share/man/man4/hwt.4 b/share/man/man4/hwt.4 index df02a4672f36..299332c72542 100644 --- a/share/man/man4/hwt.4 +++ b/share/man/man4/hwt.4 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.Dd July 7, 2025 +.Dd July 12, 2025 .Dt HWT 4 .Os .Sh NAME @@ -131,6 +131,7 @@ For SPE-only, the kernel is waiting for userspace to notify that it has copied out a buffer to avoid data loss/overwriting buffers. .El .Sh SEE ALSO +.Xr tracing 7 , .Xr hwt 8 .Sh HISTORY The diff --git a/share/man/man4/md.4 b/share/man/man4/md.4 index 0c99d61f8392..1da26ddda037 100644 --- a/share/man/man4/md.4 +++ b/share/man/man4/md.4 @@ -5,7 +5,7 @@ .\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp .\" ---------------------------------------------------------------------------- .\" -.Dd January 8, 2020 +.Dd July 16, 2025 .Dt MD 4 .Os .Sh NAME @@ -158,7 +158,7 @@ installation process. The .Nm driver did a hostile takeover of the -.Xr vn 4 +.Sy vn driver in .Fx 5.0 . .Sh AUTHORS diff --git a/share/man/man4/mtw.4 b/share/man/man4/mtw.4 index 17722be73203..6aa59d848d36 100644 --- a/share/man/man4/mtw.4 +++ b/share/man/man4/mtw.4 @@ -24,23 +24,41 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd Feb 03, 2025 +.Dd May 3, 2025 .Dt MTW 4 .Os .Sh NAME -.Nm if_mtw -.Nd "Mediatek MT7601U" -.Ed +.Nm mtw +.Nd MediaTek MT7601U USB IEEE 802.11n wireless network driver +.Sh SYNOPSIS +.Cd device usb +.Cd device mtw +.Cd device wlan +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="if_mtw" .Sh DESCRIPTION -This module provides support for Mediatek MT7601U with the firmware from net/wifi-firmware-mtw-kmod - +This module provides support for +MediaTek MT7601U USB wireless network adapters. +If the appropriate hardware is detected, +the driver will be automatically loaded with +.Xr devmatch 8 . +If driver autoloading is explicitly disabled, enable the module in +.Xr rc.conf 5 . +The +.Nm +driver can be configured at runtime with +.Xr ifconfig 8 +or at boot with +.Xr rc.conf 5 . .Sh HARDWARE The .Nm -driver supports Mediatek MT7601U -based USB wireless network adapters including (but not all of them tested): +driver supports MediaTek MT7601U based USB wireless network adapters +including (but not all of them tested): .Pp -.Bl -column -compact +.Bl -bullet -compact .It ASUS USB-N10 v2 .It @@ -58,17 +76,43 @@ TP-LINK TL-WN727N v4 (tested working) .It Yealink WF40 .El +.Sh FILES +The +.Nm +driver requires firmware from +.Pa ports/net/wifi-firmware-mt7601u-kmod . +This firmware package will be installed automatically with +.Xr fwget 8 +if the appropriate hardware is detected at installation or runtime. .Sh SEE ALSO -.Xr usb 4 -.Sh BUGS +.Xr usb 4 , +.Xr wlan 4 , +.Xr networking 7 , +.Xr fwget 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY The .Nm -only works in station mode and monitor mode. The firmware does not always reinitialize when reloading the module, or when rebooting, without first unplugging the device. -.Sh History -The mtw driver first appeared in OpenBSD 7.1. The mtw driver was ported to FreeBSD in FreeBSD 15.0. +driver first appeared in +.Ox 7.1 +and +.Fx 15.0 . .Sh AUTHORS .An -nosplit -The mtw driver was written by +The +.Nm +driver was written by .An James Hastings Aq Mt hastings@openbsd.org -ported to FreeBSD by -.An Jesper Schmitz Mouridsen Aq Mt jsm@FreeBSD.org +and ported to +.Fx +by +.An Jesper Schmitz Mouridsen Aq Mt jsm@FreeBSD.org . +.Sh BUGS +.Nm +only works in +.Cm station +mode and +.Cm monitor +mode. +The firmware does not always reinitialize when reloading the module, +or when rebooting, without first unplugging the device. diff --git a/share/man/man4/sa.4 b/share/man/man4/sa.4 index 96b11ebe5360..699a940a34d1 100644 --- a/share/man/man4/sa.4 +++ b/share/man/man4/sa.4 @@ -457,7 +457,8 @@ One EOM notification will be sent, BPEW status will be set for one position query, and then the driver state will be reset to normal. .Sh SEE ALSO .Xr mt 1 , -.Xr cam 4 +.Xr cam 4 , +.Xr mtio 4 .Sh AUTHORS .An -nosplit The diff --git a/share/man/man4/snd_uaudio.4 b/share/man/man4/snd_uaudio.4 index 00329a6d8e40..7193c85fa4f0 100644 --- a/share/man/man4/snd_uaudio.4 +++ b/share/man/man4/snd_uaudio.4 @@ -1,3 +1,6 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" .\" $NetBSD: uaudio.4,v 1.15 2002/02/12 19:53:57 jdolecek Exp $ .\" .\" Copyright (c) 1999 The NetBSD Foundation, Inc. @@ -27,32 +30,30 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd February 15, 2025 +.Dd July 17, 2025 .Dt SND_UAUDIO 4 .Os .Sh NAME .Nm snd_uaudio .Nd USB audio and MIDI device driver .Sh SYNOPSIS -To compile this driver into the kernel, place the following lines in your -kernel configuration file: -.Bd -ragged -offset indent .Cd "device sound" .Cd "device usb" .Cd "device snd_uaudio" -.Ed .Pp -Alternatively, to load the driver as a module at boot time, place the -following line in -.Xr loader.conf 5 : -.Bd -literal -offset indent -snd_uaudio_load="YES" -.Ed -.Sh DESCRIPTION -The -.Nm -driver provides support for USB audio class devices and USB MIDI class devices. +In +.Xr rc.conf 5 : +.Cd kld_list="snd_uaudio" .Pp +In +.Xr sysctl.conf 5 : +.Cd hw.usb.uaudio.buffer_ms +.Cd hw.usb.uaudio.default_bits +.Cd hw.usb.uaudio.default_channels +.Cd hw.usb.uaudio.default_rate +.Cd hw.usb.uaudio.handle_hid +.Cd hw.usb.uaudio.debug +.Sh DESCRIPTION A USB audio device consists of a number of components: input terminals (e.g.\& USB digital input), output terminals (e.g.\& speakers), and a number of units in between (e.g.\& volume control). @@ -68,6 +69,11 @@ sample rate and sample size. Refer to the .Ql USB Audio Class Specification for more information. +.Sh HARDWARE +The +.Nm +driver provides support for USB audio class devices and +USB MIDI class devices. .Sh SYSCTL VARIABLES The following settings can be entered at the .Xr loader 8 diff --git a/share/man/man4/ufshci.4 b/share/man/man4/ufshci.4 new file mode 100644 index 000000000000..d722c9902b98 --- /dev/null +++ b/share/man/man4/ufshci.4 @@ -0,0 +1,181 @@ +.\" +.\" Copyright (c) 2025, Samsung Electronics Co., Ltd. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" ufshci driver man page. +.\" +.\" Author: Jaeyoon Choi <j_yoon.choi@samsung.com> +.\" +.Dd July 17, 2025 +.Dt UFSHCI 4 +.Os +.Sh NAME +.Nm ufshci +.Nd Universal Flash Storage Host Controller Interface driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in the kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ufshci" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ufshci_load="YES" +.Ed +.Sh DESCRIPTION +Universal Flash Storage (UFS) is a low-power, high-performance storage +standard composed of a host controller and a single target device. +.Pp +The driver currently provides: +.Bl -bullet +.It +Initialization of the host controller and the target device +.It +Handling of UFS Interconnect (UIC) commands +.It +Support for UTP Transfer Requests (UTR) and UTP Task Management Requests (UTMR) +.It +Support for the SCSI command set +.It +Operation in the legacy single-doorbell queue mode +.It +Support for the PCI Express bus +.El +.Pp +After initialization, the controller is registered with the +.Xr cam 4 +subsystem and its logical unit appears as the device node +.Pa /dev/daX . +.Pp +The driver is under active development; upcoming work includes full +UFS 4.1 feature coverage, additional power-management modes, and +ACPI/FDT-based attach support. +.Sh HARDWARE +The +.Nm +driver supports both host controllers and devices implementing the +Universal Flash Storage Host Controller Interface 4.1 and earlier. +.Sh CONFIGURATION +The +.Nm +driver currently operates with a single doorbell (one I/O-queue), so any +tunables that change the queue count are ignored. +When Multi-Circular Queue (MCQ) support is added and multiple queues +become available, the following queue count tunable values will take effect: +.Pp +To force a single I/O queue pair shared by all CPUs, set the following +tunable value in loader.conf(5): +.Bd -literal -offset indent +hw.ufshci.per_cpu_io_queues=0 +.Ed +.Pp +To assign more than one CPU per I/O queue pair, thereby reducing the +number of MSI-X vectors consumed by the device, set the following tunable +value in loader.conf(5): +.Bd -literal -offset indent +hw.ufshci.min_cpus_per_ioq=X +.Ed +.Pp +To change the I/O command timeout value (in seconds), set the following tunable +value in loader.conf(5): +.Bd -literal -offset indent +hw.ufshci.timeout_period=X +.Ed +.Pp +To change the I/O command retry count, set the following tunable value in +loader.conf(5): +.Bd -literal -offset indent +hw.ufshci.retry_count=X +.Ed +.Pp +To force the driver to use legacy INTx interrupts, set the following tunable +value in loader.conf(5): +.br +(Note: until MCQ support is available the driver always uses legacy INTx, so +this value effectively remains 1) +.Bd -literal -offset indent +hw.ufshci.force_intx=1 +.Ed +.Sh SYSCTL VARIABLES +The following controller-level +.Xr sysctl 8 +nodes are currently implemented: +.Bl -tag -width indent +.It Va dev.ufshci.0.num_failures +(R) Number of command failures for the entire controller. +.It Va dev.ufshci.0.num_retries +(R) Number of command retries for the entire controller. +.It Va dev.ufshci.0.num_intr_handler_calls +(R) Number of times the interrupt handler has been called. +.It Va dev.ufshci.0.num_cmds +(R) Total number of commands issued by the controller. +.It Va dev.ufshci.0.timeout_period +(RW) Configured timeout period (in seconds). +.It Va dev.ufshci.0.cap +(R) Host controller capabilities register value. +.It Va dev.ufshci.0.num_io_queues +(R) Number of I/O-queue pairs. +.It Va dev.ufshci.0.io_queue_mode +(R) Indicates single doorbell mode or multi circular queue mode. +.It Va dev.ufshci.0.minor_version +(R) Host controller minor version. +.It Va dev.ufshci.0.major_version +(R) Host controller major version. +.It Va dev.ufshci.0.utmrq.num_failures +(R) Number of failed UTP task-management requests. +.It Va dev.ufshci.0.utmrq.ioq.num_retries +(R) Number of retried UTP task-management requests. +.It Va dev.ufshci.0.utmrq.num_intr_handler_calls +(R) Number of interrupt handler calls caused by UTP task-management requests. +.It Va dev.ufshci.0.utmrq.num_cmds +(R) Number of UTP task-management requests issued. +.It Va dev.ufshci.0.utmrq.cq_head +(R) Current location of the UTP task-management completion queue head. +.It Va dev.ufshci.0.utmrq.sq_tail +(R) Current location of the UTP task-management submission queue tail. +.It Va dev.ufshci.0.utmrq.sq_head +(R) Current location of the UTP task-management submission queue head. +.It Va dev.ufshci.0.utmrq.num_trackers +(R) Number of trackers in the UTP task-management queue. +.It Va dev.ufshci.0.utmrq.num_entries +(R) Number of entries in the UTP task-management queue. +.It Va dev.ufshci.0.ioq.0.num_failures +(R) Number of failed UTP transfer requests. +.It Va dev.ufshci.0.ioq.0.num_retries +(R) Number of retried UTP transfer requests. +.It Va dev.ufshci.0.ioq.0.num_intr_handler_calls +(R) Number of interrupt-handler calls caused by UTP transfer requests. +.It Va dev.ufshci.0.ioq.0.num_cmds +(R) Number of UTP transfer requests issued. +.It Va dev.ufshci.0.ioq.0.cq_head +(R) Current location of the UTP transfer completion queue head. +.It Va dev.ufshci.0.ioq.0.sq_tail +(R) Current location of the UTP transfer submission queue tail. +.It Va dev.ufshci.0.ioq.0.sq_head +(R) Current location of the UTP transfer submission queue head. +.It Va dev.ufshci.0.ioq.0.num_trackers +(R) Number of trackers in the UTP transfer queue. +.It Va dev.ufshci.0.ioq.0.num_entries +(R) Number of entries in the UTP transfer queue. +.El +.Sh SEE ALSO +.Xr cam 4 , +.Xr pci 4 , +.Xr disk 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 15.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Samsung Electronics and originally written by +.An Jaeyoon Choi Aq Mt j_yoon.choi@samsung.com . +.Pp +This manual page was written by +.An Jaeyoon Choi Aq Mt j_yoon.choi@samsung.com . diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5 index b5843d67e106..8954e872c231 100644 --- a/share/man/man5/pf.conf.5 +++ b/share/man/man5/pf.conf.5 @@ -27,7 +27,7 @@ .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd July 7, 2025 +.Dd July 9, 2025 .Dt PF.CONF 5 .Os .Sh NAME @@ -365,7 +365,7 @@ set timeout { adaptive.start 60000, adaptive.end 120000 } set limit states 100000 .Ed .Pp -With 9000 state table entries, the timeout values are scaled to 50% +With 90000 state table entries, the timeout values are scaled to 50% (tcp.first 60, tcp.established 43200). .It Ar set loginterface Enable collection of packet and byte count statistics for the given @@ -1387,7 +1387,7 @@ part of the new destination address according to the specified subnet. It is possible to embed a complete IPv4 address into an IPv6 address using a network prefix of /96 or smaller. .Pp -When a destination address is not specified it is assumed that the host +When a destination address is not specified, it is assumed that the host part is 32-bit long. For IPv6 to IPv4 translation this would mean using only the lower 32 bits of the original IPv6 destination address. @@ -2122,10 +2122,10 @@ options, or scrubbed with will also not be recoverable from intermediate packets. Such connections will stall and time out. .It Xo Ar icmp-type Aq Ar type -.Ar code Aq Ar code +.Ar Op code Aq Ar code .Xc .It Xo Ar icmp6-type Aq Ar type -.Ar code Aq Ar code +.Ar Op code Aq Ar code .Xc This rule only applies to ICMP or ICMPv6 packets with the specified type and code. @@ -2574,6 +2574,7 @@ will not work if .Xr pf 4 operates on a .Xr bridge 4 . +Also they act on incoming SYN packets only. .Pp Example: .Bd -literal -offset indent @@ -2783,8 +2784,8 @@ This means that it will not work on other protocols and will not match a currently established connection. .Pp Caveat: operating system fingerprints are occasionally wrong. -There are three problems: an attacker can trivially craft his packets to -appear as any operating system he chooses; +There are three problems: an attacker can trivially craft packets to +appear as any operating system; an operating system patch could change the stack behavior and no fingerprints will match it until the database is updated; and multiple operating systems may have the same fingerprint. @@ -3111,7 +3112,7 @@ rule can also contain a filter ruleset in a brace-delimited block. In that case, no separate loading of rules into the anchor is required. Brace delimited blocks may contain rules or other brace-delimited blocks. -When an anchor is populated this way the anchor name becomes optional. +When an anchor is populated this way, the anchor name becomes optional. .Bd -literal -offset indent anchor "external" on $ext_if { block diff --git a/share/man/man5/rc.conf.5 b/share/man/man5/rc.conf.5 index 2fd63e4f743d..de2181d638d1 100644 --- a/share/man/man5/rc.conf.5 +++ b/share/man/man5/rc.conf.5 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd May 21, 2025 +.Dd July 15, 2025 .Dt RC.CONF 5 .Os .Sh NAME @@ -1164,8 +1164,8 @@ and is not found. Multiple rules can be set as follows: .Bd -literal -pf_fallback_rules="\\ - block drop log all\\ +pf_fallback_rules=" + block drop log all pass in quick on em0" .Pp .Ed diff --git a/share/man/man5/src.conf.5 b/share/man/man5/src.conf.5 index 63e9f471f1f1..a3db00aed42f 100644 --- a/share/man/man5/src.conf.5 +++ b/share/man/man5/src.conf.5 @@ -1,5 +1,5 @@ .\" DO NOT EDIT-- this file is @generated by tools/build/options/makeman. -.Dd July 5, 2025 +.Dd July 14, 2025 .Dt SRC.CONF 5 .Os .Sh NAME @@ -493,7 +493,7 @@ Do not build .Xr cxgbetool 8 .Pp This is a default setting on -arm/armv7, powerpc/powerpc and riscv/riscv64. +arm/armv7 and riscv/riscv64. .It Va WITH_CXGBETOOL Build .Xr cxgbetool 8 @@ -655,7 +655,7 @@ and .Xr efivar 8 . .Pp This is a default setting on -i386/i386, powerpc/powerpc, powerpc/powerpc64 and powerpc/powerpc64le. +i386/i386, powerpc/powerpc64 and powerpc/powerpc64le. .It Va WITH_EFI Build .Xr efivar 3 @@ -687,7 +687,7 @@ Build Flattened Device Tree support as part of the base system. This includes the device tree compiler (dtc) and libfdt support library. .Pp This is a default setting on -arm/armv7, arm64/aarch64, powerpc/powerpc, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. +arm/armv7, arm64/aarch64, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. .It Va WITHOUT_FILE Do not build .Xr file 1 @@ -750,7 +750,7 @@ Do not build HTML docs. Do not build or install HyperV utilities. .Pp This is a default setting on -arm/armv7, powerpc/powerpc, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. +arm/armv7, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. .It Va WITH_HYPERV Build or install HyperV utilities. .Pp @@ -916,7 +916,7 @@ On 64-bit platforms, do not build 32-bit library set and a runtime linker. .Pp This is a default setting on -arm/armv7, i386/i386, powerpc/powerpc, powerpc/powerpc64le and riscv/riscv64. +arm/armv7, i386/i386, powerpc/powerpc64le and riscv/riscv64. .It Va WITH_LIB32 On 64-bit platforms, build the 32-bit library set and a .Nm ld-elf32.so.1 @@ -935,7 +935,7 @@ arm/armv7 and riscv/riscv64. Build the LLDB debugger. .Pp This is a default setting on -amd64/amd64, arm64/aarch64, i386/i386, powerpc/powerpc, powerpc/powerpc64 and powerpc/powerpc64le. +amd64/amd64, arm64/aarch64, i386/i386, powerpc/powerpc64 and powerpc/powerpc64le. .It Va WITHOUT_LLD_BOOTSTRAP Do not build the LLD linker during the bootstrap phase of the build. @@ -1038,7 +1038,7 @@ with support for verification based on certificates obtained from UEFI. Disable inclusion of GELI crypto support in the boot chain binaries. .Pp This is a default setting on -powerpc/powerpc, powerpc/powerpc64 and powerpc/powerpc64le. +powerpc/powerpc64 and powerpc/powerpc64le. .It Va WITH_LOADER_GELI Build GELI bootloader support. .Pp @@ -1048,7 +1048,7 @@ amd64/amd64, arm/armv7, arm64/aarch64, i386/i386 and riscv/riscv64. Do not build the 32-bit UEFI loader. .Pp This is a default setting on -arm/armv7, arm64/aarch64, i386/i386, powerpc/powerpc, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. +arm/armv7, arm64/aarch64, i386/i386, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. .It Va WITH_LOADER_IA32 Build the 32-bit UEFI loader. .Pp @@ -1058,7 +1058,7 @@ amd64/amd64. Do not build kboot, a linuxboot environment loader .Pp This is a default setting on -arm/armv7, i386/i386, powerpc/powerpc, powerpc/powerpc64le and riscv/riscv64. +arm/armv7, i386/i386, powerpc/powerpc64le and riscv/riscv64. .It Va WITH_LOADER_KBOOT Build kboot, a linuxboot environment loader .Pp @@ -1068,7 +1068,7 @@ amd64/amd64, arm64/aarch64 and powerpc/powerpc64. Do not build LUA bindings for the boot loader. .Pp This is a default setting on -powerpc/powerpc, powerpc/powerpc64 and powerpc/powerpc64le. +powerpc/powerpc64 and powerpc/powerpc64le. .It Va WITH_LOADER_LUA Build LUA bindings for the boot loader. .Pp @@ -1083,7 +1083,7 @@ amd64/amd64, arm/armv7, arm64/aarch64, i386/i386 and riscv/riscv64. Build openfirmware bootloader components. .Pp This is a default setting on -powerpc/powerpc, powerpc/powerpc64 and powerpc/powerpc64le. +powerpc/powerpc64 and powerpc/powerpc64le. .It Va WITHOUT_LOADER_PXEBOOT Do not build pxeboot on i386/amd64. When the pxeboot is too large, or unneeded, it may be disabled with this option. @@ -1104,7 +1104,7 @@ amd64/amd64, arm64/aarch64, i386/i386, powerpc/powerpc64le and riscv/riscv64. Build ubldr. .Pp This is a default setting on -arm/armv7, powerpc/powerpc and powerpc/powerpc64. +arm/armv7 and powerpc/powerpc64. .It Va WITH_LOADER_VERBOSE Build with extra verbose debugging in the loader. May explode already nearly too large loader over the limit. @@ -1309,7 +1309,7 @@ Do not build .Xr mlx5tool 8 .Pp This is a default setting on -arm/armv7, powerpc/powerpc and riscv/riscv64. +arm/armv7 and riscv/riscv64. .It Va WITH_MLX5TOOL Build .Xr mlx5tool 8 @@ -1401,7 +1401,7 @@ Build the InfiniBand software stack, including kernel modules and userspace libraries. .Pp This is a default setting on -amd64/amd64, arm64/aarch64, i386/i386, powerpc/powerpc, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. +amd64/amd64, arm64/aarch64, i386/i386, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. .It Va WITH_OFED_EXTRA Build the non-essential components of the .Dq "OpenFabrics Enterprise Distribution" @@ -1412,7 +1412,7 @@ Enable building LDAP support for kerberos using an openldap client from ports. Do not build LLVM's OpenMP runtime. .Pp This is a default setting on -arm/armv7 and powerpc/powerpc. +arm/armv7. .It Va WITH_OPENMP Build LLVM's OpenMP runtime. .Pp @@ -1465,7 +1465,7 @@ is set explicitly) Do not include kernel TLS support in OpenSSL. .Pp This is a default setting on -arm/armv7, i386/i386, powerpc/powerpc and riscv/riscv64. +arm/armv7, i386/i386 and riscv/riscv64. .It Va WITH_OPENSSL_KTLS Include kernel TLS support in OpenSSL. .Pp @@ -1502,7 +1502,7 @@ Do not build dynamically linked binaries as Position-Independent Executable (PIE). .Pp This is a default setting on -arm/armv7, i386/i386 and powerpc/powerpc. +arm/armv7 and i386/i386. .It Va WITH_PIE Build dynamically linked binaries as Position-Independent Executable (PIE). diff --git a/share/man/man5/style.Makefile.5 b/share/man/man5/style.Makefile.5 index cc5d2f6bb28a..fe8754924575 100644 --- a/share/man/man5/style.Makefile.5 +++ b/share/man/man5/style.Makefile.5 @@ -1,3 +1,6 @@ +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" .\" Copyright (c) 2002-2003, 2023 David O'Brien <obrien@FreeBSD.org> .\" All rights reserved. .\" @@ -30,10 +33,7 @@ .Os .Sh NAME .Nm style.Makefile -.Nd -.Fx -.Pa Makefile -file style guide +.Nd FreeBSD Makefile style guide .Sh DESCRIPTION This file specifies the preferred style for makefiles in the .Fx 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 4c9aee8ce913..7085bac78385 100644 --- a/share/man/man7/tracing.7 +++ b/share/man/man7/tracing.7 @@ -8,7 +8,7 @@ .Os .Sh NAME .Nm tracing -.Nd introduction to tracing and performance monitoring facilities on FreeBSD +.Nd introduction to FreeBSD tracing and performance monitoring .Sh DESCRIPTION .Fx features a large variety of tracing and performance monitoring facilities. @@ -73,6 +73,10 @@ 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 .Xr pmcstat 8 , and its kernel counterpart, diff --git a/share/man/man8/nanobsd.8 b/share/man/man8/nanobsd.8 index 2ba072541ada..838f9ddc9afa 100644 --- a/share/man/man8/nanobsd.8 +++ b/share/man/man8/nanobsd.8 @@ -1,3 +1,6 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" .\" Copyright (c) 2006 Daniel Gerzo <danger@FreeBSD.org> .\" All rights reserved. .\" @@ -22,13 +25,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd November 10, 2024 +.Dd July 14, 2025 .Dt NANOBSD 8 .Os .Sh NAME .Nm nanobsd.sh -.Nd utility used to create a FreeBSD system image suitable for embedded -applications +.Nd create an embedded FreeBSD system image .Sh SYNOPSIS .Nm .Op Fl BbfhIiKknqvWwX diff --git a/share/man/man9/vnode.9 b/share/man/man9/vnode.9 index 5dd087725e92..d17492668298 100644 --- a/share/man/man9/vnode.9 +++ b/share/man/man9/vnode.9 @@ -24,7 +24,7 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd October 9, 2024 +.Dd July 15, 2025 .Dt VNODE 9 .Os .Sh NAME @@ -113,7 +113,7 @@ The function declarations and definitions are generated from .Pa sys/kern/vnode_if.src by the -.Pa sys/tools/vndoe_if.awk +.Pa sys/tools/vnode_if.awk script. The interfaces are documented in their respective manual pages like .Xr VOP_READ 9 |