Where is the documentation for writing an Arduino core?

Question

I'm interested in writing an "Arduino core" (i. e. porting Arduino to a new MCU and new board(s)). I'm having trouble finding much documentation on how to do so. Am I missing something?

This page says "anyone may develop a core for their own boards following the rules and requirements we have issued." So, where are those "rules and requirements?"

I found something called the "Platform Specification", which sounded promising, but it only documents the config files; it does not say anything about the code that needs to be written to support a new platform.

I found ArduinoCore-API, which says it is the "hardware independent layer of Arduino core." But it doesn't mention anything about how to write the hardware-dependent part of the core.

I'd be grateful if anyone could point me to the Arduino core documentation. It's not turning up in my web searches. Thanks!

Clarifications:

• Yes, I can look at existing cores as examples, but I'd rather have the documentation, as well. Especially since existing cores may be of varying quality, or may not be up to the latest standard. Documentation is always a good thing.
• The reason I want to write a core is because... I want to use an MCU which is not currently supported! (Specifically, I want to add support for the GD32F350, but really that shouldn't be relevant to answering "Where is the documentation?")

Answer 1

There are two major parts to writing an Arduino core: the hardware independent portions and the hardware dependent.

The hardware independent portions are pretty much done for you in the ArduinoCore-API. However I wouldn't just use that verbatim but use it as a starting point and adapt it to your needs. This is because it actually has a couple of unresolved issues and not everything may 100% fit your needs. We don't use it for the chipKIT core because:

• It has an unresolved issue around the naming of the String.h file which conflicts with the libc's string.h on case insensitive filesystems
• Our USB stack is vastly different to how the Arduino "Pluggable USB" works
• We have extra facilities in a number of standard objects to make use of more efficient use of more advanced hardware

Once you have the hardware independent portion sorted you need to write, from scratch, the hardware dependent portion. The basic list of functions you need to implement are listed in the Arduino reference. How you write them cannot be documented, since that depends on the hardware. And you may well need to (or want to) write considerably more functions that just those. For example on chipKIT as well as the standard analogWrite() function we also have functions to change the PWM frequency and resolution - things that aren't part of the "standard", but are incredibly useful.

A good starting point is to examine the Arduino.h file of an existing core (the AVR core is a good baseline) which will list most of the functions and their parameter/return types. That gives you what the functions expect to receive and what they should emit, but how those functions are written is completely down to you.

And then of course you have to implement the boards variants etc to make the whole things work...

Also, be warned that writing (and maintaining) a core is a long and involved process and will consume the rest of your life.