[1/2] dt-bindings: hwinfo: Introduce board-id

From: Elliot Berman <quic_eberman@quicinc.com>

Device manufacturers frequently ship multiple boards or SKUs under a
single software package. These software packages will ship multiple
devicetree blobs and require some mechanism to pick the correct DTB for
the board the software package was deployed. Introduce a common
definition for adding board identifiers to device trees. board-id
provides a mechanism for bootloaders to select the appropriate DTB which
is vendor/OEM-agnostic.

Isn't that what the compatible property is for?
-----------------------------------------------
The compatible property can be used for board matching, but requires
bootloaders and/or firmware to maintain a database of possible strings
to match against or have complex compatible string matching. Compatible
string matching becomes complicated when there are multiple versions of
board: the device tree selector should recognize a DTB that cares to
distinguish between v1/v2 and a DTB that doesn't make the distinction.
An eeprom either needs to store the compatible strings that could match
against the board or the bootloader needs to have vendor-specific
decoding logic for the compatible string. Neither increasing eeprom
storage nor adding vendor-specific decoding logic is desirable.

The solution proposed here is simpler to implement and doesn't require
updating firmware or bootloader for every new board.

How is this better than Qualcomm's qcom,msm-id/qcom,board-id?
-------------------------------------------------------------
The selection process for devicetrees was Qualcomm-specific and not
useful for other devices and bootloaders that were not developed by
Qualcomm because a complex algorithm was used to implement. Board-ids
provide a matching solution that can be implemented by bootloaders
without introducing vendor-specific code. Qualcomm uses three
devicetree properties: msm-id (interchangeably: soc-id), board-id, and
pmic-id.  This does not scale well for use casese which use identifiers,
for example, to distinguish between a display panel. For a display
panel, an approach could be to add a new property: display-id,
but now	bootloaders need to be updated to also read this property. We
want to	avoid requiring to update bootloaders with new hardware
identifiers: a bootloader need only recognize the identifiers it can
handle.

Signed-off-by: Elliot Berman <quic_eberman@quicinc.com>
Signed-off-by: Amrit Anand <quic_amrianan@quicinc.com>
---
 .../devicetree/bindings/hwinfo/board-id.yaml       | 53 ++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/hwinfo/board-id.yaml

On 1/21/2024 12:40 AM, Trilok Soni wrote:
> On 1/20/2024 3:20 AM, Amrit Anand wrote:
>> From: Elliot Berman <quic_eberman@quicinc.com>
>>
>> Device manufacturers frequently ship multiple boards or SKUs under a
>> single software package. These software packages will ship multiple
>> devicetree blobs and require some mechanism to pick the correct DTB for
>> the board the software package was deployed. Introduce a common
>> definition for adding board identifiers to device trees. board-id
>> provides a mechanism for bootloaders to select the appropriate DTB which
>> is vendor/OEM-agnostic.
> Please extend CC list to more architectures? linux-arm-kernel, risc-v etc; since
> the proposal below is not specific to ARM but any architecture is using the
> devicetree.
Wouldn't devicetree@vger.kernel.org will have concern folks from all the 
architectures?
Please correct me.

Thanks,
Amrit.

On 22/01/2024 11:10, Amrit Anand wrote:
> 
> On 1/21/2024 12:40 AM, Trilok Soni wrote:
>> On 1/20/2024 3:20 AM, Amrit Anand wrote:
>>> From: Elliot Berman <quic_eberman@quicinc.com>
>>>
>>> Device manufacturers frequently ship multiple boards or SKUs under a
>>> single software package. These software packages will ship multiple
>>> devicetree blobs and require some mechanism to pick the correct DTB for
>>> the board the software package was deployed. Introduce a common
>>> definition for adding board identifiers to device trees. board-id
>>> provides a mechanism for bootloaders to select the appropriate DTB which
>>> is vendor/OEM-agnostic.
>> Please extend CC list to more architectures? linux-arm-kernel, risc-v etc; since
>> the proposal below is not specific to ARM but any architecture is using the
>> devicetree.
> Wouldn't devicetree@vger.kernel.org will have concern folks from all the 
> architectures?
> Please correct me.

No.

Best regards,
Krzysztof

On 1/23/2024 10:51 AM, Elliot Berman wrote:
> 
> 
> On 1/23/2024 9:18 AM, Conor Dooley wrote:
>> On Tue, Jan 23, 2024 at 12:50:07PM +0100, Krzysztof Kozlowski wrote:
>>> On 22/01/2024 11:10, Amrit Anand wrote:
>>>>
>>>> On 1/21/2024 12:40 AM, Trilok Soni wrote:
>>>>> On 1/20/2024 3:20 AM, Amrit Anand wrote:
>>>>>> From: Elliot Berman <quic_eberman@quicinc.com>
>>>>>>
>>>>>> Device manufacturers frequently ship multiple boards or SKUs under a
>>>>>> single software package. These software packages will ship multiple
>>>>>> devicetree blobs and require some mechanism to pick the correct DTB for
>>>>>> the board the software package was deployed. Introduce a common
>>>>>> definition for adding board identifiers to device trees. board-id
>>>>>> provides a mechanism for bootloaders to select the appropriate DTB which
>>>>>> is vendor/OEM-agnostic.
>>>>> Please extend CC list to more architectures? linux-arm-kernel, risc-v etc; since
>>>>> the proposal below is not specific to ARM but any architecture is using the
>>>>> devicetree.
>>>> Wouldn't devicetree@vger.kernel.org will have concern folks from all the 
>>>> architectures?
>>>> Please correct me.
>>>
>>> No.
>>
>> The chromium guys should get a CC on future versions of this stuff,
>> since they like doing wacky things with compatible strings in their
>> bootloader and this problem is one they also face. Doug Anderson and the
>> mediatek chromebook folks would be a good start.
>>
> 
> Please CC Peter Griffin from Linaro as he helped restart this 
> discussion at Plumbers.
> 
> Peter Griffin <peter.griffin@linaro.org>
> 
> Also, for the oneplus boards:
> Caleb Connolly <caleb.connolly@linaro.org>

Thank you everyone. Amrit - please take care of above comments
when you post next revision and as suggested please add other
architecture mailing lists using the devicetree. Thank you.

On 1/23/2024 5:39 PM, Krzysztof Kozlowski wrote:
> On 20/01/2024 12:20, Amrit Anand wrote:
>> From: Elliot Berman <quic_eberman@quicinc.com>
>>
>
>
>> How is this better than Qualcomm's qcom,msm-id/qcom,board-id?
>> -------------------------------------------------------------
>> The selection process for devicetrees was Qualcomm-specific and not
>> useful for other devices and bootloaders that were not developed by
>> Qualcomm because a complex algorithm was used to implement. Board-ids
>> provide a matching solution that can be implemented by bootloaders
>> without introducing vendor-specific code. Qualcomm uses three
>> devicetree properties: msm-id (interchangeably: soc-id), board-id, and
>> pmic-id.  This does not scale well for use casese which use identifiers,
>> for example, to distinguish between a display panel. For a display
>> panel, an approach could be to add a new property: display-id,
>> but now	bootloaders need to be updated to also read this property. We
>> want to	avoid requiring to update bootloaders with new hardware
> Some mis-indentation in two lines above.
Sure will take care of this.
>
>> identifiers: a bootloader need only recognize the identifiers it can
>> handle.
>>
>> Signed-off-by: Elliot Berman <quic_eberman@quicinc.com>
>> Signed-off-by: Amrit Anand <quic_amrianan@quicinc.com>
>> ---
>>   .../devicetree/bindings/hwinfo/board-id.yaml       | 53 ++++++++++++++++++++++
>>   1 file changed, 53 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/hwinfo/board-id.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/hwinfo/board-id.yaml b/Documentation/devicetree/bindings/hwinfo/board-id.yaml
> I think we should add it to dtschema, because bootloaders are using these.
Do you want us to move this file completely to the below mentioned repo 
and under which directory?
https://github.com/devicetree-org/dt-schema

>
>> new file mode 100644
>> index 0000000..82d5ff7
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/hwinfo/board-id.yaml
>> @@ -0,0 +1,53 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/hwinfo/board-id.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Board Identifier for Devicetree Selection
>> +
>> +maintainers:
>> +  - Amrit Anand <quic_amrianan@quicinc.com>
>> +  - Elliot Berman <quic_eberman@quicinc.com>
>> +
>> +description: |
> Do not need '|' unless you need to preserve formatting.
Will drop it.
>
>> +  Device manufacturers frequently ship multiple boards under a single
>> +  software package. These software packages will ship multiple devicetree
>> +  blobs and require some mechanism to pick the correct DTB for the board
>> +  the software package was deployed. board-id provides a mechanism for
>> +  bootloaders to select the appropriate DTB which is vendor/OEM-agnostic.
>> +
>> +select:
>> +  anyOf:
>> +    - required:
>> +        - 'board-id'
>> +    - required:
>> +        - 'board-id-types'
>> +    - required:
>> +        - '#board-id-cells'
> I don't fully get why do you need this select. Isn't the schema selected
> by nodename? Or maybe it is for the final required: but then this could
> be just set of dependencies.
The nodename here would be "/". So it will be applied to all the DTs, right?
Here, we wanted this to apply only if the above mentioned properties are 
present.
Do you suggest moving this to qcom,board-id.yaml and the required: as well.
So that vendor specific yaml could be applied?
>> +
>> +properties:
>> +  $nodename:
>> +    const: "/"
> Blank line.
Will add it.
>> +  board-id:
>> +    $ref: /schemas/types.yaml#/definitions/uint32-matrix
>> +    description: |
> Do not need '|' unless you need to preserve formatting.
Ack
>> +      A list of identifiers that can be used to match with this devicetree.
> s/devicetree/Devicetree/ ?
Will update
>> +      The interpretatation of each cell can be matched with the
> Typo: interpretation
Will update
>> +      board-id-type at the same index.
>> +
>> +  board-id-types:
>> +    $ref: /schemas/types.yaml#/definitions/non-unique-string-array
>> +    description:
>> +      Defines the type of each cell, indicating to the DeviceTree selection
> s/DeviceTree/Devicetree/ ?
Will update
>
>> +      mechanism how to parse the board-id.
>> +
>> +  '#board-id-cells':
>   What are the cells for?
Bootloader will use this to check the number of entries in a tuple of 
board-id.
Vendors can have different logic in bootloader to specify the number
So wanted to make it flexible.

Thanks,
Amrit.

On 1/24/2024 1:35 AM, Trilok Soni wrote:
> On 1/23/2024 10:51 AM, Elliot Berman wrote:
>>
>> On 1/23/2024 9:18 AM, Conor Dooley wrote:
>>> On Tue, Jan 23, 2024 at 12:50:07PM +0100, Krzysztof Kozlowski wrote:
>>>> On 22/01/2024 11:10, Amrit Anand wrote:
>>>>> On 1/21/2024 12:40 AM, Trilok Soni wrote:
>>>>>> On 1/20/2024 3:20 AM, Amrit Anand wrote:
>>>>>>> From: Elliot Berman <quic_eberman@quicinc.com>
>>>>>>>
>>>>>>> Device manufacturers frequently ship multiple boards or SKUs under a
>>>>>>> single software package. These software packages will ship multiple
>>>>>>> devicetree blobs and require some mechanism to pick the correct DTB for
>>>>>>> the board the software package was deployed. Introduce a common
>>>>>>> definition for adding board identifiers to device trees. board-id
>>>>>>> provides a mechanism for bootloaders to select the appropriate DTB which
>>>>>>> is vendor/OEM-agnostic.
>>>>>> Please extend CC list to more architectures? linux-arm-kernel, risc-v etc; since
>>>>>> the proposal below is not specific to ARM but any architecture is using the
>>>>>> devicetree.
>>>>> Wouldn't devicetree@vger.kernel.org will have concern folks from all the
>>>>> architectures?
>>>>> Please correct me.
>>>> No.
>>> The chromium guys should get a CC on future versions of this stuff,
>>> since they like doing wacky things with compatible strings in their
>>> bootloader and this problem is one they also face. Doug Anderson and the
>>> mediatek chromebook folks would be a good start.
>>>
>> Please CC Peter Griffin from Linaro as he helped restart this
>> discussion at Plumbers.
>>
>> Peter Griffin <peter.griffin@linaro.org>
>>
>> Also, for the oneplus boards:
>> Caleb Connolly <caleb.connolly@linaro.org>
> Thank you everyone. Amrit - please take care of above comments
> when you post next revision and as suggested please add other
> architecture mailing lists using the devicetree. Thank you.
Sure, will keep this in mind when sending next version. Thanks for 
pointing out.

Thanks,
Amrit.

On 24/01/2024 13:42, Amrit Anand wrote:

>>> +select:
>>> +  anyOf:
>>> +    - required:
>>> +        - 'board-id'
>>> +    - required:
>>> +        - 'board-id-types'
>>> +    - required:
>>> +        - '#board-id-cells'
>> I don't fully get why do you need this select. Isn't the schema selected
>> by nodename? Or maybe it is for the final required: but then this could
>> be just set of dependencies.
> The nodename here would be "/". So it will be applied to all the DTs, right?
> Here, we wanted this to apply only if the above mentioned properties are 
> present.

The nodename will select it.

> Do you suggest moving this to qcom,board-id.yaml and the required: as well.
> So that vendor specific yaml could be applied?

I suggest dropping the select.

Different topic is that we cannot even test it because you did not
provide any user of this binding.

>>> +
>>> +properties:
>>> +  $nodename:
>>> +    const: "/"
>> Blank line.
> Will add it.
>>> +  board-id:
>>> +    $ref: /schemas/types.yaml#/definitions/uint32-matrix
>>> +    description: |
>> Do not need '|' unless you need to preserve formatting.
> Ack
>>> +      A list of identifiers that can be used to match with this devicetree.
>> s/devicetree/Devicetree/ ?
> Will update
>>> +      The interpretatation of each cell can be matched with the
>> Typo: interpretation
> Will update
>>> +      board-id-type at the same index.
>>> +
>>> +  board-id-types:
>>> +    $ref: /schemas/types.yaml#/definitions/non-unique-string-array
>>> +    description:
>>> +      Defines the type of each cell, indicating to the DeviceTree selection
>> s/DeviceTree/Devicetree/ ?
> Will update
>>
>>> +      mechanism how to parse the board-id.
>>> +
>>> +  '#board-id-cells':
>>   What are the cells for?
> Bootloader will use this to check the number of entries in a tuple of 
> board-id.

Doesn't the board-id-type define number of cells? How could you have the
same board-id-type with different number of elements on board A and board B?


Best regards,
Krzysztof