dtdoctor: reverse-engineer four more error classes, report disabled ancestors

[kartben]

Builds on zephyrproject-rtos#117239 (dtdoctor-tests).

DT Doctor currently understands exactly one symbol shape: __device_dts_ord_<N>, i.e. DEVICE_DT_GET() on a node identifier that does resolve but has no struct device. That is only the first of the failure modes doc/build/dts/troubleshooting.rst documents.

The errors users hit more often are the ones where the node identifier itself never resolves, so the unexpanded macro leaks straight into the compiler output:

error: '__device_dts_ord_DT_N_NODELABEL_my_serial_ORD' undeclared   # DEVICE_DT_GET(DT_NODELABEL(my_serial))
error: 'DT_N_S_soc_S_uart_40002000_P_currentspeed' undeclared       # DT_PROP(..., currentspeed)
error: '__device_dts_ord_DT_N_INST_0_vnd_foo_ORD' undeclared        # DT_DRV_INST(0) with no instance
error: 'DT_N_S_leds_S_led_0_P_gpios_IDX_0_VAL_pen' undeclared       # DT_GPIO_PIN(LED, gpios)

Today the wrapper's regexes require __device_dts_ord_\d+, so none of these are even detected. The user gets the raw macro soup and nothing else. Everything needed to explain them is already in edt.pickle.

What's added

Family	Symbol shape	Diagnosis
Node identifier naming no node	DT_N_NODELABEL_*, DT_N_ALIAS_*, DT_CHOSEN_*, unknown DT_N_S_*	Which label, alias, chosen entry or path is missing, fuzzy "did you mean" drawn from the devicetree, and the overlay snippet to write
Property a node does not have	<node-id>_P_<prop>	Node's real properties in both DTS and C spellings, binding path, and a typo distinguished from a property the binding declares but the node never sets (DT_PROP_OR() / DT_NODE_HAS_PROP())
DT_INST() / DT_DRV_COMPAT	DT_N_INST_<i>_<compat>	How many instances the compatible has and each one's status in index order, or unknown-compatible plus the DT_DRV_COMPAT lowercase-and-underscores rule
Specifier index, name or cell	<node-id>_P_<pha>_IDX_<i>_VAL_<cell>, _IRQ_*, _REG_*	The controller that defines the cells, its cell list with this node's values, and the closest match. A bad index or name lists the entries that do exist.
Device below a disabled parent	__device_dts_ord_<N> (resolved node)	Both node diagnoses now walk the ancestor chain and name every disabled ancestor with the file and line where its status is set — enabling the node or its driver alone would not be enough

How

One reverse map: every node identifier macro gen_defines.py emits, mapped back to its edtlib.Node. Match a failing macro against it. The longest part that does name a node tells us what exists, and the leftover tells us what does not.

The name mangling is taken from gen_defines.node_z_path_id() / str2ident() rather than reimplemented, since the two drifting apart would silently resolve macros to the wrong node.

A node identifier that resolves now falls through to the existing enabled/disabled diagnosis, so DEVICE_DT_GET(DT_NODELABEL(x)) gets the same answer the ordinal form already got.

Example output

+-----------------------------------------------------------------------------------+
| DT Doctor                                                                         |
+===================================================================================+
| No node label 'my_serail' exists in this build's devicetree.                      |
|                                                                                   |
| Did you mean one of these?                                                        |
|                                                                                   |
|  - my_serial                                                                      |
|                                                                                   |
| Node labels are the 'name:' part written in front of a node in a DTS file, e.g.   |
| 'my_serial: uart@40002000'. In C they are lowercased, so DT_NODELABEL(my_serial). |
|                                                                                   |
| Node labels can be added to an existing node from a devicetree overlay:           |
|                                                                                   |
|     my_serial: &uart0 {};                                                         |
|                                                                                   |
| See <build>/zephyr/zephyr.dts for the devicetree this build actually used.        |
+-----------------------------------------------------------------------------------+

and for a cell, where the answer lives in a binding the user never mentioned:

+-------------------------------------------------------------------------------------+
| DT Doctor                                                                           |
+=====================================================================================+
| 'led0: /leds/led_0' has no 'pen' cell in entry 0 of the 'gpios' property.           |
|                                                                                     |
| Entry 0 is controlled by 'gpio0: /soc/gpio@50000000', which defines these cells:    |
|                                                                                     |
|  - pin     (currently 13)                                                           |
|  - flags   (currently 1)                                                            |
|                                                                                     |
| Did you mean one of these?                                                          |
|                                                                                     |
|  - pin                                                                              |
|                                                                                     |
| Cell names come from the controller's binding, not this node's. See its             |
| '*-cells:' list in                                                                  |
| zephyr/dts/bindings/gpio/nordic,nrf-gpio.yaml                                       |
+-------------------------------------------------------------------------------------+

Subtleties worth a look during review

• Path identifiers are prefixes of each other and of the alternate-ID namespaces. A naive longest-prefix match resolved DT_N_NODELABEL_foo_ORD to the root node and DT_N_S_soc_S_uart_9999 to /soc. Matching is scoped to the namespace the macro is written in, plus a leftover-_S_ check so a partially matched path blames the node the full path names rather than the ancestor that happened to match.

• Recovering a name from a macro that has no generated counterpart. Trimming trailing _-separated components until something fuzzy-matched over-trims, and would report DT_N_ALIAS_no_such_alias_ORD as an alias named no_such: a wrong name next to a suggestion, which is worse than no suggestion. There is no need to guess. What <devicetree.h> appends always starts with an upper case component (_ORD, _P_, _REG_IDX_0), and gen_defines.py lower-cases every name it builds identifiers from, so the first upper case component is exactly where the name ends. The specifier parser leans on the same invariant to keep _VAL_ from being read as part of a name.

• Nothing keys off gpios in particular. The specifier handler runs on any phandle-array property, and Zephyr's in-tree bindings declare several hundred distinct ones (reset-gpios, int-gpios, clocks, pwms, dmas). Only interrupts and reg are a fixed pair, since those hang off the node rather than off a property. The fixture carries a second phandle-array with a different specifier space so this stays pinned.

• Specifier entry names are keyed by the specifier space, not the property name. cs-gpios entries are named through gpio-names, not cs-gpio-names. The integration fixture uses a dtdoctor-gpios property with gpio-names so this is pinned end to end rather than only in a unit test.

• A node below a disabled parent still counts as okay. edtlib and gen_defines.py only look at a node's own status, so its driver builds, its instance macros exist, and the failure surfaces on the parent's ordinal. Reporting disabled ancestors in both node diagnoses is what keeps the user from fixing one node per rebuild all the way up the chain.

Testing

Every commit in the series is green on its own, with the suites growing 37 → 83 → 105 → 110 unit and 7 → 20 → 26 → 27 integration.

• tests/misc/dtdoctor/unit/ fixture devicetrees carry node labels, an alias, a /chosen entry, two instances of one compatible, properties that are set / declared-but-unset / of a type with no plain value macro, all three specifier spaces (a named phandle-array, a second one in a different space, a deliberately unnamed interrupt, a register), and enabled/disabled nodes below disabled parents and grandparents. One test module per family. 110 tests pass.
• tests/misc/dtdoctor/unit/test_dtdoctor_wrapper.py covers the new symbol shapes across the gcc, GNU ld, clang and lld message formats, transcribed from real toolchain output, plus a check that unrelated undeclared symbols are still ignored.
• tests/misc/dtdoctor/e2e/ exercises each family against the build's real edt.pickle, and compiles real macro uses (DEVICE_DT_GET(DT_NODELABEL(dtdoctor_no_such_label)), DT_PROP(…, no_such_prop), DT_PHA_BY_IDX(…)) with the application's own compile commands replayed from compile_commands.json, in C and C++, so the leaked-macro shapes come from the real <devicetree.h> expansion rather than transcription. Toolchain message drift is what these shapes are most exposed to, and it is not something the unit suite can catch. 27 tests collected.
• ruff check and ruff format clean on all touched files; check_compliance.py (Gitlint, Ruff, YAMLLint, KeepSorted, Identity) clean over the whole range.

One caveat: the unit suite runs everywhere, but the integration suite was validated against a hand-built edt.pickle using host toolchains. The real twister/ctest run against the Zephyr SDK on qemu_cortex_m3 still needs CI.