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

✔️ PASSED

f6c6376 doc: resolved build issues

Success	Failures	Total	Runtime
1	0	1	03m:54s

Artifacts

Documentation preview

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:23:35Z

+A practical CPU porting workflow usually looks like this:
+
+1. create the CPU directory and build-system files,
+2. add startup support and a working `cpu_init()`,


Suggested change

2. add startup support and a working `cpu_init()`,

2. add startup support and a working `cpu_init()` function,

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.

crasbe · 2026-04-07T15:47:14Z

+### Generic high-level shape
+
+```c
+spi_init(bus);
+spi_init_cs(bus, cs);
+
+spi_acquire(bus, cs, SPI_MODE_0, SPI_CLK_1MHZ);
+spi_transfer_bytes(bus, cs, false, tx_buf, rx_buf, len);
+spi_release(bus);
+```


This would be application/device driver level though.

Is it too specific? Thought this would be nice as an addition to the bullet points above this snippet

Perhaps you could specify that this is not part of the CPU code but just given as an example to clarify how the functions will be called on the application/driver level.

crasbe · 2026-04-07T15:48:54Z

+
+- boot to `cpu_init()`,
+- confirm the vector table works,
+- get `examples/basic/hello-world` running over UART,


I'd probably include something like "light up an LED at different stages of the code if you don't observe output on the UART". That often helped me in the past.

crasbe · 2026-04-07T15:49:11Z

+### 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


Suggested change

existing common code where possible. For this case, a base directory

existing common code where possible. In this case, a base directory

crasbe · 2026-04-07T15:49:51Z

+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 risk of
+subtle startup or interrupt bugs.


Suggested change

subtle startup or interrupt bugs.

subtle startup or interrupt bugs, as well as code divergation issues in the future.

crasbe · 2026-04-07T15:51:05Z

+Correct handling of repeated starts, ACK/NACK conditions, and bus-busy recovery
+is more important than adding optional optimizations early.
+
+## General Recommendations


I wonder if this chapter wouldn't have a better home further on top. Currently this is a repetition of many things that were already explained in greater detail 🤔

I put this chapter at the end to wrap-up the sections explaining the different directories/files. Moving it at the top would put the mentioning of some concepts/files above the explanation wouldn't it? maybe im missing your point

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

AnnsAnns · 2026-04-22T08:43:33Z

+{% filetree %}
+- cpu/foo
+  - include
+    - cpu_conf.h
+    - periph_cpu.h
+    - vendor*
+  - ldscripts*
+  - periph*
+    - gpio.c
+    - i2c.c
+    - spi.c
+    - …
+  - vectors
+    - vectors_<model>.c
+  - Makefile
+  - Makefile.dep*
+  - Makefile.features*
+  - Makefile.include
+  - cpu.c
+{% /filetree %}


Suggested change

{% filetree %}

- cpu/foo

- include

- cpu_conf.h

- periph_cpu.h

- vendor*

- ldscripts*

- periph*

- gpio.c

- i2c.c

- spi.c

- …

- vectors

- vectors_<model>.c

- Makefile

- Makefile.dep*

- Makefile.features*

- Makefile.include

- cpu.c

{% /filetree %}

<FileTree>

- cpu/foo

- include

- cpu_conf.h

- periph_cpu.h

- vendor*

- ldscripts*

- periph*

- gpio.c

- i2c.c

- spi.c

- …

- vectors

- vectors_<model>.c

- Makefile

- Makefile.dep*

- Makefile.features*

- Makefile.include

- cpu.c

</FileTree>

That syntax is for Markdoc, we use MDX. To use this component rename the file to "porting_cpus.mdx" and also import import { FileTree } from '@astrojs/starlight/components'; at the top of the file. See: https://guide.riot-os.org/misc/how_to_doc/ and https://starlight.astro.build/components/file-tree/ for the component itself

Thank you for pointing this out! I updated to mdx in the last commit.

crasbe

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

crasbe · 2026-04-29T09:10:17Z

+- architecture-common code such as `cpu/cortexm_common/` when porting
+  Cortex-M-based MCUs
+- merged RIOT PRs adding CPU support, for reference and pattern matching:
+  <https://github.com/RIOT-OS/RIOT/pulls?q=is%3Apr+is%3Amerged+%22cpu%2F%22+%22boards%2F%22>


Suggested change

<https://github.com/RIOT-OS/RIOT/pulls?q=is%3Apr+is%3Amerged+%22cpu%2F%22+%22boards%2F%22>

[see GitHub](https://github.com/RIOT-OS/RIOT/pulls?q=is%3Apr+is%3Amerged+%22cpu%2F%22+%22boards%2F%22)

To fix the build error:

11:07:49 [ERROR] Unexpected character `/` (U+002F) before local name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a link in MDX, use `[text](url)`) Stack trace: at /home/cbuec/RIOTstuff/riot-vanillaice/RIOT/doc/guides/advanced_tutorials/porting_cpus.mdx:650:10 [...] See full stack trace in the browser, or rerun with --verbose.

crasbe · 2026-04-29T09:14:53Z

+description: Guide on how to port new CPU families to RIOT-OS
+---
+
+import { FileTree } from '@astrojs/starlight/components';


Suggested change

import { FileTree } from '@astrojs/starlight/components';

import FileTree from '@components/FileTree.astro';

To fix the next occurring issue:

11:11:12 [ERROR] Cannot find module '@astrojs/starlight/components' imported from '/home/cbuec/RIOTstuff/riot-vanillaice/RIOT/doc/guides/advanced_tutorials/porting_cpus.mdx' Stack trace: at fetchModule (file:///home/cbuec/RIOTstuff/riot-vanillaice/RIOT/doc/starlight/node_modules/vite/dist/node/chunks/config.js:33980:34) [...] See full stack trace in the browser, or rerun with --verbose.

I just saw that I recommended this line. Sorry for suggesting something incorrect 🫨

No, it was @AnnsAnns, not me 👀

crasbe · 2026-04-29T09:14:59Z

+    - spi.c
+    - …
+  - vectors
+    - vectors_<model>.c


Suggested change

- vectors_<model>.c

- vectors_\<model\>.c

To fix the next error:

11:10:05 [ERROR] Expected a closing tag for `<model>` (50:15-50:22) before the end of `paragraph` Stack trace: at /home/cbuec/RIOTstuff/riot-vanillaice/RIOT/doc/guides/advanced_tutorials/porting_cpus.mdx:50:7 [...] See full stack trace in the browser, or rerun with --verbose.

Thanks for the suggestions! I have resolved the build issues in the newest commit

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?

add guide for porting new MCUs

6f89055

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 and others added 7 commits April 20, 2026 13:22

doc: revise CPU guide updates

d8c5416

doc: add starlight frontmatter to CPU porting guide

f7e56e2

doc: address CPU porting guide review feedback

273edba

doc(starlight): add CPU porting guide to advanced tutorials nav

85d8e65

doc(starlight): align advanced tutorials nav entry

a092521

doc: revise text and formatting for CPU guide

4b4cd24

doc: fix trailing whitespace in CPU porting guide

182d3f8

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

fjrdev and others added 2 commits April 29, 2026 08:57

doc: update CPU guide board-porting link

0569e06

doc: move CPU porting guide to mdx

130acd3

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

doc: resolved build issues

f6c6376

crasbe approved these changes May 4, 2026

View reviewed changes

	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.

	2. add startup support and a working `cpu_init()`,
	2. add startup support and a working `cpu_init()` function,

	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.

	existing common code where possible. For this case, a base directory
	existing common code where possible. In this case, a base directory

	subtle startup or interrupt bugs.
	subtle startup or interrupt bugs, as well as code divergation issues in the future.

	<https://github.com/RIOT-OS/RIOT/pulls?q=is%3Apr+is%3Amerged+%22cpu%2F%22+%22boards%2F%22>
	[see GitHub](https://github.com/RIOT-OS/RIOT/pulls?q=is%3Apr+is%3Amerged+%22cpu%2F%22+%22boards%2F%22)

	import { FileTree } from '@astrojs/starlight/components';
	import FileTree from '@components/FileTree.astro';

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!

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!

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!

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

riot-ci commented Apr 3, 2026 •

edited

Loading

AnnsAnns Apr 7, 2026 •

edited

Loading

AnnsAnns Apr 22, 2026 •

edited

Loading