Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Doc] How to link dts bindings with Kconfig flags #29779

Open
erwango opened this issue Nov 4, 2020 · 10 comments
Open

[Doc] How to link dts bindings with Kconfig flags #29779

erwango opened this issue Nov 4, 2020 · 10 comments
Assignees
Labels
area: Devicetree Tooling PR modifies or adds a Device Tree tooling area: Documentation Enhancement Changes/Updates/Additions to existing features

Comments

@erwango
Copy link
Member

erwango commented Nov 4, 2020

Is your enhancement proposal related to a problem? Please describe.
DTS bindings are now available in zephyr documentation (https://docs.zephyrproject.org/latest/reference/devicetree/bindings.html)
and maintainers have a way to document these important pieces of driver configuration.
The last important missing piece of information is to indicate how a driver should be enabled, operation typically achieved using Kconfig flags.

This piece of info would would be missing to automatize generation of supported features in boards documentation (cf #29652).

One easy way to get this link would be to document drivers matching Kconfig flag in dts bindings flag directly.
But, as said @mbolivar-nordic: "kind of defeats the 'OS independent' goal for bindings IMO".

So I'm raising this issue in order to reach an agreement on how to document dts bindings Kconfig relation w/o breaking OS independent promises.

@erwango erwango added Enhancement Changes/Updates/Additions to existing features area: Documentation labels Nov 4, 2020
@erwango
Copy link
Member Author

erwango commented Nov 4, 2020

@erwango erwango added the area: Devicetree Tooling PR modifies or adds a Device Tree tooling label Nov 4, 2020
@mbolivar-nordic
Copy link
Contributor

mbolivar-nordic commented Nov 4, 2020

I did some prototyping on this last night. So far I have a way for drivers to declare (via Doxygen) what devicetree compatibles they support, and build an index mapping compatible(s) <-> driver(s) from that.

Note that this map can be many-to-many. It's not a function. A single compatible can be handled by multiple drivers. A single driver can handle multiple compatibles.

Next steps are to generate documentation pages for these drivers and include the detailed description (again from Doxygen) into the Sphinx pages. I verified that the usual ways of embedding restructured text work. That allows us to say something like this in a driver file comment:

/**
 * @file
 * @dtcompatible{vnd,foo}
 * This the Foo driver for Vnd devices. To enable this driver, set :option:`CONFIG_FOO` ...
 */

And the :option: part provides a link to the existing Kconfig index.

I will post a proof of concept sometime this week.

@mbolivar-nordic
Copy link
Contributor

cc @pabigot

@erwango
Copy link
Member Author

erwango commented Nov 5, 2020

I did some prototyping on this last night. So far I have a way for drivers to declare (via Doxygen) what devicetree compatibles they support, and build an index mapping compatible(s) <-> driver(s) from that.

I'm fine with the approach! Txs @mbolivar-nordic.
One tiny reservation is that it will rely purely on developer and reviewers. Maybe and automated check could be added, or we can get the doc generation could fail if not present ?

@mbolivar-nordic
Copy link
Contributor

One tiny reservation is that it will rely purely on developer and reviewers. Maybe and automated check could be added, or we can get the doc generation could fail if not present ?

Sure, I'm happy to discuss and add CI checks like that depending on what subsystem maintainers decide should be required for driver documentation.

@mbolivar-nordic
Copy link
Contributor

Sorry for the delay, but here is a draft: #30104

There is a new "device drivers" index that pulls in Doxygen content from driver sources. It's at top level and is available on the sidebar.

@mbolivar-nordic
Copy link
Contributor

Sorry for the delay, but here is a draft: #30104

any comments on this?

@erwango
Copy link
Member Author

erwango commented Dec 9, 2020

It's in my TODO list, sorry for the delay.

@zephyrbot
Copy link
Collaborator

Hi @carlescufi, @kartben,

This issue, marked as an Enhancement, was opened a while ago and did not get any traction. It was just assigned to you based on the labels. If you don't consider yourself the right person to address this issue, please re-assing it to the right person.

Please take a moment to review if the issue is still relevant to the project. If it is, please provide feedback and direction on how to move forward. If it is not, has already been addressed, is a duplicate, or is no longer relevant, please close it with a short comment explaining the reason.

@erwango you are also encouraged to help moving this issue forward by providing additional information and confirming this request/issue is still relevant to you.

Thanks!

@erwango
Copy link
Member Author

erwango commented Feb 9, 2024

@kartben Feel free to close if this looks as a duplicate or if direction is not the good one

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area: Devicetree Tooling PR modifies or adds a Device Tree tooling area: Documentation Enhancement Changes/Updates/Additions to existing features
Projects
Development

No branches or pull requests

5 participants