[PATCH] dt-bindings: firmware: Add documentation for qcom,platform-parts-info

[Naman Jain]

Add documentation to describe device tree bindings for QCOM's
platform-parts-info node. Firmware populates these nodes to pass the
information to kernel regarding the subset of hardware blocks
and features like Camera, Modem, Display present in a product.

This is to support that the same software image runs seamlessly on
different platforms where one or more HW blocks are not supported or
if some sub parts for a particular block are not supported.

Purpose of these definitions is to allow clients to know about this,
and thus, handle these cases gracefully.
For eg: Camera drivers and user space daemons can use this to know
if camera is not supported on the device, or some particular HW blocks
inside a camera are not supported.

Signed-off-by: Naman Jain <quic_namajain@xxxxxxxxxxx>
---
 .../firmware/qcom,platform-parts-info.yaml    | 88 +++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/firmware/qcom,platform-parts-info.yaml

diff --git a/Documentation/devicetree/bindings/firmware/qcom,platform-parts-info.yaml b/Documentation/devicetree/bindings/firmware/qcom,platform-parts-info.yaml
new file mode 100644
index 000000000000..64e085d3ea88
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/qcom,platform-parts-info.yaml
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/qcom,platform-parts-info.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: QCOM Platform's Parts Information
+
+description:
+  Qualcomm platforms support a feature where a subset of hardware blocks
+  like Camera, GPU, Display, Modem, CPUs are available in a product,
+  based on features selected for a particular Stock keeping unit (SKU)
+  and the same software images are supposed to work seamlessly with these.
+  This is to support usecases where lets say a software image running on handset
+  device which supports display and camera, can work just fine on another
+  IoT product which doesn't need these. This also enables usecases, where certain
+  sub parts for a HW block are not supported.
+
+  Firmware (bootloader), reads the parts related information from lower
+  layers and passes this information to kernel via this device tree interface,
+  so that the respective clients are aware of it.
+  For example, Camera drivers and its user space daemons can use this interface
+  to know if camera is not supported on the device or if certain sub feature inside
+  camera is not supported.
+
+maintainers:
+  - Naman Jain <quic_namajain@xxxxxxxxxxx>
+
+properties:
+  $nodename:
+    const: qcom,platform-parts-info
+
+  qcom,subset-parts-names:
+    description:
+      List of part name strings, sorted in same order as the subset-parts property.
+      Parts here can be modem, camera, display etc. which are either partially supported
+      or not supported at all.
+    $ref: /schemas/types.yaml#/definitions/string-array
+    minItems: 1
+    maxItems: 13
+    items:
+      enum: [gpu, video, camera, display, audio, wlan, compute, sensors, npu, spss, nav, nsp, eva]
+
+  qcom,subset-parts:
+    description:
+      A matrix, with each row corresponding to a specific part type (GPU, Camera etc) mentioned
+      in subset-parts-names property. The number of rows here are expected to be same as number of
+      subset-parts-names provided. A row can contain multiple bitmask values representing
+      multiple parts of the same type, if supported on a platform, like 2 display panels, or
+      3 cameras for example.
+      Each bitmask value, has its 0th bit set if that part is completely not supported.
+      Otherwise, rest of the bits will correspond to specific functionalities
+      of that part not supported.
+      If the bitmask is 0xffff, i.e. all bits set, then that value is invalid and not to be
+      considered.
+    $ref: /schemas/types.yaml#/definitions/uint32-matrix
+    minItems: 1
+    maxItems: 13
+    items:
+      maxItems: 3
+      items:
+        description:
+          Bitmask value corresponding to a part of a specific part type, or 0xffff if data is
+          invalid and not to be considered.
+
+  qcom,subset-cores:
+    description:
+      A bitmask value, encoded from LSB with a set bit corresponding to actual physical CPU
+      not supported on the SoC.
+    $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+  - qcom,subset-cores
+
+additionalProperties: false
+
+examples:
+  - |
+    firmware {
+        qcom,platform-parts-info {                    /* populated by firmware */
+            qcom,subset-parts-names = "gpu", "display", "camera";
+            qcom,subset-parts = <0x1 0xffff 0xffff>,  /* GPU 1 is completely not supported */
+                                <0x0 0x1 0xffff>,     /* Display 2 is fully not supported */
+                                <0x30 0xffff 0xffff>; /* Camera 1 is partially supported */
+            qcom,subset-cores = <0x90>;               /* CPU 4 and 7 are not supported */
+        };
+    };
+...
-- 
2.17.1