1.\" Copyright (c) 2022 Christos Margiolis <christos@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd February 27, 2023 28.Dt DTRACE_KINST 4 29.Os 30.Sh NAME 31.Nm dtrace_kinst 32.Nd a DTrace provider for tracing arbitrary instructions in a given kernel function 33.Sh SYNOPSIS 34kinst::<function>:<instruction> 35.Sh DESCRIPTION 36The DTrace 37.Nm kinst 38provider allows the user to trace any instruction in a given kernel function. 39<function> corresponds to the function to be traced, and <instruction> is the 40offset to the specific instruction, and can be obtained from the function's 41disassembly using kgdb from the gdb package. 42.Pp 43.Nm kinst 44creates probes on-demand, meaning it searches for and parses the function's 45instructions each time 46.Xr dtrace 1 47is run, and not at module load time. 48This is in contrast to FBT's load-time parsing, since 49.Nm kinst 50can potentially create thousands of probes for just a single function, instead 51of up to two (entry and return) in the case of FBT. 52A result of this is that 53.Cm dtrace -l -P kinst 54will not match any probes. 55.Sh IMPLEMENTATION NOTES 56The provider is currently implemented only for amd64. 57.Sh EXAMPLES 58Find the offset corresponding to the third instruction in 59.Fn vm_fault 60and trace it, printing the contents of the RSI register: 61.Bd -literal -offset indent 62# kgdb 63(kgdb) disas /r vm_fault 64Dump of assembler code for function vm_fault: 65 0xffffffff80876df0 <+0>: 55 push %rbp 66 0xffffffff80876df1 <+1>: 48 89 e5 mov %rsp,%rbp 67 0xffffffff80876df4 <+4>: 41 57 push %r15 68 69# dtrace -n 'kinst::vm_fault:4 {printf("%#x", regs[R_RSI]);}' 70 2 81500 vm_fault:4 0x827c56000 71 2 81500 vm_fault:4 0x827878000 72 2 81500 vm_fault:4 0x1fab9bef0000 73 2 81500 vm_fault:4 0xe16cf749000 74 0 81500 vm_fault:4 0x13587c366000 75 ... 76.Ed 77.Pp 78Trace all instructions in 79.Fn amd64_syscall : 80.Bd -literal -offset indent 81# dtrace -n 'kinst::amd64_syscall:' 82.Ed 83.Sh SEE ALSO 84.Xr dtrace 1 85.Sh HISTORY 86The 87.Nm kinst 88provider first appeared in 89.Fx 9014.0. 91.Sh AUTHORS 92This manual page was written by 93.An Christos Margiolis Aq Mt christos@FreeBSD.org . 94