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

[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@quicinc.com>
---
 .../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@quicinc.com>
+
+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

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

[Krzysztof Kozlowski]

On 01/09/2023 08:02, Naman Jain wrote:
> 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.

Whether camera is or is not supported, is defined by presence of camera
node or by its status field.

Existing firmware (e.g. U-Boot) is also doing this - patching DTS when
needed.

I do not think introducing some parallel way makes any sense, so no,
that's not the way to do it.

Best regards,
Krzysztof

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

[Naman Jain]

On 9/1/2023 12:52 PM, Krzysztof Kozlowski wrote:
> On 01/09/2023 08:02, Naman Jain wrote:
>> 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.
> Whether camera is or is not supported, is defined by presence of camera
> node or by its status field.
>
> Existing firmware (e.g. U-Boot) is also doing this - patching DTS when
> needed.
>
> I do not think introducing some parallel way makes any sense, so no,
> that's not the way to do it.
>
> Best regards,
> Krzysztof


Thanks Krzysztof for reviewing the patch. I think for telling whether 
the Camera HW block is not
supported / not present, firmware can either remove the device tree 
node, or change its status
to disabled, so that is fine.
With this patch, I was trying to address the use case, where Camera is 
supported but certain features
of that particular Camera are not supported, due to dependent HW blocks 
not present, or due to
product decision to not support it. We wanted to avoid the firmware to 
have this overhead of knowing
what these individual bits mean and thus, disable few of the HW blocks 
that are supposed to be
disabled. And this is applicable for each of these HW blocks.

For example, we can know from 32 bits provided for modem, if 3G/4G/5G is 
supported or not on a
platform. That is decided based on presence/absence of certain HW 
blocks, but it may or may not be as
simple as disabling a particular DT node.
Basically we wanted to defer it to the subsystem drivers, to do whatever 
they like with this
information on sub-parts that are available.

Will rephrase my commit message to make it clearer, but would like to 
hear your thoughts on this first.


Thanks,

Naman Jain


>

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

[Krzysztof Kozlowski]

On 04/09/2023 10:38, Naman Jain wrote:
> 
> On 9/1/2023 12:52 PM, Krzysztof Kozlowski wrote:
>> On 01/09/2023 08:02, Naman Jain wrote:
>>> 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.
>> Whether camera is or is not supported, is defined by presence of camera
>> node or by its status field.
>>
>> Existing firmware (e.g. U-Boot) is also doing this - patching DTS when
>> needed.
>>
>> I do not think introducing some parallel way makes any sense, so no,
>> that's not the way to do it.
>>
>> Best regards,
>> Krzysztof
> 
> 
> Thanks Krzysztof for reviewing the patch. I think for telling whether 
> the Camera HW block is not
> supported / not present, firmware can either remove the device tree 
> node, or change its status
> to disabled, so that is fine.
> With this patch, I was trying to address the use case, where Camera is 
> supported but certain features
> of that particular Camera are not supported, due to dependent HW blocks 
> not present, or due to
> product decision to not support it. We wanted to avoid the firmware to 
> have this overhead of knowing
> what these individual bits mean and thus, disable few of the HW blocks 
> that are supposed to be
> disabled. And this is applicable for each of these HW blocks.

What is and what is not supported by camera, is obvious from the
compatible and you do not need this patch.

> 
> For example, we can know from 32 bits provided for modem, if 3G/4G/5G is 
> supported or not on a
> platform.

Again, compatible-dependent.

> That is decided based on presence/absence of certain HW 
> blocks, but it may or may not be as
> simple as disabling a particular DT node.
> Basically we wanted to defer it to the subsystem drivers, to do whatever 
> they like with this
> information on sub-parts that are available.
> 
> Will rephrase my commit message to make it clearer, but would like to 
> hear your thoughts on this first.

Sorry, no, such node is not the solution.

Best regards,
Krzysztof

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

[Konrad Dybcio]

On 4.09.2023 10:38, Naman Jain wrote:
> 
> On 9/1/2023 12:52 PM, Krzysztof Kozlowski wrote:
>> On 01/09/2023 08:02, Naman Jain wrote:
>>> 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.
>> Whether camera is or is not supported, is defined by presence of camera
>> node or by its status field.
>>
>> Existing firmware (e.g. U-Boot) is also doing this - patching DTS when
>> needed.
>>
>> I do not think introducing some parallel way makes any sense, so no,
>> that's not the way to do it.
>>
>> Best regards,
>> Krzysztof
> 
> 
> Thanks Krzysztof for reviewing the patch. I think for telling whether the Camera HW block is not
> supported / not present, firmware can either remove the device tree node, or change its status
> to disabled, so that is fine.
Messing with the device tree for no reason (e.g. filling in
/memory@something/reg is expected) or without user intervention
(e.g. static DTBO flashed by the user) is not favored.

Konrad