Document interfaces that should be implemented by boards platforms

[matthijskooijman]

Describe the request

We need some more exhaustive documentation about the "interface" that a core or variant should expose.

In particular:

• All of the required keys in platform.txt, boards.txt and programmers.txt, and what they are used for, should be listed. These keys form the "external interface" of the core, which can be used by the IDE or arduino-builder. A core can also contain arbitrary other keys, which are used for variable substitutions internally, but cannot be relied on to exist is all cores. Currently, this distinction is blurry and ad-hoc.
• All of the macros, functions and variables that a variant of the Arduino core should expose should be documented. Some of these are mean to be used by the sketch directly (and should actually be documented as part of the normal Arduino reference), but some of them are only used internally by the Arduino core as part of another API. Currently, no definitive list of these exists, making variants (both third-party and Arduino ones) inconsistent or incomplete.

Both of these pieces of documentation should be updated when the requirements change in future IDE or core versions, with the changes mentioned explicitly and with the IDE or core version that introduced them.

Describe the current behavior

The **Arduino Platform Specification documents a good deal of the structure and has examples, but is not exhaustive or explicit.

Additional context

Related

• Provide dedicated sets of "extra flags" properties for platform developers and users #846
• Recommend defining standardized MCU and CPU identification macros in platform specification #988
• feature request: add board name string to compile defines in platform.txt file #1007
• reducing arch specific #ifdefs in Firmata lib with better alignment across variant files #1030
• I can not find the platform.local.txt documentation. Arduino#3371
• align constants across core board variants Arduino#3681
• documentation missing: clear overview for identification of boards: supersets, subsets, and single boards docs-content#359

Additional requests

• Preprocessor define to identify compiling with Arduino-IDE/CLI #2751
• https://forum.arduino.cc/t/how-does-ide2-compile-multiple-in-files/1325307/8

Issue checklist

• I searched for previous requests in the issue tracker
• I verified the feature was still missing when using the latest nightly build
• My request contains all necessary details

[matthijskooijman]

One additional angle should be covered: The interface that the Arduino core offers to its variants and derived (board-only) platforms. E.g., what variables does each tool, recipe, programmer, etc. assume are present and how they are used.

[per1234]

Other thing that should be documented(assuming it's the intended behavior) is that Burn Bootloader uses the platform.txt of the selected board but Upload Using Programmer uses the platform.txt of the selected programmer. This has caused confusion for me and at least two other 3rd party cores because it wasn't documented(see arduino/Arduino#2886 and SpenceKonde/ATTinyCore@9c50151).

Edit: I've added this information to the wiki.

[matthijskooijman]

Also note this proposal I made (quite) a while ago already, which suggests to apply some versioning scheme to these interfaces, to make it easier to change them in the future while keeping compatibility: https://groups.google.com/a/arduino.cc/g/developers/c/H6vCRlgRTCo/m/22oQfVY3AgAJ

[matthijskooijman]

I just noticed that in the area of versioning, the SAMD core already applies some versioning to its variants by letting the variants define a constant to indicate what version of the core-variant interface they implement (I think). I dont' think there's any specific documentation about what this version number implies exactly, though.

See: https://github.com/arduino/ArduinoCore-samd/blob/56e13aa5ebb21f8aca8805e2bc0835a1f1fea372/cores/arduino/Arduino.h#L52

[ianfixes]

Subscribing for interest, via Arduino-CI/arduino_ci#251

I am trying to put boundaries around what would be considered the proper set of compilation mocks for Arduino, and the lack of official documentation on stuff like these:

#define portOutputRegister(P) ( (volatile uint8_t *)( pgm_read_word( port_to_output_PGM + (P))) )
#define portInputRegister(P) ( (volatile uint8_t *)( pgm_read_word( port_to_input_PGM + (P))) )
#define portModeRegister(P) ( (volatile uint8_t *)( pgm_read_word( port_to_mode_PGM + (P))) )

I can't find any official-looking documentation to say whether these are meant to exist for the long term and/or what their function should be (so that I can create proper unit tests for my mockups of them).