linux-tracepoint-example
========================

Example kernel module registering a tracepoint. 

Author:  Giovanni Santini
Mail:    giovanni.santini@proton.me
License: GPLv2


Overview
--------

Tracepoints (aka. static event tracing) is an important part of the
tracing infrastructure provided by the Linux kernel. Tracepoints allow
the registration of static tracepoints throughtout the kernel.

Tracepoints are essentially callbacks that get called when execution
reaches the tracepoint. We define these through macros, in particular
we need to define the event name, the prototype of the callback, the
arguments used, a structure that a trace could use to store the data
passed into the tracepoint, a way to assign the data to the structure,
and the way to output the structure in human readable format.

Tracepoints are placed all around the kernel; when they are executed
(and enabled), they will log the specified data under
`/sys/kernel/tracing/trace`. You can list / enable / disable specific
tracepoints from tracefs.

The macros are complete magic. I am now trying to understand how this
works with a debugger.

For further reading, read the linux kernel source directly.

This series of articles is great:

   https://lwn.net/Articles/379903/
   

Compilation
-----------

To build and load the kernel module, you first need the kernel
sources. In addition to building the module, we will also build the
kernel and an image to boot it with qemu for development. This is
advised since kernel panics in your module may crash the system.

Download a kernel version:

    wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.19.3.tar.xz
    tar -xvf linux-6.19.3.tar.xz && mv linux-6.19.3 linux
    cd linux
    make defconfig && make -j$(nproc)
    cd ..

Build the module:

    make KVERSION=6.19.3

Clean the build:

    make clean

Create an image, copy the module, and boot with qemu:

    make img
    make copy
    make qemu


Usage
-----

Inside the image, you will find the module in the /root directory. You
can load it with `insmod`

    insmod ./hello-ptrace.ko

Check messages in `dmeg`:

    dmesg

Activate trace event:

   cd /sys/kernel/debug/tracing
   ls events
   block   ext4    header_event  i915  jbd2  module  sched  skb       timer
   enable  ftrace  header_page   irq   kmem  power   hello  syscalls  workqueue
   ls events/hello
   enable  filter  hello
   echo 1 > events/silly/hello/enable

Read events:

   cat trace

List loaded modules:

    lsmod | grep hello

Remove it with:

    rmmod -f hello


Debugging
---------

Follow this guide to debug kernel modules with gdb:

    https://www.kernel.org/doc/html/v6.17/process/debugging/gdb-kernel-debugging.html

    cat /sys/module/<your_module_name>/sections/.text
    
    make qemu-debug
    gdb ./linux/arch/x86/boot/vmlinux
    (gdb) target remote :1234
    (gdb) add-symbol-file /path/to/your/module.ko 0xffffffffa0000000