scripts: edtlib: Rename 'child-bus:'/'parent-bus:' to 'bus:'/'on-bus:'

I keep mixing these up, so that's probably a sign that the names are
bad. The root of the problem is that "parent-bus" can be read as both
"this is the parent bus" and as "the parent bus is this".

Use 'bus:' for the bus "provider" and 'on-bus:' for nodes on the bus
instead, which is less confusing.

Support the old keys for backwards compatibility, along with a
deprecation warning.

Signed-off-by: Ulf Magnusson <[email protected]>

doc/guides/dts/index.rst

@@ -618,6 +618,8 @@ The binding below shows various legacy syntax.
    parent:
        bus: spi
 
+   parent-bus: spi
+
    properties:
        compatible:
            constraint: "company,device"
@@ -650,7 +652,7 @@ This should now be written like this:
 
    include: foo.yaml
 
-   parent-bus: spi
+   bus: spi
 
    properties:
        frequency:

dts/binding-template.yaml

@@ -62,19 +62,16 @@ compatible: "manufacturer,device"
 # 'required: true' is always respected.
 include: other.yaml # or [other1.yaml, other2.yaml]
 
-# If the node describes a bus, then the bus type should be given, like below.
-# The name has "child" in it since it describes the bus children of the node
-# appear on.
-child-bus: <string describing bus type, e.g. "i2c">
+# If the node describes a bus, then the bus type should be given, like below
+bus: <string describing bus type, e.g. "i2c">
 
 # If the node appears on a bus, then the bus type should be given, like below.
 #
 # When looking for a binding for a node, the code checks if the binding for the
-# parent node contains 'child-bus: <bus type>'. If it does, then only bindings
-# with a matching 'parent-bus: <bus type>' are considered. This allows the same
-# type of device to have different bindings depending on what bus it appears
-# on.
-parent-bus: <string describing bus type, e.g. "i2c">
+# parent node contains 'bus: <bus type>'. If it does, then only bindings with a
+# matching 'on-bus: <bus type>' are considered. This allows the same type of
+# device to have different bindings depending on what bus it appears on.
+on-bus: <string describing bus type, e.g. "i2c">
 
 # 'properties' describes properties on the node, e.g.
 #

scripts/dts/edtlib.py

@@ -278,13 +278,13 @@ def _init_compat2binding(self, bindings_dirs):
             bus = _binding_bus(binding)
 
             # Do not allow two different bindings to have the same
-            # 'compatible:'/'parent-bus:' combo
+            # 'compatible:'/'on-bus:' combo
             old_binding = self._compat2binding.get((binding_compat, bus))
             if old_binding:
                 msg = "both {} and {} have 'compatible: {}'".format(
                     old_binding[1], binding_path, binding_compat)
                 if bus is not None:
-                    msg += " and 'parent-bus: {}'".format(bus)
+                    msg += " and 'on-bus: {}'".format(bus)
                 _err(msg)
 
             self._compat2binding[binding_compat, bus] = (binding, binding_path)
@@ -484,28 +484,47 @@ def _check_binding(self, binding, binding_path):
                      .format(prop, binding_path))
 
         ok_top = {"title", "description", "compatible", "properties", "#cells",
-                  "parent-bus", "child-bus", "parent", "child",
+                  "bus", "on-bus", "parent-bus", "child-bus", "parent", "child",
                   "child-binding", "sub-node"}
 
         for prop in binding:
             if prop not in ok_top and not prop.endswith("-cells"):
                 _err("unknown key '{}' in {}, expected one of {}, or *-cells"
                      .format(prop, binding_path, ", ".join(ok_top)))
 
-        for pc in "parent", "child":
-            # 'parent/child-bus:'
-            bus_key = pc + "-bus"
+        for bus_key in "bus", "on-bus":
             if bus_key in binding and \
                not isinstance(binding[bus_key], str):
                 _err("malformed '{}:' value in {}, expected string"
                      .format(bus_key, binding_path))
 
+        # There are two legacy syntaxes for 'bus:' and 'on-bus:':
+        #
+        #     child/parent-bus: foo
+        #     child/parent: bus: foo
+        #
+        # We support both, with deprecation warnings.
+        for pc in "parent", "child":
+            # Legacy 'parent/child-bus:' keys
+            bus_key = pc + "-bus"
+            if bus_key in binding:
+                self._warn("'{}:' in {} is deprecated and will be removed - "
+                           "please use a top-level '{}:' key instead (see "
+                           "binding-template.yaml)"
+                           .format(bus_key, binding_path,
+                                   "bus" if bus_key == "child-bus" else "on-bus"))
+
+                if not isinstance(binding[bus_key], str):
+                    _err("malformed '{}:' value in {}, expected string"
+                         .format(bus_key, binding_path))
+
             # Legacy 'child/parent: bus: ...' keys
             if pc in binding:
-                self._warn("'{0}: bus: ...' in {1} is deprecated and will be "
-                           "removed - please use a top-level '{0}-bus:' key "
-                           "instead (see binding-template.yaml)"
-                           .format(pc, binding_path))
+                self._warn("'{}: bus: ...' in {} is deprecated and will be "
+                           "removed - please use a top-level '{}' key instead "
+                           "(see binding-template.yaml)"
+                           .format(pc, binding_path,
+                                   "bus" if pc == "child" else "on-bus:"))
 
                 # Just 'bus:' is expected
                 if binding[pc].keys() != {"bus"}:
@@ -902,8 +921,8 @@ def _binding_from_parent(self):
         return None
 
     def _bus_from_parent_binding(self):
-        # _init_binding() helper. Returns the bus specified by 'child-bus: ...'
-        # in the parent binding (or the legacy 'child: bus: ...'), or None if
+        # _init_binding() helper. Returns the bus specified by 'bus:' in the
+        # parent binding (or the legacy 'child-bus:'/'child: bus:'), or None if
         # missing.
 
         if not self.parent:
@@ -913,6 +932,10 @@ def _bus_from_parent_binding(self):
         if not binding:
             return None
 
+        if "bus" in binding:
+            return binding["bus"]
+
+        # Legacy key
         if "child-bus" in binding:
             return binding["child-bus"]
 
@@ -1481,12 +1504,16 @@ def _binding_paths(bindings_dirs):
 
 
 def _binding_bus(binding):
-    # Returns the bus specified by 'parent-bus: ...' in the binding (or the
-    # legacy 'parent: bus: ...'), or None if missing
+    # Returns the bus specified by 'on-bus:' in the binding (or the
+    # legacy 'parent-bus:' and 'parent: bus:'), or None if missing
 
     if not binding:
         return None
 
+    if "on-bus" in binding:
+        return binding["on-bus"]
+
+    # Legacy key
     if "parent-bus" in binding:
         return binding["parent-bus"]
 

scripts/dts/test-bindings/bar-bus.yaml

@@ -4,4 +4,4 @@ description: Bar bus controller
 
 compatible: "bar-bus"
 
-child-bus: "bar"
+bus: "bar"

scripts/dts/test-bindings/device-on-bar-bus.yaml

@@ -4,4 +4,4 @@ description: Device on bar bus
 
 compatible: "on-bus"
 
-parent-bus: "bar"
+on-bus: "bar"

scripts/dts/test-bindings/device-on-foo-bus.yaml

@@ -4,4 +4,4 @@ description: Device on foo bus
 
 compatible: "on-bus"
 
-parent-bus: "foo"
+on-bus: "foo"

scripts/dts/test-bindings/foo-bus.yaml

@@ -4,4 +4,4 @@ description: Foo bus controller
 
 compatible: "foo-bus"
 
-child-bus: "foo"
+bus: "foo"

scripts/dts/test.dts

@@ -294,7 +294,7 @@
 	};
 
 	//
-	// For testing 'child-bus:' and 'parent-bus:'
+	// For testing 'bus:' and 'on-bus:'
 	//
 
 	buses {

scripts/dts/testedtlib.py

@@ -119,7 +119,7 @@ def verify_streq(actual, expected):
                  "OrderedDict([('foo', <Property, name: foo, type: int, value: 0>), ('bar', <Property, name: bar, type: int, value: 1>), ('baz', <Property, name: baz, type: int, value: 2>), ('qaz', <Property, name: qaz, type: int, value: 3>)])")
 
     #
-    # Test 'child/parent-bus:'
+    # Test 'bus:' and 'on-bus:'
     #
 
     verify_streq(edt.get_node("/buses/foo-bus/node").binding_path,