# 使用 OpenOCD 进行调试

OpenOCD 是一个开源片上调试器，它为嵌入式设备提供调试、系统内编程和边界扫描测试。OpenOCD 支持一系列接口，例如 JTAG 和 SWD，这使其成为一种多功能调试工具。OpenOCD 支持 GDB、LLDB 和其他调试工具，为开发者提供了熟悉且强大的调试环境。有关更多信息，请参阅 [OpenOCD](https://openocd.org/)。

在使用 OpenOCD 之前，请查看以下信息。

- 使用 Ubuntu Linux 主机进行调试设置。
- Qualcomm 支持 OpenOCD 版本 0.12.0。有关更多信息，请参阅 `openocd/configure.ac`。
- 使用 QC 嵌入式 USB 调试器 (EUD) 解决方案通过 USB Type-C、LLDB 和 GDB 作为命令行调试器支持 OpenOCD。
- 保持 Qualcomm Linux 编译版本准备就绪。有关更多信息，请参阅 [Qualcomm Linux 编译指南](https://docs.qualcomm.com/bundle/publicresource/topics/80-70023-254/flash_images.html#move-to-edl-mode)。

## 已知限制

- Qualcomm 支持 APSS Linux 内核空间的 OpenOCD 调试。
- 目前，仅支持基于 QCS6490、IQ-9100/IQ-9075 芯片组的设备。
- 在控制台 shell 或 adb 中手动启用 EUD 之前，不支持在启动期间进行内核调试。
- 启用 EUD 时，系统会禁用 USB 主机模式。

## 设置 Ubuntu 主机

要设置 Ubuntu 主机，请执行以下操作：

1. 安装以下先决条件包：

sudo apt-get install libusb-1.0
        
        sudo apt-get install libftdi-dev
        
        sudo apt-get install libftdi1
        
        sudo apt-get install pkg-config
        
        sudo apt-get install build-essential
        
        sudo apt-get install libtool-bin
        
        sudo apt-get install g++
        Copy to clipboard
2. 确保 `autoconf` 的版本至少为 v2.71。

autoconf --version
        Copy to clipboard

## 下载 OpenOCD

要下载支持 Qualcomm 芯片组的 OpenOCD，请运行以下命令：

git clone https://git.codelinaro.org/clo/la/openocd-org/openocd.git -b qcom_changes
    
    cd openocd
    
    git submodule update --init --recursive
    Copy to clipboard

## 编译 OpenOCD

下载源代码后，执行以下操作来编译 OpenOCD：

1. 转到 OpenOCD 目录。

cd openocd
        Copy to clipboard
2. 生成配置脚本。

./bootstrap
        Copy to clipboard
3. 配置编译。此步骤会根据您提供的选项生成编译 OpenOCD 所需的 make 文件。在以下命令中，系统会纳入 EUD 以进行调试。

> 
> 
> ./configure --disable-werror --enable-eud --disable-internal-libjaylink --disable-jlink --disable-ftdi --disable-dummy --disable-rshim --disable-stlink --disable-ti-icdi --disable-ulink --disable-usb-blaster-2 --disable-ft232r --disable-vsllink --disable-xds110 --disable-cmsis-dap-v2 --disable-osbdm --disable-opendous --disable-aice --disable-usbprog --disable-rlink --disable-armjtagew --disable-cmsis-dap --disable-nulink --disable-kitprog --disable-usb-blaster --disable-presto --disable-openjtag --disable-parport --disable-parport-giveio --disable-jtag_vpi --disable-jtag_dpi --disable-amtjtagaccel --disable-zy1000-master --disable-zy1000 --disable-ioutil --disable-bcm2835gpio --disable-imx_gpio --disable-ep93xx --disable-at91rm9200 --disable-gw16012 --disable-oocd_trace --disable-buspirate --disable-sysfsgpio --disable-xlnx-pcie-xvc --disable-minidriver-dummy --disable-remote-bitbang --disable-parport-ppdev --disable-esp-usb-jtag
>         Copy to clipboard

Note

禁用 Qualcomm Linux 中不需要的适配器。

有关编译配置的更多信息，请运行 `./configure -help` 命令。
4. 编译源代码。

make
        Copy to clipboard
5. 清理编译版本。

make clean
        Copy to clipboard

编译成功后，会在 `openocd/src/` 目录中生成 OpenOCD 二进制文件。

## 设置命令行调试器

Qualcomm 支持在主机上使用 LLDB 和 GDB 调试器。有关设置的更多信息，请参阅以下内容：

- LLDB

> 
> 
> 有关安装，请转到 [LLVM packages](https://apt.llvm.org/)。要自动安装版本 19 的脚本，请参阅以下示例：
> 
> 
> /# wget https://apt.llvm.org/llvm.sh
>         /# chmod +x llvm.sh
>         /# sudo ./llvm.sh 19
>         /# export PATH=/usr/lib/llvm-19/bin:$PATH
>         /# lldb -version
>         lldb version 19.1.7
>         Copy to clipboard
- GDB

> 
> 
> 有关安装，请转到 [GNU toolchain downloads](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads)。要安装版本 14.2，请参阅以下示例：
> 
> 
> /# wget https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-elf.tar.xz
>         /# tar -xf arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-elf.tar.xz
>         Copy to clipboard

以下是可选命令：

/# sudo mv arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-elf /opt/
    
    /# export PATH=/opt/arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-elf/bin:$PATH
    
    /# aarch64-none-elf-gdb -version
    Copy to clipboard

示例输出：

GNU gdb (Arm GNU Toolchain **14.2.Rel1** (Build arm-14.52)) 15.2.90.20241130-git
    
    Copyright (C) 2024 Free Software Foundation, Inc.
    
    License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
    
    This is free software: you are free to change and redistribute it.
    
    There is NO WARRANTY, to the extent permitted by law.
    Copy to clipboard

## 设置 APPS 内核编译

Qualcomm 建议使用 `export DEBUG_BUILD=1` 命令进行调试编译。有关更多信息，请参阅 [Qualcomm Linux 编译指南](https://docs.qualcomm.com/bundle/publicresource/topics/80-70023-254/build_landing_page.html#move-to-edl-mode)和 [Qualcomm Linux 内核指南](https://docs.qualcomm.com/bundle/publicresource/topics/80-70023-3/kernel_landing_page.html)。

在调试编译版本中进行以下更改：

**禁用 SELinux**

> 
> 
> 打开 `<root>/layers/meta-qti-bsp/recipes-kernel/linux/linux-qcom-custom_6.6.bb` 文件并禁用 SELinux，如下所示：
> 
> 
> 
> > 
> > 
> > # Enable selinux support
> >     # SELINUX_CFG = "${@oe.utils.vartrue('DEBUG_BUILD', 'selinux_debug.cfg', 'selinux.cfg', d)}"
> >     # KERNEL_CONFIG_FRAGMENTS:append = " ${@bb.utils.contains('DISTRO_FEATURES', 'selinux', '${WORKDIR}/${SELINUX_CFG}', '', d)}"
> >     Copy to clipboard
> 
> 
> 
> 打开 `<root>/sources/kernel/kernel_platform/kernel/arch/arm64/configs/qcom_defconfig` 文件并修改如下：
> 
> 
> 
> > 
> > 
> > # CONFIG_MODULE_SIG=y
> >     # CONFIG_MODULE_SIG_FORCE=y
> >     # CONFIG_SLAB_FREELIST_RANDOM=y
> >     # CONFIG_SLAB_FREELIST_HARDENED=y
> >     # CONFIG_SHUFFLE_PAGE_ALLOCATOR=y
> >     # CONFIG_SECURITY=y
> >     # CONFIG_SECURITY_NETWORK=y
> >     # CONFIG_HARDENED_USERCOPY=y
> >     # CONFIG_FORTIFY_SOURCE=y
> >     # CONFIG_SECURITY_SELINUX=y
> >     Copy to clipboard

## 设置目标设备

要调试应用程序，需要从目标设备中删除 modem 二进制文件。要在调试 OpenOCD 之前移除 modem 二进制文件，请运行以下示例命令：

1. 对于 IQ-9075 平台，使用 DIP 开关设置（SW3-3 开关为低电平）禁用硬件看门狗。
2. 在主机上启用 EUD。启用 EUD 时，主机无需任何额外的驱动程序即可检测 EUD 目标设备。
3. 使用控制台 shell 或 adb 在目标设备上启用 EUD。

    - 对于 QCS6490，运行以下命令：

> 
> 
> /# echo 1 >/sys/bus/platform/devices/88e0000.eud/enable
>             Copy to clipboard
    - 对于 IQ-9100/IQ-9075，运行以下命令：

> 
> 
> /# echo 1 >/sys/bus/platform/devices/88e1000.eud/enable
>             Copy to clipboard

Note

    - 启用 EUD 后，USB 主机模式将不起作用，因为它不会从端口接口上的 glink 接收到角色信息。
    - 每次系统重启时，都需要使用这些 adb 命令启用 EUD。
4. 禁用 CPU 1-7。仅启用 CPU-0 并运行以下命令：

adb shell
        echo 0 > /sys/devices/system/cpu/cpu1/online
        echo 0 > /sys/devices/system/cpu/cpu2/online
        echo 0 > /sys/devices/system/cpu/cpu3/online
        echo 0 > /sys/devices/system/cpu/cpu4/online
        echo 0 > /sys/devices/system/cpu/cpu5/online
        echo 0 > /sys/devices/system/cpu/cpu6/online
        echo 0 > /sys/devices/system/cpu/cpu7/online
        Copy to clipboard

要禁用核心 0 的 LPM，请运行以下命令：

> 
> 
> /# echo 1 > /sys/devices/system/cpu/cpu0/cpuidle/state0/disable
>     
>     /# echo 1 > /sys/devices/system/cpu/cpu0/cpuidle/state1/disable
>     
>     /# echo 1 > /sys/devices/system/cpu/cpu0/cpuidle/state2/disable
>     Copy to clipboard

要使用 UART 登录，请运行以下命令：

> 
> 
> /# mount -o remount,rw /
>     /# cd /lib/firmware/qcom/qcm6490/ && rm -rf modem*
>     /# cd /lib/firmware/qcom/qcm6490/ && ls
>     /# cd /lib/firmware/qcom/qcs6490/ && rm -rf modem*
>     /# cd /lib/firmware/qcom/qcs6490/ && ls
>     /# reboot
>     Copy to clipboard

## 调试 Linux 内核

完成设置后，即可调试 Linux 内核。以下是 QCS6490（Qualcomm Dragonwing™ RB3 Gen 2 开发套件）目标设备的示例调试命令：

1. 使用修改后的 APPS 内核设置刷写设备。关于更多详细信息，请参阅[设置 APPS 内核编译](https://docs.qualcomm.com/doc/80-70023-12SC/topic/debug_using_openocd.html#section-pqr-xyz)。
2. 使用 USB Type-C 线缆将 Qualcomm Dragonwing™ RB3 Gen 2 设备连接到主机。
3. 使用控制台 shell 或 adb 在目标上启用 EUD。

    启用 9501 EUD 端口后，主机上的预期输出如下：

/#lsusb

Bus 001 Device 038: ID 05c6:9501 Qualcomm, Inc.

Bus 001 Device 037: ID 05c6:9500 Qualcomm, Inc.
4. 在主机上运行 OpenOCD。

cd openocd/src
        Copy to clipboard

    - 对于 QCS6490（Dragonwing™ RB3 Gen 2 开发套件），运行以下命令：

> 
> 
> sudo ./openocd -f ../tcl/interface/eud.cfg -f ../tcl/target/qualcomm/qcs6400.cfg
>             Copy to clipboard
    - 对于 IQ-9100，运行以下命令：

> 
> 
> sudo ./openocd -f ../tcl/interface/eud.cfg -f ../tcl/target/qualcomm/qcs9100.cfg
>             Copy to clipboard

    以下是 QCS6490 的示例输出：

Open On-Chip Debugger 0.12.0-01020-g3124da65c (2025-03-21-15:28)
        Licensed under GNU GPL v2
        For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
        Info : only one transport option; autoselect 'swd'
        Warn : Transport "swd" was already selected
        force hard breakpoints
        Info : Listening on port 6666 for tcl connections
        Info : Listening on port 4444 for telnet connections
        Info : Using EUD 2.1.7
        Error: Translation from adapter speed to khz not implemented
        Info : adapter-specific clock speed value 6
        Info : SWD DPIDR 0x5ba02477
        Info : QCS6490.cpu0: hardware has 6 breakpoints, 4 watchpoints
        Info : starting gdb server for QCS6490.cpu0 on 3333
        Info : Listening on port 3333 for gdb connections
        Info : QCS6490.cpu0 cluster 0 core 0 multi core
        QCS6490.cpu0 halted in AArch64 state due to debug-request, current mode: EL0T
        cpsr: 0x60001000 pc: 0xffffffc080010c00
        MMU: enabled, D-Cache: enabled, I-Cache: enabled
        Copy to clipboard

Note

如果 OpenOCD 连接失败，请尝试重新运行 OpenOCD 命令。
5. LLDB 和 GDB 两种调试器支持主机。有关更多信息，请参见以下内容：

    - 使用 LLDB

> 
> 
> 1. 打开新终端并使用以下命令运行 LLDB：
> 
> 
> /# lldb
>                 Copy to clipboard
>         2. 要加载应用程序符号，请运行以下命令：
> 
> 
> (lldb) target create <vmlinux_path>
>                 Copy to clipboard
>         3. 要映射源代码，请运行以下命令：
> 
> 
> (lldb) settings set target.source-map <build_path_from_vmlinux> <local_path_to_source_code>
>                 Copy to clipboard
> 
> 
>             在此命令中，`<build_path_from_vmlinux>` 是 `/usr/src/kernel/<SUFFIX>`，其中 `SUFFIX` 是内核中的实际代码目录。例如，`/usr/src/kernel/drivers/usb/gadget`。
>         4. 要调试内核模块，请执行以下操作（如果不需要，请忽略此指令）：
> 
> 
> (lldb) target modules add <path_to_.ko>
>                 (lldb) target modules load --file <path_to_.ko> --slide <.ko_start_address>
>                 Copy to clipboard
> 
> 
>             要直接获取 `<.ko_start_address>` 字符串，请运行以下命令：
> 
> 
> echo 0 > /proc/sys/kernel/kptr_restrict
>                 cat /proc/modules
>                 Copy to clipboard
> 
> 
>             要映射源代码，请运行以下命令：
> 
> 
> (lldb) settings set target.source-map <build_path_from_.ko> <local_path_to_source_code>
>                 Copy to clipboard
>         5. 连接到 OpenOCD。
> 
> 
> (lldb) gdb-remote 3333
>                 Copy to clipboard
>         6. 有关更多 LLDB 命令，请参阅 [Tutorial](https://lldb.llvm.org/use/tutorial.html)。
    - 使用 GDB

> 
> 
> 1. 打开新终端并使用以下命令运行 GDB：
> 
> 
> /# aarch64_none_elf_gdb
>                 Copy to clipboard
>         2. 要加载应用程序符号，请运行以下命令：
> 
> 
> (gdb) add-symbol-file <vmlinux_path>
>                 Copy to clipboard
>         3. 要映射源代码，请运行以下命令：
> 
> 
> (gdb) set substitute-path <build_path_from_vmlinux> <local_path_to_source_code>
>                 Copy to clipboard
> 
> 
>             在此命令中，`<build_path_from_vmlinux>` 是 `/usr/src/kernel/<SUFFIX>`，其中 `SUFFIX` 是内核中的实际代码目录。例如 `/usr/src/kernel/drivers/usb/gadget`。
>         4. 要调试内核模块，请执行以下操作（如果不需要，请忽略此指令）：
> 
> 
> (gdb) add-symbol-file <path_to_.ko> -o <.ko_start_address>
>                 Copy to clipboard
> 
> 
>             要直接获取 `<.ko_start_address>` 字符串，请运行以下命令：
> 
> 
> echo 0 > /proc/sys/kernel/kptr_restrict
>                 cat /proc/modules
>                 Copy to clipboard
> 
> 
>             要映射源代码，请运行以下命令：
> 
> 
> (gdb) set substitute-path <build_path_from_.ko> <local_path_to_source_code>
>                 Copy to clipboard
>         5. 连接到 OpenOCD。
> 
> 
> (gdb) target remote localhost:3333
>                 Copy to clipboard
>         6. 有关更多 GDB 命令，请参阅 [GDB command reference](https://visualgdb.com/gdbreference/commands/)。

Last Published: Jan 20, 2026

[Previous Topic
使用 Crash utility 工具进行调试](https://docs.qualcomm.com/bundle/publicresource/80-70023-12SC/topics/crash_utility.md) [Next Topic
调试常见系统问题](https://docs.qualcomm.com/bundle/publicresource/80-70023-12SC/topics/general_system_debugging.md)