docs: qemu board runner table shows debug even when only west debugserver is supported #104438
Description
Describe the bug
The board-level "Programming and Debugging" table in the docs is confusing for QEMU boards.
For example, the page shows a table with a debug column for a QEMU board (shown in the screenshot for qemu_cortex_m3). I initially interpreted this as meaning I could run:
west debug
But in practice, QEMU only supports:
west debugserver
and not west debug (at least for this case).
This makes the table misleading because it suggests west debug support when the practical workflow is debugserver only.
Regression
- This is a regression.
Steps to reproduce
- Open the board documentation page that includes the "Programming and Debugging" table (example:
qemu_cortex_m3shown in screenshot). - See that the table includes a
debugcolumn. - Try
west debugfor that board. - Observe that the board supports
west debugserverworkflow, notwest debug.
Relevant log output
❯ git describe
v4.3.0-6701-g28793caf8272
❯ rm -rf build && west build -b qemu_cortex_m3 -t debug zephyr/samples/hello_world
-- west build: generating a build system
Loading Zephyr default modules (Zephyr base).
-- Application: /home/yashi/src/zephyr-project/zephyr/samples/hello_world
-- CMake version: 4.2.3
-- Found Python3: /home/yashi/src/zephyr-project/.venv/bin/python (found suitable version "3.13.12", minimum required is "3.10") found components: Interpreter
-- Cache files will be written to: /home/yashi/.cache/zephyr
-- Zephyr version: 4.3.99 (/home/yashi/src/zephyr-project/zephyr)
-- Found west (found suitable version "1.5.0", minimum required is "0.14.0")
-- Board: qemu_cortex_m3, qualifiers: ti_lm3s6965
-- ZEPHYR_TOOLCHAIN_VARIANT not set, trying to locate Zephyr SDK
-- Found host-tools: zephyr 0.17.4 (/home/yashi/zephyr-sdk-0.17.4)
-- Found toolchain: zephyr 0.17.4 (/home/yashi/zephyr-sdk-0.17.4)
-- Found Dtc: /home/yashi/zephyr-sdk-0.17.4/sysroots/x86_64-pokysdk-linux/usr/bin/dtc (found suitable version "1.7.0", minimum required is "1.4.6")
-- Found BOARD.dts: /home/yashi/src/zephyr-project/zephyr/boards/qemu/cortex_m3/qemu_cortex_m3.dts
-- Generated zephyr.dts: /home/yashi/src/zephyr-project/build/zephyr/zephyr.dts
-- Generated pickled edt: /home/yashi/src/zephyr-project/build/zephyr/edt.pickle
-- Generated devicetree_generated.h: /home/yashi/src/zephyr-project/build/zephyr/include/generated/zephyr/devicetree_generated.h
Parsing /home/yashi/src/zephyr-project/zephyr/Kconfig
Loaded configuration '/home/yashi/src/zephyr-project/zephyr/boards/qemu/cortex_m3/qemu_cortex_m3_defconfig'
Merged configuration '/home/yashi/src/zephyr-project/zephyr/samples/hello_world/prj.conf'
Configuration saved to '/home/yashi/src/zephyr-project/build/zephyr/.config'
Kconfig header saved to '/home/yashi/src/zephyr-project/build/zephyr/include/generated/zephyr/autoconf.h'
-- Found GnuLd: /home/yashi/zephyr-sdk-0.17.4/arm-zephyr-eabi/arm-zephyr-eabi/bin/ld.bfd (found version "2.38")
-- The C compiler identification is GNU 12.2.0
-- The CXX compiler identification is GNU 12.2.0
-- The ASM compiler identification is GNU
-- Found assembler: /home/yashi/zephyr-sdk-0.17.4/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
-- Using ccache: /usr/bin/ccache
-- Found gen_kobject_list: /home/yashi/src/zephyr-project/zephyr/scripts/build/gen_kobject_list.py
-- Configuring done (4.0s)
-- Generating done (0.1s)
-- Build files have been written to: /home/yashi/src/zephyr-project/build
-- west build: running target debug
[0/1] Debugging qemu_cortex_m3
WARNING: CMake debug target is deprecated, call west directly instead
-- west debug: rebuilding
[1/127] Preparing syscall dependency handling
[3/127] Generating include/generated/zephyr/version.h
-- Zephyr version: 4.3.99 (/home/yashi/src/zephyr-project/zephyr), build: v4.3.0-6701-g28793caf8272
[127/127] Linking C executable zephyr/zephyr.elf
Memory region Used Size Region Size %age Used
FLASH: 9440 B 256 KB 3.60%
RAM: 4104 B 64 KB 6.26%
IDT_LIST: 0 GB 32 KB 0.00%
Generating files from /home/yashi/src/zephyr-project/build/zephyr/zephyr.elf for board: qemu_cortex_m3/ti_lm3s6965
FATAL ERROR: no runners.yaml found in /home/yashi/src/zephyr-project/build/zephyr. Either board qemu_cortex_m3/ti_lm3s6965 doesn't support west flash/debug/simulate, or a pristine build is needed.
FAILED: [code=1] zephyr/cmake/flash/CMakeFiles/debug /home/yashi/src/zephyr-project/build/zephyr/cmake/flash/CMakeFiles/debug
cd /home/yashi/src/zephyr-project/build && cmake -E echo WARNING:\ CMake\ debug\ target\ is\ deprecated,\ call\ west\ directly\ instead && /usr/bin/cmake -DTARGET=debug -DDEPENDENCIES="" -P /home/yashi/src/zephyr-project/zephyr/cmake/flash/check_runner_dependencies.cmake && /usr/bin/cmake -E env ZEPHYR_BASE=/home/yashi/src/zephyr-project/zephyr /home/yashi/src/zephyr-project/.venv/bin/python -m west debug
ninja: build stopped: subcommand failed.
FATAL ERROR: command exited with status 1: /usr/bin/cmake --build /home/yashi/src/zephyr-project/build --target debugImpact
Annoyance – Minor irritation; no significant impact on usability or functionality.
Environment
No response
Additional Context
I suspect the table may be generated from runner metadata (possibly board_runner_info), but I am not sure how the command/support matrix is currently derived from doc/_extensions/.
If the table is auto-generated, it may need to distinguish between:
debugdebugserverdebugserver_<emu>
instead of collapsing them in a way that implies broader support than exists.