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>
This commit is contained in:
Ulf Magnusson
Carles Cufí
parent
1ac67d1559
commit
36b7ca44b8
22 changed files with 25 additions and 31 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -459,12 +459,28 @@ class EDT:
|
|||
# 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 @@ class EDT:
|
|||
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:
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
# SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
title: Bar bus controller
|
||||
description: Bar bus controller
|
||||
|
||||
compatible: "bar-bus"
|
||||
|
|
|
|||
|
|
@ -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 @@ child-binding:
|
|||
required: true
|
||||
|
||||
child-binding:
|
||||
title: grandchild node
|
||||
description: grandchild node
|
||||
properties:
|
||||
grandchild-prop:
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
# SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
title: Property default value test
|
||||
description: Property default value test
|
||||
|
||||
compatible: "defaults"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
# SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
title: Device on bar bus
|
||||
description: Device on bar bus
|
||||
|
||||
compatible: "on-bus"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
# SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
title: Device on foo bus
|
||||
description: Device on foo bus
|
||||
|
||||
compatible: "on-bus"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
# SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
title: Foo bus controller
|
||||
description: Foo bus controller
|
||||
|
||||
compatible: "foo-bus"
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
# SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
title: Binding in test-bindings/
|
||||
description: Binding in test-bindings/
|
||||
|
||||
compatible: "in-dir-1"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
# SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
title: Include ordering test
|
||||
description: Include ordering test
|
||||
|
||||
compatible: "order-1"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
# SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
title: Include ordering test
|
||||
description: Include ordering test
|
||||
|
||||
compatible: "order-2"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
# SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
title: Parent binding
|
||||
description: Parent binding
|
||||
|
||||
compatible: "binding-include-test"
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
# SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
title: Device.props test
|
||||
description: Device.props test
|
||||
|
||||
compatible: "props"
|
||||
|
|
|
|||
|
|
@ -42,6 +42,7 @@ def run():
|
|||
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)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue