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 <Ulf.Magnusson@nordicsemi.no>
This commit is contained in:
Ulf Magnusson 2019-11-26 22:19:55 +01:00 committed by Carles Cufí
commit 379145ffce
9 changed files with 56 additions and 30 deletions

View file

@ -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:

View file

@ -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.
#

View file

@ -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"]

View file

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

View file

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

View file

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

View file

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

View file

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

View file

@ -119,7 +119,7 @@ warning: "#cells:" in test-bindings/deprecated.yaml is deprecated and will be re
"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,