> ## 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.

# 调试 Yocto 构建

本节介绍如何解决 Qualcomm Linux 工作区中常见的 Yocto 构建失败并调试问题。

## **调试工具**

在 `<workspace>/layers/poky/meta` 目录中定义的 `packagegroup-core-tools-debug` 会将调试工具添加为 `rootfs` 的一部分。`<workspace>/layers/meta-qcom-hwe/recipes-devtools` 目录中包含追加的包组 recipe，即 `packagegroup-core-tools-debug.bbappend`。该追加文件向此包组中添加了 `ltrace`、`perf`、`sysstat` 和 `valgrind` 工具。有关更多信息，请参阅[调试 Linux 用户空间问题](https://dragonwingdocs.qualcomm.com/System/Debug-Subsystem/Debug%20linux%20userspace%20issues)。

## **常见 Yocto 构建失败**

有关与 QA 问题（如版本回退）相关的常见构建失败，请参阅[验证 QA 问题：版本回退](./verify-qa-issue-version-going-backwards)。

## **层排除问题**

如果 BitBake 未解析新添加的层，则该层中的配方（recipe）不会包含在镜像中。

1. 运行以下命令，并确认输出中包含该层：
   ```text theme={null}
   bitbake -e | grep ^BBLAYERS=
   ```

2. 如果找不到该层，请检查 `conf/bblayers.conf` 文件的内容，确保其中包含了该层。

## **调试构建**

要生成调试构建，请运行以下命令：

```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
```

要了解当 `DEBUG_BUILD` 设置为 **1** 时使用哪些内核 defconfig 和配置片段，请参阅[内核配方](./meta-qcom#kernel-recipes)下的内核配方部分。

以下来自 `recipes-kernel/linux/linux-qcom_6.18.bb` 的代码片段为正在构建的内核启用调试配置片段：

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

有关专门的调试构建指南，请参阅[创建用于调试的构建](./create-a-build-for-debugging)。

## **工具与日志**

### 验证 QDL 和 ModemManager

如果你使用的是带有 `systemd` 的 Linux 发行版，请使用 `systemctl` 命令停止 `ModemManager`。以下是 Ubuntu 22.04 上的示例：

1. 要验证 `ModemManager` 的状态，运行以下命令：
   ```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. 要停止 `ModemManager`，运行以下命令：
   ```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. `ps aux` 命令不会显示任何 `/usr/sbin/ModemManager` 的条目。如果你需要 `ModemManager`，必须在刷写完成后重新启动它，并验证它是否已启动：
   ```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
   ```