[PATCH v2] docs: dt-bindings: add DTS Coding Style document

[Michal Simek]

On 11/21/23 11:28, Krzysztof Kozlowski wrote:
> On 21/11/2023 11:13, Dmitry Baryshkov wrote:
>> On Tue, 21 Nov 2023 at 10:09, Geert Uytterhoeven <geert at linux-m68k.org> wrote:
>>>
>>> Hi Krzysztof,
>>>
>>> On Tue, Nov 21, 2023 at 8:47 AM Krzysztof Kozlowski
>>> <krzysztof.kozlowski at linaro.org> wrote:
>>>> On 21/11/2023 08:33, Michal Simek wrote:
>>>>> On 11/20/23 20:31, Krzysztof Kozlowski wrote:
>>>>>> On 20/11/2023 20:18, Geert Uytterhoeven wrote:
>>>>>>> On Mon, Nov 20, 2023 at 3:53 PM Krzysztof Kozlowski
>>>>>>> <krzysztof.kozlowski at linaro.org> wrote:
>>>>>>>> On 20/11/2023 15:01, Michal Simek wrote:> >
>>>>>>>>> On 11/20/23 09:40, Krzysztof Kozlowski wrote:
>>>>>>>>>> Document preferred coding style for Devicetree sources (DTS and DTSI),
>>>>>>>>>> to bring consistency among all (sub)architectures and ease in reviews.
>>>>>>>
>>>>>>>>>> +Organizing DTSI and DTS
>>>>>>>>>> +-----------------------
>>>>>>>>>> +
>>>>>>>>>> +The DTSI and DTS files should be organized in a way representing the common
>>>>>>>>>> +(and re-usable) parts of the hardware.  Typically this means organizing DTSI
>>>>>>>>>> +and DTS files into several files:
>>>>>>>>>> +
>>>>>>>>>> +1. DTSI with contents of the entire SoC (without nodes for hardware not present
>>>>>>>>>> +   on the SoC).
>>>>>>>>>> +2. If applicable: DTSI with common or re-usable parts of the hardware (e.g.
>>>>>>>>>> +   entire System-on-Module).
>>>>>>>>>
>>>>>>>>> DTS/DTSI - SOMs can actually run as they are that's why it is fair to say that
>>>>>>>>> there doesn't need to be DTS representing the board.
>>>>>>>>
>>>>>>>> I have never seen a SoM which can run without elaborate hardware-hacking
>>>>>>>> (e.g. connecting multiple wires to the SoM pins). The definition of the
>>>>>>>> SoM is that it is a module. Module can be re-used, just like SoC.
>>>>>>>
>>>>>>> /me looks at his board farm...
>>>
>>>>>>> I guess there are (many) other examples...
>>>>>>
>>>>>> OK, I never had such in my hands. Anyway, the SoM which can run
>>>>>> standalone  has a meaning of a board, so how exactly you want to
>>>>>> rephrase the paragraph?
>>>>>
>>>>> What about?
>>>>>
>>>>> 2. If applicable: DTSI with common or re-usable parts of the hardware (e.g.
>>>>> entire System-on-Module). DTS if runs standalone.
>>>>
>>>> OK, but then it's duplicating the option 3. It also suggests that SoM
>>>> should be a DTS, which is not what we want for such case. Such SoMs must
>>>> have DTSI+DTS.
>>>
>>> So you want us to have a one-line <SoM>.dts, which just includes <SoM>.dtsi?
>>
>> Well, I think it is impossible to run SoM directly. There is a carrier
>> board anyway, which includes at least regulators. So, I guess, the
>> SoM.dts will not be a oneline file.
> 
> Geert claims he has SoM with an USB connector which can run when power
> is supplied by that USB connector. I can imagine a CPU board (so a SoM
> in format of a board, not small DIMM-card) which has connectors e.g. for
> power and a slot for external motherboard for additional, optional
> interfaces.
> 
> Look at picture on 14th page:
> https://www.renesas.com/us/en/document/mat/rza2m-cpu-board-users-manual
> 
> This looks like some case of SoM, although maybe not that popular
> outside of Renesas :)

In our case we have SOMs
https://www.xilinx.com/products/som/kria.html#portfolio

and also carrier cards (CC) like this
https://www.xilinx.com/products/som/kria/kv260-vision-starter-kit.html

and we also have debug boards.

There must be a carrier card in our case and there is power connector (with also 
non sw accessible regulators), jtag, boot pins and for example ttl to usb 
connector for UART but SOM spec describe directly which peripherals are on 
certain pins by default.
It means we have CC card but there is nothing on it to describe for SOM itself.

Our default boot process is to boot with SOM peripherals described by spec. And 
then do CC identification and switching to SOM+CC dtb description at U-Boot.

Some combinations are described here.
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/arm64/boot/dts/xilinx/Makefile?h=v6.7-rc2#n21

We can create dtsi for SOM and then dts which just one line which includes SOM dtsi.

Thanks,
Michal