InstructionLevelDynamicTracing [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Instruction-level dynamic tracing ======

  * Student: [[/ChristosMargiolis|ChristosMargiolis]] (christos@)
  * Mentor:  [[/MarkJohnston|MarkJohnston]] (markj@)

===== Project description =====

The objective of this project is to implement a new DTrace provider for
dynamically tracing all instructions in a given function. FBT (Function
Boundary Tracing) is a DTrace provider providing probes for the entry
and return points of a kernel function. The new provider – we’ll call
it ''%%kinst%%'' – will reuse parts of the FBT mechanism, but extend it to be
able to put probes on arbitrary points in a given kernel function. This
provider will be especially useful for tracing long kernel functions.
It will also set the building blocks for inline function tracing.

===== Deliverables =====

==== Required ====

  * Implement support in dtrace(1). The new provider will be called in the form of ''%%dtrace -n 'kinst::<function>:<offset>'%%'' where ''%%function%%'' is the name of the kernel function we want to trace, and ''%%offset%%'' is the specific instruction. The offset can be extracted using the function's disassembly.
  * Implement the new provider in the kernel. The way this provider is going to achieve tracing of all instructions is by using the following algorithm:
    * Disassemble ''%%function%%''.
    * Verify that ''%%offset%%'' is an instruction boundary. If not, dtrace(1) exits with an error, else fetch the instruction at ''%%offset%%''.
    * Allocate a "trampoline" (executable memory) where it will store the instruction and its address, so that it can ''%%jmp%%'' back when done.
    * Overwrite ''%%instruction%%'' with interrupt 3, which is the [[https://wiki.osdev.org/Exceptions#Breakpoint|breakpoint exception]] in x86 architectures.
    * If the breakpoint handler was triggered by a breakpoint installed by DTrace, send the trace data.
    * ''%%iret%%'' to the trampoline.
    * Execute ''%%instruction%%'' and ''%%jmp%%'' back to the original address in order to continue execution.

==== Optional ====

  * Implement the provider for other architectures as well (arm64, riscv, ...).
  * Write a standalone C program which takes a function as input, and prints all inline calls (address ranges) in that function, using DWARF via dwarf(3).
  * Write a standalone program which takes a C file and a line number, and resolves ''%%<file>:<line>%%'' tuples to ''%%<function>:<offset>%%'' ones (to be used as arguments in ''%%kinst%%''), in case ''%%<line>%%'' corresponds to a kernel function. This lets us avoid the hassle of manually debugging and scanning ELF symbol tables. The program could use DWARF as well.

===== Test plan =====

Testing is done on a bhyve VM running -CURRENT.

===== Weekly progress =====

^  Email archive  ^
| [[https://lists.freebsd.org/archives/soc-status/2022-June/000004.html|Week 1]] |
| [[https://lists.freebsd.org/archives/soc-status/2022-June/000011.html|Week 2]] |
| [[https://lists.freebsd.org/archives/soc-status/2022-July/000019.html|Week 3]] |
| [[https://lists.freebsd.org/archives/soc-status/2022-July/000023.html|Week 4]] |
| [[https://lists.freebsd.org/archives/soc-status/2022-July/000035.html|Week 5-6]] |
| [[https://lists.freebsd.org/archives/soc-status/2022-August/000048.html|Week 7-8]] |
| [[https://lists.freebsd.org/archives/soc-status/2022-August/000050.html|Week 9]] |
| [[https://lists.freebsd.org/archives/soc-status/2022-August/000058.html|Week 10-11]] |
| [[https://lists.freebsd.org/archives/soc-status/2022-September/000062.html|Week 12]] |

===== Development =====

  * [[https://github.com/christosmarg/freebsd/tree/kinst|GitHub development tree]]
  * [[https://reviews.freebsd.org/D35827|Initial code review]]
  * [[https://reviews.freebsd.org/D36851|Final code review]]

===== Commits =====

  * [[https://cgit.freebsd.org/src/commit/?id=f0bc4ed144fc59b6f72d90c46b91ca803d3b29ce|Initial commit]]
  * [[https://cgit.freebsd.org/src/commit/?id=2179a159ea93e37b7fb2126ae0b1627b875f808b|kinst support in libdtrace]]
  * [[https://cgit.freebsd.org/src/commit/?id=6f6d1fc7c8e5e5ffc5484abcf95d34b1a2434a2b|Manual page]]

===== Documentation =====

  * [[https://illumos.org/books/dtrace/dtrace-ebook.pdf|DTrace ebook]]
  * [[https://freebsdfoundation.org/wp-content/uploads/2014/05/DTrace.pdf|Mark Johnston: DTrace]]
  * [[https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html|Intel Software Developer's Manual]]

----

{{tag>Gsoc}}