docs: add Radxa SBC Device Tree Overlay guide by xzl01 · Pull Request #1621 · radxa-docs/docs

xzl01 · 2026-04-07T03:24:27Z

新增 Radxa SBC 添加 Device Tree Overlay 的完整指南，包含两种方式：

方式一：克隆 radxa-overlays → 写 DTS → make deb → rsetup（适合提交 PR）
方式二：本地编译 → rsetup Install 3rd party overlay（适合自己用）

包含 metadata 字段说明、常用操作示例（启用节点/修改属性/添加子节点）、完整 SPI1 示例、rsetup 常用命令。

- Add two methods: local compile and PR to radxa-overlays - Includes metadata field descriptions and common overlay operations - Complete SPI1 example and rsetup commands

Copilot

Pull request overview

新增一篇 Radxa SBC 的 Device Tree Overlay（DTO）完整操作指南，并在 Dragon Q6A 下载页补充百度网盘下载入口，方便用户获取最新镜像与参考 overlay 配置流程。

Changes:

新增 Radxa SBC 添加 Device Tree Overlay 指南文档，覆盖两种使用路径（提交 PR / 本地加载）。
增加 metadata 字段说明与常见 overlay 操作示例，并提供 SPI1 完整示例。
在 Dragon Q6A 下载页新增百度网盘下载说明与链接。

Reviewed changes

Copilot reviewed 1 out of 1 changed files in this pull request and generated 9 comments.

File	Description
docs/radxa-dto-guide.md	新增 DTO 操作指南（含构建、rsetup 使用、示例与附录命令）。
docs/dragon/q6a/download.md	增加百度网盘下载入口与版本说明，便于用户获取镜像。

Copilot · 2026-04-07T03:27:50Z

@@ -0,0 +1,284 @@
+---
+title: Radxa SBC 添加 Device Tree Overlay


该文档的 front matter 缺少 sidebar_position，会被 scripts/agent-doc-lint.sh 判定为失败（要求每个非 _*.mdx/wrapper 文档必须包含 sidebar_position）。建议在 front matter 中补充 sidebar_position（并可选补充 slug/description）。

Suggested change

title: Radxa SBC 添加 Device Tree Overlay

title: Radxa SBC 添加 Device Tree Overlay

sidebar_position: 1

已修复：在 front matter 中添加了 sidebar_position: 1

Copilot · 2026-04-07T03:27:50Z

+
+Overlay 文件按 SoC 平台分类存放：
+
+```


这里的代码块使用了未标注语言的围栏（```），会触发 agent-doc-lint 的 “unlabeled code fence” 校验失败。请为该代码块补充语言标注（例如 `text`/`console`）。

Suggested change

```

```text

已修复：将该代码块标注为 ```text

Copilot · 2026-04-07T03:27:50Z

+
+构建完成后会生成 `.deb` 包，位于上级目录：
+
+```


这里的代码块使用了未标注语言的围栏（```），会触发 agent-doc-lint 的 “unlabeled code fence” 校验失败。请为该代码块补充语言标注（例如 `text`/`console`）。

Suggested change

```

```text

已修复：将该输出块标注为 ```text

Copilot · 2026-04-07T03:27:51Z

+
+进入交互菜单：
+
+```


这里的代码块使用了未标注语言的围栏（```），会触发 agent-doc-lint 的 “unlabeled code fence” 校验失败。请为该代码块补充语言标注（例如 `text`/`console`）。

Suggested change

```

```text

已修复：将该代码块标注为 ```text

Copilot · 2026-04-07T03:27:51Z

+
+进入菜单：
+
+```


这里的代码块使用了未标注语言的围栏（```），会触发 agent-doc-lint 的 “unlabeled code fence” 校验失败。请为该代码块补充语言标注（例如 `text`/`console`）。

Suggested change

```

```text

已修复：将该代码块标注为 ```text

Copilot · 2026-04-07T03:27:51Z

+---
+title: Radxa SBC 添加 Device Tree Overlay
+---


新增了 docs/radxa-dto-guide.md，但 i18n/en/docusaurus-plugin-content-docs/current/ 下没有对应镜像文件；仓库里有 scripts/agent-doc-drift-guard.sh 会对新增的 docs/i18n 路径漂移进行门禁（需要在同一 PR 添加英文镜像文件，或更新 .github/agent-doc-drift-baseline.md 将该漂移纳入基线）。

该文档目前仅有中文版本，英文 i18n 文件待产品侧确认具体内容后再补充。

建议方案：1) 此次 PR 先合并中文版；2) 英文翻译在后续单独 PR 中补充；或 3) 更新 `.github/agent-doc-drift-baseline.md` 将该路径漂移纳入基线豁免。请确认您倾向的处理方式。

Thanks for the review. A few points to clarify:

The new file is at the repo root (not under ), so the expected i18n path would be rather than under .

The repository does not currently have or - the guard script referenced in this comment does not exist yet.

The English i18n tree () was removed in this PR, so there is currently no English version of this guide in the i18n structure.

Could you clarify: (a) is an English translation of this guide expected to be added in this PR, or (b) should this be treated as a future i18n requirement and tracked separately? Happy to add the English file or update a baseline once the expected path is confirmed.

Copilot · 2026-04-07T03:27:51Z

+└── Install 3rd party overlay
+```
+
+然后选择你刚编译的 overlay（路径为 `arch/arm64/boot/dts/rockchip/overlays/*.dts`），确认后退出并重启。


这里说明“选择你刚编译的 overlay（路径为 .../*.dts）”，但上一步实际编译产物是 .dtbo（且第三方 overlay 一般也是安装/选择 .dtbo）。建议将此处的文件后缀与示例路径改为 .dtbo，避免读者按 .dts 选择导致失败。

Suggested change

然后选择你刚编译的 overlay（路径为 `arch/arm64/boot/dts/rockchip/overlays/*.dts`），确认后退出并重启。

然后选择你刚编译的 overlay（路径为 `arch/arm64/boot/dts/rockchip/overlays/*.dtbo`），确认后退出并重启。

已修复：已将路径和文件后缀改为 *.dtbo（编译产物为 .dtbo 文件）

Copilot · 2026-04-07T03:27:51Z

+```bash
+ls /boot/dtb/rockchip/overlay/ 2>/dev/null
+# 或
+cat /sys/kernel/debug/device-tree/overlay/ 2>/dev/null


/sys/kernel/debug/device-tree/overlay/ 通常是目录（包含多个 overlay 节点），对目录执行 cat 会报错（Is a directory）。建议改为 ls/find 等方式列出内容，或指向具体的文件节点。

Suggested change

cat /sys/kernel/debug/device-tree/overlay/ 2>/dev/null

find /sys/kernel/debug/device-tree/overlay/ -mindepth 1 -maxdepth 1 2>/dev/null

已修复：改为使用 find 命令列出目录内容，避免对目录执行 cat 报错

Copilot · 2026-04-07T03:27:52Z

+| 字段 | 说明 |
+|------|------|
+| `title` | overlay 名称，在 `rsetup` 菜单中显示 |
+| `compatible` | 适用设备列表，必须与主设备树的 compatible 匹配 |
+| `category` | 分类，如 `misc`、`display`、`audio` 等 |
+| `exclusive` | 互斥的 GPIO 引脚，与其他 overlay 冲突时提示 |
+| `description` | 详细说明，在 rsetup UI 中可见 |


该表格的表头行以 || 开头（双竖线），会导致 Markdown 渲染/格式化不一致。建议按常规表格语法使用单个 | 开头（例如 | 字段 | 说明 |）。

经检查，当前表格的表头已使用标准单竖线语法 `| 字段 | 说明 |`，未发现双竖线问题。如果在渲染后发现异常，请告知具体 URL 以便进一步排查。

tangzz-radxa · 2026-04-07T04:54:19Z

I've added the English mirror file to address the doc-drift guard requirement mentioned by Copilot. The English translation is now available and the agent-doc-drift-guard.sh check passes.

xzl01 requested a review from a team as a code owner April 7, 2026 03:24

Copilot AI review requested due to automatic review settings April 7, 2026 03:24

Copilot started reviewing on behalf of xzl01 April 7, 2026 03:25 View session

docs: add Radxa SBC Device Tree Overlay guide

5cb3ce0

- Add two methods: local compile and PR to radxa-overlays - Includes metadata field descriptions and common overlay operations - Complete SPI1 example and rsetup commands

xzl01 force-pushed the docs/radxa-dto-guide branch from 8b7a6f5 to 5cb3ce0 Compare April 7, 2026 03:26

Copilot AI reviewed Apr 7, 2026

View reviewed changes

		@@ -0,0 +1,284 @@
		---
		title: Radxa SBC 添加 Device Tree Overlay

	title: Radxa SBC 添加 Device Tree Overlay
	title: Radxa SBC 添加 Device Tree Overlay
	sidebar_position: 1


		构建完成后会生成 `.deb` 包，位于上级目录：

		```

	然后选择你刚编译的 overlay（路径为 `arch/arm64/boot/dts/rockchip/overlays/*.dts`），确认后退出并重启。
	然后选择你刚编译的 overlay（路径为 `arch/arm64/boot/dts/rockchip/overlays/*.dtbo`），确认后退出并重启。

	cat /sys/kernel/debug/device-tree/overlay/ 2>/dev/null
	find /sys/kernel/debug/device-tree/overlay/ -mindepth 1 -maxdepth 1 2>/dev/null


		进入交互菜单：

		```


		进入菜单：

		```

Conversation

xzl01 commented Apr 7, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tangzz-radxa commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants