[documentation][device_driver_model] Add comprehensive DM documentation - Regulator, Clock, Reset, Pinctrl, NVMEM (complete bilingual)

[Copilot]

Adds comprehensive bilingual documentation for RT-Thread's Device Driver Model (DM) framework, with complete documentation for Regulator, Clock, Reset Controller, Pin Control, and NVMEM modules.

Core Documentation

• DM Overview (EN/CN): Architecture, bus/driver/platform models, OFW integration, common APIs, migration guide
• Navigation: INDEX.md tracking all 26 modules, SUMMARY.md with methodology
• Updated parent device-driver INDEX.md

Completed Modules (5/26) - All Bilingual ✅

1. Regulator Framework ✅ (Complete - EN/CN)

Application API (14 functions):

/* Power supply management */
struct rt_regulator *vdd = rt_regulator_get(dev, "vdd");
rt_regulator_enable(vdd);
rt_regulator_set_voltage(vdd, 1710000, 1890000);

Driver Implementation:

static const struct rt_regulator_ops my_ops = {
    .enable = my_enable,
    .set_voltage = my_set_voltage,
};

static rt_err_t my_probe(struct rt_platform_device *pdev) {
    /* Parse DT, register with framework */
    rt_regulator_register(&reg_node);
}

Coverage (EN/CN bilingual):

• Kconfig documentation (RT_REGULATOR_FIXED/GPIO/SCMI)
• Device tree bindings with fixed/GPIO/chained examples
• Complete MMC/SD consumer example (~150 lines)
• Driver implementation guide with working example
• Best practices, troubleshooting, performance considerations

2. Clock Framework ✅ (Complete - EN/CN)

Application API (30+ functions):

/* Clock management with prepare/enable model */
struct rt_clk *clk = rt_clk_get_by_name(dev, "baudclk");
rt_clk_prepare_enable(clk);
rt_clk_set_rate(clk, 48000000);
rt_ubase_t rate = rt_clk_get_rate(clk);

Coverage (EN/CN bilingual):

• Kconfig documentation (RT_USING_CLK, RT_CLK_SCMI)
• Device tree bindings (fixed-clock, clock controllers, consumers)
• Complete UART driver example (~150 lines)
• Fixed-rate clock provider implementation
• Two-level prepare/enable model
• Rate management, parent switching, phase control
• Notifier API for rate change events
• Best practices, troubleshooting, performance considerations

3. Reset Controller ✅ (Complete - EN/CN)

Application API (9 functions):

/* Reset control management */
struct rt_reset_control *rst = rt_reset_control_get_by_name(dev, "phy");
rt_reset_control_deassert(rst);
rt_reset_control_reset(rst);  /* Pulse reset */

Coverage (EN/CN bilingual):

• Kconfig documentation (RT_USING_RESET, RT_RESET_SCMI, RT_RESET_SIMPLE)
• Device tree bindings with consumer examples
• Complete USB driver example (~150 lines) demonstrating proper sequencing
• Simple reset controller provider implementation
• Best practices for initialization/cleanup sequences
• Troubleshooting guide

4. Pin Control Framework ✅ (Complete - EN/CN)

Application API (5 functions):

/* Pin configuration management */
rt_pin_ctrl_confs_apply_by_name(dev, "default");
rt_pin_ctrl_confs_apply_by_name(dev, "sleep");  /* Power management */
rt_ssize_t pin = rt_pin_get_named_pin(dev, "reset-gpios", 0, NULL, NULL);

Coverage (EN/CN bilingual):

• Kconfig documentation (RT_USING_PINCTRL, RT_PINCTRL_SCMI, RT_PINCTRL_SINGLE)
• Device tree bindings with pin group definitions
• Complete SPI driver example demonstrating pin configuration
• Pin state management for power management (default/sleep)
• GPIO coordination with pinctrl
• PIN_CONFIG_* parameters documentation
• Best practices for power management with pin states

5. NVMEM Framework ✅ (Complete - EN/CN)

Application API (12 functions):

/* Non-volatile memory cell access */
struct rt_nvmem_cell *cell = rt_nvmem_get_cell_by_name(dev, "mac-address");
rt_nvmem_cell_read(cell, &offset, data, sizeof(data));
rt_u32 value;
rt_nvmem_cell_read_u32(cell, &offset, &value);

Coverage (EN/CN bilingual):

• Kconfig documentation (RT_USING_NVMEM)
• Device tree bindings with cell-based memory organization
• Complete Ethernet driver example using MAC address from EEPROM (~150 lines)
• I2C EEPROM provider implementation (~200 lines)
• Write-protect GPIO support
• Bit-level access support
• Typed read operations (u8/u16/u32/u64)
• Best practices, troubleshooting, performance considerations

Module Inventory

Completed: regulator ✅, clk ✅, reset ✅, pinctrl ✅, nvmem ✅

Remaining High Priority: pmdomain, pic, dma, mailbox

All Modules: Power Management (regulator, clk, pinctrl, reset, pmdomain), Communication (mailbox, dma), Storage (nvmem, mtd, block), System (pic, ofw, firmware, thermal, mfd, iio, phy, pci), Other (hwcache, hwspinlock, input, led, ata, nvme, rtc, watchdog, graphic)

Documentation Standards

Each module follows established template:

1. Technology overview + RT-Thread implementation
2. Complete Kconfig + menuconfig paths
3. Device tree bindings + consumer examples
4. Full API reference with signatures/examples
5. Driver implementation guide
6. Complete working code examples
7. Best practices + troubleshooting
8. Full bilingual (EN/CN)

Statistics

• Files: 17 markdown files
• Documentation: ~297KB total (~237KB module-specific)
• Modules Documented: 5/26 complete (19.2%)
  • All 5 modules complete with full bilingual support ✅
• Code Examples: 50+ complete examples
• API Functions: 105+ documented
• Languages: Complete English + Chinese for all 5 modules

Remaining modules will follow the same comprehensive bilingual structure. Next priorities: pic, dma, mailbox, pmdomain.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature] 请出一份关于 DM 的文档</issue_title>
<issue_description>### Describe problem solved by the proposed feature

最近在大量更新 DM , 但我却找不到关于 DM 的文档.
可否出一份 DM 的文档?

Describe your preferred solution

No response

Describe possible alternatives

No response</issue_description>

<agent_instructions>根据 RT_USING_DM，Enable Device Driver Model with Device Tree 的方式，在 documentation/6.components/device-driver 目录下建立新的目录： device_driver_model ，提供相关的 README.md README_zh.md 文档。并深入分析 components/drivers 目录下的代码，给出更细致，详细的中英文文档，例如针对regulator模块需要包括几个方面：

• 模块的介绍，包括通用性介绍，也包括这部分在rt-thread device drivers 中实现的介绍
• Kconfig 描述：可以配置哪些选项，分别是什么；以及在 menuconfig 中的位置是什么；
• 在设备树中的介绍，sample写法，以及会影响到哪些；
• 这个外设对应用层的API是什么需要依次详细描述，以及在应用层如何使用（需要提供综合性的示例）
• 这个外设对应的驱动接口是什么，应该如何编写、适配这个外设。

需要先给出device drivers model的总体介绍，然后再对 components/drivers 进行分析，列出所有涉及到的外设，再对对应的外设代码进行详细代码分析，然后依据代码来编写外设的中英文文档。如涉及到绘图，可以以 opus 4.5 以 svg 方式绘图（注意框图的对齐，需要做到清晰，工整。如涉及到关系箭头指向，尽可能使用折线方式进行绘制）

完成后，需要依次检查svg绘图，需要做到绘图清晰，工整，svg文件语法无错(特别是一些转义字符处理上)。</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@Rbb666 @GuEe-GUI 大佬看看 @BernardXiong @GuEe-GUI 可以上AI，写好大纲，然后由AI来展开，来写。AI部分推荐Claude Code、GLM 4.7、MiniMax M2.1。文档部分，codex要弱些，会比较简略。

• Fixes [Feature] 请出一份关于 DM 的文档 #11025

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[github-actions]

👋 感谢您对 RT-Thread 的贡献！Thank you for your contribution to RT-Thread!

为确保代码符合 RT-Thread 的编码规范，请在你的仓库中执行以下步骤运行代码格式化工作流（如果格式化CI运行失败）。
To ensure your code complies with RT-Thread's coding style, please run the code formatting workflow by following the steps below (If the formatting of CI fails to run).

---

🛠 操作步骤 | Steps

1. 前往 Actions 页面 | Go to the Actions page
   点击进入工作流 → | Click to open workflow →

2. 点击 Run workflow | Click Run workflow

• 设置需排除的文件/目录（目录请以"/"结尾）
  Set files/directories to exclude (directories should end with "/")
• 将目标分支设置为 \ Set the target branch to：copilot/create-device-driver-model-docs
• 设置PR number为 \ Set the PR number to：11115

3. 等待工作流完成 | Wait for the workflow to complete
   格式化后的代码将自动推送至你的分支。
   The formatted code will be automatically pushed to your branch.

完成后，提交将自动更新至 copilot/create-device-driver-model-docs 分支，关联的 Pull Request 也会同步更新。
Once completed, commits will be pushed to the copilot/create-device-driver-model-docs branch automatically, and the related Pull Request will be updated.

如有问题欢迎联系我们，再次感谢您的贡献！💐
If you have any questions, feel free to reach out. Thanks again for your contribution!

[github-actions]

📌 Code Review Assignment

🏷️ Tag: documentation

Reviewers: CXSforHPU GorrayLi lianux-mm unicornx

Changed Files (Click to expand)

• documentation/6.components/device-driver/INDEX.md
• documentation/6.components/device-driver/device_driver_model/INDEX.md
• documentation/6.components/device-driver/device_driver_model/README.md
• documentation/6.components/device-driver/device_driver_model/README_zh.md
• documentation/6.components/device-driver/device_driver_model/SUMMARY.md
• documentation/6.components/device-driver/device_driver_model/clk/README.md
• documentation/6.components/device-driver/device_driver_model/clk/README_zh.md
• documentation/6.components/device-driver/device_driver_model/nvmem/README.md
• documentation/6.components/device-driver/device_driver_model/nvmem/README_zh.md
• documentation/6.components/device-driver/device_driver_model/pinctrl/README.md
• documentation/6.components/device-driver/device_driver_model/pinctrl/README_zh.md
• documentation/6.components/device-driver/device_driver_model/regulator/README.md
• documentation/6.components/device-driver/device_driver_model/regulator/README_zh.md
• documentation/6.components/device-driver/device_driver_model/reset/README.md
• documentation/6.components/device-driver/device_driver_model/reset/README_zh.md

---

📊 Current Review Status (Last Updated: 2026-01-03 08:19 CST)

• ⌛ CXSforHPU Pending Review
• ⌛ GorrayLi Pending Review
• ⌛ lianux-mm Pending Review
• ⌛ unicornx Pending Review

---

📝 Review Instructions

1. 维护者可以通过单击此处来刷新审查状态: 🔄 刷新状态
   Maintainers can refresh the review status by clicking here: 🔄 Refresh Status

2. 确认审核通过后评论 LGTM/lgtm
   Comment LGTM/lgtm after confirming approval

3. PR合并前需至少一位维护者确认
   PR must be confirmed by at least one maintainer before merging

ℹ️ 刷新CI状态操作需要具备仓库写入权限。
ℹ️ Refresh CI status operation requires repository Write permission.

[BernardXiong]

@copilot 继续后续的每个模块的中英文文档

[Copilot]

@copilot 继续后续的每个模块的中英文文档

已开始继续编写各模块的中英文文档。

已完成:

• Regulator 模块 (EN/CN) ✅
• Clock 框架 (EN) ✅ - commit 36b8dd0

进行中:

• Clock 框架中文文档
• Pin Control (pinctrl)
• Reset Controller

按照优先级继续完成剩余模块。

[BernardXiong]

@copilot 继续后续的每个模块的中英文文档。在提交PR的时候，可以跳过ci

[Copilot]

@copilot 继续后续的每个模块的中英文文档。在提交PR的时候，可以跳过ci

继续编写各模块中英文文档中。

最新进展 (commit 8671d7d):

• Reset Controller 英文文档完成 ✅
• 包含完整 API (9个函数)、USB 驱动示例、Simple Reset 驱动实现

已完成模块:

1. Regulator (EN/CN) ✅
2. Clock (EN/CN) ✅
3. Reset Controller (EN) ✅ - 中文翻译进行中

进行中:

• Reset 中文文档
• Pinctrl 模块
• Pmdomain 模块

统计: 12 个文件，~175KB 文档，75+ API 已记录

继续按优先级完成剩余 23 个模块。

[BernardXiong]

@copilot 继续后续的每个模块的中英文文档。在提交PR的时候，可以跳过ci

[Copilot]

@copilot 继续后续的每个模块的中英文文档。在提交PR的时候，可以跳过ci

持续完善各模块中英文文档。

最新完成 (commit 038be91):

• Reset Controller 模块完整文档 ✅ (EN/CN)

已完成的 3 个模块 (全部 EN/CN):

1. Regulator - 电源管理 ✅
2. Clock - 时钟树管理 ✅
3. Reset - 硬件复位控制 ✅

统计数据:

• 13 个文件
• ~190KB 文档
• 30+ 代码示例
• 75+ API 函数已记录
• 完整双语支持

下一步: Pinctrl、Pmdomain、PIC 等 23 个剩余模块

按优先级继续完成文档工作。

[BernardXiong]

@copilot 继续后续模块的中英文文档。在提交PR的时候，可以跳过ci

[Copilot]

@copilot 继续后续模块的中英文文档。在提交PR的时候，可以跳过ci

持续编写模块文档。

最新完成 (commit 33910f3):

• Pinctrl 框架英文文档 ✅
• 包含 5 个主要 API、SPI 驱动示例、电源管理集成

已完成模块:

1. Regulator (EN/CN) ✅
2. Clock (EN/CN) ✅
3. Reset (EN/CN) ✅
4. Pinctrl (EN) ✅ - 中文翻译进行中

统计:

• 14 个文件
• ~204KB 文档
• 35+ 代码示例
• 80+ API 函数已记录

下一步: Pinctrl 中文文档、Pmdomain、PIC、NVMEM 等 22 个剩余模块

继续按优先级完成。

[BernardXiong]

@copilot
继续后续模块的中英文文档。在提交PR的时候，可以跳过ci

[Copilot]

@copilot
继续后续模块的中英文文档。在提交PR的时候，可以跳过ci

继续编写各模块文档。

最新完成 (commit c4e97d6):

• Pinctrl 框架完整文档 ✅ (EN/CN)

已完成模块 (全部 EN/CN):

1. Regulator ✅
2. Clock ✅
3. Reset ✅
4. Pinctrl ✅

统计: 15 个文件，~224KB 文档，85+ API 函数

下一步: Pmdomain、PIC、NVMEM 等 22 个剩余模块

继续按优先级编写文档。

[BernardXiong]

@copilot 继续

[Copilot]

@copilot 继续

持续编写模块文档中。

最新完成 (commit 30ccfaf):

• NVMEM 框架英文文档 ✅
• 包含 9 个 Consumer API、3 个 Provider API
• 完整以太网驱动示例（从 EEPROM 读取 MAC 地址）
• I2C EEPROM 驱动实现示例

已完成模块 (bilingual/EN):

1. Regulator (EN/CN) ✅
2. Clock (EN/CN) ✅
3. Reset (EN/CN) ✅
4. Pinctrl (EN/CN) ✅
5. NVMEM (EN) ✅ - 中文翻译进行中

统计: 16 个文件，~248KB 文档，95+ API 函数

下一步: NVMEM 中文、PIC、DMA、Mailbox 等 21 个剩余模块

继续按优先级完成文档工作。

[BernardXiong]

@copilot 继续完成NVMEM中文文档，PIC的中英文文档

[Copilot]

@copilot 继续完成NVMEM中文文档，PIC的中英文文档

NVMEM 中文文档已完成 (commit c7dd643)。

现在开始创建 PIC (Platform Interrupt Controller) 中英文文档。