# Configure debug methods

Use the following methods to understand the high-level categorization of ways to debug the kernel, and report issues identified with the inherent debug features in the Qualcomm Linux kernel.

For more information about debug, see [Qualcomm Linux Debug
Guide](doc/80-70030-12/80-70030-12.pdf).

## Debug with printk

Use the `printk` technique to debug in the Linux kernel for printing messages and tracing.

The wrappers around printk defined in `include/linux/printk.h` support adding a log level to your log statements. For example:

pr_emerg("At line %d: Func: %s\n", __LINE__, __func__);
    pr_info("At line");
    Copy to clipboard

For more information, see [Message logging with printk](https://www.kernel.org/doc/html/next/core-api/printk-basics.html).

## Compile the device tree

To debug the device tree, do the following:

1. Clone the kernel code using `devtool modify linux-qcom-custom` command.
2. Make changes in the device tree.
3. Build DTB using `bitbake dtb-qcom-image` command.
4. Flash `build-qcom-wayland/tmp-glibc/deploy/images/qcs6490-rb3gen2-vision-kit/dtb-qcom-image-qcs6490-rb3gen2-vision-kit.rootfs.vfat` (which is same as dtb.bin) to `dtb_a` and `dtb_b` partitions using the `fastboot` command.
5. Restart the device.

## Debug the kernel modules

To debug the kernel modules, do the following:

1. Clone the kernel code using the `devtool modify linux-qcom-custom` command.
2. Kernel module signing is disabled by default. To manually disable kernel module signing configuration, `CONFIG_MODULE_SIG` using the `menuconfig` commands. For more information about `menuconfig` commands, see [Configure the kernel](https://docs.qualcomm.com/doc/80-70030-3/topic/kernel-development.html#kernel-configuration3).

CONFIG_MODULE_SIG
        Copy to clipboard

CONFIG_MODULE_SIG_FORCE
        Copy to clipboard

Note

This is a one-time step.
3. Make changes in kernel or modules.
4. Re-build kernel modules using `bitbake esp-qcom-image` command.
5. Push `tmp-glibc/deploy/images/qcs6490-rb3gen2-vision-kit/linux-qcs6490-rb3gen2-vision-kit.efi` kernel image to the device at `/tmp` directory, and rename it as `vmlinuz` (kernel binary).
6. Update kernel using `cp /tmp/vmlinuz /boot/ostree/poky-<SHA>/vmlinuz-6.6.52-03343-gdfbbed24a2c5-dirty` command.
7. Push `build-qcom-wayland/tmp-glibc/deploy/images/qcs6490-rb3gen2-vision-kit/modules--6.6-r0-qcs6490-rb3gen2-vision-kit-<DATE>.tgz` kernel modules to the device at `/tmp` directory.
8. Remount root using `mount -o remount,rw /` and `mount -o remount,rw /usr` commands.
9. Unzip using `tar -xzf modules--6.6-r0-qcs6490-rb3gen2-vision-kit-<DATE>.tgz` command.
10. Update the kernel modules using, `cp -rf /tmp/lib/modules/6.6.65-debug-04076-g029659012248-dirty/ /lib/modules/` command.
11. Restart the device.

To permanently disable module signing, do the following steps:

1. Disable the following kernel configuration options:

CONFIG_MODULE_SIG
        CONFIG_MODULE_SIG_FORCE
        Copy to clipboard
2. In `conf/machine/include/qcom-base.inc` file, remove the following line:

INHERIT += " qmodule"
        Copy to clipboard
3. In `recipes-kernel/linux/linux-qcom-custom_6.6.bb` file, remove the following line:

do_package[nostamp] = "1"
        Copy to clipboard

## Debug with log levels

You can print messages using any other log levels defined in
`/linux/printk.h`. The console logs are controlled using the log level
used in printk and the log level chosen on the device.

Choose the log level according to your use case. You may encounter numerous logs if a lower log level is chosen in a frequently called function.

The following example shows the logs for kernel print levels:

pr_info("At func %s\n", __func__);
    pr_notice("At func %s\n", __func__);
    pr_warn("At func %s\n", __func__);
    pr_err("At func %s\n", __func__);
    pr_crit("At func %s\n", __func__);
    pr_alert("At func %s\n", __func__);
    pr_emerg("At func %s\n", __func__);
    Copy to clipboard

## Enable and mount the debugfs file system

Debugfs is a file system that allows kernel developers to provide kernel
information to the user space.

Debugfs is used to access kernel data structures and variables, trace
events, debug messages, and statistics.

- Ensure that your kernel configuration has `CONFIG_DEBUG_FS` set
(enabled by default).
- If not, you can enable it in your kernel configuration using
`menuconfig`.
- Mount debugfs if it’s not mounted by default.

mount -t debugfs none /sys/kernel/debug
        Copy to clipboard

## Debug with kernel probes

Kprobes allows you to break into any kernel routine and collect debugging and performance information nondisruptively.

The kernel code address is trapped using a handler routine to invoke when the breakpoint is hit. Kprobes is useful during scheduler debug when you generate traces at different scheduling events to understand the
system behavior.

For more information, see [Kernel Probes](https://www.kernel.org/doc/html/next/trace/kprobes.html).

## Configure Ftrace for profiling and tracing

The ftrace provides tracing utilities that enable system-wide profiling and runtime tracing.

For more information about ftrace, see
[Function trace](https://docs.qualcomm.com/bundle/publicresource/topics/80-70030-12/debugging_linux_kernel.html#function-tracer).

### Enable memory-mapped input/output traces

The memory-mapped I/O (MMIO) traces in the Qualcomm Linux kernel provide
information to understand how drivers interact with MMIO devices and
their associated hardware states.

Generic MMIO traces use `__raw_{read,write}{b,l,w,q}` accessors to
read/write from/to memory-mapped registers.

In the following cases, the device hangs or some undefined behavior
leads to device crashes:

> 
> 
> Table: Reasons of device crashes
> 
> 
> | Reasons | Explanation |
> | --- | --- |
> | Unclocked access | If the access to the register space is unclocked, the device crashes. |
> | Protected register space | If the register space is protected and not set for access to the nonsecure world exceptions happen. For example, only exception level (EL3) access is allowed and any EL2/EL1 access is forbidden. |
> | xPU control | xPU memory protection units control access to certain memory or register regions for specific clients. |

The earlier scenarios result in instant reboot, synchronous errors (SErrors)/network on chip (NoC) issues, or interconnect hangs. `CONFIG_TRACE_MMIO_ACCESS` provides ftrace trace events to log such MMIO register accesses, offering early enablement of trace events, filtering capability, and the ability to dump the ftrace logs on console.

The following is the sample output from the trace buffer when the MMIO
traces are enabled:

# List all rwmmio trace events
      cat /sys/kernel/tracing/available_events | grep rwmmio
    
    # Enable all rwmmio trace events
      cat /sys/kernel/tracing/available_events | grep rwmmio >> /sys/kernel/tracing/set_event
    
    # List all traces
      cat /sys/kernel/tracing/trace
    rwmmio_read: gic_peek_irq+0xd0/0xd8 readl addr=0xffff800010040104
    rwmmio_write: gic_poke_irq+0xe4/0xf0 writel addr=0xffff800010040184
    rwmmio_read: gic_do_wait_for_rwp+0x54/0x90 readl addr=0xffff800010040000
    rwmmio_write: gic_set_affinity+0x1bc/0x1e8 writeq addr=0xffff800010046130
    Copy to clipboard

Last Published: Jun 25, 2026

[Previous Topic
Capture the kernel logs](https://docs.qualcomm.com/bundle/publicresource/80-70030-3/topics/capture-the-kernel-logs.md) [Next Topic
Access content from the device](https://docs.qualcomm.com/bundle/publicresource/80-70030-3/topics/access-content-from-the-device.md)