[PATCH RFC v3 5/9] dt-bindings: board: Document board-ids for Qualcomm devices

[Conor Dooley]

On Tue, May 21, 2024 at 11:38:02AM -0700, Elliot Berman wrote:
> Document board identifiers for devices from Qualcomm Technologies, Inc.
> These platforms are described with two mechanisms: the hardware SoC
> registers and the "CDT" which is in a RO storage.
> 
> The hardware SoC registers describe both the SoC (e.g. SM8650, SC7180)
> as well as revision. Add qcom,soc to describe only the SoC itself and
> qcom,soc-version when the devicetree only works with a certain revision.
> 
> The CDT describes all other information about the board/platform.
> Besides the platform type (e.g. MTP, ADP, CRD), there are 3 further
> levels of versioning as well as additional fields to describe the PMIC
> and boot storage device attached. The 3 levels of versioning are a
> subtype, major, and minor version of the platform. Support describing
> just the platform type (qcom,platform), the platform type and subtype
> (qcom,platform-type), and all 4 numbers (qcom,platform-version).
> 
> Signed-off-by: Elliot Berman <quic_eberman at quicinc.com>
> ---
>  .../devicetree/bindings/board/qcom,board-id.yaml   | 144 +++++++++++++++++++++
>  1 file changed, 144 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/board/qcom,board-id.yaml b/Documentation/devicetree/bindings/board/qcom,board-id.yaml
> new file mode 100644
> index 000000000000..53ba7acab4c3
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/board/qcom,board-id.yaml
> @@ -0,0 +1,144 @@
> +# SPDX-License-Identifier: BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/board/qcom,board-id.yaml
> +$schema: http://devicetree.org/meta-schemas/core.yaml
> +
> +title: Board identifiers for devices from Qualcomm Technologies, Inc.
> +description: Board identifiers for devices from Qualcomm Technologies, Inc.
> +
> +maintainers:
> +  - Elliot Berman <quic_eberman at quicinc.com>
> +
> +properties:
> +  $nodename:
> +    const: 'board-id'
> +
> +  qcom,soc:
> +    description:
> +      List of Qualcomm SoCs this devicetree is applicable to.
> +
> +  qcom,soc-version:
> +    items:
> +      items:
> +        - description: Qualcomm SoC identifier
> +        - description: SoC version
> +
> +  qcom,platform:
> +    description:
> +      List of Qualcomm platforms this devicetree is applicable to.
> +
> +  qcom,platform-type:
> +    items:
> +      items:
> +        - description: Qualcomm platform type identifier
> +        - description: Qualcomm platform subtype
> +
> +  qcom,platform-version:
> +    items:
> +      items:
> +        - description: Qualcomm platform type identifier
> +        - description: Qualcomm platform subtype
> +        - description: Qualcomm platform major and minor version.
> +
> +  qcom,boot-device:
> +    description:
> +      Boot device type
> +
> +  qcom,pmic:
> +    description:
> +      List of Qualcomm PMIC attaches
> +
> +  qcom,pmic-id:
> +    items:
> +      items:
> +        - description: Qualcomm PMIC identifier
> +        - description: Qualcomm PMIC revision
> +
> +allOf:
> +  # either describe soc or soc-version; it's confusing to have both

Why not just use the one that has the most information and discard the
others? If your dtb picker for this platform doesn't care about the soc
version, then just don't look at that cell?

Likewise for platform and PMIC, why can't you ignore the cells you don't
care about, rather than having a new property for each variant? Nothing
in this patch explains why multiple variants are required rather than
just dealing with the most informational.

Thanks,
Conor.

> +  - if:
> +      properties:
> +        qcom,soc: true
> +    then:
> +      properties:
> +        qcom,soc-version: false
> +  - if:
> +      properties:
> +        qcom,soc-version: true
> +    then:
> +      properties:
> +        qcom,soc: false
> +
> +  # describe one of platform, platform-type, or platform-version; it's confusing to have multiple
> +  - if:
> +    properties:
> +      qcom,platform: true
> +    then:
> +      properties:
> +        qcom,platform-type: false
> +        qcom,platform-version: false
> +  - if:
> +    properties:
> +      qcom,platform-type: true
> +    then:
> +      properties:
> +        qcom,platform: false
> +        qcom,platform-version: false
> +  - if:
> +    properties:
> +      qcom,platform: true
> +    then:
> +      properties:
> +        qcom,platform: false
> +        qcom,platform-type: false
> +
> +  # either describe pmic or pmic-id; it's confusing to have both
> +  - if:
> +    properties:
> +      qcom,pmic: true
> +    then:
> +      properties:
> +        qcom,pmic-id: false
> +  - if:
> +    properties:
> +      qcom,pmic-id: true
> +    then:
> +      properties:
> +        qcom,pmic: false
> +
> +additionalProperties: true
> +
> +examples:
> +  - |
> +    #include <dt-bindings/arm/qcom,ids.h>
> +    / {
> +      compatible = "qcom,sm8650";
> +      board-id {
> +        qcom,soc = <QCOM_ID_SM8650>;
> +        qcom,platform = <QCOM_BOARD_ID_MTP>;
> +      };
> +    };
> +
> +  - |
> +    #include <dt-bindings/arm/qcom,ids.h>
> +    / {
> +      compatible = "qcom,sm8650";
> +      board-id {
> +        qcom,soc-version = <QCOM_ID_SM8650 QCOM_SOC_REVISION(1)>,
> +                           <QCOM_ID_SM8650 QCOM_SOC_REVISION(2)>;
> +        qcom,platform-type = <QCOM_BOARD_ID_MTP 0>, <QCOM_BOARD_ID_MTP 1>;
> +      };
> +    };
> +
> +  - |
> +    #include <dt-bindings/arm/qcom,ids.h>
> +    / {
> +      compatible = "qcom,sm8650";
> +      board-id {
> +        qcom,soc = <QCOM_ID_SM8650>;
> +        qcom,platform-version = <QCOM_BOARD_ID(MTP, 0, 1, 0)>,
> +                                <QCOM_BOARD_ID(MTP, 0, 1, 1)>;
> +        qcom,boot-device = <QCOM_BOARD_BOOT_UFS>;
> +      };
> +    };
> 
> -- 
> 2.34.1
> 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 228 bytes
Desc: not available
URL: <http://lists.infradead.org/pipermail/linux-arm-kernel/attachments/20240525/d39d53d7/attachment.sig>