Commit 379145ff authored by Ulf Magnusson's avatar Ulf Magnusson Committed by Carles Cufi
Browse files

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: default avatarUlf Magnusson <Ulf.Magnusson@nordicsemi.no>
parent 847f4e6a

doc/guides/dts/index.rst

+3 −1
Original line number Diff line number Diff line
@@ -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

+6 −9
Original line number Diff line number Diff line
@@ -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

+41 −14
Original line number Diff line number Diff line
@@ -278,13 +278,13 @@ class EDT: 
            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,7 +484,7 @@ class EDT: 
                     .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:
@@ -492,20 +492,39 @@ class EDT: 
                _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 @@ class Node: 
        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 @@ class Node: 
        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

+1 −1
Original line number Diff line number Diff line
@@ -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

+1 −1
Original line number Diff line number Diff line
@@ -4,4 +4,4 @@ description: Device on bar bus 


compatible: "on-bus"



parent-bus: "bar"
 
on-bus: "bar"

CRA Git | Maintained and supported by SUSTech CRA and CCSE