edtlib: tests: refine coverage of Binding objects initialization

Add a series of unit tests which try to cover somewhat systematically
the possible inputs and what we finally get at the exit
of the Binding constructor.

Running the assumption that any (valid) YAML binding file is
something we can make a Binding instance with:
- check which properties are defined at which level (binding,
  child-binding, grandchild-binding, etc) and their specifications
  once the binding is initialized
- check how including bindings are permitted to specialize
  the specifications of inherited properties
- check the rules applied when overwriting a binding's description
  or compatible string (at the binding, child-binding, etc, levels)

Some tests covering known issues are disabled by default:
- this permits to document these issues
- while not causing CI errors (when running the python-devicetree
  unit tests)
- enabling these tests without causing errors should allow us
  to consider the related issues are fixed

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

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

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

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Test inheritance rules applied to compatible strings
+# and bindings descriptions.
+
+description: Binding description.
+
+compatible: vnd,compat-desc
+
+include: compat_desc_base.yaml
+
+child-binding:
+  description: Child-binding description.
+  compatible: vnd,child-compat-desc
+
+  child-binding:
+    description: Grandchild-binding description.
+    compatible: vnd,grandchild-compat-desc

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

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Base file for testing inheritance rules applied to
+# compatible strings and bindings descriptions.
+
+description: Binding description (base).
+
+compatible: vnd,compat-desc-base
+
+child-binding:
+  description: Child-binding description (base).
+  compatible: vnd,child-compat-desc-base
+
+  child-binding:
+    description: Grandchild-binding description (base).
+    compatible: vnd,grandchild-compat-desc-base

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

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Test consequences of inclusion order on inherited
+# compatible strings and descriptions.
+
+description: Binding description (multi).
+
+compatible: vnd,compat-desc-multi
+
+# Descriptions at the child-binding level and bellow
+# will depend on inclusion order: the first wins.
+include:
+  - compat_desc_base.yaml
+  - compat_desc.yaml