[docs]Update the contribution document

CYFS3 · Rbb666 · commit b245c1869ef1 · 2026-07-09T18:02:01.000+08:00
diff --git a/documentation/7.contribution/INDEX.md b/documentation/7.contribution/INDEX.md
@@ -8,4 +8,6 @@ All the real-time operating system kernel and open source components can be used
 
 @subpage page_rtt_code_style_en
 
-@subpage page_howto_doxygen
+@subpage page_bsp_contribution_guide_en
+
+@subpage page_howto_doxygen
diff --git a/documentation/7.contribution/bsp_contribution_guide_cn.md b/documentation/7.contribution/bsp_contribution_guide_cn.md
@@ -0,0 +1,91 @@
+# BSP 贡献规范
+
+本文说明新增或调整 BSP 时应遵循的目录层级关系，避免把板级、芯片级和架构级代码混放。
+
+## BSP 目录层级
+
+BSP 目录根据共享代码所在层级，主要分为厂商级共享和厂商 + 系列级共享两类。无论采用哪种结构，都应遵循以下原则：
+
+- `board/` 放置板级初始化、引脚、时钟、链接脚本等只属于当前开发板的内容。
+- 上层或同级共享 `libraries/` 放置同一厂商或同一系列 BSP 共用的芯片库、HAL、CMSIS、SDK、驱动和驱动适配代码，驱动目录也应放在 `libraries/` 下。
+- 同级 `tools/` 放置同一厂商或同一系列 BSP 共用的辅助脚本。
+
+若多个 BSP 共用同一个软件包或 SDK，不应在每个 BSP 目录下重复维护，应放在共享层级或使用软件包机制，并由 BSP 通过构建脚本引用。新增 BSP 时不要随意新建额外层级，也不要把 BSP 代码放入 `components/`、`src/`、`include/` 等非 BSP 目录；抽象驱动框架属于 `components/drivers/`，芯片或 CPU 架构公共移植代码属于 `libcpu/`。
+
+### 厂商级共享目录结构（以 STM32 为例）
+
+STM32 BSP 通常直接位于 `bsp/stm32/<board>`，同一厂商下多个 BSP 共用的驱动适配、模板、工具和软件包选择放在 `bsp/stm32/libraries/` 与 `bsp/stm32/tools/`：
+
+```text
+bsp/stm32/
+├── libraries/
+│   ├── HAL_Drivers/        # STM32 BSP 共用的驱动适配
+│   ├── drivers/            # 多个 STM32 BSP 共用的驱动（如有）
+│   ├── templates/          # 新增 BSP 参考模板
+│   └── Kconfig             # 原厂 HAL/CMSIS 软件包选择
+├── tools/                  # 厂商级辅助脚本
+├── stm32f407-atk-explorer/
+│   ├── board/              # 当前开发板专用的初始化、引脚、时钟、链接脚本
+│   ├── Kconfig
+│   ├── SConscript
+│   └── SConstruct
+└── stm32f429-atk-apollo/
+    ├── board/
+    ├── Kconfig
+    ├── SConscript
+    └── SConstruct
+```
+
+### 厂商 + 系列级共享目录结构（以 NXP 为例）
+
+NXP 这类 BSP 通常会先按厂商、产品线或芯片系列分层，再把当前系列共用的驱动适配、模板、工具和软件包选择放在系列目录下。例如 i.MX RT 使用 `bsp/nxp/imx/imxrt/libraries/`，LPC55S 使用 `bsp/nxp/lpc/lpc55sxx/libraries/`，MCX 按 `mcxa`、`mcxc`、`mcxe`、`mcxn` 等系列分别维护 `libraries/`。
+
+NXP 目录下也存在一些历史 BSP，例如 `lpc176x` 这类单 BSP 目录，或少量旧目录使用 `Libraries/` 命名。新增或重构 BSP 时不应继续扩散旧结构；若驱动、SDK 或模板需要被多个 BSP 复用，应迁移或放入对应系列的 `libraries/` 与 `tools/` 层级。
+
+```text
+bsp/nxp/
+├── imx/
+│   └── imxrt/
+│       ├── libraries/
+│       │   ├── drivers/        # i.MX RT 系列共用的驱动和驱动适配
+│       │   ├── templates/      # 新增 BSP 参考模板
+│       │   └── Kconfig         # NXP i.MX RT SDK 软件包选择
+│       ├── tools/              # 当前系列 BSP 共用的辅助脚本
+│       └── imxrt1052-nxp-evk/
+│           ├── board/          # 当前开发板专用的初始化、引脚、时钟、链接脚本
+│           ├── Kconfig
+│           ├── SConscript
+│           └── SConstruct
+├── lpc/
+│   └── lpc55sxx/
+│       ├── libraries/          # LPC55S 系列共用的驱动适配、模板和软件包选择
+│       ├── tools/
+│       └── lpc55s69_nxp_evk/
+│           ├── board/
+│           ├── Kconfig
+│           ├── SConscript
+│           └── SConstruct
+└── mcx/
+    ├── tools/                  # MCX 系列共用工具
+    └── mcxn/
+        ├── libraries/          # MCXN 系列共用的 CMSIS、系列驱动和软件包选择
+        └── frdm-mcxn947/
+            ├── board/
+            ├── Kconfig
+            ├── SConscript
+            └── SConstruct
+```
+
+### 原厂 HAL/SDK 软件包
+
+若原厂 HAL、CMSIS 或 SDK 已经以 RT-Thread 软件包形式提供，BSP 不应再提交或维护重复的完整源码副本。BSP 应通过 `Kconfig` 选择相应 `PKG_USING_*` 软件包，并在 `SConscript` 中按配置引用软件包内容；`pkgs --update` 负责下载软件包源码。
+
+这种情况下，`libraries/` 主要保留驱动适配、可复用驱动、模板、工具脚本和软件包选择逻辑。不要把 `pkgs --update` 下载出的软件包目录作为 BSP 源码提交，也不要让 `scons --dist` 打包当前 BSP 没有启用的软件包或库文件。
+
+## 提交要求
+
+- 新增 BSP 应保持层级清晰，只提交当前开发板必需的板级文件。
+- 同一厂商或同一系列 BSP 共用的库、驱动适配、可复用驱动、模板和脚本应放在共享 `libraries/` 或 `tools/` 层级，避免在多个 BSP 中重复拷贝。
+- 驱动适配代码和可复用驱动应放在 `libraries/` 下，不应放在单个开发板目录中。
+- 原厂 HAL、CMSIS 或 SDK 已软件包化时，应优先通过软件包机制引用，不应在 BSP 中重复提交软件包源码。
+- 构建脚本应从共享层级引用公共代码，`scons --dist` 打包时不应带入当前 BSP 不需要的软件包或库文件。
diff --git a/documentation/7.contribution/bsp_contribution_guide_en.md b/documentation/7.contribution/bsp_contribution_guide_en.md
@@ -0,0 +1,134 @@
+@page page_bsp_contribution_guide_en BSP Contribution Guide
+
+# BSP Contribution Guide
+
+This document describes the directory hierarchy requirements for adding or
+updating BSPs, so board-level, chip-level, and architecture-level code stay in
+clear layers.
+
+## BSP Directory Hierarchy
+
+BSP directories usually fall into two hierarchy styles depending on where shared
+code is kept: vendor-level sharing, and vendor + series-level sharing. In either
+case, follow these principles:
+
+- `board/` contains board initialization, pin settings, clock settings, linker
+  scripts, and other files that only belong to the current board.
+- The upper or sibling shared `libraries/` directory contains chip libraries,
+  HAL, CMSIS, SDK, drivers, and driver adaptation code shared by BSPs from the
+  same vendor or series. Driver directories should also be placed under
+  `libraries/`.
+- The sibling `tools/` directory contains helper scripts shared by BSPs from the
+  same vendor or series.
+
+If multiple BSPs share the same package or SDK, do not maintain duplicate copies
+under each BSP. Put the shared source in the common layer or use the package
+mechanism, then reference it from the BSP build scripts. When adding a BSP, do
+not create extra directory levels without a clear need, and do not place BSP
+code under non-BSP directories such as `components/`, `src/`, or `include/`.
+Abstract driver frameworks belong in `components/drivers/`, and shared chip or
+CPU architecture porting code belongs in `libcpu/`.
+
+### Vendor-Level Shared Layout (STM32 Example)
+
+STM32 BSPs are usually placed directly under `bsp/stm32/<board>`. Driver
+adaptation code, templates, tools, and package selections shared by STM32 BSPs
+are kept under `bsp/stm32/libraries/` and `bsp/stm32/tools/`:
+
+```text
+bsp/stm32/
+├── libraries/
+│   ├── HAL_Drivers/        # Driver adaptation shared by STM32 BSPs
+│   ├── drivers/            # Drivers shared by multiple STM32 BSPs, if any
+│   ├── templates/          # Reference templates for new BSPs
+│   └── Kconfig             # Vendor HAL/CMSIS package selections
+├── tools/                  # Vendor-level helper scripts
+├── stm32f407-atk-explorer/
+│   ├── board/              # Board-only initialization, pins, clocks, linker scripts
+│   ├── Kconfig
+│   ├── SConscript
+│   └── SConstruct
+└── stm32f429-atk-apollo/
+    ├── board/
+    ├── Kconfig
+    ├── SConscript
+    └── SConstruct
+```
+
+### Vendor + Series-Level Shared Layout (NXP Example)
+
+NXP-style BSPs are usually split first by vendor, product line, or chip series.
+Driver adaptation code, templates, tools, and package selections shared by a
+series are kept under that series directory. For example, i.MX RT uses
+`bsp/nxp/imx/imxrt/libraries/`, LPC55S uses
+`bsp/nxp/lpc/lpc55sxx/libraries/`, and MCX keeps separate `libraries/`
+directories under series such as `mcxa`, `mcxc`, `mcxe`, and `mcxn`.
+
+The NXP tree also contains historical BSP layouts, such as single-BSP LPC
+directories like `lpc176x`, and a few older directories named `Libraries/`.
+Do not extend those legacy layouts when adding or restructuring BSPs. If
+drivers, SDK code, or templates are reused by multiple BSPs, move or place them
+under the corresponding series-level `libraries/` and `tools/` layer.
+
+```text
+bsp/nxp/
+├── imx/
+│   └── imxrt/
+│       ├── libraries/
+│       │   ├── drivers/        # Drivers and driver adaptation shared by i.MX RT BSPs
+│       │   ├── templates/      # Reference templates for new BSPs
+│       │   └── Kconfig         # NXP i.MX RT SDK package selections
+│       ├── tools/              # Helper scripts shared by this series
+│       └── imxrt1052-nxp-evk/
+│           ├── board/          # Board-only initialization, pins, clocks, linker scripts
+│           ├── Kconfig
+│           ├── SConscript
+│           └── SConstruct
+├── lpc/
+│   └── lpc55sxx/
+│       ├── libraries/          # Driver adaptation, templates, and package selections shared by LPC55S BSPs
+│       ├── tools/
+│       └── lpc55s69_nxp_evk/
+│           ├── board/
+│           ├── Kconfig
+│           ├── SConscript
+│           └── SConstruct
+└── mcx/
+    ├── tools/                  # Helper tools shared by MCX series
+    └── mcxn/
+        ├── libraries/          # CMSIS, series drivers, and package selections shared by MCXN BSPs
+        └── frdm-mcxn947/
+            ├── board/
+            ├── Kconfig
+            ├── SConscript
+            └── SConstruct
+```
+
+### Vendor HAL/SDK Packages
+
+If the vendor HAL, CMSIS, or SDK is already provided as an RT-Thread package,
+the BSP should not submit or maintain another full copy of the same source code.
+The BSP should select the corresponding `PKG_USING_*` package in `Kconfig` and
+reference package contents from `SConscript` according to the enabled
+configuration. `pkgs --update` is responsible for downloading package sources.
+
+In this case, `libraries/` mainly keeps driver adaptation code, reusable
+drivers, templates, helper scripts, and package selection logic. Do not commit
+package directories downloaded by `pkgs --update` as BSP source, and do not let
+`scons --dist` include packages or libraries that are not enabled by the current
+BSP.
+
+## Submission Requirements
+
+- Keep the BSP hierarchy clear and only submit board-level files required by the
+  current board.
+- Libraries, driver adaptation code, reusable drivers, templates, and scripts
+  shared by BSPs from the same vendor or series should be placed in the shared
+  `libraries/` or `tools/` layer to avoid duplicate copies across BSPs.
+- Driver adaptation code and reusable drivers should be placed under
+  `libraries/`, not under a single board directory.
+- If the vendor HAL, CMSIS, or SDK has been packaged, prefer the package
+  mechanism and do not submit duplicate package source code under the BSP.
+- Build scripts should reference common code from the shared layer, and
+  `scons --dist` should not include packages or libraries that are not required
+  by the current BSP.
diff --git a/documentation/7.contribution/coding_style_cn.md b/documentation/7.contribution/coding_style_cn.md
@@ -289,30 +289,15 @@ rt_timer + 动词短语的形式表示能够应用于 timer 对象的方法。
 
 ## 14.格式化代码
 
-格式化代码是指通过脚本自动整理你的代码，并使其符合 RT-Thread 的编码规范。本文提供以下两种自动格式化代码方法，可以自行选择或配合使用。
+RT-Thread 现在使用 clang-format 作为统一的代码格式化工具。提交 C/C++、头文件及相关源文件前，请优先使用仓库根目录的 `.clang-format` 配置进行格式化，不要再使用与该配置不一致的手工排版或旧的 astyle 参数。
 
-### 使用 astyle 格式化
+常用命令如下：
 
-用 astyle 自动格式化代码，参数如下：
-
-          --style=allman
-          --indent=spaces=4
-          --indent-preproc-block
-          --pad-oper
-          --pad-header
-          --unpad-paren
-          --suffix=none
-          --align-pointer=name
-          --lineend=linux
-          --convert-tabs
-          --verbose
-
-能满足函数空格、缩进、函数语句等的规范。
-
-### 使用 formatting 格式化
+```shell
+clang-format -style=file -i path/to/file.c
+clang-format -style=file -i path/to/file.h
+```
 
-使用 [formatting](https://github.com/mysterywolf/formatting) 扫描文件来格式化代码：formatting 可以满足编码规则的基本要求，如：
+批量格式化时应只处理本次修改相关的源文件，避免对无关文件做大范围格式化。若某个子目录存在自己的 `.clang-format`，以离文件最近的配置为准。
 
-- 将源文件编码统一为 UTF-8
-- 将 TAB 键替换为 4 空格
-- 将每行末尾多余的空格删除，并统一换行符为 '\n'
+除 clang-format 外，仍需保持源文件编码为 UTF-8，行尾使用 `\n`，删除行尾多余空格，并避免提交由编辑器自动产生的无关格式化变更。
diff --git a/documentation/7.contribution/coding_style_en.md b/documentation/7.contribution/coding_style_en.md
@@ -211,16 +211,24 @@ When creating a new object, think twice on memory allocations: whether a static
 object could be created or it could only created dynamically on the heap. Allocations
 can be slower, but may be necessary in dynamic environments.
 
-# 14. Use astyle to format the code automatically
-parameters: --style=allman
-            --indent=spaces=4
-            --indent-preproc-block
-            --pad-oper
-            --pad-header
-            --unpad-paren
-            --suffix=none
-            --align-pointer=name
-            --lineend=linux
-            --convert-tabs
-            --verbose
+# 14. Format Code
+
+RT-Thread now uses clang-format as the unified code formatting tool. Before
+submitting C/C++ source files, header files, and related source files, format
+them with the `.clang-format` configuration in the repository root. Do not use
+manual formatting or old astyle parameters that conflict with this configuration.
+
+Common commands:
+
+    clang-format -style=file -i path/to/file.c
+    clang-format -style=file -i path/to/file.h
+
+When formatting files in batches, limit the command to files related to the
+current change and avoid large unrelated formatting changes. If a subdirectory
+has its own `.clang-format`, use the nearest configuration for files under that
+directory.
+
+In addition to clang-format, keep source files encoded as UTF-8, use `\n` line
+endings, remove trailing whitespace, and avoid committing unrelated formatting
+changes produced by editors.
 
diff --git a/documentation/Doxyfile.1.9.1 b/documentation/Doxyfile.1.9.1
@@ -931,6 +931,7 @@ EXCLUDE                = ./0.doxygen/mainpage.h \
                          ./6.components/device-driver/clock_time/clock_timer_zh.md \
                          ./env/env-vscode.md \
                          ./7.contribution/coding_style_cn.md \
+                         ./7.contribution/bsp_contribution_guide_cn.md \
                          ../src/utest/perf/README.md
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
diff --git a/documentation/Doxyfile.1.9.8 b/documentation/Doxyfile.1.9.8
@@ -1021,6 +1021,7 @@ EXCLUDE                = ./0.doxygen/mainpage.h \
                          ./6.components/device-driver/clock_time/clock_timer_zh.md \
                          ./env/env-vscode.md \
                          ./7.contribution/coding_style_cn.md \
+                         ./7.contribution/bsp_contribution_guide_cn.md \
                          ../src/utest/perf/README.md
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
