doc: boards: extensions: Add Sphinx directive for board supported hardware

[kartben]

Introduce a new directive for displaying hardware features supported by a board, using information available in the Devicetree.

It outputs a table for each board target, where the table contains type of hw peripheral / description / link to documentation of the binding.

As a way to demonstrate the feature in action, documentation of the BBC micro:bit boards has been updated to adopt the new directive.

Only the last commit is relevant, the rest is tackled in #79754.

Same as other PR: due to this PR updating the doc-build.yml workflow, it's not publishing the CI output to builds.zephyrproject.io ; best way to test the actual user experience is to get the most recent successful build from my fork (https://github.com/kartben/zephyr/actions/workflows/doc-build.yml?query=event%3Aschedule), download the html-output artifact, unzip it, and open index.html in a browser

An obvious improvement opprtunity will be to use tabs for the various board targets ; it is, interestingly enough, not that easy to do elegantly, so hopefully people are fine if this comes at a later stage :) In any case, only boards that "opt-in" to migrate to using the new directive will get the new table(s) anyway, so it's not like it's going to directly impact users :)

[jerome-pouiller]

For "SiLabs SiWx917", we plan to support additional devices: adc, pwm, spi, etc... Because the limited number of pins, we won't be able to set status = "okay"; on all the devices. Yet, I believe all these device should be mentioned in the documentation.

Maybe one of the solution would be to consider all the nodes with status = "okay" and all the nodes with a pinctrl attribute? However, I am not sure it would cover the cases.

[kartben]

@jerome-pouiller thanks for the input! It feels like status = "reserved" could maybe be used as a way to flag those nodes that are "virtually OK"? Or maybe some similar custom status that indicates that as far as Devicetree is concerned the peripheral is properly configured, but there is some action needed from the user (ideally indicated as a comment on the node, I guess!) before they actually okay it for it e.g. requires a competing peripheral to be disabled first.

[kartben]

Rebased on main now that #79754 has been merged.
No other change since #85652 (comment)

[dleach02]

@jerome-pouiller thanks for the input! It feels like status = "reserved" could maybe be used as a way to flag those nodes that are "virtually OK"? Or maybe some similar custom status that indicates that as far as Devicetree is concerned the peripheral is properly configured, but there is some action needed from the user (ideally indicated as a comment on the node, I guess!) before they actually okay it for it e.g. requires a competing peripheral to be disabled first.

@kartben what is wrong with just using the presence of the node as indicative of support regardless of "Okay" or "disabled"?

[erwango]

@kartben what is wrong with just using the presence of the node as indicative of support regardless of "Okay" or "disabled"?

Optionally, but it would make things event more complex, we can instantiate 2 kind of searches:

• "Boards search", limiting search to "Okay" nodes -> In case you want to know what is available out of the box
• "SoCs search", extending search to "disabled" nodes -> In case you want to know what is potentially available

[jerome-pouiller]

What about to differentiate the disabled nodes with a color or style? eg. Dark gray text on light gray background?

[kartben]

@jerome-pouiller thanks for the input! It feels like status = "reserved" could maybe be used as a way to flag those nodes that are "virtually OK"? Or maybe some similar custom status that indicates that as far as Devicetree is concerned the peripheral is properly configured, but there is some action needed from the user (ideally indicated as a comment on the node, I guess!) before they actually okay it for it e.g. requires a competing peripheral to be disabled first.

@kartben what is wrong with just using the presence of the node as indicative of support regardless of "Okay" or "disabled"?

@dleach02
There are many boards in-tree built on a reasonably capable MCU but that just happen to have a form factor such that some peripherals are simply not usable, no matter how hard you try, for they're not physically exposed. Think e.g. this guy https://docs.zephyrproject.org/latest/boards/ezurio/bl654_usb/doc/bl654_usb.html - it wouldn't make sense to say the "board" has QDEC support since it's not using it internally, let alone exposing pins enabling users to use it.

Optionally, but it would make things event more complex, we can instantiate 2 kind of searches [...]

I actually like that idea. I think we would still want the table of supported features to limit itself to only what's actually "okay", but for search, yeah, the users could check a "Show SoC peripherals" checkbox (unchecked by default) or something. Checking the box would remove the filtering on okay nodes to instead take into account all nodes.

Users would then have a rough idea of things that they may be able to enable on a given board and what the underlying SoC has to offer (but doesn't necessarily support btw: the presence of a matching "compatible" is no guarantee that the driver doesn't throw some kind of #error SoC family not yet supported)

[kartben]

@henrikbrixandersen please revisit as I believe your comment has been addressed.

[sylvioalves]

The PR looks very good!

I want to bring the following scenario but consider not a blocker at all. (sorry if already commented before).
I2S peripheral is supported on ESP32S3 SoCs. It means any board based on that SoC can use I2S.
However, due to pin limitation or board's default definition, it is not "okay"in .dts file. It is up to the user/application to enabled it.
After this PR, I2S will appear as "Not supported" for all those ESP32S3-based boards, which is kind of not true.

The reason I consider this issue not a blocker is that current documentation is also missing a bunch of "Supported Features" - at least for some ESP32 boards, not sure about others. In the doc below, it misses Wi-Fi, BLE, I2C, I2S.. https://docs.zephyrproject.org/latest/boards/espressif/esp32s3_devkitm/doc/index.html#supported-features

I am still not a fan of the inferring of devicetree binding descriptions based on folders, nor am I convinced that the current form is an improvement to our board documentation as I find it too noisy and too much of a "guess" when just looking at "okay" DTS nodes, but I will dismiss my change request as my original review comment was resolved (thanks!).

[kartben]

@jerome-pouiller @dleach02 @sylvioalves you may want to take a look at the WIP of the next iteration -- I think you will like it :) #86128