diff --git a/share/man/man4/dtrace_kinst.4 b/share/man/man4/dtrace_kinst.4 --- a/share/man/man4/dtrace_kinst.4 +++ b/share/man/man4/dtrace_kinst.4 @@ -1,6 +1,10 @@ .\" Copyright (c) 2022 Christos Margiolis +.\" Copyright (c) 2023 The FreeBSD Foundation .\" All rights reserved. .\" +.\" Portions of this documentation were written by Christos Margiolis +.\" under sponsorship from the FreeBSD Foundation. +.\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: @@ -24,21 +28,34 @@ .\" .\" $FreeBSD$ .\" -.Dd February 27, 2023 +.Dd July 4, 2023 .Dt DTRACE_KINST 4 .Os .Sh NAME .Nm dtrace_kinst -.Nd a DTrace provider for tracing arbitrary instructions in a given kernel function +.Nd a DTrace provider for tracing arbitrary instructions in the kernel .Sh SYNOPSIS kinst::: .Sh DESCRIPTION -The DTrace +The .Nm kinst -provider allows the user to trace any instruction in a given kernel function. - corresponds to the function to be traced, and is the -offset to the specific instruction, and can be obtained from the function's -disassembly using kgdb from the gdb package. +DTrace provider allows the user to trace any instruction in a kernel function. +.Cm +corresponds to the function to be traced, and +.Cm +is the offset to the specific instruction, and can be obtained from the +function's disassembly using gdb. +.Pp +.Nm kinst +can also trace inline functions by requesting a probe of the form +.Cm kinst::: . +If the probe is +.Cm entry +or +.Cm return +but the function is not an inline one, the probe will be delegated to FBT, +otherwise DTrace will find all call sites of the inline function and create new +probes for each one of them. .Pp .Nm kinst creates probes on-demand, meaning it searches for and parses the function's @@ -53,7 +70,8 @@ .Cm dtrace -l -P kinst will not match any probes. .Sh IMPLEMENTATION NOTES -The provider is currently implemented only for amd64. +.Nm kinst +is supported by AMD64, ARM64 and RISC-V. .Sh EXAMPLES Find the offset corresponding to the third instruction in .Fn vm_fault @@ -72,13 +90,50 @@ 2 81500 vm_fault:4 0x1fab9bef0000 2 81500 vm_fault:4 0xe16cf749000 0 81500 vm_fault:4 0x13587c366000 - ... + ^C .Ed .Pp Trace all instructions in .Fn amd64_syscall : .Bd -literal -offset indent # dtrace -n 'kinst::amd64_syscall:' +dtrace: description 'kinst::amd64_syscall:' matched 458 probes +CPU ID FUNCTION:NAME + 2 80676 amd64_syscall:323 + 2 80677 amd64_syscall:326 + 2 80678 amd64_syscall:334 + 2 80679 amd64_syscall:339 + 2 80680 amd64_syscall:345 + 2 80681 amd64_syscall:353 + ^C +.Ed +.Pp +Trace the return point of +.Fn vm_page_mvqueue , +which is an inline function: +.Bd -literal -offset indent +# dtrace -n 'kinst::critical_enter:return' +dtrace: description 'kinst::critical_enter:return' matched 130 probes +CPU ID FUNCTION:NAME + 1 71024 spinlock_enter:53 + 0 71024 spinlock_enter:53 + 1 70992 uma_zalloc_arg:49 + 1 70925 malloc_type_zone_allocated:21 + 1 70994 uma_zfree_arg:365 + 1 70924 malloc_type_freed:21 + 1 71024 spinlock_enter:53 + 0 71024 spinlock_enter:53 + 0 71024 spinlock_enter:53 + 0 71024 spinlock_enter:53 + 1 71024 spinlock_enter:53 + 0 71024 spinlock_enter:53 + 0 70947 _epoch_enter_preempt:122 + 0 70949 _epoch_exit_preempt:28 + 0 71024 spinlock_enter:53 + 0 71024 spinlock_enter:53 + 0 70947 _epoch_enter_preempt:122 + 0 70949 _epoch_exit_preempt:28 + ^C .Ed .Sh SEE ALSO .Xr dtrace 1 @@ -89,5 +144,20 @@ .Fx 14.0. .Sh AUTHORS -This manual page was written by -.An Christos Margiolis Aq Mt christos@FreeBSD.org . +.Nm kinst +has been co-authored by +.An Christos Margiolis Aq Mt christos@FreeBSD.org +and +.An Mark Johnston Aq Mt markj@FreeBSD.org . +.Sh BUGS +.Nm kinst +uses trampolines (i.e executable memory) to instrument most instructions. +The trampoline mechanism allocates pages and each page is divided into +individual trampolines. +Having multiple trampolines in the same page however, seems to be triggering an +apparent QEMU/TCG bug when multiple CPUs are writing code to the same page, +resulting in "impossible" page faults and panics, as well as freezes (when a +thread is eternally waiting for an IPI to complete). +A temporary fix could be to have one trampoline per page, meaning each CPU will +write to a different page, but we refrain from doing that until it is exactly +clear what the cause of this bug is.