edtlib: tests: refine coverage of Binding objects initialization

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