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