Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <4adc6b89-bab9-ae20-662f-dd66b2049d7f@linaro.org>
Date:   Wed, 6 Jul 2022 16:41:08 +0200
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.11.0
Subject: Re: [PATCH v3] dt-bindings: qcom: document preferred compatible
 naming
Content-Language: en-US
To:     Konrad Dybcio <konrad.dybcio@somainline.org>,
        Andy Gross <agross@kernel.org>,
        Bjorn Andersson <bjorn.andersson@linaro.org>,
        Rob Herring <robh+dt@kernel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>,
        linux-arm-msm@vger.kernel.org, devicetree@vger.kernel.org,
        linux-kernel@vger.kernel.org
Cc:     Srinivas Kandagatla <srinivas.kandagatla@linaro.org>,
        Dmitry Baryshkov <dmitry.baryshkov@linaro.org>,
        Vinod Koul <vkoul@kernel.org>, Alex Elder <elder@linaro.org>,
        Robert Foss <robert.foss@linaro.org>,
        Bhupesh Sharma <bhupesh.sharma@linaro.org>
References: <20220705092846.66731-1-krzysztof.kozlowski@linaro.org>
 <ebcfa5b0-a416-64c0-3aa4-3ae9487c61ab@somainline.org>
From:   Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
In-Reply-To: <ebcfa5b0-a416-64c0-3aa4-3ae9487c61ab@somainline.org>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 06/07/2022 14:35, Konrad Dybcio wrote:
> 
> 
> On 5.07.2022 11:28, Krzysztof Kozlowski wrote:
>> Compatibles can come in two formats.  Either "vendor,ip-soc" or
>> "vendor,soc-ip".  Qualcomm bindings were mixing both of usages, so add a
>> DT schema file documenting preferred policy and enforcing it for all new
>> compatibles, except few existing patterns.
>>
>> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
>>
>> ---
>>
>> Changes since v2:
>> 1. Narrow the expected pattern to be followed by dash '-' after model
>>    number (msm8996-) or by two letters and a dash (sc8280xp-).
>> 2. Add qcom,apss-wdt-xxx to list of exceptions.
>> 3. Use comment instead of description in the oneOf list.
>>
>> Changes since v1:
>> 1. Add schema instead of readme (Rob).
>>
>> Cc: Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
>> Cc: Dmitry Baryshkov <dmitry.baryshkov@linaro.org>
>> Cc: Vinod Koul <vkoul@kernel.org>
>> Cc: Alex Elder <elder@linaro.org>
>> Cc: Robert Foss <robert.foss@linaro.org>
>> Cc: Bhupesh Sharma <bhupesh.sharma@linaro.org>
>> ---
>>  .../devicetree/bindings/arm/qcom-soc.yaml     | 57 +++++++++++++++++++
>>  1 file changed, 57 insertions(+)
>>  create mode 100644 Documentation/devicetree/bindings/arm/qcom-soc.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/arm/qcom-soc.yaml b/Documentation/devicetree/bindings/arm/qcom-soc.yaml
>> new file mode 100644
>> index 000000000000..6307c925335d
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/arm/qcom-soc.yaml
>> @@ -0,0 +1,57 @@
>> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/arm/qcom-soc.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Qualcomm SoC compatibles naming convention
>> +
>> +maintainers:
>> +  - Bjorn Andersson <bjorn.andersson@linaro.org>
>> +
>> +description: |
>> +  Guidelines for new compatibles for SoC blocks/components.
>> +  When adding new compatibles in new bindings, use the format::
>> +    qcom,SoC-IP
>> +
>> +  For example::
>> +   qcom,sdm845-llcc-bwmon
>> +
>> +  When adding new compatibles to existing bindings, use the format in the
>> +  existing binding, even if it contradicts the above.
>> +
>> +select:
>> +  properties:
>> +    compatible:
>> +      pattern: "^qcom,.*(apq|ipq|mdm|msm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$"
>> +  required:
>> +    - compatible
>> +
>> +properties:
>> +  compatible:
>> +    oneOf:
>> +      # Preferred naming style for compatibles of SoC components:
>> +      - pattern: "^qcom,(apq|ipq|mdm|msm|qcs|sa|sc|sdm|sdx|sm)[0-9]+-.*$"
>> +      - pattern: "^qcom,(sa|sc)8[0-9]+[a-z][a-z]?-.*$"
>> +
>> +      # Legacy namings - variations of existing patterns/compatibles are OK,
>> +      # but do not add completely new entries to these:
>> +      - pattern: "^qcom,apss-wdt-(apq|ipq|mdm|msm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$"
>> +      - pattern: "^qcom,gcc-(apq|ipq|mdm|msm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$"
>> +      - pattern: "^qcom,mmcc-(apq|ipq|mdm|msm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$"
>> +      - pattern: "^qcom,pcie-(apq|ipq|mdm|msm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$"
>> +      - pattern: "^qcom,rpm-(apq|ipq|mdm|msm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$"
>> +      - pattern: "^qcom,scm-(apq|ipq|mdm|msm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$"
>> +      - enum:
>> +          - qcom,gpucc-sdm630
>> +          - qcom,gpucc-sdm660
>> +          - qcom,lcc-apq8064
>> +          - qcom,lcc-ipq8064
>> +          - qcom,lcc-mdm9615
>> +          - qcom,lcc-msm8960
>> +          - qcom,lpass-cpu-apq8016
>> +          - qcom,usb-ss-ipq4019-phy
>> +          - qcom,usb-hs-ipq4019-phy
>> +          - qcom,vqmmc-ipq4019-regulator
> Maybe we could add new compatibles for these drivers and replace them
> in upstream DTs, but keep the old ones in the drivers with a clear
> indication that they are there only for legacy reasons?

You cannot replace them in DTS, it would be an ABI break of DTS against
other systems or older kernels. You can deprecate them in bindings, add
new, and after few years (e.g. 1-3) change them in DTS... and still
someone will complain that you broke the ABI.

> In the specific case of gpucc-sdm630/660 I think we could even "break" backwards
> compatibility, as the only users of that driver (Adreno GPU & its SMMU) depend
> on an iommu series to function properly, which has been stuck in the freezer...
Best regards,
Krzysztof