Differential D38825 Diff 119172 share/man/man4/dtrace_kinst.4

Changeset View

Standalone View

share/man/man4/dtrace_kinst.4

Show All 18 Lines
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)		.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT		.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY		.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF		.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.		.\" SUCH DAMAGE.
.\"		.\"
.\" $FreeBSD$		.\" $FreeBSD$
.\"		.\"
.Dd February 27, 2023		.Dd March 18, 2023
.Dt DTRACE_KINST 4		.Dt DTRACE_KINST 4
.Os		.Os
.Sh NAME		.Sh NAME
.Nm dtrace_kinst		.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 a given kernel function
.Sh SYNOPSIS		.Sh SYNOPSIS
kinst::<function>:<instruction>		kinst::<function>:<instruction>
.Sh DESCRIPTION		.Sh DESCRIPTION
The DTrace		The DTrace
.Nm kinst		.Nm kinst
provider allows the user to trace any instruction in a given kernel function.		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		.Cm <function>
offset to the specific instruction, and can be obtained from the function's		corresponds to the function to be traced, and
disassembly using kgdb from the gdb package.		.Cm <instruction>
		is the offset to the specific instruction, and can be obtained from the
		function's disassembly using kgdb from the gdb package.
.Pp		.Pp
.Nm kinst		.Nm kinst
		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		creates probes on-demand, meaning it searches for and parses the function's
instructions each time		instructions each time
.Xr dtrace 1		.Xr dtrace 1
is run, and not at module load time.		is run, and not at module load time.
This is in contrast to FBT's load-time parsing, since		This is in contrast to FBT's load-time parsing, since
.Nm kinst		.Nm kinst
can potentially create thousands of probes for just a single function, instead		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 FBT.
Show All 15 Lines	Dump of assembler code for function vm_fault:
0xffffffff80876df4 <+4>: 41 57 push %r15		0xffffffff80876df4 <+4>: 41 57 push %r15

# dtrace -n 'kinst::vm_fault:4 {printf("%#x", regs[R_RSI]);}'		# dtrace -n 'kinst::vm_fault:4 {printf("%#x", regs[R_RSI]);}'
2 81500 vm_fault:4 0x827c56000		2 81500 vm_fault:4 0x827c56000
2 81500 vm_fault:4 0x827878000		2 81500 vm_fault:4 0x827878000
2 81500 vm_fault:4 0x1fab9bef0000		2 81500 vm_fault:4 0x1fab9bef0000
2 81500 vm_fault:4 0xe16cf749000		2 81500 vm_fault:4 0xe16cf749000
0 81500 vm_fault:4 0x13587c366000		0 81500 vm_fault:4 0x13587c366000
...		^C
.Ed		.Ed
.Pp		.Pp
Trace all instructions in		Trace all instructions in
.Fn amd64_syscall :		.Fn amd64_syscall :
.Bd -literal -offset indent		.Bd -literal -offset indent
# dtrace -n 'kinst::amd64_syscall:'		# 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		.Ed
.Sh SEE ALSO		.Sh SEE ALSO
.Xr dtrace 1		.Xr dtrace 1
.Sh HISTORY		.Sh HISTORY
The		The
.Nm kinst		.Nm kinst
provider first appeared in		provider first appeared in
.Fx		.Fx
14.0.		14.0.
.Sh AUTHORS		.Sh AUTHORS
This manual page was written by		This manual page was written by
.An Christos Margiolis Aq Mt christos@FreeBSD.org .		.An Christos Margiolis Aq Mt christos@FreeBSD.org .