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.Dd July 16, 2025 26.Dt DTRACE_KINST 4 27.Os 28.Sh NAME 29.Nm dtrace_kinst 30.Nd a DTrace provider for tracing arbitrary instructions in a given kernel function 31.Sh SYNOPSIS 32kinst::<function>:<instruction> 33.Sh DESCRIPTION 34The DTrace 35.Nm kinst 36provider allows the user to trace any instruction in a given kernel function. 37<function> corresponds to the function to be traced, and <instruction> is the 38offset to the specific instruction, and can be obtained from the function's 39disassembly using kgdb from the gdb package. 40.Pp 41.Nm kinst 42creates probes on-demand, meaning it searches for and parses the function's 43instructions each time 44.Xr dtrace 1 45is run, and not at module load time. 46This is in contrast to 47.Xr dtrace_fbt 4 Ap s 48load-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 52.Xr dtrace_fbt 4 . 53A result of this is that 54.Cm dtrace -l -P kinst 55will not match any probes. 56.Sh IMPLEMENTATION NOTES 57The provider is currently implemented only for amd64. 58.Sh EXAMPLES 59Find the offset corresponding to the third instruction in 60.Fn vm_fault 61and trace it, printing the contents of the RSI register: 62.Bd -literal -offset indent 63# kgdb 64(kgdb) disas /r vm_fault 65Dump of assembler code for function vm_fault: 66 0xffffffff80876df0 <+0>: 55 push %rbp 67 0xffffffff80876df1 <+1>: 48 89 e5 mov %rsp,%rbp 68 0xffffffff80876df4 <+4>: 41 57 push %r15 69 70# dtrace -n 'kinst::vm_fault:4 {printf("%#x", regs[R_RSI]);}' 71 2 81500 vm_fault:4 0x827c56000 72 2 81500 vm_fault:4 0x827878000 73 2 81500 vm_fault:4 0x1fab9bef0000 74 2 81500 vm_fault:4 0xe16cf749000 75 0 81500 vm_fault:4 0x13587c366000 76 ... 77.Ed 78.Pp 79Trace all instructions in 80.Fn amd64_syscall : 81.Bd -literal -offset indent 82# dtrace -n 'kinst::amd64_syscall:' 83.Ed 84.Sh SEE ALSO 85.Xr dtrace 1 , 86.Xr dtrace_fbt 4 87.Sh HISTORY 88The 89.Nm kinst 90provider first appeared in 91.Fx 9214.0. 93.Sh AUTHORS 94This manual page was written by 95.An Christos Margiolis Aq Mt christos@FreeBSD.org . 96