Page MenuHomeFreeBSD
Files F103326557

D40874.id124299.diff
No OneTemporary
Actions

D40874.id124299.diff
View Options

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,5 +1,8 @@
.\" Copyright (c) 2022 Christos Margiolis <christos@FreeBSD.org>
-.\" All rights reserved.
+.\" Copyright (c) 2023 The FreeBSD Foundation
+.\"
+.\" Portions of this documentation were written by Christos Margiolis
+.\" <christos@FreeBSD.org> 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
@@ -24,21 +27,33 @@
.\"
.\" $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::<function>:<instruction>
.Sh DESCRIPTION
-The DTrace
+The
+.Nm kinst
+DTrace provider allows the user to trace any instruction in a kernel function.
+.Cm <function>
+corresponds to the function to be traced, and
+.Cm <instruction>
+is the offset of the instruction, relative to the beginning of the function.
+.Pp
.Nm kinst
-provider allows the user to trace any instruction in a given kernel function.
-<function> corresponds to the function to be traced, and <instruction> is the
-offset to the specific instruction, and can be obtained from the function's
-disassembly using kgdb from the gdb package.
+can also trace inline functions by requesting a probe of the form
+.Cm kinst::<inline_func>:<entry|return> .
+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 +68,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 on the amd64, arm64 and riscv platforms.
.Sh EXAMPLES
Find the offset corresponding to the third instruction in
.Fn vm_fault
@@ -72,16 +88,54 @@
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 critical_enter ,
+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
+.Xr dtrace 1 ,
+.Xr arch 7
.Sh HISTORY
The
.Nm kinst
@@ -89,5 +143,21 @@
.Fx
14.0.
.Sh AUTHORS
-This manual page was written by
-.An Christos Margiolis Aq Mt christos@FreeBSD.org .
+.Nm kinst
+was 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 implement single-stepping for
+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.

File Metadata

Mime Type
text/plain
Expires
Sun, Nov 24, 2:29 PM (15 h, 10 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
14823450
Default Alt Text
D40874.id124299.diff (5 KB)

Event Timeline