DTRACE_KINST(4)        FreeBSD Kernel Interfaces Manual        DTRACE_KINST(4)

NAME

     dtrace_kinst - a DTrace provider for tracing arbitrary instructions in a
     given kernel function

SYNOPSIS

     kinst::<function>:<instruction>

DESCRIPTION

     The DTrace kinst provider allows the user to trace any instruction in a
     given kernel function.  <function> corresponds to the function to be
     traced, and <instruction> is the offset to the specific instruction, and
     can be obtained from the function's disassembly using kgdb from the gdb
     package.

     kinst creates probes on-demand, meaning it searches for and parses the
     function's instructions each time dtrace(1) is run, and not at module
     load time.  This is in contrast to dtrace_fbt(4)'s load-time parsing,
     since kinst can potentially create thousands of probes for just a single
     function, instead of up to two (entry and return) in the case of
     dtrace_fbt(4).  A result of this is that dtrace -l -P kinst will not
     match any probes.

IMPLEMENTATION NOTES

     The provider is currently implemented only for amd64.

EXAMPLES

     Find the offset corresponding to the third instruction in vm_fault() and
     trace it, printing the contents of the RSI register:

           # kgdb
           (kgdb) disas /r vm_fault
           Dump of assembler code for function vm_fault:
              0xffffffff80876df0 <+0>:     55      push   %rbp
              0xffffffff80876df1 <+1>:     48 89 e5        mov    %rsp,%rbp
              0xffffffff80876df4 <+4>:     41 57   push   %r15

           # dtrace -n 'kinst::vm_fault:4 {printf("%#x", regs[R_RSI]);}'
             2  81500                       vm_fault:4 0x827c56000
             2  81500                       vm_fault:4 0x827878000
             2  81500                       vm_fault:4 0x1fab9bef0000
             2  81500                       vm_fault:4 0xe16cf749000
             0  81500                       vm_fault:4 0x13587c366000
             ...

     Trace all instructions in amd64_syscall():

           # dtrace -n 'kinst::amd64_syscall:'

SEE ALSO

     dtrace(1), dtrace_fbt(4)

HISTORY

     The kinst provider first appeared in FreeBSD 14.0.

AUTHORS

     This manual page was written by Christos Margiolis
     <christos@FreeBSD.org>.

FreeBSD 15.1-STABLE-HBSD         July 16, 2025                 DTRACE_KINST(4)