scripts: edtlib.py: Deprecate 'title:'
Most bindings look something like this:
title: Foo
description: This binding provides a base representation of Foo
That kind of description doesn't add any useful information, as it's
just the title along with some copy-pasted text. I'm not sure what "base
representation" was supposed to mean originally either.
Many bindings also put something that's closer to a description in the
title, because it's not clear what's expected or how the title is used.
In reality, the title isn't used anywhere. 'description:' on the other
hand shows up as a comment in the generated header.
Deprecate 'title:' and generate a long informative warning if it shows
up in a binding.
Next commits will clean up the 'description:' strings (bringing them
closer to 'title:' in most cases) and remove 'title:' from all bindings.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
diff --git a/dts/binding-template.yaml b/dts/binding-template.yaml
index 853a23d..7514b82 100644
--- a/dts/binding-template.yaml
+++ b/dts/binding-template.yaml
@@ -1,7 +1,5 @@
-title: Short description of the node
-
description: |
- Longer free-form description of the node. Can have multiple
+ Free-form description of the device/node. Can have multiple
lines/paragraphs.
See https://yaml-multiline.info/ for formatting help.
diff --git a/scripts/dts/edtlib.py b/scripts/dts/edtlib.py
index 868fe71..a750688 100644
--- a/scripts/dts/edtlib.py
+++ b/scripts/dts/edtlib.py
@@ -459,12 +459,28 @@
# Does sanity checking on 'binding'. Only takes 'self' for the sake of
# self._warn().
- for prop in "title", "description":
- if prop not in binding:
- _err("missing '{}' property in {}".format(prop, binding_path))
+ if "title" in binding:
+ # This message is the message that people copy-pasting the old
+ # format will see in practice
+ self._warn("'title:' in {} is deprecated and will be removed (and "
+ "was never used). Just put a 'description:' that "
+ "describes the device instead. Use other bindings as "
+ "a reference, and note that all bindings were updated "
+ "recently. Think about what information would be "
+ "useful to other people (e.g. explanations of "
+ "acronyms, or datasheet links), and put that in as "
+ "well. The description text shows up as a comment "
+ "in the generated header. See yaml-multiline.info for "
+ "how to deal with multiple lines. You probably want "
+ "'description: |'.".format(binding_path))
- if not isinstance(binding[prop], str) or not binding[prop]:
- _err("missing, malformed, or empty '{}' in {}"
+ if "description" not in binding:
+ _err("missing 'description' property in " + binding_path)
+
+ for prop in "title", "description":
+ if prop in binding and (not isinstance(binding[prop], str) or
+ not binding[prop]):
+ _err("malformed or empty '{}' in {}"
.format(prop, binding_path))
ok_top = {"title", "description", "compatible", "properties", "#cells",
@@ -481,8 +497,8 @@
bus_key = pc + "-bus"
if bus_key in binding and \
not isinstance(binding[bus_key], str):
- self._warn("malformed '{}:' value in {}, expected string"
- .format(bus_key, binding_path))
+ _err("malformed '{}:' value in {}, expected string"
+ .format(bus_key, binding_path))
# Legacy 'child/parent: bus: ...' keys
if pc in binding:
diff --git a/scripts/dts/test-bindings-2/multidir.yaml b/scripts/dts/test-bindings-2/multidir.yaml
index 2bd84e7..19721b2 100644
--- a/scripts/dts/test-bindings-2/multidir.yaml
+++ b/scripts/dts/test-bindings-2/multidir.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Binding in test-bindings-2/
description: Binding in test-bindings-2/
compatible: "in-dir-2"
diff --git a/scripts/dts/test-bindings/bar-bus.yaml b/scripts/dts/test-bindings/bar-bus.yaml
index 0b4bd05..8410293 100644
--- a/scripts/dts/test-bindings/bar-bus.yaml
+++ b/scripts/dts/test-bindings/bar-bus.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Bar bus controller
description: Bar bus controller
compatible: "bar-bus"
diff --git a/scripts/dts/test-bindings/child-binding.yaml b/scripts/dts/test-bindings/child-binding.yaml
index a2bb89b..db4902a 100644
--- a/scripts/dts/test-bindings/child-binding.yaml
+++ b/scripts/dts/test-bindings/child-binding.yaml
@@ -1,12 +1,10 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: child-binding test
description: child-binding test
compatible: "child-binding"
child-binding:
- title: child node
description: child node
properties:
child-prop:
@@ -14,7 +12,6 @@
required: true
child-binding:
- title: grandchild node
description: grandchild node
properties:
grandchild-prop:
diff --git a/scripts/dts/test-bindings/defaults.yaml b/scripts/dts/test-bindings/defaults.yaml
index 682fa07..706067c 100644
--- a/scripts/dts/test-bindings/defaults.yaml
+++ b/scripts/dts/test-bindings/defaults.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Property default value test
description: Property default value test
compatible: "defaults"
diff --git a/scripts/dts/test-bindings/device-on-bar-bus.yaml b/scripts/dts/test-bindings/device-on-bar-bus.yaml
index 4cb1d74..4620148 100644
--- a/scripts/dts/test-bindings/device-on-bar-bus.yaml
+++ b/scripts/dts/test-bindings/device-on-bar-bus.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Device on bar bus
description: Device on bar bus
compatible: "on-bus"
diff --git a/scripts/dts/test-bindings/device-on-foo-bus.yaml b/scripts/dts/test-bindings/device-on-foo-bus.yaml
index 4f0e14c..e8cbef5 100644
--- a/scripts/dts/test-bindings/device-on-foo-bus.yaml
+++ b/scripts/dts/test-bindings/device-on-foo-bus.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Device on foo bus
description: Device on foo bus
compatible: "on-bus"
diff --git a/scripts/dts/test-bindings/foo-bus.yaml b/scripts/dts/test-bindings/foo-bus.yaml
index 9760007..e802469 100644
--- a/scripts/dts/test-bindings/foo-bus.yaml
+++ b/scripts/dts/test-bindings/foo-bus.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Foo bus controller
description: Foo bus controller
compatible: "foo-bus"
diff --git a/scripts/dts/test-bindings/gpio-dst.yaml b/scripts/dts/test-bindings/gpio-dst.yaml
index 955bec4..19db316 100644
--- a/scripts/dts/test-bindings/gpio-dst.yaml
+++ b/scripts/dts/test-bindings/gpio-dst.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: GPIO destination for mapping test
description: GPIO destination for mapping test
compatible: "gpio-dst"
diff --git a/scripts/dts/test-bindings/gpio-src.yaml b/scripts/dts/test-bindings/gpio-src.yaml
index 6f00cb0..b7e5c33 100644
--- a/scripts/dts/test-bindings/gpio-src.yaml
+++ b/scripts/dts/test-bindings/gpio-src.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: GPIO source for mapping test
description: GPIO source for mapping test
compatible: "gpio-src"
diff --git a/scripts/dts/test-bindings/interrupt-1-cell.yaml b/scripts/dts/test-bindings/interrupt-1-cell.yaml
index 2181b7c..ab2db66 100644
--- a/scripts/dts/test-bindings/interrupt-1-cell.yaml
+++ b/scripts/dts/test-bindings/interrupt-1-cell.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Interrupt controller with one cell
description: Interrupt controller with one cell
compatible: "interrupt-one-cell"
diff --git a/scripts/dts/test-bindings/interrupt-2-cell.yaml b/scripts/dts/test-bindings/interrupt-2-cell.yaml
index 0654c6a..2c3144d 100644
--- a/scripts/dts/test-bindings/interrupt-2-cell.yaml
+++ b/scripts/dts/test-bindings/interrupt-2-cell.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Interrupt controller with two cells
description: Interrupt controller with two cells
compatible: "interrupt-two-cell"
diff --git a/scripts/dts/test-bindings/interrupt-3-cell.yaml b/scripts/dts/test-bindings/interrupt-3-cell.yaml
index bceddd0..846dee0 100644
--- a/scripts/dts/test-bindings/interrupt-3-cell.yaml
+++ b/scripts/dts/test-bindings/interrupt-3-cell.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Interrupt controller with three cells
description: Interrupt controller with three cells
compatible: "interrupt-three-cell"
diff --git a/scripts/dts/test-bindings/multidir.yaml b/scripts/dts/test-bindings/multidir.yaml
index a9c07ab..8504475 100644
--- a/scripts/dts/test-bindings/multidir.yaml
+++ b/scripts/dts/test-bindings/multidir.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Binding in test-bindings/
description: Binding in test-bindings/
compatible: "in-dir-1"
diff --git a/scripts/dts/test-bindings/order-1.yaml b/scripts/dts/test-bindings/order-1.yaml
index 824f6b3..e6024a8 100644
--- a/scripts/dts/test-bindings/order-1.yaml
+++ b/scripts/dts/test-bindings/order-1.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Include ordering test
description: Include ordering test
compatible: "order-1"
diff --git a/scripts/dts/test-bindings/order-2.yaml b/scripts/dts/test-bindings/order-2.yaml
index ed5d4d2..cad1f9b 100644
--- a/scripts/dts/test-bindings/order-2.yaml
+++ b/scripts/dts/test-bindings/order-2.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Include ordering test
description: Include ordering test
compatible: "order-2"
diff --git a/scripts/dts/test-bindings/parent.yaml b/scripts/dts/test-bindings/parent.yaml
index 6fe5660..8a0e0f4 100644
--- a/scripts/dts/test-bindings/parent.yaml
+++ b/scripts/dts/test-bindings/parent.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Parent binding
description: Parent binding
compatible: "binding-include-test"
diff --git a/scripts/dts/test-bindings/phandle-array-controller-1.yaml b/scripts/dts/test-bindings/phandle-array-controller-1.yaml
index 9a58886..9d5c6c5 100644
--- a/scripts/dts/test-bindings/phandle-array-controller-1.yaml
+++ b/scripts/dts/test-bindings/phandle-array-controller-1.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Controller with one data value
description: Controller with one data value
compatible: "phandle-array-controller-1"
diff --git a/scripts/dts/test-bindings/phandle-array-controller-2.yaml b/scripts/dts/test-bindings/phandle-array-controller-2.yaml
index 97d18e8..e7a3cab 100644
--- a/scripts/dts/test-bindings/phandle-array-controller-2.yaml
+++ b/scripts/dts/test-bindings/phandle-array-controller-2.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Controller with two data values
description: Controller with two data values
compatible: "phandle-array-controller-2"
diff --git a/scripts/dts/test-bindings/props.yaml b/scripts/dts/test-bindings/props.yaml
index 7733e6a..971f18f 100644
--- a/scripts/dts/test-bindings/props.yaml
+++ b/scripts/dts/test-bindings/props.yaml
@@ -1,6 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
-title: Device.props test
description: Device.props test
compatible: "props"
diff --git a/scripts/dts/testedtlib.py b/scripts/dts/testedtlib.py
index fe40d09..1fa70e4 100755
--- a/scripts/dts/testedtlib.py
+++ b/scripts/dts/testedtlib.py
@@ -42,6 +42,7 @@
verify_eq(warnings.getvalue(), """\
warning: The 'properties: compatible: constraint: ...' way of specifying the compatible in test-bindings/deprecated.yaml is deprecated. Put 'compatible: "deprecated"' at the top level of the binding instead.
warning: the 'inherits:' syntax in test-bindings/deprecated.yaml is deprecated and will be removed - please use 'include: foo.yaml' or 'include: [foo.yaml, bar.yaml]' instead
+warning: 'title:' in test-bindings/deprecated.yaml is deprecated and will be removed (and was never used). Just put a 'description:' that describes the device instead. Use other bindings as a reference, and note that all bindings were updated recently. Think about what information would be useful to other people (e.g. explanations of acronyms, or datasheet links), and put that in as well. The description text shows up as a comment in the generated header. See yaml-multiline.info for how to deal with multiple lines. You probably want 'description: |'.
warning: please put 'required: true' instead of 'category: required' in properties: required: ...' in test-bindings/deprecated.yaml - 'category' will be removed
warning: please put 'required: false' instead of 'category: optional' in properties: optional: ...' in test-bindings/deprecated.yaml - 'category' will be removed
warning: 'sub-node: properties: ...' in test-bindings/deprecated.yaml is deprecated and will be removed - please give a full binding for the child node in 'child-binding:' instead (see binding-template.yaml)
