dts: edtlib: Sanity-check the final merged binding only

Sanity-checking each !included file separately was inherited from the
old scripts. It makes it messy to check that combinations of fields make
sense, e.g. to check 'const:' or 'default:' against 'type:', since those
fields might come from different files (this is handy, since it makes
sense to just add/change a 'const:' value, for example).

Drop the requirement that each !included file is a complete binding in
itself, and treat them as binding fragments instead. Only check the
final merged binding.

This also means that !included files no longer need to have a
'description:' or 'title:' (those have always been unused for !included
files), so remove those, and add comments that explain what the
fragments are for instead. That should demystify bindings a bit.

Also fix the descriptions of i2c.yaml, i2s.yaml, spi.yaml, and
uart.yaml. They're for controllers, not devices. These are copy-paste
error from the corresponding device .yaml files.

Piggyback some indentation consistency nits in binding-template.yaml.

Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
This commit is contained in:
Ulf Magnusson 2019-08-15 14:06:15 +02:00 committed by Kumar Gala
commit 1480ad9ce7
31 changed files with 56 additions and 161 deletions

View file

@ -1,7 +1,4 @@
title: base device binding
description: >
Binding for device
# Common fields for all devices
properties:
status:

View file

@ -4,13 +4,13 @@ description: >
Longer free-form description of the node.
Can go over multiple lines.
# Bindings are often based on other bindings, which are given in 'inherits'.
# The resulting binding is the union of the inherited bindings and this binding
# (internally, it's a recursive dictionary merge).
# Many bindings have common fields. These are stored in files given in
# 'inherits', which are merged into the binding (with a recursive dictionary
# merge).
#
# If a field appears both in this binding and in a binding it inherits, then
# the value in this binding takes precedence. This can be used to change a
# 'category: optional' from an inherited binding to a 'category: required' (see
# If a field appears both in the binding and in a file it inherits, then the
# value in the binding takes precedence. This can be used e.g. to change a
# 'category: optional' from an inherited file to a 'category: required' (see
# the 'properties' description below).
inherits:
!include other.yaml # or [other1.yaml, other2.yaml]
@ -38,8 +38,8 @@ parent:
sub-node:
properties:
pwms:
type: compound
category: required
type: compound
category: required
# 'properties' describes properties on the node, e.g.
#
@ -121,21 +121,21 @@ properties:
# Describes an optional property like 'maximum-speed = "full-speed";
# the enum specifies known values that the string property may take
maximum-speed:
type: string
category: optional
description: Configures USB controllers to work up to a specific speed.
enum:
- "low-speed"
- "full-speed"
- "high-speed"
- "super-speed"
type: string
category: optional
description: Configures USB controllers to work up to a specific speed.
enum:
- "low-speed"
- "full-speed"
- "high-speed"
- "super-speed"
# Describes a required property '#address-cells = <1>'; the const
# specifies that the value for the property is expected to be the value 1
"#address-cells":
type: int
category: required
const: 1
type: int
category: required
const: 1
# If the binding describes an interrupt controller, GPIO controller, pinmux
# device, or any other device referenced via a phandle plus a specifier (some
@ -151,7 +151,7 @@ properties:
# at by &gpio1 is expected to have '#gpio-cells = <2>', and its binding should
# have two elements in '#cells', corresponding to the 1 and 2 values above.
"#cells":
- cell0 # name of first cell
- cell1 # name of second cell
- cell2 # name of third cell
- and so on and so forth
- cell0 # name of first cell
- cell1 # name of second cell
- cell2 # name of third cell
- and so on and so forth

View file

@ -1,7 +1,4 @@
title: CAN Base Structure
description: >
This binding gives the base structures for all CAN devices
# Common fields for CAN devices
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: Clock Controller Base Structure
description: >
This binding gives the base structure for all Clock Controller devices
# Common fields for clock controllers
properties:
"#clock-cells":

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: CPU Base Structure
description: >
This binding gives the base structures for all CPUs
# Common fields for CPUs
inherits:
!include base.yaml

View file

@ -2,10 +2,7 @@
#
# SPDX-License-Identifier: Apache-2.0
title: ESPI Base Structure
description: >
This binding gives the base structures for all ESPI devices
# Common fields for ESPI devices
inherits:
!include base.yaml

View file

@ -4,13 +4,11 @@
# SPDX-License-Identifier: Apache-2.0
#
title: Ethernet Base Structure
description: >
This binding gives a base structures for all Ethernet devices
# Common fields for Ethernet devices
inherits:
!include base.yaml
properties:
local-mac-address:
type: uint8-array

View file

@ -1,7 +1,4 @@
title: flash controller Base Structure
description: >
This binding gives the base structures for all flash controller devices
# Common fields for flash controllers
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: GPIO Controller Base Structure
description: >
This binding gives the base structure for all GPIO Controller devices
# Common fields for GPIO controllers
properties:
"gpio-controller":

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: GPIO Nexus Base Structure
description: >
This binding gives the base structure for all GPIO nexus nodes
# Common fields for GPIO nexus nodes
properties:
gpio-map:

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: I2C Device Base Structure
description: >
This binding gives the base structures for all i2c devices
# Common fields for I2C devices
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: I2C Base Structure
description: >
This binding gives the base structures for all I2C devices
# Common fields for I2C controllers
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: I2S Device Base Structure
description: >
This binding gives the base structures for all i2s devices
# Common fields for I2S devices
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: I2S Base Structure
description: >
This binding gives the base structures for all I2S devices
# Common fields for I2S controllers
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: ADC Base Structure
description: >
This binding gives the base structures for all ADC devices
# Common fields for ADC devices
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: Interrupt Controller Base Structure
description: >
This binding gives the base structure for all Interrupt Controller devices
# Common fields for interrupt controllers
properties:
"interrupt-controller":

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: RISC-V PLIC
description: >
This binding describes the RISC-V Platform-Local Interrupt Controller
# Common fields for the RISC-V platform-local interrupt controller
inherits:
!include [interrupt-controller.yaml, base.yaml]

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: MMC/SDHC module
description: >
This binding specifies the MMC/SDHC module.
# Specifies the MMC/SDHC module
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: PHY Base Structure
description: >
This binding gives the base structures for all PHY providers
# Common fields for PHY providers
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: PWM Base Structure
description: >
This binding gives the base structures for all PWM devices
# Common fields for PWM devices
properties:
label:

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: RTC Base Structure
description: >
This binding gives the base structures for all RTC devices
# Common fields for RTC devices
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: UART Device Base Structure
description: >
This binding gives the base structures for all uart devices
# Common fields for UART devices
inherits:
!include base.yaml

View file

@ -1,7 +1,4 @@
title: Uart Base Structure
description: >
This binding gives the base structures for all UART devices
# Common fields for UART controllers
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: SPI Device Base Structure
description: >
This binding gives the base structures for all spi devices
# Common fields for SPI devices
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: SPI Base Structure
description: >
This binding gives the base structures for all SPI devices
# Common fields for SPI controllers
inherits:
!include base.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: USB Endpoints' properties
description: >
This binding gives number of endpoints that the USB hardware supports
# Common fields that give the number of endpoints supported by the USB hardware
inherits:
!include usb.yaml

View file

@ -4,10 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
#
title: USB Base Structure
description: >
This binding gives the base structures for all USB devices
# Common fields for USB devices
inherits:
!include base.yaml

View file

@ -1023,8 +1023,8 @@ class Property:
additional info from the 'properties:' section of the binding.
Only properties mentioned in 'properties:' get created. Properties with
type 'phandle-array' or type 'compound' do not get Property instance. These
types only exist for type checking.
type 'phandle-array' or type 'compound' do not get Property instances.
These types only exist for type checking.
These attributes are available on Property objects:
@ -1161,7 +1161,10 @@ def _load_binding(path):
# lists/dictionaries/strings/etc. representing the file).
with open(path, encoding="utf-8") as f:
return _merge_included_bindings(yaml.load(f, Loader=yaml.Loader), path)
binding = _merge_included_bindings(yaml.load(f, Loader=yaml.Loader),
path)
_check_binding(binding, path)
return binding
def _merge_included_bindings(binding, binding_path):
@ -1172,10 +1175,6 @@ def _merge_included_bindings(binding, binding_path):
# Properties in 'binding' take precedence over properties from included
# bindings.
# Currently, we require that each !include'd file is a well-formed
# binding in itself
_check_binding(binding, binding_path)
if "inherits" in binding:
for inherited in binding.pop("inherits"):
_merge_props(

View file

@ -225,8 +225,6 @@ def merge_included_bindings(fname, node):
# section of the binding. 'fname' is the path to the top-level binding
# file, and 'node' the current top-level YAML node being processed.
check_binding_properties(node)
if 'inherits' in node:
for inherited in node.pop('inherits'):
inherited = merge_included_bindings(fname, inherited)
@ -236,25 +234,6 @@ def merge_included_bindings(fname, node):
return node
def check_binding_properties(node):
# Checks that the top-level YAML node 'node' has the expected properties.
# Prints warnings and substitutes defaults otherwise.
if 'title' not in node:
print("extract_dts_includes.py: node without 'title' -", node)
for prop in 'title', 'description':
if prop not in node:
node[prop] = "<unknown {}>".format(prop)
print("extract_dts_includes.py: '{}' property missing "
"in '{}' binding. Using '{}'."
.format(prop, node['title'], node[prop]))
if 'id' in node:
print("extract_dts_includes.py: WARNING: id field set "
"in '{}', should be removed.".format(node['title']))
def define_str(name, value, value_tabs, is_deprecated=False):
line = "#define " + name
if is_deprecated:

View file

@ -1,8 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
title: Child binding
description: Child binding
inherits:
!include grandchild.yaml

View file

@ -1,8 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
title: Grandchild binding
description: Grandchild binding
properties:
foo:
category: optional