Document interfaces that should be implemented by boards platforms

matthijskooijman commented 9 years ago

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

Additional requests

Issue checklist

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

matthijskooijman commented 9 years ago

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 commented 9 years ago

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 https://github.com/arduino/Arduino/issues/2886 and https://github.com/SpenceKonde/ATTinyCore/commit/9c501518037cfa78242500e5749e15ccce3418c8).

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

matthijskooijman commented 4 years ago

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 commented 3 years ago

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 commented 3 years ago

Subscribing for interest, via https://github.com/Arduino-CI/arduino_ci/issues/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).

arduino / arduino-cli