doc/guides: add guide for porting new MCUs by fjrdev · Pull Request #22173 · RIOT-OS/RIOT

fjrdev · 2026-04-02T15:01:48Z

Contribution description

This PR features a markdown file describing the process of porting new CPUs into the RIOT ecosystem, since there is currently only a porting guide for boards but not for CPUs. The guide first gives a general overview of the process and then dives into to process of creating the file-structure for a new CPU. A description + code examples are given for the required files. Furthermore, a roadmap is given for the implementing the most important peripherals. This guide was created during the port of the Infineon PSOC-6, which is a new CPU for RIOT. A PR for this will follow in a bit.

This PR adds a new Markdown guide at doc/guides/advanced_tutorials/RIOT_CPU_PORTING.md that documents the process of porting a new CPU to RIOT.

At the moment, RIOT provides guidance for board porting, but there is no CPU porting guide. This contribution is intended to fill that gap by describing the overall CPU porting workflow, the expected file structure, the role of the main CPU-specific files and high-level descriptions for implementing core peripherals (GPIO, UART, Timer, SPI and I2C).

This guide was written during the ongoing port of the Infineon PSoC-6 CPU family to RIOT. The corresponding CPU port itself will be submitted in a separate PR in the near future. It is intended to make future CPU ports easier to structure and understand.

Scope:

documentation only
no functional code changes

Testing procedure

Issues/PRs references

None

Declaration of AI-Tools / LLMs usage:

AI-Tools / LLMs that were used are:

none

crasbe · 2026-04-03T09:07:39Z

There is a compile error when trying to build the documentation:

make doc-starlight
...

11:06:27 [content] Syncing content
[InvalidContentEntryDataError] docs → advanced_tutorials/porting_cpus data does not match collection schema.

  **: [
  {
    "expected": "string",
    "code": "invalid_type",
    "path": [
      "title"
    ],
    "message": "title: Required"
  }
]

  Hint:
    See https://docs.astro.build/en/guides/content-collections/ for more information on content schemas.
  Error reference:
    https://docs.astro.build/en/reference/errors/invalid-content-entry-data-error/
  Location:
    /home/cbuec/RIOTstuff/riot-vanilla/RIOT/doc/guides/advanced_tutorials/porting_cpus.md:0:0
  Stack trace:
    at getEntryData (/home/cbuec/RIOTstuff/riot-vanilla/RIOT/doc/starlight/node_modules/astro/dist/content/utils.js:123:16)
    at async eval (/home/cbuec/RIOTstuff/riot-vanilla/RIOT/doc/starlight/node_modules/astro/dist/content/loaders/glob.js:211:13)

crasbe

Thank you for adding this much needed guide!

The remarks about rearranging the Typical Responsibilities lists is valid for all files, I did not want to add "Same" comments for every occurance.

Once the documentation is buildable, we can perhaps think about using actual Subheadings for the Example: etc "headings" that are currently just in text style.

crasbe · 2026-04-03T09:08:17Z

+- documentation and tests that make the port maintainable.
+
+This document focuses on the CPU side. For the board side, also refer to the
+existing RIOT guide on porting boards.


It would be nice if you could add a link to said guide.

crasbe · 2026-04-03T09:09:28Z

+└── cpu.c
+```
+
+Not every subdirectory is mandatory, but most non-trivial ports will need at


Maybe you could add an asterisk to the mandatory or non-mandatory files?

crasbe · 2026-04-03T09:11:21Z

+Typical responsibilities:
+
+- define `MODULE = cpu`,
+- include `$(RIOTBASE)/Makefile.base`,
+- optionally add subdirectories such as `periph/`, `vectors/`, or a common CPU
+  family directory.


This feels a bit redundant because that's exactly what's in the code below. I'd probably remove it tbh.

crasbe · 2026-04-03T09:11:54Z

+Typical responsibilities:
+
+- pull in common CPU-family dependency files,
+- select required helper modules


crasbe · 2026-04-03T09:14:32Z

+`cpu.c` contains `cpu_init()`, which performs the minimum hardware and runtime
+initialization needed before RIOT starts normal execution.
+
+Typical responsibilities:
+
+- call generic core initialization for the architecture,
+- set interrupt priorities and interrupt grouping if required,
+- configure clocks or clock assumptions used by the CPU port,
+- perform any CPU-local setup that must happen before peripherals are used.


crasbe · 2026-04-03T09:15:07Z

+corresponding peripheral implementation.
+
+:::note
+Refer to the Technical Reference Manual of the target CPU for details on implementing the boot process.


Suggested change

Refer to the Technical Reference Manual of the target CPU for details on implementing the boot process.

Refer to the Technical Reference Manual of the target CPU for details on

implementing the boot process.

Long line.

crasbe · 2026-04-03T09:19:14Z

+### Reuse common code
+
+If the MCU belongs to an already supported architecture or family, reuse the
+existing common code where possible. For this case, a base directory (e.g. `cpu/<CPU_FAM>_common`) should be created that contains all shared/common configurations. This drastically reduces maintenance and lowers the


crasbe · 2026-04-03T09:19:22Z

+
+### Refer to the manual of the target CPU
+
+Many CPUs are shipped with detailed manuals containing register-level information about peripherals, clock trees, the boot sequence, interrupt handling, and more. This information should be read, understood, and then mapped to the RIOT framework.


riot-ci · 2026-04-03T12:24:49Z

Murdock results

❌ FAILED

41ff982 doc: add CPU porting guide tutorial

Artifacts

crasbe · 2026-04-07T10:48:39Z

I think the last two commits were not meant to be added here? 👀

fjrdev · 2026-04-07T11:13:58Z

I think the last two commits were not meant to be added here? 👀

Oh sorry. you are right! Will fix it + your suggestions asap!

crasbe · 2026-04-07T12:51:48Z

To avoid this kind of issue, it is usually a good idea to create a separate branch for a pull request and not use the master branch. Every change to your fork's master branch is automatically reflected to the PR.

Unfortunately it is not possible to change the branch after opening the PR AFAIK.

fjrdev · 2026-04-07T14:42:28Z

@crasbe Thanks a lot for reviewing! I have added your feedback in the latest version. I will add subheading to the corresponding sections. Can we use # levels here as well?

crasbe · 2026-04-07T15:13:50Z

@AnnsAnns: as our recently graduated CPU-porting expert, would you like to take a look at this too? 👁️👁️

crasbe · 2026-04-07T15:19:52Z

You'll have to add the guide to the Astro configuration file, otherwise it won't show up in the nagivation side bar:

diff --git a/doc/starlight/astro.config.ts b/doc/starlight/astro.config.ts
index 1d6bf1f3d4..06a48f592b 100644
--- a/doc/starlight/astro.config.ts
+++ b/doc/starlight/astro.config.ts
@@ -142,6 +142,7 @@ export default defineConfig({
                 "advanced_tutorials/unittests",
                 "advanced_tutorials/device_drivers",
                 "advanced_tutorials/porting_boards",
+                "advanced_tutorials/porting_cpus",
                 "advanced_tutorials/event_queue",
               ],
             },

AnnsAnns · 2026-04-07T15:37:53Z

For sure will take a look, I was really happy to hear that somebody was working on this when crasbe mentioned this as I wanted to also do something like this, thank you for this PR 🫡

crasbe

Now that the documentation can be built in Starlight, I gave this a more thorough review. Nothing major, just some minor improvements here and there :)

crasbe · 2026-04-07T15:25:34Z

+
+## Build System Files
+
+### `Makefile`


With the Code formatting, our current style file does not respect the sublevel headings:

@AnnsAnns @LasseRosenow is that something that you'd want to fix in the style file or should the use of code formatting just be avoided for sublevel headlines?

I'd personally say just avoid formatting in titles

You'd personally say just avoid formatting in titles? Did I understand that correctly? 🤪

Most normal Github behavior, how is this the default git forge but it can't handle weird internet connections, I was legit just in an ICE on train wifi 😭

crasbe · 2026-04-07T15:27:37Z

+### `Makefile`
+
+The top-level CPU `Makefile` defines the CPU module and may include common
+subdirectories that are shared with other CPUs.


Suggested change

subdirectories that are shared with other CPUs.

subdirectories that are shared with other CPUs. `$(RIOTCPU)` is the `cpu/` subdirectory

of the RIOT basefolder `$(RIOTBASE)`.

crasbe · 2026-04-07T15:28:27Z

+
+This file declares what the CPU provides to the rest of RIOT by defining the
+CPU architecture, including common family feature files as well as defining
+the implemented peripherals with `FEATURES_PROVIDED`.


Suggested change

the implemented peripherals with `FEATURES_PROVIDED`.

the implemented peripherals with `FEATURES_PROVIDED` in alphabetical order.

crasbe · 2026-04-07T15:29:46Z

+
+### `Makefile.include`
+
+This file contains low-level build configuration for the CPU.


Suggested change

This file contains low-level build configuration for the CPU.

This file contains low-level build configuration and additional compiler and

linker search paths for the CPU.

AnnsAnns

Either the wifi is too spotty or github is having problems so I'll have to halt my review for now since I'm getting a lot of errors, so far this was a nice read though 👍

AnnsAnns · 2026-04-07T16:17:52Z

+
+## Build System Files
+
+### `Makefile`


I'd personally say just avoid formatting in titles

AnnsAnns · 2026-04-07T16:18:08Z

+
+## Build System Files
+
+### `Makefile`


I'd personally say just avoid formatting in titles

fjrdev · 2026-04-20T10:25:22Z

@crasbe @AnnsAnns Thanks a lot for the helpful feedback and your time! I have included your suggestions in the guide :)

AnnsAnns

Read through it again, looks good for the most part, just one minor nitpick from my side left

crasbe

You know that you can run make doc-starlight locally to check if it works, right? 👀

AnnsAnns · 2026-04-29T10:17:17Z

I'd recommend looking at https://guide.riot-os.org/misc/how_to_doc/#how-to-run-the-site-locally if something is not working, otherwise feel free to reach out for help

fjrdev · 2026-05-04T09:45:36Z

You know that you can run make doc-starlight locally to check if it works, right? 👀

Didn't know that, thanks for pointing out! :D

crasbe

IMO this is good to go now. Thank you!

@AnnsAnns what do you think?

AnnsAnns

Looks good :)

Please squash everything down and then we are good to go!

crasbe · 2026-05-18T10:13:04Z

Unfortunately there is now a merge conflict after #22254 was merged, but that should be easy to resolve.

We have a short section about how to deal with merge conflicts in our Contibution Guidelines: https://doc.riot-os.org/general/contributing/#squash-commits-after-review

If you need additional help, let me know :)

basilfx · 2026-05-18T12:19:13Z

+- get `examples/basic/hello-world` running over UART,
+- if UART output is missing, toggle an LED at key checkpoints in startup and
+  `cpu_init()` to localize where execution stops,
+- validate one timer instance so `ztimer` works,


Which test would be advised to run?

basilfx · 2026-05-18T12:22:34Z

+
+- `examples/basic/hello-world` for startup and UART,
+- `tests/periph_gpio` or GPIO-based samples for pin control,
+- timer-based examples for `periph_timer` and `ztimer`,


Suggested change

- timer-based examples for `periph_timer` and `ztimer`,

- timer-based tests for `periph_timer` and `ztimer`,

- refer to test applications in `tests/periph/timer` and `sys/ztimer*`

Something like this, to refer them to exact locations.

AnnsAnns · 2026-07-15T14:06:01Z

This PR is fairly close to the finish line, are you still interested in getting this merged, its really useful @fjrdev

fjrdev requested review from AnnsAnns, aabadie and jia200x as code owners April 2, 2026 15:01

github-actions Bot added the Area: doc Area: Documentation label Apr 2, 2026

crasbe reviewed Apr 3, 2026

View reviewed changes

crasbe changed the title ~~add guide for porting new MCUs~~ doc/guides: add guide for porting new MCUs Apr 3, 2026

fjrdev requested review from MichelRottleuthner, MrKevinWeiss and leandrolanzieri as code owners April 7, 2026 10:11

github-actions Bot added Area: tests Area: tests and testing framework Area: build system Area: Build system Area: drivers Area: Device drivers Area: boards Area: Board ports Area: cpu Area: CPU/MCU ports Area: Kconfig Area: Kconfig integration labels Apr 7, 2026

fjrdev force-pushed the master branch from 2c89970 to 6f89055 Compare April 7, 2026 12:33

github-actions Bot removed Area: tests Area: tests and testing framework Area: build system Area: Build system Area: drivers Area: Device drivers Area: boards Area: Board ports Area: cpu Area: CPU/MCU ports Area: Kconfig Area: Kconfig integration labels Apr 7, 2026

fjrdev mentioned this pull request Apr 7, 2026

adding support for new MCU (Infineon PSOC-6) along with new board (PSOC-6 AI Kit) #22178

Draft

crasbe reviewed Apr 7, 2026

View reviewed changes

Comment thread doc/guides/advanced_tutorials/porting_cpus.md Outdated

crasbe reviewed Apr 7, 2026

View reviewed changes

AnnsAnns reviewed Apr 7, 2026

View reviewed changes

crasbe reviewed Apr 20, 2026

View reviewed changes

Comment thread doc/starlight/astro.config.ts Outdated

fjrdev force-pushed the master branch from 6e8795f to 182d3f8 Compare April 20, 2026 11:22

AnnsAnns requested changes Apr 21, 2026

View reviewed changes

Comment thread doc/guides/advanced_tutorials/porting_cpus.md Outdated

Comment thread doc/guides/advanced_tutorials/porting_cpus.mdx

AnnsAnns reviewed Apr 22, 2026

View reviewed changes

Comment thread doc/guides/advanced_tutorials/porting_cpus.md Outdated

fjrdev force-pushed the master branch from 5cad12c to 130acd3 Compare April 29, 2026 06:57

crasbe requested changes Apr 29, 2026

View reviewed changes

Comment thread doc/guides/advanced_tutorials/porting_cpus.mdx Outdated

Comment thread doc/guides/advanced_tutorials/porting_cpus.mdx Outdated

Comment thread doc/guides/advanced_tutorials/porting_cpus.mdx Outdated

crasbe approved these changes May 4, 2026

View reviewed changes

AnnsAnns approved these changes May 7, 2026

View reviewed changes

crasbe mentioned this pull request May 9, 2026

Should we sunset the Wiki? #22265

Open

doc: add CPU porting guide tutorial

41ff982

fjrdev force-pushed the master branch from f6c6376 to 41ff982 Compare May 18, 2026 09:59

basilfx reviewed May 18, 2026

View reviewed changes

AnnsAnns added the State: waiting for author State: Action by the author of the PR is required label Jul 15, 2026

	Refer to the Technical Reference Manual of the target CPU for details on implementing the boot process.
	Refer to the Technical Reference Manual of the target CPU for details on
	implementing the boot process.


		### Refer to the manual of the target CPU

		Many CPUs are shipped with detailed manuals containing register-level information about peripherals, clock trees, the boot sequence, interrupt handling, and more. This information should be read, understood, and then mapped to the RIOT framework.

	subdirectories that are shared with other CPUs.
	subdirectories that are shared with other CPUs. `$(RIOTCPU)` is the `cpu/` subdirectory
	of the RIOT basefolder `$(RIOTBASE)`.

	the implemented peripherals with `FEATURES_PROVIDED`.
	the implemented peripherals with `FEATURES_PROVIDED` in alphabetical order.


		### `Makefile.include`

		This file contains low-level build configuration for the CPU.

	This file contains low-level build configuration for the CPU.
	This file contains low-level build configuration and additional compiler and
	linker search paths for the CPU.

	- timer-based examples for `periph_timer` and `ztimer`,
	- timer-based tests for `periph_timer` and `ztimer`,
	- refer to test applications in `tests/periph/timer` and `sys/ztimer*`

Uh oh!

Conversation

fjrdev commented Apr 2, 2026

Contribution description

Testing procedure

Issues/PRs references

Declaration of AI-Tools / LLMs usage:

Uh oh!

crasbe commented Apr 3, 2026

Uh oh!

crasbe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

riot-ci commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Murdock results

Artifacts

Uh oh!

crasbe commented Apr 7, 2026

Uh oh!

fjrdev commented Apr 7, 2026

Uh oh!

crasbe commented Apr 7, 2026

Uh oh!

Uh oh!

fjrdev commented Apr 7, 2026

Uh oh!

crasbe commented Apr 7, 2026

Uh oh!

crasbe commented Apr 7, 2026

Uh oh!

AnnsAnns commented Apr 7, 2026

Uh oh!

crasbe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnnsAnns Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

riot-ci commented Apr 3, 2026 •

edited

Loading

AnnsAnns Apr 7, 2026 •

edited

Loading