diff options
Diffstat (limited to 'documentation/7.contribution')
| -rw-r--r-- | documentation/7.contribution/INDEX.md | 4 | ||||
| -rw-r--r-- | documentation/7.contribution/bsp_contribution_guide_cn.md | 91 | ||||
| -rw-r--r-- | documentation/7.contribution/bsp_contribution_guide_en.md | 134 | ||||
| -rw-r--r-- | documentation/7.contribution/coding_style_cn.md | 31 | ||||
| -rw-r--r-- | documentation/7.contribution/coding_style_en.md | 32 |
5 files changed, 256 insertions, 36 deletions
diff --git a/documentation/7.contribution/INDEX.md b/documentation/7.contribution/INDEX.md index 65178d5919..d4d5a3ee5b 100644 --- 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
\ No newline at end of file +@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 new file mode 100644 index 0000000000..c81a3c89b9 --- /dev/null +++ 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 new file mode 100644 index 0000000000..824a8d41b7 --- /dev/null +++ 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 index d752611a53..0b975a2e65 100644 --- 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 index 6bb0abc91c..c1953ed0aa 100644 --- 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. |