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 February 27, 2023 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 FBT's load-time parsing, since 47.Nm kinst 48can potentially create thousands of probes for just a single function, instead 49of up to two (entry and return) in the case of FBT. 50A result of this is that 51.Cm dtrace -l -P kinst 52will not match any probes. 53.Sh IMPLEMENTATION NOTES 54The provider is currently implemented only for amd64. 55.Sh EXAMPLES 56Find the offset corresponding to the third instruction in 57.Fn vm_fault 58and trace it, printing the contents of the RSI register: 59.Bd -literal -offset indent 60# kgdb 61(kgdb) disas /r vm_fault 62Dump of assembler code for function vm_fault: 63 0xffffffff80876df0 <+0>: 55 push %rbp 64 0xffffffff80876df1 <+1>: 48 89 e5 mov %rsp,%rbp 65 0xffffffff80876df4 <+4>: 41 57 push %r15 66 67# dtrace -n 'kinst::vm_fault:4 {printf("%#x", regs[R_RSI]);}' 68 2 81500 vm_fault:4 0x827c56000 69 2 81500 vm_fault:4 0x827878000 70 2 81500 vm_fault:4 0x1fab9bef0000 71 2 81500 vm_fault:4 0xe16cf749000 72 0 81500 vm_fault:4 0x13587c366000 73 ... 74.Ed 75.Pp 76Trace all instructions in 77.Fn amd64_syscall : 78.Bd -literal -offset indent 79# dtrace -n 'kinst::amd64_syscall:' 80.Ed 81.Sh SEE ALSO 82.Xr dtrace 1 83.Sh HISTORY 84The 85.Nm kinst 86provider first appeared in 87.Fx 8814.0. 89.Sh AUTHORS 90This manual page was written by 91.An Christos Margiolis Aq Mt christos@FreeBSD.org . 92