> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging Yocto builds

This section explains how to resolve common Yocto build failures and debug issues in the Qualcomm Linux workspace.

## **Debug tools**

`packagegroup-core-tools-debug` defined in the `<workspace>/layers/poky/meta` directory adds debug tools as part of `rootfs`. The `<workspace>/layers/meta-qcom-hwe/recipes-devtools` directory contains the appended package group recipe as `packagegroup-core-tools-debug.bbappend`. This append file adds `ltrace`, `perf`, `sysstat`, and `valgrind` tools to this package group. For more information, see [Debug Linux user space issues](https://dragonwingdocs.qualcomm.com/System/Debug-Subsystem/Debug%20linux%20userspace%20issues).

## **Common Yocto build failures**

For common build failures related to QA issues such as version going backwards, see [Verify QA issue: Version going backwards](./verify-qa-issue-version-going-backwards).

## **Layer exclusion issues**

If BitBake didn't parse a newly added layer, the recipes from that layer aren't included in the image.

1. Run the following command, and verify that you see the layer in the output:
   ```text theme={null}
   bitbake -e | grep ^BBLAYERS=
   ```

2. If you can't find the layer, confirm the contents of the `conf/bblayers.conf` file to ensure that the layer is included.

## **Debug builds**

To generate a debug build, run the following command:

```text theme={null}
kas shell meta-qcom/ci/<machine-name>.yml:meta-qcom/ci/<distro-name>.yml:meta-qcom/ci/debug.yml
bitbake qcom-multimedia-image
```

To understand which kernel defconfig and config fragments are used when `DEBUG_BUILD` is set to **1**, see Kernel recipe, under [Kernel recipes](./meta-qcom#kernel-recipes).

The following code snippet from `recipes-kernel/linux/linux-qcom_6.18.bb` enables the debug configuration fragment for the kernel being built:

```text theme={null}
KBUILD_CONFIG_EXTRA:append = " ${@oe.utils.vartrue('DEBUG_BUILD', '${S}/kernel/configs/debug.config', '', d)}"
```

For a dedicated debug build guide, see [Create a build for debugging](./create-a-build-for-debugging).

## **Tooling & logs**

### Verify QDL and ModemManager

If you are using a Linux distribution with `systemd`, use the `systemctl` command to stop `ModemManager`. The following is an example from Ubuntu 22.04:

1. To verify the `ModemManager` status, run the following command:
   ```text theme={null}
   systemctl status ModemManager
   ```
   ```text theme={null}
   ModemManager.service - Modem Manager
   Loaded: loaded (/lib/systemd/system/ModemManager.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2023-11-28 16:28:15 IST; 3 months 4 days ago
   Main PID: 1338 (ModemManager)
   Tasks: 3 (limit: 4915)
   CGroup: /system.slice/ModemManager.service
           └─1338 /usr/sbin/ModemManager --filter-policy=strict
   ```
   ```text theme={null}
   ps aux | grep -i modemmanager
   ```
   ```text theme={null}
   root      1338  0.0  0.0 434332  9544 ?        Ssl   2023  10:39 /usr/sbin/ModemManager --filter-policy=strict
   ```
2. To stop `ModemManager`, run the following command:
   ```text theme={null}
   systemctl stop ModemManager
   systemctl status ModemManager
   ```
   ```text theme={null}
   ModemManager.service - Modem Manager
   Loaded: loaded (/lib/systemd/system/ModemManager.service; enabled; vendor preset: enabled)
   Active: inactive (dead) since Sun 2024-03-03 20:08:32 IST; 4s ago
   Process: 1338 ExecStart=/usr/sbin/ModemManager --filter-policy=strict (code=exited, status=0/SUCCESS)
   Main PID: 1338 (code=exited, status=0/SUCCESS)
   ```
3. The `ps aux` command doesn't show any entry for `/usr/sbin/ModemManager`. If you need `ModemManager`, you must restart it after the flashing is complete and verify if it has started:
   ```text theme={null}
   systemctl start ModemManager
   systemctl status ModemManager
   ```
   ```text theme={null}
   ModemManager.service - Modem Manager
   Loaded: loaded (/lib/systemd/system/ModemManager.service; enabled; vendor preset: enabled)
   Active: active (running) since Sun 2024-03-03 20:11:46 IST; 43s ago
   Main PID: 14785 (ModemManager)
   Tasks: 3 (limit: 4915)
   CGroup: /system.slice/ModemManager.service
           └─14785 /usr/sbin/ModemManager --filter-policy=strict
   ```
   ```text theme={null}
   ps aux | grep -i modemmanager
   ```
   ```text theme={null}
   root     14785  4.6  0.0 434332  9160 ?        Ssl  20:11   0:00 /usr/sbin/ModemManager --filter-policy=strict
   ```