[BREAKING CHANGE] reorganize and unify STM32 ports

[raiden00pl]

Summary

This PR is the first step toward unification and reorganisation of STM32 ports. This is a huge, breaking change that impacts many users. It also introduces the standard for STM32 ports described in the documentation page. Any new STM32 port or new STM32 feature should adhere to these rules.

This reorganization allows for the separation of STM32 families with minimal code duplication. Ultimately, we'll be able to eliminate most of the duplication between STM32 families, but this is a long-term task. Subsequent changes won't be as invasive, and most won't require breaking changes.

This PR focuses on the first step in the STM32 redesign, which is the most invasive and includes a lot of breaking changes.

Summary of changes:

1. Each STM32 family has its own directory.
2. STM32 families can use the STM32 common directory, which allows them to use common drivers and common hardware definitions shared between families.
3. Peripheral drivers included by a family depend on the peripheral's IP core version.
4. STM32 Kconfig option names are unified.
5. STM32 boards can use common board drivers.
6. STM32 hardware definition names are unified.
7. Kconfig files have been split into smaller ones, which makes them much easier to manage. This was proposed several times for new STM32 ports before, but doing it for one STM32 port and leaving the rest untouched didn't make sense. Now it's done for all STM32 ports, as it should be.
8. Added a documentation page discussing STM32 ports organisation.
9. Add boards/common/stm32 support for STM32L4

What is not done yet:

1. Migrate all other families to STM32 arch common directories.
   The stm32f7, stm32h7, and stm32l4 should be easy. The rest, based on the Cortex-M33, will require more time because I'm not familiar with these chips yet. After this migration, support for the missing stm32 families should be much easier.
2. Migrate all other families to STM32 board common directories.
   This change will later enable us to solve another problem - the standardization of ST boards, so all nucleo board follows the same patterns and provide the same features.
3. Unify and clean up Kconfig options and families features. Ultimately, each family should support the same features as the hardware allows. At the moment Kconfig has some long and ugly lines, they need to be analyzed and simplified. Kconfig still has a few sections that have not been generalized, mainly due to drift of some families from other implementations.
4. Some families have driver changes that haven't been propagated to other families. This needs to be properly analyzed and ported where possible.
5. regenerate CODEOWNERS

I know this PR is huge, but it can't really be done in smaller steps. This is an attempt to fix a problem that's been building for over a decade. I will create a separate PR so it is easier to review, this PR is to show the final effect . The best way to review this change is to download the entire branch and view it locally. Github is unable to render changes well and misses many git rename operations.

If the community deems this change desirable, it should be included in version 13.0, as it's a significant change that's causing a lot of disruption. I think this is the best time for this reorganization, even if it will upset many users and likely break something.

For all AI skeptics here - this PR was created with AI assistance and burned hundreds of dollars worth of tokens. There is no other way to do it, doing it manually is unrealistic, especially if you do it alone and for free :) This PR doesn't add new code, it only organizes the old code, so the code license remains the same as the original code

References:
#18894
#16172

Impact

Breaking change that impacts many users. There should be no functional changes; users should only need to update defconfig options in theory, but this is a huge change done mostly with AI assistance, so there is some chance that things will be broken.
The larger the PR, the greater the chance that something will break uncontrollably. Therefore, if this change is to be implemented upstream, it should be in release 13.0, which already contains a lot of breaking changes.

I tried to preserve the git history as much as possible, but for Kconfig it was not possible.

What we gain from this PR:

1. Unification and standardization of STM32. Portability between STM32 families will finally be as it should be.
   No more questions about how to create new STM32 ports, everything is set in advance and the user has to comply.
2. After the migration of the remaining families to common/stm32 is completed, maintaining the families will be much easier. Fewer files to track, less duplicate code.
3. Adding support for new STM32 families will be easier. Reusable blocks can be easily included by new ports.
4. All STM32 boards can use the same boards/common, which can significantly simplify boards code. Ultimately, it should be possible to standardize all STM32 boards like nucleo and create common board initialization logic.

Testing

CI

upstream build and test on HW:

• nucleo-l073rz:nsh - OK
• nucleo-f103rb:nsh - OK
• nucleo-l152re:nsh - OK
• nucleo-f091rc:nsh - OK
• nucleo-c071rb:jumbo - OK
• nucleo-h743zi:nsh - OK
• nucleo-f446re:jumbo - OK

Later I will do tests with my Dawn project (https://github.com/railab/dawn) where I have a lot of HW automated tests based on NTFC, so it should catch most of the regressions.

[raiden00pl]

It would be good to pinging everyone who uses stm32 with nuttx

[patrickelectric]

It appears that CODEOWNERS is still keeping stm32f0l0g0.

[hartmannathan]

Hi, @raiden00pl thanks for taking this HUGE task upon yourself! I have sometimes been frustrated by the stm32 support being disjoint because of the different families being treated as different archs. This is a substantial change so I just want to kindly ask you to bear with me, because it will take me some time to review and test.

[hartmannathan]

@michi-jung This is the hardest part, it has to be done by ourself. I used to do it manually, now the comparison can be easily automated with LLM. ChibiOS might provide some guidance: https://github.com/ChibiOS/ChibiOS/tree/master/os/hal/ports/STM32/LLD For NuttX we can make an even simpler distinction based on the registers: when the order of registers is identical, we can assume that the IP is the same, or at least compatible to the extent that the same driver code can be used

Yes, although STM doesn't document the actual version numbers of the peripheral IP blocks, we can ascertain this information based on the functionality they expose via registers and register bits. We can think of the registers and bits as the API of the peripherals. If the APIs match, we can consider the peripherals to be the same version.

It's possible that the register addresses may be different, or that the bits within the register might be in a different position or order. So we might need some kind of "fuzzy matching".

[hartmannathan]

For all AI skeptics here - this PR was created with AI assistance and burned hundreds of dollars worth of tokens. There is no other way to do it, doing it manually is unrealistic, especially if you do it alone and for free :) This PR doesn't add new code, it only organizes the old code, so the code license remains the same as the original code

@raiden00pl, I am an AI skeptic. :-) Out of curiosity, would you be willing to share the prompts you used? It could be a blog post or something like that, to document how the changes were made as well as a learning resource for others who are trying to wrap their heads around this new way of working.

[vrmay23]

How can I support with testing stm32h7 and F7 family?

…

On Mon, Jun 1, 2026, 20:31 hartmannathan ***@***.***> wrote: *hartmannathan* left a comment (apache/nuttx#19004) <#19004 (comment)> For all AI skeptics here - this PR was created with AI assistance and burned hundreds of dollars worth of tokens. There is no other way to do it, doing it manually is unrealistic, especially if you do it alone and for free :) This PR doesn't add new code, it only organizes the old code, so the code license remains the same as the original code @raiden00pl <https://github.com/raiden00pl>, I am an AI skeptic. :-) Out of curiosity, would you be willing to share the prompts you used? It could be a blog post or something like that, to document how the changes were made as well as a learning resource for others who are trying to wrap their heads around this new way of working. — Reply to this email directly, view it on GitHub <#19004?email_source=notifications&email_token=BO3QXU27YGTA4RXDT3EMOIL45XDXXA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINJZGUZTSMJZGA42M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-4595391909>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BO3QXU7XKYUTKHVIXIQ4ORL45XDXXAVCNFSM6AAAAACZUL6Y4GVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DKOJVGM4TCOJQHE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[raiden00pl]

@hartmannathan I had an idea and plan for this reorganisation for years in my private notes, but it was not possible to do it manually without investing months of work. This wasn't a task that could be solved with a few prompts. The AI has too small context for this and isn't able to think outside the box very well. AI was used here more like an "intelligent tool" for things that I would have had to do manually. I don't have a single master prompt but used many simple prompts in an interactive workflow. I just instructed AI how I would do it step by step, like: "rename all public STM32 arch API to use common prefix stm32_", "move all stm32f0l0g0 files to common/stm32 and rename them to use the m0 suffix", "build set of configuration after each step" and so on. In fact, the order of commits exactly reflects my plan from the beginning.

With such a huge change, keeping git history clean manually is a really big challenge, but for AI this is a really simple job. Moving files, fixups, squashing commits, and resolving conflicts is something that takes hours for a human, but can be easily done by AI.
Fixing issues found by local build/CI is also easy for AI, but not an entirely automated task and needs careful reviews. Simple for human solutions like: "Merge SPI Kconfig options with I2S options to fix undefined STM32_SPI_DMA symbol" were completely unthinkable for codex/claude/deepseek.

There were more issues that AI was not able to solve without manual intervention, like optimizing complex dependencies in Kconfig or even merge similar header files. There are still many complex conditions in Kconfig that must be simplified, but this is work for a human and careful analysis; AI has no idea how to properly solve it.

[raiden00pl]

@vrmay23 Any compilation of externally maintained boards and configurations will be useful. Upstream configurations should be OK now (CI pass), but upstream boards don't provide full coverage for stm32 architectures features, so the more out-of-tree configurations we compile, the greater the certainty that there will be no regressions. F7 and H7 have no functional changes, so if the code compiles - it should work. Unless some Kconfig option was not migrated correctly - with such a big change there's always a chance of that