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/:

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.

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.