doc: sca: dtdoctor: the specifier diagnosis is not gpio-specific

The page listed the specifier spaces as "gpios, interrupts or reg", which
undersells it and reads as a limitation that is not there: the 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 and so on.
Plain 'gpios' is a handful of them. Only 'interrupts' and 'reg' are genuinely a
fixed pair, since those hang off the node rather than off a property.

Every cell test used 'gpios' too, so nothing would have caught a refactor that
accidentally keyed off it. Give the fixture a second phandle-array with a
different specifier space and cell count, and assert on it.

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NS18GhZ19Qeb67QoRkCu7K

Author: claude

doc/develop/sca/dtdoctor.rst

@@ -40,11 +40,12 @@ An instance that does not exist
    Reports how many instances of the compatible the build has and which of them are
    enabled, or, when nothing declares that compatible at all, suggests the closest ones.
 
-A bad index, name or cell in a ``gpios``, ``interrupts`` or ``reg`` specifier
-   Names the controller the entry points at and lists the cells it defines together with
-   this node's values, or lists the entries that do exist. Cell names come from the
-   controller's binding rather than from the node using it, which is what makes these
-   awkward to track down by hand.
+A bad index, name or cell in a specifier
+   Covers any ``phandle-array`` property -- ``gpios``, ``pwms``, ``clocks``, ``dmas`` and
+   the rest -- as well as ``interrupts`` and ``reg``. Names the controller the entry points
+   at and lists the cells it defines together with this node's values, or lists the entries
+   that do exist. Cell names come from the controller's binding rather than from the node
+   using it, which is what makes these awkward to track down by hand.
 
 Devicetree names are written differently in C than in DTS: lowercased, with ``-``, ``,``,
 ``.``, ``@``, ``/`` and ``+`` all becoming ``_``. ``dtdoctor`` spells out both forms

scripts/tests/dtdoctor/conftest.py

@@ -149,6 +149,9 @@
 # entries are named and whose cells come from a controller's binding, an interrupt whose
 # entries are *not* named, and a single register. The controllers carry the cell names, so
 # 'pin'/'flags' and 'irq'/'priority' are what a diagnosis has to be able to find.
+#
+# 'pwms' is a second phandle-array, with a different specifier space and cell count, so the
+# diagnoses stay pinned as working on any phandle-array rather than just on 'gpios'.
 DTS_SPECIFIERS = """
 /dts-v1/;
 
@@ -162,6 +165,11 @@
 		#gpio-cells = <2>;
 	};
 
+	pwm0: pwm@40003000 {
+		compatible = "vnd,pwm-ctrl";
+		#pwm-cells = <2>;
+	};
+
 	irq0: interrupt-controller@e000e100 {
 		compatible = "vnd,irq-ctrl";
 		interrupt-controller;
@@ -173,6 +181,7 @@
 		reg = <0x40002000 0x1000>;
 		gpios = <&gpio0 13 1>, <&gpio0 14 0>;
 		gpio-names = "red", "green";
+		pwms = <&pwm0 3 5000>;
 		interrupt-parent = <&irq0>;
 		interrupts = <5 2>;
 	};

scripts/tests/dtdoctor/fixture/bindings/vnd,pwm-ctrl.yaml

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
+# SPDX-License-Identifier: Apache-2.0
+
+description: |
+  Test PWM controller. A second specifier space, with a different cell count from
+  the GPIO one, so the diagnoses are pinned as working on any phandle-array rather
+  than just on 'gpios'.
+
+compatible: "vnd,pwm-ctrl"
+
+pwm-cells:
+  - channel
+  - period
+
+properties:
+  "#pwm-cells":
+    type: int
+    required: true

scripts/tests/dtdoctor/fixture/bindings/vnd,specifier-consumer.yaml

@@ -12,6 +12,8 @@ properties:
     type: phandle-array
   gpio-names:
     type: string-array
+  pwms:
+    type: phandle-array
   interrupts:
     type: array
   interrupt-names:

scripts/tests/dtdoctor/test_dtdoctor_cells.py

@@ -78,6 +78,23 @@ def test_gpio_name_not_found(make_edt):
     assert " - red" in out
 
 
+def test_cells_are_not_gpio_specific(make_edt):
+    # Nothing here keys off 'gpios': the handler runs on any phandle-array property, of
+    # which Zephyr's in-tree bindings declare several hundred distinct names
+    edt, _ = make_edt(DTS_SPECIFIERS)
+    out = diagnose(edt, "_P_pwms_IDX_0_VAL_chanel")
+    assert "has no 'chanel' cell in entry 0 of the 'pwms' property." in out
+    assert "Entry 0 is controlled by 'pwm0: /pwm@40003000'" in out
+    assert " - channel   (currently 3)" in out
+    assert " - period    (currently 5000)" in out
+
+
+def test_non_gpio_specifier_index_out_of_range(make_edt):
+    edt, _ = make_edt(DTS_SPECIFIERS)
+    out = diagnose(edt, "_P_pwms_IDX_2_VAL_channel")
+    assert "has no entry 2 in the 'pwms' property -- there is only 1." in out
+
+
 def test_unknown_interrupt_cell(make_edt):
     edt, _ = make_edt(DTS_SPECIFIERS)
     out = diagnose(edt, "_IRQ_IDX_0_VAL_priorty")