From bf15c6c59fd225b15eb0487b230bf069d80ab970 Mon Sep 17 00:00:00 2001
From: cms19859230182-lang
 <276597748+cms19859230182-lang@users.noreply.github.com>
Date: Tue, 20 Oct 2026 02:39:50 +0800
Subject: [PATCH 1/2] [bsp][allwinner][d1s] add qemu-d1s.sh to run this BSP on
 the d1s QEMU machine

Add a small launcher that boots rtthread.bin of this BSP on the d1s
machine from d1s-qemu (a QEMU 10.1.2 patch series), using sbi.bin and
u-boot.dtb from this directory and UART0 as console, and document it in
README.md. No source or configuration of the BSP is changed.
---
 bsp/allwinner/d1s/README.md   | 28 ++++++++++++++++++++++++++++
 bsp/allwinner/d1s/qemu-d1s.sh | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100755 bsp/allwinner/d1s/qemu-d1s.sh

diff --git a/bsp/allwinner/d1s/README.md b/bsp/allwinner/d1s/README.md
index ab1aa971f7af..48c1d262bd3c 100644
--- a/bsp/allwinner/d1s/README.md
+++ b/bsp/allwinner/d1s/README.md
@@ -2,3 +2,31 @@
 
 * [基于柿饼M7运行 RT-Smart](./README-M7.md)
 * [基于麻雀MQ运行 RT-Smart](./README-MQ.md)
+* [在 QEMU 中运行（Run on QEMU）](#在-qemu-中运行run-on-qemu)
+
+## 在 QEMU 中运行（Run on QEMU）
+
+没有板子时，可以用 [d1s-qemu](https://github.com/cms19859230182-lang/d1s-qemu)
+提供的 QEMU `d1s` 机型启动本 BSP 编出的 `rtthread.bin`：
+
+```sh
+# 1. 编译 d1s-qemu（见该仓库 README）
+git clone https://github.com/cms19859230182-lang/d1s-qemu
+cd d1s-qemu && scripts/fetch-qemu.sh && scripts/apply-patches.sh && scripts/build.sh
+
+# 2. 在本目录编译 RT-Thread（工具链见 README-M7.md；也可用环境变量指定，例如
+#    RTT_EXEC_PATH=/path/to/toolchain/bin RTT_CC_PREFIX=riscv64-linux-musleabi-）
+scons
+
+# 3. 启动（UART0 接到终端）
+D1S_QEMU_DIR=/path/to/d1s-qemu ./qemu-d1s.sh
+```
+
+当前状态：默认配置下能打印 RT-Thread Smart 启动信息，完成 SD/MMC（SMHC0/SMHC1，
+`run.sh` 自动挂空白镜像）初始化并进入 `msh />`；空白镜像没有文件系统，根文件系统挂载失败属正常现象。
+
+Without a board, `rtthread.bin` from this BSP can be started on the `d1s`
+machine of d1s-qemu with `D1S_QEMU_DIR=/path/to/d1s-qemu ./qemu-d1s.sh`.
+The RT-Thread Smart banner is printed, SD/MMC (SMHC0/SMHC1, blank images
+attached by run.sh) is probed and the boot reaches `msh />`. Mounting the root
+file system fails on the blank images, which is expected.
diff --git a/bsp/allwinner/d1s/qemu-d1s.sh b/bsp/allwinner/d1s/qemu-d1s.sh
new file mode 100755
index 000000000000..8bf70384d1d2
--- /dev/null
+++ b/bsp/allwinner/d1s/qemu-d1s.sh
@@ -0,0 +1,32 @@
+#!/bin/sh
+#
+# Copyright (c) 2006-2026, RT-Thread Development Team
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Boot this BSP's rtthread.bin on the d1s QEMU machine from
+# https://github.com/cms19859230182-lang/d1s-qemu
+#
+# Usage (after building d1s-qemu and running scons in this directory):
+#   D1S_QEMU_DIR=/path/to/d1s-qemu ./qemu-d1s.sh [extra run.sh options]
+#
+# sbi.bin and u-boot.dtb are taken from this directory; the console of
+# this BSP is UART0, so it is connected to the terminal.
+
+set -eu
+
+here=$(cd "$(dirname "$0")" && pwd)
+dir=${D1S_QEMU_DIR:-}
+
+if [ -z "$dir" ] || [ ! -x "$dir/run.sh" ]; then
+    echo "please set D1S_QEMU_DIR to a built d1s-qemu checkout" >&2
+    echo "see https://github.com/cms19859230182-lang/d1s-qemu" >&2
+    exit 1
+fi
+
+if [ ! -f "$here/rtthread.bin" ]; then
+    echo "$here/rtthread.bin not found, run scons first" >&2
+    exit 1
+fi
+
+exec "$dir/run.sh" "$here/rtthread.bin" --bsp "$here" --console uart0 "$@"

From 3242adc8b9909f969dfbc7491b7b822e42ad1d0b Mon Sep 17 00:00:00 2001
From: cms19859230182-lang
 <276597748+cms19859230182-lang@users.noreply.github.com>
Date: Wed, 21 Oct 2026 18:23:00 +0800
Subject: [PATCH 2/2] [bsp][allwinner][d1s] add target-qemu/ and wrap
 qemu-d1s.sh

Move the QEMU runner under target-qemu/ with an AI-oriented README
and QEMU_TIMEOUT support. Keep qemu-d1s.sh as a thin compatibility
wrapper. Point the BSP README QEMU section at target-qemu/.
---
 bsp/allwinner/d1s/README.md               |  2 +
 bsp/allwinner/d1s/qemu-d1s.sh             | 33 +----------
 bsp/allwinner/d1s/target-qemu/README.md   | 68 +++++++++++++++++++++++
 bsp/allwinner/d1s/target-qemu/run-qemu.sh | 44 +++++++++++++++
 4 files changed, 116 insertions(+), 31 deletions(-)
 create mode 100644 bsp/allwinner/d1s/target-qemu/README.md
 create mode 100755 bsp/allwinner/d1s/target-qemu/run-qemu.sh

diff --git a/bsp/allwinner/d1s/README.md b/bsp/allwinner/d1s/README.md
index 48c1d262bd3c..b5ca45ef6216 100644
--- a/bsp/allwinner/d1s/README.md
+++ b/bsp/allwinner/d1s/README.md
@@ -24,9 +24,11 @@ D1S_QEMU_DIR=/path/to/d1s-qemu ./qemu-d1s.sh
 
 当前状态：默认配置下能打印 RT-Thread Smart 启动信息，完成 SD/MMC（SMHC0/SMHC1，
 `run.sh` 自动挂空白镜像）初始化并进入 `msh />`；空白镜像没有文件系统，根文件系统挂载失败属正常现象。
+更完整的步骤与常见失败见 [target-qemu/](./target-qemu/)（`run-qemu.sh` + README）。
 
 Without a board, `rtthread.bin` from this BSP can be started on the `d1s`
 machine of d1s-qemu with `D1S_QEMU_DIR=/path/to/d1s-qemu ./qemu-d1s.sh`.
 The RT-Thread Smart banner is printed, SD/MMC (SMHC0/SMHC1, blank images
 attached by run.sh) is probed and the boot reaches `msh />`. Mounting the root
 file system fails on the blank images, which is expected.
+See [target-qemu/](./target-qemu/) for the fuller guide (`run-qemu.sh` + README).
diff --git a/bsp/allwinner/d1s/qemu-d1s.sh b/bsp/allwinner/d1s/qemu-d1s.sh
index 8bf70384d1d2..7848419feb98 100755
--- a/bsp/allwinner/d1s/qemu-d1s.sh
+++ b/bsp/allwinner/d1s/qemu-d1s.sh
@@ -1,32 +1,3 @@
 #!/bin/sh
-#
-# Copyright (c) 2006-2026, RT-Thread Development Team
-#
-# SPDX-License-Identifier: Apache-2.0
-#
-# Boot this BSP's rtthread.bin on the d1s QEMU machine from
-# https://github.com/cms19859230182-lang/d1s-qemu
-#
-# Usage (after building d1s-qemu and running scons in this directory):
-#   D1S_QEMU_DIR=/path/to/d1s-qemu ./qemu-d1s.sh [extra run.sh options]
-#
-# sbi.bin and u-boot.dtb are taken from this directory; the console of
-# this BSP is UART0, so it is connected to the terminal.
-
-set -eu
-
-here=$(cd "$(dirname "$0")" && pwd)
-dir=${D1S_QEMU_DIR:-}
-
-if [ -z "$dir" ] || [ ! -x "$dir/run.sh" ]; then
-    echo "please set D1S_QEMU_DIR to a built d1s-qemu checkout" >&2
-    echo "see https://github.com/cms19859230182-lang/d1s-qemu" >&2
-    exit 1
-fi
-
-if [ ! -f "$here/rtthread.bin" ]; then
-    echo "$here/rtthread.bin not found, run scons first" >&2
-    exit 1
-fi
-
-exec "$dir/run.sh" "$here/rtthread.bin" --bsp "$here" --console uart0 "$@"
+# Kept for compatibility; see target-qemu/run-qemu.sh
+exec "$(cd "$(dirname "$0")" && pwd)/target-qemu/run-qemu.sh" "$@"
diff --git a/bsp/allwinner/d1s/target-qemu/README.md b/bsp/allwinner/d1s/target-qemu/README.md
new file mode 100644
index 000000000000..f32387f67a2a
--- /dev/null
+++ b/bsp/allwinner/d1s/target-qemu/README.md
@@ -0,0 +1,68 @@
+# D1s on QEMU (for humans and AI agents)
+
+This directory boots the `bsp/allwinner/d1s` image on the d1s QEMU machine
+(<https://github.com/cms19859230182-lang/d1s-qemu>). It's written as a short
+step-by-step guide that an AI coding agent can follow without guessing.
+
+## 1. Prepare the QEMU environment
+
+```sh
+git clone https://github.com/cms19859230182-lang/d1s-qemu
+cd d1s-qemu
+# follow its README to build; the result must provide an executable ./run.sh
+export D1S_QEMU_DIR=$PWD
+```
+
+Check: `test -x "$D1S_QEMU_DIR/run.sh" && echo ok`.
+
+## 2. Build the BSP
+
+```sh
+cd rt-thread/bsp/allwinner/d1s
+export RTT_EXEC_PATH=/path/to/riscv64-unknown-elf/bin   # RISC-V toolchain
+scons -j$(nproc)
+```
+
+Check: `rtthread.bin` exists in `bsp/allwinner/d1s/`. `sbi.bin` and
+`u-boot.dtb` are already in the BSP directory, and `run.sh` uses them.
+
+## 3. Run
+
+Interactive:
+
+```sh
+./target-qemu/run-qemu.sh
+```
+
+Non-interactive smoke test (recommended for agents, always set a timeout):
+
+```sh
+QEMU_TIMEOUT=30 ./target-qemu/run-qemu.sh < /dev/null > qemu.log 2>&1 || true
+```
+
+Extra arguments are passed through to d1s-qemu's `run.sh`.
+
+## 4. Pass/fail criteria
+
+- **Pass:** `qemu.log` contains the RT-Thread banner (` \ | /`) and the
+  `msh />` prompt.
+- Optional interactive check: at `msh />` run `list_thread` and `version`.
+- Exit code 124 just means the timeout was reached. That's normal for a
+  smoke test, so judge the run by the log, not the exit code.
+
+```sh
+grep -q 'msh />' qemu.log && echo PASS || echo FAIL
+```
+
+## 5. Common failures
+
+| Symptom | Cause / fix |
+|---|---|
+| `please set D1S_QEMU_DIR ...` | Export `D1S_QEMU_DIR` pointing at a *built* d1s-qemu checkout. |
+| `rtthread.bin not found` | Run `scons` in `bsp/allwinner/d1s` first. |
+| No output at all | Wrong console: this BSP uses UART0, and the script already passes `--console uart0`. Also check that the build succeeded and isn't stale. |
+| Hangs after OpenSBI banner | `sbi.bin` or `u-boot.dtb` is missing or mismatched in the BSP directory, or the image was linked for the wrong address. |
+| Agent session hangs | You forgot `QEMU_TIMEOUT`. Always set it when running non-interactively. |
+
+The old entry point `bsp/allwinner/d1s/qemu-d1s.sh` still works as a thin
+wrapper around this script.
diff --git a/bsp/allwinner/d1s/target-qemu/run-qemu.sh b/bsp/allwinner/d1s/target-qemu/run-qemu.sh
new file mode 100755
index 000000000000..541c065f359b
--- /dev/null
+++ b/bsp/allwinner/d1s/target-qemu/run-qemu.sh
@@ -0,0 +1,44 @@
+#!/bin/sh
+#
+# Copyright (c) 2006-2026, RT-Thread Development Team
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Boot this BSP's rtthread.bin on the d1s QEMU machine from
+# https://github.com/cms19859230182-lang/d1s-qemu
+#
+# Usage (after building d1s-qemu and running scons in bsp/allwinner/d1s):
+#   D1S_QEMU_DIR=/path/to/d1s-qemu ./target-qemu/run-qemu.sh [run.sh options]
+#
+# Environment:
+#   D1S_QEMU_DIR   built d1s-qemu checkout (must contain executable run.sh)
+#   QEMU_TIMEOUT   seconds before QEMU is killed (default 0 = no limit,
+#                  set e.g. 30 for CI / AI smoke tests)
+#
+# sbi.bin and u-boot.dtb are taken from the BSP directory; the console of
+# this BSP is UART0, so it is connected to the terminal.
+
+set -eu
+
+here=$(cd "$(dirname "$0")" && pwd)
+bsp=$(cd "$here/.." && pwd)
+dir=${D1S_QEMU_DIR:-}
+tmo=${QEMU_TIMEOUT:-0}
+
+if [ -z "$dir" ] || [ ! -x "$dir/run.sh" ]; then
+    echo "please set D1S_QEMU_DIR to a built d1s-qemu checkout" >&2
+    echo "see https://github.com/cms19859230182-lang/d1s-qemu" >&2
+    exit 1
+fi
+
+if [ ! -f "$bsp/rtthread.bin" ]; then
+    echo "$bsp/rtthread.bin not found, run scons in $bsp first" >&2
+    exit 1
+fi
+
+if [ "$tmo" -gt 0 ] 2>/dev/null; then
+    exec timeout --foreground "$tmo" \
+        "$dir/run.sh" "$bsp/rtthread.bin" --bsp "$bsp" --console uart0 "$@"
+fi
+
+exec "$dir/run.sh" "$bsp/rtthread.bin" --bsp "$bsp" --console uart0 "$@"