doc/doxygen: add build system doc page for BOARD, CPU, FEATURE #12473

fjmolinas · 2019-10-16T15:50:29Z

Contribution description

This PR is part of #8420 and tries to get to a definition of what a BOARD, CPU and FEATURE is. Having an agreement on this should help resolving discussion on #11676 and others about what a FEATURE is and how it should be used. This should also help maintainability by having an agreement on the definition.

Testing procedure

Do you agree with the definitions?
Does naming make sense?
Does the placing make sense?

Issues/PRs references

Part of #8420

fjmolinas · 2019-10-16T15:51:25Z

@cladmi if you can take a look and see if this makes sense with the global picture you had for these concepts/variables in the build system scope it would be much appreciated :)

cladmi

This summarize well what I had also understood of the RIOT build system for BOARD/CPU/FEATURES.
It describe the currently expected state. It is not always respected and still has flaws but at least gives a common explanation.
I had my dirty version in #10062 (comment)

This document does not explain "why" it is this way but keeping with this allows releasing it as reference.
I got stuck not writing a similar document because I wanted to have the why and ended up with nothing.

On features a lot more could be said with with the policy/dependency resolution that somehow explain why it is this way, the limitation, the future, but is a big task on its own so good to not include it in there.

doc/doxygen/src/board-cpu-features.md

cladmi · 2019-10-30T11:49:12Z

Somehow, the fact that I only stayed in tracking issues tells me that there would have been good to have a place for documenting these earlier in the repository. To allow moving the still not entirely precise issues to the repository in a better formatted document.
I had issues writing these as documentation when my mind was not clear and there were 100 exceptions to this.

Not an RDM as it just representing what is supposed to be there and in a more loose format.
And still allow having things that are not yet in the repository but would seal the agreement on the evolutions.

It would also push to have documentation first for these things and prevent things that go against the documentation just because somebody wants it his way.

aabadie

I llke this document, it makes things clearer with features. Maybe you could also add some words about: where features are provided (in Makefile.features), where features are required (in application Makefile or Makefile.dep) and eventually some words about the FEATURES_USED variable ?

aabadie · 2019-12-16T10:19:14Z

doc/doxygen/src/board-cpu-features.md

+FEATURES                                                             {#features}
+========
+
+`FEATURES_PROVIDED` are hardware (including toolchain) features (e.g.:`periph_hwrng`,


Suggested change

`FEATURES_PROVIDED` are hardware (including toolchain) features (e.g.:`periph_hwrng`,

`FEATURES_PROVIDED` are available hardware (including toolchain) features (e.g.:`periph_hwrng`,

aabadie · 2019-12-16T10:19:41Z

doc/doxygen/src/board-cpu-features.md

+========
+
+`FEATURES_PROVIDED` are hardware (including toolchain) features (e.g.:`periph_hwrng`,
+`periph_uart`) that are available or characteristics (e.g:`arch_32bits`) of a board.


Suggested change

`periph_uart`) that are available or characteristics (e.g:`arch_32bits`) of a board.

`periph_uart`) or characteristics (e.g:`arch_32bits`) of a board/cpu.

aabadie · 2019-12-16T10:19:52Z

doc/doxygen/src/board-cpu-features.md

+`periph_uart`) that are available or characteristics (e.g:`arch_32bits`) of a board.
+
+Providing a `FEATURE`
+--------------------


Suggested change

--------------------

---------------------

aabadie · 2019-12-16T10:20:26Z

doc/doxygen/src/board-cpu-features.md

+--------------------
+
+For a `FEATURE` to be provided by a `board` it must meet 2 criteria, and for
+`periph` and other `hw` it must follow the 3rd criteria.


What is hw ?

aabadie · 2019-12-16T10:20:47Z

doc/doxygen/src/board-cpu-features.md

+--------------------
+
+For a `FEATURE` to be provided by a `board` it must meet 2 criteria, and for
+`periph` and other `hw` it must follow the 3rd criteria.


Suggested change

`periph` and other `hw` it must follow the 3rd criteria.

`periph` and other `hw` it must follow a 3rd criteria.

aabadie · 2019-12-16T10:27:02Z

doc/doxygen/src/board-cpu-features.md

+CPU/CPU_MODEL                                                             {#cpu}
+======
+
+`CPU` and `CPU_MODEL` refer to the `SOC` (system on a chip) or `MCU` (microcontroller)


SOC was already used earlier but not defined. I would move the definition when it's used the first time. Also no need to "highlight" it with backticks. Same for MCU. Maybe use italic ?

doc/doxygen/src/board-cpu-features.md

aabadie · 2019-12-16T10:27:50Z

doc/doxygen/src/board-cpu-features.md

+and the way each manufacturer groups there products.
+
+These variables allows declaring the `FEATURES` that the mcu/soc provides as well
+resolving dependencies.


Suggested change

resolving dependencies.

as resolving dependencies.

aabadie · 2019-12-16T10:29:32Z

doc/doxygen/src/board-cpu-features.md

+BOARDS                                                                 {#boards}
+======
+
+In RIOT build-system terms a `BOARD` is a grouping of:


Suggested change

In RIOT build-system terms a `BOARD` is a grouping of:

In the RIOT build-system, the variable `BOARD` is a grouping of:

I don't agree with the need of mentioning variable.

ok, but add a comma after terms, this is more readable.

aabadie · 2019-12-16T10:30:13Z

doc/doxygen/src/board-cpu-features.md

+sensor/actuator, but it doesn't necessarily provide that `FEATURE`.
+
+e.g.:
+    - `samr21-xpro` provides a `at86r233` radio as well as the necessary


Suggested change

- `samr21-xpro` provides a `at86r233` radio as well as the necessary

- `samr21-xpro` provides a `at86rf233` radio as well as the necessary

fjmolinas · 2020-01-14T15:27:07Z

@aabadie addressed your typo comments and requested for more info in two commits.

aabadie · 2020-01-14T17:44:48Z

addressed your typo comments and requested for more info in two commits.

I still see unaddressed comments. Did you forget to push ?

fjmolinas · 2020-01-14T21:08:54Z

I still see unaddressed comments. Did you forget to push ?

Damn I did, will address tomorrow

fjmolinas · 2020-01-15T08:12:27Z

@aabadie rebased and now your comments are addressed please take a look.

fjmolinas · 2020-01-15T12:42:30Z

ping @aabadie

aabadie

All my comments are addressed and the document is now IMHO in a good shape.

ACK

aabadie · 2020-01-15T12:49:49Z

Please fix the remaining whitespaces, you can squash directly.

fjmolinas · 2020-01-15T12:59:10Z

@aabadie Maybe I should move this to the build-system-basics page? seems a little weird standing alone.

fjmolinas · 2020-01-15T14:54:51Z

@aabadie Maybe I should move this to the build-system-basics page? seems a little weird standing alone.

Got ACK to do it ~~IRL~~ Offline.

aabadie · 2020-01-15T15:03:10Z

I generated the doc locally and it looks nice. My ACK holds :)

fjmolinas added Area: doc Area: Documentation Area: build system Area: Build system Discussion: RFC The issue/PR is used as a discussion starting point about the item of the issue/PR labels Oct 16, 2019

cladmi reviewed Oct 30, 2019

View reviewed changes

This was referenced Nov 18, 2019

make: improve handling of the stdio_rtt module, improve dependency management at application level #12724

Merged

Makefile.dep: make stdio_uart a feature required by ethos #12739

Closed

fjmolinas requested a review from aabadie December 14, 2019 18:14

fjmolinas mentioned this pull request Dec 15, 2019

Makefile.features: add driver_% provided features and FEATURES_REQUIRED_DRIVERS #12952

Closed

aabadie requested changes Dec 16, 2019

View reviewed changes

fjmolinas added this to the Release 2020.01 milestone Dec 16, 2019

fjmolinas force-pushed the pr_board_cpu_features_doc branch from c6b789d to 692ae71 Compare January 15, 2020 08:11

aabadie approved these changes Jan 15, 2020

View reviewed changes

fjmolinas force-pushed the pr_board_cpu_features_doc branch from 692ae71 to e31c07d Compare January 15, 2020 12:55

doc/doxygen: add build system doc page for BOARD, CPU, FEATURE

963ec79

fjmolinas force-pushed the pr_board_cpu_features_doc branch from e31c07d to 963ec79 Compare January 15, 2020 14:53

fjmolinas added the CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR label Jan 15, 2020

aabadie merged commit 784920b into RIOT-OS:master Jan 15, 2020

fjmolinas deleted the pr_board_cpu_features_doc branch April 24, 2020 13:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc/doxygen: add build system doc page for BOARD, CPU, FEATURE #12473

doc/doxygen: add build system doc page for BOARD, CPU, FEATURE #12473

fjmolinas commented Oct 16, 2019 •

edited

Loading

fjmolinas commented Oct 16, 2019

cladmi left a comment

cladmi commented Oct 30, 2019

aabadie left a comment

aabadie Dec 16, 2019

aabadie Dec 16, 2019

aabadie Dec 16, 2019

aabadie Dec 16, 2019

aabadie Dec 16, 2019

aabadie Dec 16, 2019

aabadie Dec 16, 2019

aabadie Dec 16, 2019

fjmolinas Jan 14, 2020

aabadie Jan 14, 2020

aabadie Dec 16, 2019

fjmolinas commented Jan 14, 2020

aabadie commented Jan 14, 2020

fjmolinas commented Jan 14, 2020

fjmolinas commented Jan 15, 2020

fjmolinas commented Jan 15, 2020

aabadie left a comment

aabadie commented Jan 15, 2020

fjmolinas commented Jan 15, 2020

fjmolinas commented Jan 15, 2020 •

edited

Loading

aabadie commented Jan 15, 2020

	`FEATURES_PROVIDED` are hardware (including toolchain) features (e.g.:`periph_hwrng`,
	`FEATURES_PROVIDED` are available hardware (including toolchain) features (e.g.:`periph_hwrng`,

	`periph_uart`) that are available or characteristics (e.g:`arch_32bits`) of a board.
	`periph_uart`) or characteristics (e.g:`arch_32bits`) of a board/cpu.

	`periph` and other `hw` it must follow the 3rd criteria.
	`periph` and other `hw` it must follow a 3rd criteria.

	In RIOT build-system terms a `BOARD` is a grouping of:
	In the RIOT build-system, the variable `BOARD` is a grouping of:

	- `samr21-xpro` provides a `at86r233` radio as well as the necessary
	- `samr21-xpro` provides a `at86rf233` radio as well as the necessary

doc/doxygen: add build system doc page for BOARD, CPU, FEATURE #12473

doc/doxygen: add build system doc page for BOARD, CPU, FEATURE #12473

Conversation

fjmolinas commented Oct 16, 2019 • edited Loading

Contribution description

Testing procedure

Issues/PRs references

fjmolinas commented Oct 16, 2019

cladmi left a comment

Choose a reason for hiding this comment

cladmi commented Oct 30, 2019

aabadie left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fjmolinas commented Jan 14, 2020

aabadie commented Jan 14, 2020

fjmolinas commented Jan 14, 2020

fjmolinas commented Jan 15, 2020

fjmolinas commented Jan 15, 2020

aabadie left a comment

Choose a reason for hiding this comment

aabadie commented Jan 15, 2020

fjmolinas commented Jan 15, 2020

fjmolinas commented Jan 15, 2020 • edited Loading

aabadie commented Jan 15, 2020

fjmolinas commented Oct 16, 2019 •

edited

Loading

fjmolinas commented Jan 15, 2020 •

edited

Loading