[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

[jerpelea]

I will port it to 13.0

[raiden00pl]

FYI to all people who have contributed to stm32 recently or I know that in the past they were interested in stm32 with nuttx. This PR will be a breaking change for most stm32 users. For those who are not interested in nuttx - sorry for the pinging :)

In short, the goal of this PR is simple: unification of STM32 ports. No more unnecessary code duplication, incompatible Kconfig options and arch specific API. Ultimately, maintaining the code, applying changes, and adding new stm32 ports should be easier. However, this requires a hard breaking change that unifies and standardizes many things. The changes in this PR are the first step that contains most of the necessary breaking changes and these changes should be part of the upcoming release 13.0.

With this PR all architecture API is unified and uses stm32_xxx() functions, all public options shared between families are unified and use CONFIG_STM32_ prefix, each stm32 family has its own separate directory in arch and boards, common code between families goes to arch/src/common/stm32. At the moment common code is mainly used by f0 l0 g0 c0 f1 l1 f2 f3 f4 g4, in the future the rest of the families will be migrated to common code.

@alexcekay @ImBonkers @patrickelectric @csanchezdll @cjj66619 @dlizewski @shizacat @ppisa @pbarada @neilberkman @matiamic @vrmay23 @kywwilson11 @zdebanos @rzsa @davids5 @antmerlino @fjpanag @hartmannathan @michi-jung @juniskane @onegray @mlyszczek @stbenn @daniel-p-carvalho @rcsim

[michi-jung]

Hi @raiden00pl

In the summary of changes you wrote:

Peripheral drivers included by a family depend on the peripheral's IP core version.

That is an excellent idea, but may I ask where you get the IP core versions from? When I asked an FAE from STMicroelectronics I was told that they do not publish the IP core version number per STM32 type.

Thanks!
Michael

[michallenc]

This is a huge change and I will need some time to dig deep in and understand all the consequences. Just some initial thoughts.

STM32 families can use the STM32 common directory, which allows them to use common drivers and common hardware definitions shared between families.

So far I am sceptical towards this. One of the greatest NuttX design characteristics is the simplicity of source code and its arch section. Having a directory with common drivers with various compile time or runtime conditions deciding what code should be run breaks this simplicity. Yes, the current approach can bring some duplicity, but I still think it's a better approach. I would cite NuttX principles here: Sometimes is better to duplicate some logic than to introduce coupling.

We need to really consider this, because the architectural design is what makes NuttX accessible. It's super easy to explain someone the driver's organization and the relation between boards and arch section. You just call stm32_adc_initialize from your BSP and go to arch/arm/stm32l4/stm32_adc.c if you want to know what the function does. No need to figure out what file in common section is for my chip and what code actually applies because of various ifdef guards.

STM32 boards can use common board drivers.

This on the other hand is something I agree with. I will need to take a detailed look, but I like the idea BSPs would serve mainly for pin definitions and would call the common init functions. After all, these functions are nothing more than arch init call and character device driver registration.

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.

+1 this is great, searching in or editing one large Kconfig file is a pain. Maybe I would just move all those Kconfig.adc, Kconfig.pwm and so on files to a subdirectory and keep the root directory for main Kconfig file and drivers. I think we could apply the same logic to all MCUs in the future.

[raiden00pl]

@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

[raiden00pl]

So far I am sceptical towards this. One of the greatest NuttX design characteristics is the simplicity of source code and its arch section. Having a directory with common drivers with various compile time or runtime conditions deciding what code should be run breaks this simplicity. Yes, the current approach can bring some duplicity, but I still think it's a better approach. I would cite NuttX principles here: Sometimes is better to duplicate some logic than to introduce coupling.

@michallenc Some code duplication makes sense. Code duplication across ~20 families and all posbile peripherals is pointless and difficult to maintain, especially when IP core implementations are shared between families. The problem here is that ST doesn't provide this information in an easy and readable way. Therefore, we can use ChibiOS whose author is or was an ST employee: https://github.com/ChibiOS/ChibiOS/tree/master/os/hal/ports/STM32/LLD

We need to really consider this, because the architectural design is what makes NuttX accessible. It's super easy to explain someone the driver's organization and the relation between boards and arch section. You just call stm32_adc_initialize from your BSP and go to arch/arm/stm32l4/stm32_adc.c if you want to know what the function does. No need to figure out what file in common section is for my chip and what code actually applies because of various ifdef guards.

That's why documentation was created that directly indicates which IP core is used by which family. Regarding the STM32L4 - this port was created based on the principle that "code duplication is not a bad thing." Currently, this code has drifted from the rest of the ports to the point that it's the worst to generalize, and it uses essentially the same peripherals as other STM32 M4s.

If we're duplicating code, we should duplicate it for all families, not as currently, where some are done this way, some are done that way (stm32/stm32f0l0g0 vs stm32l4/stm32f7/stm32h7/....). Duplicating it for all families means we need to duplicate the code for the old arch/stm32: f1, f2, f3, f4, g4, l1 and for the old arch/stm32f0l0g0: f0, l0, g0, c0. 10 new architectures to maintain. From the common stm32 arch drivers way, or ten new architectures and code duplication way, I think the common arch is the only reasonable way.

[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

[michallenc]

So far I am sceptical towards this. One of the greatest NuttX design characteristics is the simplicity of source code and its arch section. Having a directory with common drivers with various compile time or runtime conditions deciding what code should be run breaks this simplicity. Yes, the current approach can bring some duplicity, but I still think it's a better approach. I would cite NuttX principles here: Sometimes is better to duplicate some logic than to introduce coupling.

@michallenc Some code duplication makes sense. Code duplication across ~20 families and all posbile peripherals is pointless and difficult to maintain, especially when IP core implementations are shared between families. The problem here is that ST doesn't provide this information in an easy and readable way. Therefore, we can use ChibiOS whose author is or was an ST employee: https://github.com/ChibiOS/ChibiOS/tree/master/os/hal/ports/STM32/LLD

We need to really consider this, because the architectural design is what makes NuttX accessible. It's super easy to explain someone the driver's organization and the relation between boards and arch section. You just call stm32_adc_initialize from your BSP and go to arch/arm/stm32l4/stm32_adc.c if you want to know what the function does. No need to figure out what file in common section is for my chip and what code actually applies because of various ifdef guards.

That's why documentation was created that directly indicates which IP core is used by which family. Regarding the STM32L4 - this port was created based on the principle that "code duplication is not a bad thing." Currently, this code has drifted from the rest of the ports to the point that it's the worst to generalize, and it uses essentially the same peripherals as other STM32 M4s.

If we're duplicating code, we should duplicate it for all families, not as currently, where some are done this way, some are done that way (stm32/stm32f0l0g0 vs stm32l4/stm32f7/stm32h7/....). Duplicating it for all families means we need to duplicate the code for the old arch/stm32: f1, f2, f3, f4, g4, l1 and for the old arch/stm32f0l0g0: f0, l0, g0, c0. 10 new architectures to maintain. From the common stm32 arch drivers way, or ten new architectures and code duplication way, I think the common arch is the only reasonable way.

I agree the support for STM32 is quite messy and STM doesn't make it easy with their naming convention. We don't need duplicate implementations for f1, f2, f3 and so on though. These can be in one common folder, if the chips are the same (or with really little changes). We also have imxrt1060 and imxrt1170 in common imxrt folder or same70 and samv71 in samv7. These chips use one IP core, the differences are mostly in having different peripherals available.

But with this change, we would not only mix different IP core implementations in one directory but also different Cortex versions if I understand it correctly. And this is something I think we should duplicate. From my point of view the unification abandons the way we wrote the code for many years and I am afraid we open a Pandora box leading to more messy and unclear code.

It also forces us to assign IP core versions to chips - yes, we can automate it by relying on 3rd party project which may end in a year or two or on LLM, which is even worse, because we can't trust that thing. So we have to do it manually by comparing registers and hoping we got it right. But that's a minor issue we can handle.