edtlib: tests: refine bindings initialization coverage

Bindings initialization supports a rich include mechanism:
- a base binding may be "include:"ed at any level: binding,
  child-binding, grandchild-binding, etc, the defined
  properties being injected (in cascade) at the level
  of inclusion
- whenever an "include:" appears, the including binding
  may filter the properties it expects at the binding,
  child-binding, etc, levels; these filters must apply
  transitively across included files
- when base bindings are inherited which contain
  definitions about a same property, rules apply: sometimes
  the last one "wins", but not always,
  and quite a few things are not allowed (e.g. downgrading
  a "required: true" or changing a "const:" value)

All this happens (recursively) in the Binding constructor,
independently of any actual devicetree model (EDT instance).

These additional unit tests try to cover somewhat systematically
what we finally get at the exit of the constructor once the object
is completely initialized.

Signed-off-by: Christophe Dufaza <[email protected]>

Author: dottspina

scripts/dts/python-devicetree/tests/test-bindings-init/base.yaml

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Base include file for testing bindings initialization.
+#
+# Involves base property definitions ("type:", "description:", "const:",
+# "required:", "enum:" and "default:") up to the grandchild-binding level.
+#
+# Binding:
+#   + prop-1
+#   + prop-2
+#   + prop-enum
+#   + prop-req
+#   + prop-const
+#   + prop-default
+#
+#   Child-binding:
+#     + child-prop-1
+#     + child-prop-2
+#     + child-prop-enum
+#     + child-prop-req
+#     + child-prop-const
+#     + child-prop-default
+#
+#     Grandchild-binding:
+#       + grandchild-prop-1
+#       + grandchild-prop-2
+#       + grandchild-prop-enum
+#       + grandchild-prop-req
+#       + grandchild-prop-const
+#       + grandchild-prop-default
+
+description: Base property specifications.
+
+properties:
+  prop-1:
+    description: Base property 1.
+    type: int
+  prop-2:
+    type: string
+  prop-enum:
+    type: string
+    required: false
+    enum:
+      - FOO
+      - BAR
+  prop-const:
+    type: int
+    const: 8
+  prop-req:
+    type: int
+    required: true
+  prop-default:
+    type: int
+    default: 1
+
+child-binding:
+  description: Base child-binding description.
+
+  properties:
+    child-prop-1:
+      description: Base child-prop 1.
+      type: int
+    child-prop-2:
+      type: string
+    child-prop-enum:
+      type: string
+      required: false
+      enum:
+        - CHILD_FOO
+        - CHILD_BAR
+    child-prop-const:
+      type: int
+      const: 16
+    child-prop-req:
+      type: int
+      required: true
+    child-prop-default:
+      type: int
+      default: 2
+
+  child-binding:
+    description: Base grandchild-binding description.
+
+    properties:
+      grandchild-prop-1:
+        description: Base grandchild-prop 1.
+        type: int
+      grandchild-prop-2:
+        type: string
+      grandchild-prop-enum:
+        type: string
+        required: false
+        enum:
+          - GRANDCHILD_FOO
+          - GRANDCHILD_BAR
+      grandchild-prop-const:
+        type: int
+        const: 32
+      grandchild-prop-req:
+        type: int
+        required: true
+      grandchild-prop-default:
+        type: int
+        default: 3

scripts/dts/python-devicetree/tests/test-bindings-init/base_amend.yaml

@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Amends base properties specifications:
+# - extends property specifications by adding definitions,
+#   e.g. setting a "default:" value
+# - overwrites existing definitions of a property,
+#   e.g. change its "description:"
+# - specify new properties
+#
+# The same kind of amendments are applied to the same properties
+# at each level (binding, child-binding, grandchild-binding).
+#
+# | Definition     | Extended for | Overwritten for |
+# |----------------|--------------|-----------------|
+# | description:   | prop-2       | prop-1          |
+# | required:      |              | prop-enum       |
+# | enum:          | prop-2       |                 |
+# | const:         | prop-1       |                 |
+# | default:       | prop-2       |                 |
+#
+# Non authorized amendments, e.g. changing a "const:" value
+# or downgrading a "required: true" definition are tested separately.
+
+description: Amended description.
+
+include: base.yaml
+
+properties:
+  prop-1:
+    # The including binding is permitted to overwrite a property description.
+    description: Overwritten description.
+    # The including binding is permitted to set a "const:" value.
+    const: 0xf0
+
+  prop-2:
+    # The including binding is permitted to add a property description.
+    description: New description.
+    # The including binding is permitted to limit property values
+    # to an enumeration.
+    enum:
+      - EXT_FOO
+      - EXT_BAR
+    # The including binding is permitted to set a default value.
+    default: EXT_FOO
+
+  # The including binding is permitted to promote a property
+  # to requirement.
+  prop-enum:
+    required: true
+
+  # The including binding is permitted to define a new property.
+  prop-new:
+    type: int
+
+# Same amendments at the child-binding level.
+child-binding:
+  properties:
+    child-prop-1:
+      description: Overwritten description (child).
+      const: 0xf1
+
+    child-prop-2:
+      description: New description (child).
+      enum:
+        - CHILD_EXT_FOO
+        - CHILD_EXT_BAR
+      default: CHILD_EXT_FOO
+
+    child-prop-enum:
+      required: true
+
+    child-prop-new:
+      type: int
+
+  # Same amendments at the grandchild-binding level.
+  child-binding:
+    # Plus amended grandchild-binding description.
+    description: Amended grandchild-binding description.
+
+    properties:
+      grandchild-prop-1:
+        description: Overwritten description (grandchild).
+        const: 0xf2
+
+      grandchild-prop-2:
+        description: New description (grandchild).
+        enum:
+          - GRANDCHILD_EXT_FOO
+          - GRANDCHILD_EXT_BAR
+        default: GRANDCHILD_EXT_FOO
+
+      grandchild-prop-enum:
+        required: true
+
+      grandchild-prop-new:
+        type: int

scripts/dts/python-devicetree/tests/test-bindings-init/base_inherit.yaml

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Inherit base specifications without modification.
+
+include: base.yaml

scripts/dts/python-devicetree/tests/test-bindings-init/base_multi.yaml

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Includes base bindings at multiple levels (binding,
+# child-binding, grandchild-binding):
+#
+#   include: base.yaml
+#   child-binding:
+#     include: base.yaml
+#     child-binding:
+#       include: base.yaml
+#
+# Which properties are specified at which levels is summarized bellow
+# for convenience.
+#
+# Child-binding level:
+#   From top-level "include:" element.
+#   - child-prop-1 (amended)
+#   - child-prop-2
+#   - child-prop-enum
+#   From "child-binding: include:" element.
+#   - prop-1 (amended)
+#   - prop-2 (amended)
+#   - prop-enum (amended)
+#
+# Grandchild-binding level:
+#   From top-level "include:" element.
+#   - grandchild-prop-1 (amended)
+#   - grandchild-prop-2
+#   - grandchild-prop-enum
+#   From "child-binding: include:" element.
+#   - child-prop-1 (amended)
+#   - child-prop-2
+#   - child-prop-enum
+#   From "child-binding: child-binding: include:" element.
+#   - prop-1 (amended)
+#   - prop-2 (amended)
+#   - prop-enum (amended)
+#
+# Grand-grandchild-binding level:
+#   From "child-binding: include:" element.
+#   - child-prop-1
+#   - child-prop-2
+#   - child-prop-enum
+#   From "child-binding: child-binding: include:" element.
+#   - grandchild-prop-1
+#   - grandchild-prop-2
+#   - grandchild-prop-enum
+
+description: Description of 'base_multi.yaml'.
+
+include:
+  - name: base.yaml
+    child-binding:
+      property-allowlist: [child-prop-1, child-prop-2, child-prop-enum]
+      child-binding:
+        property-allowlist: [grandchild-prop-1, grandchild-prop-2, grandchild-prop-enum]
+
+child-binding:
+  include:
+    - name: base.yaml
+      property-allowlist: [prop-1, prop-2, prop-enum]
+      child-binding:
+        property-allowlist: [child-prop-1, child-prop-2, child-prop-enum]
+        child-binding:
+          property-allowlist: [grandchild-prop-1, grandchild-prop-2, grandchild-prop-enum]
+
+  properties:
+    # Amend top-level "include:" element.
+    child-prop-1:
+      const: 0xf1
+    # Amend this "child-binding: include:" element.
+    prop-1:
+      const: 0xf1
+    prop-2:
+      description: New description (child).
+    prop-enum:
+      required: true
+      default: FOO
+
+  child-binding:
+    include:
+      - name: base.yaml
+        property-allowlist: [prop-1, prop-2, prop-enum]
+        child-binding:
+          property-allowlist: [child-prop-1, child-prop-2, child-prop-enum]
+          child-binding:
+            property-allowlist: [grandchild-prop-1, grandchild-prop-2, grandchild-prop-enum]
+
+    properties:
+      # Amend above top-level "include:" element.
+      grandchild-prop-1:
+        const: 0xf2
+      # Amend above "child-binding: include:" element.
+      child-prop-1:
+        const: 0xf2
+      # Amend this "child-binding: child-binding: include:" element.
+      prop-1:
+        const: 0xf2
+      prop-2:
+        description: New description (grandchild).
+      prop-enum:
+        required: true
+        default: FOO