Improve devicetree file navigation

[tleb]

There are currently features to navigate devicetree files, but not much. Ideas to take this further:

• Have context-aware parsing of node aliases. Names such as vsys_3v3 give too many results to be useful. It should start with results in parent (/children?) DTS/DTSI.
• Make links from property names to their documentation. That requires knowing the compatible of current node, which can be hard when extending existing nodes.
• What else?

[fstachura]

Have context-aware parsing of node aliases. Names such as vsys_3v3 give too many results to be useful. It should start with results in parent (/children?) DTS/DTSI.

I don't understand. Could you maybe describe what is the desired result for https://elixir.bootlin.com/linux/latest/A/ident/vsys_3v3 ? Or which results are the problem? Is this an issue with sorting?
I don't have much experience with DTS files, so to clarify, my understanding is that node aliases are defined in the aliases section, and parent DTS files are basically (and I know that this is a major simplification) other DTS files, included into the processed file.

[tleb]

A .DTS file is a textual representation of a .DTB file. That latter is a binary file format many platforms use to describe hardware (in a tree structure).

The tricky part is twofold:

• A .DTS gets the C pre-processor applied to it. This means it can do includes of other files; those are almost always called .DTSI (additional I for include).

• You can edit nodes declared elsewhere by referring to them using their alias. Syntax is something like:

  / {
      // ...
      
      foo: bar {
          compatible = "mobileye,eyeq5-gpio";
      };
  };
  &foo {
      status = "enabled";
  };
  

Most often, you have a .DTSI file that represents the SoC. Then all boards that use this SoC include this file and expand it to define what is contained on the boad. Almost always, the structure is more complex than that; it depends on the platform.

So if you want to get an overview of what a node contains, you must first find where the node is declared and then find all references to its alias. BUT you want to search for those aliases only in .DTS/.DTSI that are related to your platform.

Aliases are also used to point to nodes without modifying them. For example you pick GPIOs by using the GPIO controller alias (this is called a phandle).

Example: take this main_gpio0 phandle. It is in a .DTS file. To find where it comes from, you do not want to find all aliases named main_gpio0 in the kernel. You only want to look for it in its "parent" .DTSI files.

Some more complexities:

• It is actually more complex than that because you do not have to use aliases: you can redeclare the same node with the same path and properties will be combined. This is almost never used and I guess it would be fine to not support this (though it could be a real pain).
• It also gets more complex with overlays, that are small devicetree files that can be added on top of the current platform devicetree at runtime. I do not think we have a way to know on which devicetrees an overlay is expected to be applied. Worrying about overlays might be a lot of work.
• The aliases section is not the same thing. It gets stored in the .DTB and used by Linux to know which serial is which. Same thing with mmc, eth, etc.

[tpetazzoni]

I think we want more than that, especially indexing of the compatible string. It'd be great if when clicking on a compatible string, one could easily get to:

1. The driver supporting this compatible string
2. The DT binding defining this compatible string
3. The various Device Tree files that reference this compatible string

[tleb]

This is already supported though, see for example ti,sierra-phy-t0. You however need to specify precisely that you want a "DT compatible" search. I don't know why it doesn't match with the default "All symbols". I guess it is because the compatibles are stored in a separate database. This is, at first glance, a rather easy fix.

[tpetazzoni]

This is already supported though, see for example ti,sierra-phy-t0. You however need to specify precisely that you want a "DT compatible" search. I don't know why it doesn't match with the default "All symbols". I guess it is because the compatibles are stored in a separate database. This is, at first glance, a rather easy fix.

Wow, that's nice. I had forgotten about this! But if I click on a compatible string in a DT, does it use that database ?

[tleb]

Yes, it does use the right database. Example.