16f6d1fc7SChristos Margiolis.\" Copyright (c) 2022 Christos Margiolis <christos@FreeBSD.org> 26f6d1fc7SChristos Margiolis.\" All rights reserved. 36f6d1fc7SChristos Margiolis.\" 46f6d1fc7SChristos Margiolis.\" Redistribution and use in source and binary forms, with or without 56f6d1fc7SChristos Margiolis.\" modification, are permitted provided that the following conditions 66f6d1fc7SChristos Margiolis.\" are met: 76f6d1fc7SChristos Margiolis.\" 1. Redistributions of source code must retain the above copyright 86f6d1fc7SChristos Margiolis.\" notice, this list of conditions and the following disclaimer. 96f6d1fc7SChristos Margiolis.\" 2. Redistributions in binary form must reproduce the above copyright 106f6d1fc7SChristos Margiolis.\" notice, this list of conditions and the following disclaimer in the 116f6d1fc7SChristos Margiolis.\" documentation and/or other materials provided with the distribution. 126f6d1fc7SChristos Margiolis.\" 136f6d1fc7SChristos Margiolis.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 146f6d1fc7SChristos Margiolis.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 156f6d1fc7SChristos Margiolis.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 166f6d1fc7SChristos Margiolis.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 176f6d1fc7SChristos Margiolis.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 186f6d1fc7SChristos Margiolis.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 196f6d1fc7SChristos Margiolis.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 206f6d1fc7SChristos Margiolis.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 216f6d1fc7SChristos Margiolis.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 226f6d1fc7SChristos Margiolis.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 236f6d1fc7SChristos Margiolis.\" SUCH DAMAGE. 246f6d1fc7SChristos Margiolis.\" 252d71406aSChristos Margiolis.Dd February 27, 2023 266f6d1fc7SChristos Margiolis.Dt DTRACE_KINST 4 276f6d1fc7SChristos Margiolis.Os 286f6d1fc7SChristos Margiolis.Sh NAME 296f6d1fc7SChristos Margiolis.Nm dtrace_kinst 302d71406aSChristos Margiolis.Nd a DTrace provider for tracing arbitrary instructions in a given kernel function 316f6d1fc7SChristos Margiolis.Sh SYNOPSIS 326f6d1fc7SChristos Margioliskinst::<function>:<instruction> 336f6d1fc7SChristos Margiolis.Sh DESCRIPTION 346f6d1fc7SChristos MargiolisThe DTrace 356f6d1fc7SChristos Margiolis.Nm kinst 366f6d1fc7SChristos Margiolisprovider allows the user to trace any instruction in a given kernel function. 376f6d1fc7SChristos Margiolis<function> corresponds to the function to be traced, and <instruction> is the 386f6d1fc7SChristos Margiolisoffset to the specific instruction, and can be obtained from the function's 392d71406aSChristos Margiolisdisassembly using kgdb from the gdb package. 406f6d1fc7SChristos Margiolis.Pp 416f6d1fc7SChristos Margiolis.Nm kinst 426f6d1fc7SChristos Margioliscreates probes on-demand, meaning it searches for and parses the function's 436f6d1fc7SChristos Margiolisinstructions each time 446f6d1fc7SChristos Margiolis.Xr dtrace 1 452d71406aSChristos Margiolisis run, and not at module load time. 462d71406aSChristos MargiolisThis is in contrast to FBT's load-time parsing, since 476f6d1fc7SChristos Margiolis.Nm kinst 486f6d1fc7SChristos Margioliscan potentially create thousands of probes for just a single function, instead 496f6d1fc7SChristos Margiolisof up to two (entry and return) in the case of FBT. 502d71406aSChristos MargiolisA result of this is that 512d71406aSChristos Margiolis.Cm dtrace -l -P kinst 522d71406aSChristos Margioliswill not match any probes. 532d71406aSChristos Margiolis.Sh IMPLEMENTATION NOTES 542d71406aSChristos MargiolisThe provider is currently implemented only for amd64. 556f6d1fc7SChristos Margiolis.Sh EXAMPLES 562d71406aSChristos MargiolisFind the offset corresponding to the third instruction in 576f6d1fc7SChristos Margiolis.Fn vm_fault 58*092a543eSMark Johnstonand trace it, printing the contents of the RSI register: 596f6d1fc7SChristos Margiolis.Bd -literal -offset indent 606f6d1fc7SChristos Margiolis# kgdb 616f6d1fc7SChristos Margiolis(kgdb) disas /r vm_fault 626f6d1fc7SChristos MargiolisDump of assembler code for function vm_fault: 636f6d1fc7SChristos Margiolis 0xffffffff80876df0 <+0>: 55 push %rbp 646f6d1fc7SChristos Margiolis 0xffffffff80876df1 <+1>: 48 89 e5 mov %rsp,%rbp 656f6d1fc7SChristos Margiolis 0xffffffff80876df4 <+4>: 41 57 push %r15 666f6d1fc7SChristos Margiolis 67*092a543eSMark Johnston# dtrace -n 'kinst::vm_fault:4 {printf("%#x", regs[R_RSI]);}' 68*092a543eSMark Johnston 2 81500 vm_fault:4 0x827c56000 69*092a543eSMark Johnston 2 81500 vm_fault:4 0x827878000 70*092a543eSMark Johnston 2 81500 vm_fault:4 0x1fab9bef0000 71*092a543eSMark Johnston 2 81500 vm_fault:4 0xe16cf749000 72*092a543eSMark Johnston 0 81500 vm_fault:4 0x13587c366000 732d71406aSChristos Margiolis ... 746f6d1fc7SChristos Margiolis.Ed 756f6d1fc7SChristos Margiolis.Pp 766f6d1fc7SChristos MargiolisTrace all instructions in 776f6d1fc7SChristos Margiolis.Fn amd64_syscall : 786f6d1fc7SChristos Margiolis.Bd -literal -offset indent 796f6d1fc7SChristos Margiolis# dtrace -n 'kinst::amd64_syscall:' 806f6d1fc7SChristos Margiolis.Ed 816f6d1fc7SChristos Margiolis.Sh SEE ALSO 822d71406aSChristos Margiolis.Xr dtrace 1 836f6d1fc7SChristos Margiolis.Sh HISTORY 846f6d1fc7SChristos MargiolisThe 856f6d1fc7SChristos Margiolis.Nm kinst 866f6d1fc7SChristos Margiolisprovider first appeared in 876f6d1fc7SChristos Margiolis.Fx 886f6d1fc7SChristos Margiolis14.0. 896f6d1fc7SChristos Margiolis.Sh AUTHORS 906f6d1fc7SChristos MargiolisThis manual page was written by 916f6d1fc7SChristos Margiolis.An Christos Margiolis Aq Mt christos@FreeBSD.org . 92