michaelh/zephyr
1
0
Fork 0
Code Releases Activity

dts: Remove support for deprecated DTS binding syntax

Browse source 
We deprecated a number of aspects of the DTS binding syntax in Zephyr
2.1.  Remove the support for the deprecated syntax.  Remove from docs
about the deprecated syntax as well.

Removed reference in release-notes-2.1.rst to legacy_binding_syntax
since that anchor doesn't exist anymore.

Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
This commit is contained in:
Kumar Gala 2020-06-09 09:48:29 -05:00 • committed by Anas Nashif
commit 6bf761fc0a
7 changed files with 14 additions and 271 deletions
Download patch file Download diff file Expand all files Collapse all files

78
doc/guides/dts/bindings.rst
View file

@ -73,81 +73,3 @@ Below is a template that shows the Zephyr bindings file syntax. It is stored in
.. literalinclude:: ../../../dts/binding-template.yaml
:language: yaml
.. _legacy_binding_syntax:
Legacy bindings syntax
**********************
The bindings syntax described above was introduced in the Zephyr 2.1 release.
This section describes how to update bindings written in the legacy syntax,
starting with this example written in the legacy syntax.
.. code-block:: yaml
title: ...
description: ...
inherits:
!include foo.yaml
parent:
bus: spi
parent-bus: spi
properties:
compatible:
constraint: "company,device"
type: string-array
frequency:
type: int
category: optional
sub-node:
properties:
child-prop:
type: int
category: required
# Assume this is a binding for an interrupt controller
"#cells":
- irq
- priority
- flags
This should now be written like this:
.. code-block:: yaml
description: ...
compatible: "company,device"
include: foo.yaml
bus: spi
properties:
frequency:
type: int
required: false
child-binding:
description: ...
properties:
child-prop:
type: int
required: true
interrupt-cells:
- irq
- priority
- cells
The legacy syntax is still supported for backwards compatibility, but generates
deprecation warnings. Support for the legacy bindings syntax was originally
scheduled to be dropped in the Zephyr 2.3 release, but will now be maintained
until Zephyr 2.4.

3
doc/releases/release-notes-2.1.rst
View file

@ -419,8 +419,6 @@ Build and Infrastructure
* Various parts of the binding format have been simplified. The format is
better documented now too.
See :ref:`legacy_binding_syntax` for more information.
Libraries / Subsystems
***********************
@ -945,4 +943,3 @@ release:
* :github:`2686` - Add qemu\_cortex\_m0/m0+ board.
* :github:`2490` - Provide sanity test cases for NANO\_ESF/NANO\_ISF structures
* :github:`2144` - clearly document internal kernel interfaces

7
dts/binding-template.yaml
View file

@ -359,10 +359,3 @@ pwm-cells:
gpio-cells:
- pin
- flags
# This older syntax is deprecated and will generate a warning when used. It
# works as a catch-all, where the name of the referencing 'phandle-array'
# property doesn't matter.
"#cells":
- pin
- flags

140
scripts/dts/edtlib.py
View file

@ -394,53 +394,23 @@ class EDT:
# compatible:
# constraint: <string>
def new_style_compat():
# New-style 'compatible: "foo"' compatible
if binding is None or "compatible" not in binding:
# Empty file, binding fragment, spurious file, or old-style
# compat
return None
if binding is None or "compatible" not in binding:
# Empty file, binding fragment, spurious file, or old-style
# compat
return None
compatible = binding["compatible"]
if not isinstance(compatible, str):
_err("malformed 'compatible: {}' field in {} - "
"should be a string, not {}"
.format(compatible, binding_path,
type(compatible).__name__))
compatible = binding["compatible"]
if not isinstance(compatible, str):
_err("malformed 'compatible: {}' field in {} - "
"should be a string, not {}"
.format(compatible, binding_path,
type(compatible).__name__))
return compatible
def old_style_compat():
# Old-style 'constraint: "foo"' compatible
try:
return binding["properties"]["compatible"]["constraint"]
except Exception:
return None
new_compat = new_style_compat()
old_compat = old_style_compat()
if old_compat:
self._warn("The 'properties: compatible: constraint: ...' way of "
"specifying the compatible in {} is deprecated. Put "
"'compatible: \"{}\"' at the top level of the binding "
"instead.".format(binding_path, old_compat))
if new_compat:
_err("compatibles for {} should be specified with either "
"'compatible:' at the top level or with the legacy "
"'properties: compatible: constraint: ...' field, not "
"both".format(binding_path))
return old_compat
return new_compat
return compatible
def _merge_included_bindings(self, binding, binding_path):
# Merges any bindings listed in the 'include:' section of 'binding'
# into the top level of 'binding'. Also supports the legacy
# 'inherits: !include ...' syntax for including bindings.
# into the top level of 'binding'.
#
# Properties in 'binding' take precedence over properties from included
# bindings.
@ -463,19 +433,6 @@ class EDT:
if "child-binding" in binding and "include" in binding["child-binding"]:
self._merge_included_bindings(binding["child-binding"], binding_path)
# Legacy syntax
if "inherits" in binding:
self._warn("the 'inherits:' syntax in {} is deprecated and will "
"be removed - please use 'include: foo.yaml' or "
"'include: [foo.yaml, bar.yaml]' instead"
.format(binding_path))
inherits = binding.pop("inherits")
if not isinstance(inherits, list) or \
not all(isinstance(elm, str) for elm in inherits):
_err("malformed 'inherits:' in " + binding_path)
fnames += inherits
if not fnames:
return binding
@ -589,21 +546,6 @@ class EDT:
# Does sanity checking on 'binding'. Only takes 'self' for the sake of
# self._warn().
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 "description" not in binding:
_err("missing 'description' property in " + binding_path)
@ -628,43 +570,6 @@ class EDT:
_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("'{}: 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"}:
_err("expected (just) 'bus:' in '{}:' in {}"
.format(pc, binding_path))
if not isinstance(binding[pc]["bus"], str):
_err("malformed '{}: bus:' value in {}, expected string"
.format(pc, binding_path))
self._check_binding_properties(binding, binding_path)
if "child-binding" in binding:
@ -674,25 +579,6 @@ class EDT:
self._check_binding(binding["child-binding"], binding_path)
if "sub-node" in binding:
self._warn("'sub-node: properties: ...' in {} is deprecated and "
"will be removed - please give a full binding for the "
"child node in 'child-binding:' instead (see "
"binding-template.yaml)".format(binding_path))
if binding["sub-node"].keys() != {"properties"}:
_err("expected (just) 'properties:' in 'sub-node:' in {}"
.format(binding_path))
self._check_binding_properties(binding["sub-node"], binding_path)
if "#cells" in binding:
self._warn('"#cells:" in {} is deprecated and will be removed - '
"please put 'interrupt-cells:', 'pwm-cells:', "
"'gpio-cells:', etc., instead. The name should match "
"the name of the corresponding phandle-array property "
"(see binding-template.yaml)".format(binding_path))
def ok_cells_val(val):
# Returns True if 'val' is an okay value for '*-cells:' (or the
# legacy '#cells:')
@ -714,7 +600,7 @@ class EDT:
return
ok_prop_keys = {"description", "type", "required", "category",
"constraint", "enum", "const", "default"}
"enum", "const", "default"}
for prop_name, options in binding["properties"].items():
for key in options:

4
scripts/dts/test-bindings/deprecated-include.yaml
View file

@ -1,4 +0,0 @@
properties:
required-2:
type: int
required: true

36
scripts/dts/test-bindings/deprecated.yaml
View file

@ -1,36 +0,0 @@
# SPDX-License-Identifier: BSD-3-Clause
title: Deprecated stuff
description: Deprecated stuff
# Deprecated include syntax
inherits:
!include deprecated-include.yaml
properties:
# Deprecated way of specifying the 'compatible' string
compatible:
constraint: "deprecated"
type: string-array
# Deprecated 'category' key (replaced with 'required')
required:
type: int
category: required
optional:
type: int
category: optional
# Deprecated older 'child-binding'-alike
sub-node:
properties:
foos:
type: phandle-array
required: true
# Deprecated older catch-all version of *-cells
"#cells":
- foo
- bar

17
scripts/dts/testedtlib.py
View file

@ -28,15 +28,8 @@ def run():
warnings = io.StringIO()
edt = edtlib.EDT("test.dts", ["test-bindings"], warnings)
# Deprecated features are tested too, which generate warnings. Verify them.
# Verify warnings
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)
warning: "#cells:" in test-bindings/deprecated.yaml is deprecated and will be removed - please put 'interrupt-cells:', 'pwm-cells:', 'gpio-cells:', etc., instead. The name should match the name of the corresponding phandle-array property (see binding-template.yaml)
warning: unit address and first address in 'reg' (0x1) don't match for /reg-zero-size-cells/node
warning: unit address and first address in 'reg' (0x5) don't match for /reg-ranges/parent/node
warning: unit address and first address in 'reg' (0x30000000200000001) don't match for /reg-nested-ranges/grandparent/parent/node
@ -159,14 +152,6 @@ warning: unit address and first address in 'reg' (0x30000000200000001) don't mat
verify_streq(grandchild.description, "grandchild node")
verify_streq(grandchild.props, "OrderedDict([('grandchild-prop', <Property, name: grandchild-prop, type: int, value: 2>)])")
#
# Test deprecated 'sub-node' key (replaced with 'child-binding') and
# deprecated '#cells' key (replaced with '*-cells')
#
verify_streq(edt.get_node("/deprecated/sub-node").props,
"OrderedDict([('foos', <Property, name: foos, type: phandle-array, value: [<ControllerAndData, controller: <Node /deprecated in 'test.dts', binding test-bindings/deprecated.yaml>, data: OrderedDict([('foo', 1), ('bar', 2)])>]>)])")
#
# Test EDT.compat2enabled
#