diff mbox series

[2/2] dt-bindings: rng: convert Samsung Exynos TRNG to dtschema

Message ID 20210811084306.28740-2-krzysztof.kozlowski@canonical.com (mailing list archive)
State New, archived
Headers show
Series [1/2] dt-bindings: irqchip: convert Samsung Exynos IRQ combiner to dtschema | expand

Commit Message

Krzysztof Kozlowski Aug. 11, 2021, 8:43 a.m. UTC
Convert Samsung Exynos SoC True Random Number Generator bindings to DT
schema format using json-schema.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
---
 .../bindings/rng/samsung,exynos5250-trng.txt  | 17 -------
 .../bindings/rng/samsung,exynos5250-trng.yaml | 44 +++++++++++++++++++
 MAINTAINERS                                   |  2 +-
 3 files changed, 45 insertions(+), 18 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
 create mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml

Comments

Lukasz Stelmach Aug. 17, 2021, 9:55 a.m. UTC | #1
It was <2021-08-11 śro 10:43>, when Krzysztof Kozlowski wrote:
> Convert Samsung Exynos SoC True Random Number Generator bindings to DT
> schema format using json-schema.
>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
> ---
>  .../bindings/rng/samsung,exynos5250-trng.txt  | 17 -------
>  .../bindings/rng/samsung,exynos5250-trng.yaml | 44 +++++++++++++++++++
>  MAINTAINERS                                   |  2 +-
>  3 files changed, 45 insertions(+), 18 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>  create mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>
> diff --git
> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
> deleted file mode 100644
> index 5a613a4ec780..000000000000
> --- a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
> +++ /dev/null
> @@ -1,17 +0,0 @@
> -Exynos True Random Number Generator
> -
> -Required properties:
> -
> -- compatible  : Should be "samsung,exynos5250-trng".
> -- reg         : Specifies base physical address and size of the registers map.
> -- clocks      : Phandle to clock-controller plus clock-specifier pair.
> -- clock-names : "secss" as a clock name.
> -
> -Example:
> -
> -	rng@10830600 {
> -		compatible = "samsung,exynos5250-trng";
> -		reg = <0x10830600 0x100>;
> -		clocks = <&clock CLK_SSS>;
> -		clock-names = "secss";
> -	};
> diff --git
> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
> new file mode 100644
> index 000000000000..a50c34d5d199
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
> @@ -0,0 +1,44 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id:
> https://protect2.fireeye.com/v1/url?k=f38ca35b-ac179a0d-f38d2814-0cc47a31ce52-1faa1ecb65482b8a&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fschemas%2Frng%2Fsamsung%2Cexynos5250-trng.yaml%23
> +$schema:
> https://protect2.fireeye.com/v1/url?k=9409519d-cb9268cb-9408dad2-0cc47a31ce52-12394c4409905980&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fmeta-schemas%2Fcore.yaml%23
> +
> +title: Samsung Exynos SoC True Random Number Generator
> +
> +maintainers:
> +  - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
> +  - Łukasz Stelmach <l.stelmach@samsung.com>
> +
> +properties:
> +  compatible:
> +    const: samsung,exynos5250-trng
> +
> +  clocks:
> +    maxItems: 1

How about copying description from above into the description: property?

> +
> +  clock-names:
> +    items:
> +      - const: secss
> +
> +  reg:
> +    maxItems: 1

ditto.

> +
> +required:
> +  - compatible
> +  - clocks
> +  - clock-names
> +  - reg
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/clock/exynos5250.h>
> +
> +    rng@10830600 {
> +        compatible = "samsung,exynos5250-trng";
> +        reg = <0x10830600 0x100>;
> +        clocks = <&clock CLK_SSS>;
> +        clock-names = "secss";
> +    };
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 4477215ef649..ebdb07a49b02 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -16398,7 +16398,7 @@ SAMSUNG EXYNOS TRUE RANDOM NUMBER GENERATOR (TRNG) DRIVER
>  M:	Łukasz Stelmach <l.stelmach@samsung.com>
>  L:	linux-samsung-soc@vger.kernel.org
>  S:	Maintained
> -F:	Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
> +F:	Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>  F:	drivers/char/hw_random/exynos-trng.c
>  
>  SAMSUNG FRAMEBUFFER DRIVER
Krzysztof Kozlowski Aug. 17, 2021, 10:05 a.m. UTC | #2
On 17/08/2021 11:55, Lukasz Stelmach wrote:
> It was <2021-08-11 śro 10:43>, when Krzysztof Kozlowski wrote:
>> Convert Samsung Exynos SoC True Random Number Generator bindings to DT
>> schema format using json-schema.
>>
>> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
>> ---
>>  .../bindings/rng/samsung,exynos5250-trng.txt  | 17 -------
>>  .../bindings/rng/samsung,exynos5250-trng.yaml | 44 +++++++++++++++++++
>>  MAINTAINERS                                   |  2 +-
>>  3 files changed, 45 insertions(+), 18 deletions(-)
>>  delete mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>  create mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>
>> diff --git
>> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>> deleted file mode 100644
>> index 5a613a4ec780..000000000000
>> --- a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>> +++ /dev/null
>> @@ -1,17 +0,0 @@
>> -Exynos True Random Number Generator
>> -
>> -Required properties:
>> -
>> -- compatible  : Should be "samsung,exynos5250-trng".
>> -- reg         : Specifies base physical address and size of the registers map.
>> -- clocks      : Phandle to clock-controller plus clock-specifier pair.
>> -- clock-names : "secss" as a clock name.
>> -
>> -Example:
>> -
>> -	rng@10830600 {
>> -		compatible = "samsung,exynos5250-trng";
>> -		reg = <0x10830600 0x100>;
>> -		clocks = <&clock CLK_SSS>;
>> -		clock-names = "secss";
>> -	};
>> diff --git
>> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>> new file mode 100644
>> index 000000000000..a50c34d5d199
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>> @@ -0,0 +1,44 @@
>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id:
>> https://protect2.fireeye.com/v1/url?k=f38ca35b-ac179a0d-f38d2814-0cc47a31ce52-1faa1ecb65482b8a&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fschemas%2Frng%2Fsamsung%2Cexynos5250-trng.yaml%23
>> +$schema:
>> https://protect2.fireeye.com/v1/url?k=9409519d-cb9268cb-9408dad2-0cc47a31ce52-12394c4409905980&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fmeta-schemas%2Fcore.yaml%23
>> +
>> +title: Samsung Exynos SoC True Random Number Generator
>> +
>> +maintainers:
>> +  - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
>> +  - Łukasz Stelmach <l.stelmach@samsung.com>
>> +
>> +properties:
>> +  compatible:
>> +    const: samsung,exynos5250-trng
>> +
>> +  clocks:
>> +    maxItems: 1
> 
> How about copying description from above into the description: property?

But what to copy? There is no description except generic clock bindings.

> 
>> +
>> +  clock-names:
>> +    items:
>> +      - const: secss
>> +
>> +  reg:
>> +    maxItems: 1
> 
> ditto.

The same, I have no clue what to copy. It's obvious that reg contains
"physical address and size of the registers map".


Best regards,
Krzysztof
Lukasz Stelmach Aug. 17, 2021, 12:34 p.m. UTC | #3
It was <2021-08-17 wto 12:05>, when Krzysztof Kozlowski wrote:
> On 17/08/2021 11:55, Lukasz Stelmach wrote:
>> It was <2021-08-11 śro 10:43>, when Krzysztof Kozlowski wrote:
>>> Convert Samsung Exynos SoC True Random Number Generator bindings to DT
>>> schema format using json-schema.
>>>
>>> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
>>> ---
>>>  .../bindings/rng/samsung,exynos5250-trng.txt  | 17 -------
>>>  .../bindings/rng/samsung,exynos5250-trng.yaml | 44 +++++++++++++++++++
>>>  MAINTAINERS                                   |  2 +-
>>>  3 files changed, 45 insertions(+), 18 deletions(-)
>>>  delete mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>  create mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>
>>> diff --git
>>> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>> deleted file mode 100644
>>> index 5a613a4ec780..000000000000
>>> --- a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>> +++ /dev/null
>>> @@ -1,17 +0,0 @@
>>> -Exynos True Random Number Generator
>>> -
>>> -Required properties:
>>> -
>>> -- compatible  : Should be "samsung,exynos5250-trng".
>>> -- reg         : Specifies base physical address and size of the registers map.
>>> -- clocks      : Phandle to clock-controller plus clock-specifier pair.
>>> -- clock-names : "secss" as a clock name.
>>> -
>>> -Example:
>>> -
>>> -	rng@10830600 {
>>> -		compatible = "samsung,exynos5250-trng";
>>> -		reg = <0x10830600 0x100>;
>>> -		clocks = <&clock CLK_SSS>;
>>> -		clock-names = "secss";
>>> -	};
>>> diff --git
>>> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>> new file mode 100644
>>> index 000000000000..a50c34d5d199
>>> --- /dev/null
>>> +++ b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>> @@ -0,0 +1,44 @@
>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>> +%YAML 1.2
>>> +---
>>> +$id:
>>> https://protect2.fireeye.com/v1/url?k=f38ca35b-ac179a0d-f38d2814-0cc47a31ce52-1faa1ecb65482b8a&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fschemas%2Frng%2Fsamsung%2Cexynos5250-trng.yaml%23
>>> +$schema:
>>> https://protect2.fireeye.com/v1/url?k=9409519d-cb9268cb-9408dad2-0cc47a31ce52-12394c4409905980&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fmeta-schemas%2Fcore.yaml%23
>>> +
>>> +title: Samsung Exynos SoC True Random Number Generator
>>> +
>>> +maintainers:
>>> +  - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
>>> +  - Łukasz Stelmach <l.stelmach@samsung.com>
>>> +
>>> +properties:
>>> +  compatible:
>>> +    const: samsung,exynos5250-trng
>>> +
>>> +  clocks:
>>> +    maxItems: 1
>> 
>> How about copying description from above into the description: property?
>
> But what to copy? There is no description except generic clock bindings.
>

The description that "was" in the txt file.

>> 
>>> +
>>> +  clock-names:
>>> +    items:
>>> +      - const: secss
>>> +
>>> +  reg:
>>> +    maxItems: 1
>> 
>> ditto.
>
> The same, I have no clue what to copy. It's obvious that reg contains
> "physical address and size of the registers map".
>
>
> Best regards,
> Krzysztof
>
>
Krzysztof Kozlowski Aug. 17, 2021, 2:07 p.m. UTC | #4
On 17/08/2021 14:34, Lukasz Stelmach wrote:
> It was <2021-08-17 wto 12:05>, when Krzysztof Kozlowski wrote:
>> On 17/08/2021 11:55, Lukasz Stelmach wrote:
>>> It was <2021-08-11 śro 10:43>, when Krzysztof Kozlowski wrote:
>>>> Convert Samsung Exynos SoC True Random Number Generator bindings to DT
>>>> schema format using json-schema.
>>>>
>>>> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
>>>> ---
>>>>  .../bindings/rng/samsung,exynos5250-trng.txt  | 17 -------
>>>>  .../bindings/rng/samsung,exynos5250-trng.yaml | 44 +++++++++++++++++++
>>>>  MAINTAINERS                                   |  2 +-
>>>>  3 files changed, 45 insertions(+), 18 deletions(-)
>>>>  delete mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>>  create mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>>
>>>> diff --git
>>>> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>> deleted file mode 100644
>>>> index 5a613a4ec780..000000000000
>>>> --- a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>> +++ /dev/null
>>>> @@ -1,17 +0,0 @@
>>>> -Exynos True Random Number Generator
>>>> -
>>>> -Required properties:
>>>> -
>>>> -- compatible  : Should be "samsung,exynos5250-trng".
>>>> -- reg         : Specifies base physical address and size of the registers map.
>>>> -- clocks      : Phandle to clock-controller plus clock-specifier pair.
>>>> -- clock-names : "secss" as a clock name.
>>>> -
>>>> -Example:
>>>> -
>>>> -	rng@10830600 {
>>>> -		compatible = "samsung,exynos5250-trng";
>>>> -		reg = <0x10830600 0x100>;
>>>> -		clocks = <&clock CLK_SSS>;
>>>> -		clock-names = "secss";
>>>> -	};
>>>> diff --git
>>>> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>> new file mode 100644
>>>> index 000000000000..a50c34d5d199
>>>> --- /dev/null
>>>> +++ b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>> @@ -0,0 +1,44 @@
>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>>> +%YAML 1.2
>>>> +---
>>>> +$id:
>>>> https://protect2.fireeye.com/v1/url?k=f38ca35b-ac179a0d-f38d2814-0cc47a31ce52-1faa1ecb65482b8a&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fschemas%2Frng%2Fsamsung%2Cexynos5250-trng.yaml%23
>>>> +$schema:
>>>> https://protect2.fireeye.com/v1/url?k=9409519d-cb9268cb-9408dad2-0cc47a31ce52-12394c4409905980&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fmeta-schemas%2Fcore.yaml%23
>>>> +
>>>> +title: Samsung Exynos SoC True Random Number Generator
>>>> +
>>>> +maintainers:
>>>> +  - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
>>>> +  - Łukasz Stelmach <l.stelmach@samsung.com>
>>>> +
>>>> +properties:
>>>> +  compatible:
>>>> +    const: samsung,exynos5250-trng
>>>> +
>>>> +  clocks:
>>>> +    maxItems: 1
>>>
>>> How about copying description from above into the description: property?
>>
>> But what to copy? There is no description except generic clock bindings.
>>
> 
> The description that "was" in the txt file.

But there was no description of fields except copy&paste of the core
schema. Do you describe C code like:

...
/* unsigned int is a integer number greater or equal 0 */
unsigned int i;
...


Best regards,
Krzysztof
Rob Herring Aug. 17, 2021, 9:15 p.m. UTC | #5
On Wed, 11 Aug 2021 10:43:06 +0200, Krzysztof Kozlowski wrote:
> Convert Samsung Exynos SoC True Random Number Generator bindings to DT
> schema format using json-schema.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
> ---
>  .../bindings/rng/samsung,exynos5250-trng.txt  | 17 -------
>  .../bindings/rng/samsung,exynos5250-trng.yaml | 44 +++++++++++++++++++
>  MAINTAINERS                                   |  2 +-
>  3 files changed, 45 insertions(+), 18 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>  create mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
> 

Applied, thanks!
Lukasz Stelmach Aug. 17, 2021, 10:17 p.m. UTC | #6
It was <2021-08-17 wto 16:07>, when Krzysztof Kozlowski wrote:
> On 17/08/2021 14:34, Lukasz Stelmach wrote:
>> It was <2021-08-17 wto 12:05>, when Krzysztof Kozlowski wrote:
>>> On 17/08/2021 11:55, Lukasz Stelmach wrote:
>>>> It was <2021-08-11 śro 10:43>, when Krzysztof Kozlowski wrote:
>>>>> Convert Samsung Exynos SoC True Random Number Generator bindings to DT
>>>>> schema format using json-schema.
>>>>>
>>>>> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
>>>>> ---
>>>>>  .../bindings/rng/samsung,exynos5250-trng.txt  | 17 -------
>>>>>  .../bindings/rng/samsung,exynos5250-trng.yaml | 44 +++++++++++++++++++
>>>>>  MAINTAINERS                                   |  2 +-
>>>>>  3 files changed, 45 insertions(+), 18 deletions(-)
>>>>>  delete mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>>>  create mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>>>
>>>>> diff --git
>>>>> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>>> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>>> deleted file mode 100644
>>>>> index 5a613a4ec780..000000000000
>>>>> --- a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>>> +++ /dev/null
>>>>> @@ -1,17 +0,0 @@
>>>>> -Exynos True Random Number Generator
>>>>> -
>>>>> -Required properties:
>>>>> -
>>>>> -- compatible  : Should be "samsung,exynos5250-trng".
>>>>> -- reg         : Specifies base physical address and size of the registers map.
>>>>> -- clocks      : Phandle to clock-controller plus clock-specifier pair.
>>>>> -- clock-names : "secss" as a clock name.
>>>>> -
>>>>> -Example:
>>>>> -
>>>>> -	rng@10830600 {
>>>>> -		compatible = "samsung,exynos5250-trng";
>>>>> -		reg = <0x10830600 0x100>;
>>>>> -		clocks = <&clock CLK_SSS>;
>>>>> -		clock-names = "secss";
>>>>> -	};
>>>>> diff --git
>>>>> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>>> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>>> new file mode 100644
>>>>> index 000000000000..a50c34d5d199
>>>>> --- /dev/null
>>>>> +++ b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>>> @@ -0,0 +1,44 @@
>>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>>>> +%YAML 1.2
>>>>> +---
>>>>> +$id:
>>>>> https://protect2.fireeye.com/v1/url?k=f38ca35b-ac179a0d-f38d2814-0cc47a31ce52-1faa1ecb65482b8a&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fschemas%2Frng%2Fsamsung%2Cexynos5250-trng.yaml%23
>>>>> +$schema:
>>>>> https://protect2.fireeye.com/v1/url?k=9409519d-cb9268cb-9408dad2-0cc47a31ce52-12394c4409905980&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fmeta-schemas%2Fcore.yaml%23
>>>>> +
>>>>> +title: Samsung Exynos SoC True Random Number Generator
>>>>> +
>>>>> +maintainers:
>>>>> +  - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
>>>>> +  - Łukasz Stelmach <l.stelmach@samsung.com>
>>>>> +
>>>>> +properties:
>>>>> +  compatible:
>>>>> +    const: samsung,exynos5250-trng
>>>>> +
>>>>> +  clocks:
>>>>> +    maxItems: 1
>>>>
>>>> How about copying description from above into the description: property?
>>>
>>> But what to copy? There is no description except generic clock bindings.
>>>
>> 
>> The description that "was" in the txt file.
>
> But there was no description of fields except copy&paste of the core
> schema. Do you describe C code like:
>
> ...
> /* unsigned int is a integer number greater or equal 0 */
> unsigned int i;
> ...

I believe having descriptions for reg and clocks

>>>>> -- reg         : Specifies base physical address and size of the registers map.
>>>>> -- clocks      : Phandle to clock-controller plus clock-specifier pair.

right next to properties' formal definitions is beneficial for anyone
browsing the YAML file. If you think otherwise, oh well, I am fine with
that.
Krzysztof Kozlowski Aug. 18, 2021, 6:37 a.m. UTC | #7
On 18/08/2021 00:17, Lukasz Stelmach wrote:
> It was <2021-08-17 wto 16:07>, when Krzysztof Kozlowski wrote:
>> On 17/08/2021 14:34, Lukasz Stelmach wrote:
>>> It was <2021-08-17 wto 12:05>, when Krzysztof Kozlowski wrote:
>>>> On 17/08/2021 11:55, Lukasz Stelmach wrote:
>>>>> It was <2021-08-11 śro 10:43>, when Krzysztof Kozlowski wrote:
>>>>>> Convert Samsung Exynos SoC True Random Number Generator bindings to DT
>>>>>> schema format using json-schema.
>>>>>>
>>>>>> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
>>>>>> ---
>>>>>>  .../bindings/rng/samsung,exynos5250-trng.txt  | 17 -------
>>>>>>  .../bindings/rng/samsung,exynos5250-trng.yaml | 44 +++++++++++++++++++
>>>>>>  MAINTAINERS                                   |  2 +-
>>>>>>  3 files changed, 45 insertions(+), 18 deletions(-)
>>>>>>  delete mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>>>>  create mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>>>>
>>>>>> diff --git
>>>>>> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>>>> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>>>> deleted file mode 100644
>>>>>> index 5a613a4ec780..000000000000
>>>>>> --- a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
>>>>>> +++ /dev/null
>>>>>> @@ -1,17 +0,0 @@
>>>>>> -Exynos True Random Number Generator
>>>>>> -
>>>>>> -Required properties:
>>>>>> -
>>>>>> -- compatible  : Should be "samsung,exynos5250-trng".
>>>>>> -- reg         : Specifies base physical address and size of the registers map.
>>>>>> -- clocks      : Phandle to clock-controller plus clock-specifier pair.
>>>>>> -- clock-names : "secss" as a clock name.
>>>>>> -
>>>>>> -Example:
>>>>>> -
>>>>>> -	rng@10830600 {
>>>>>> -		compatible = "samsung,exynos5250-trng";
>>>>>> -		reg = <0x10830600 0x100>;
>>>>>> -		clocks = <&clock CLK_SSS>;
>>>>>> -		clock-names = "secss";
>>>>>> -	};
>>>>>> diff --git
>>>>>> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>>>> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>>>> new file mode 100644
>>>>>> index 000000000000..a50c34d5d199
>>>>>> --- /dev/null
>>>>>> +++ b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
>>>>>> @@ -0,0 +1,44 @@
>>>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>>>>> +%YAML 1.2
>>>>>> +---
>>>>>> +$id:
>>>>>> https://protect2.fireeye.com/v1/url?k=f38ca35b-ac179a0d-f38d2814-0cc47a31ce52-1faa1ecb65482b8a&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fschemas%2Frng%2Fsamsung%2Cexynos5250-trng.yaml%23
>>>>>> +$schema:
>>>>>> https://protect2.fireeye.com/v1/url?k=9409519d-cb9268cb-9408dad2-0cc47a31ce52-12394c4409905980&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fmeta-schemas%2Fcore.yaml%23
>>>>>> +
>>>>>> +title: Samsung Exynos SoC True Random Number Generator
>>>>>> +
>>>>>> +maintainers:
>>>>>> +  - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
>>>>>> +  - Łukasz Stelmach <l.stelmach@samsung.com>
>>>>>> +
>>>>>> +properties:
>>>>>> +  compatible:
>>>>>> +    const: samsung,exynos5250-trng
>>>>>> +
>>>>>> +  clocks:
>>>>>> +    maxItems: 1
>>>>>
>>>>> How about copying description from above into the description: property?
>>>>
>>>> But what to copy? There is no description except generic clock bindings.
>>>>
>>>
>>> The description that "was" in the txt file.
>>
>> But there was no description of fields except copy&paste of the core
>> schema. Do you describe C code like:
>>
>> ...
>> /* unsigned int is a integer number greater or equal 0 */
>> unsigned int i;
>> ...
> 
> I believe having descriptions for reg and clocks
> 
>>>>>> -- reg         : Specifies base physical address and size of the registers map.
>>>>>> -- clocks      : Phandle to clock-controller plus clock-specifier pair.
> 
> right next to properties' formal definitions is beneficial for anyone
> browsing the YAML file. If you think otherwise, oh well, I am fine with
> that.

Useful descriptions would be beneficial. Descriptions which are copy of
schema, therefore equal to explaining unsigned int, are not beneficial.
Make the document just unnecessarily bigger, are irrelevant and hide
actual important information. One of the principles is to keep things
simple. Duplicating description from schema into specific bindings is
rather the opposite of such approach.


Best regards,
Krzysztof
Rob Herring Aug. 20, 2021, 6:27 p.m. UTC | #8
On Tue, Aug 17, 2021 at 5:17 PM Lukasz Stelmach <l.stelmach@samsung.com> wrote:
>
> It was <2021-08-17 wto 16:07>, when Krzysztof Kozlowski wrote:
> > On 17/08/2021 14:34, Lukasz Stelmach wrote:
> >> It was <2021-08-17 wto 12:05>, when Krzysztof Kozlowski wrote:
> >>> On 17/08/2021 11:55, Lukasz Stelmach wrote:
> >>>> It was <2021-08-11 śro 10:43>, when Krzysztof Kozlowski wrote:
> >>>>> Convert Samsung Exynos SoC True Random Number Generator bindings to DT
> >>>>> schema format using json-schema.
> >>>>>
> >>>>> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
> >>>>> ---
> >>>>>  .../bindings/rng/samsung,exynos5250-trng.txt  | 17 -------
> >>>>>  .../bindings/rng/samsung,exynos5250-trng.yaml | 44 +++++++++++++++++++
> >>>>>  MAINTAINERS                                   |  2 +-
> >>>>>  3 files changed, 45 insertions(+), 18 deletions(-)
> >>>>>  delete mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
> >>>>>  create mode 100644 Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
> >>>>>
> >>>>> diff --git
> >>>>> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
> >>>>> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
> >>>>> deleted file mode 100644
> >>>>> index 5a613a4ec780..000000000000
> >>>>> --- a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
> >>>>> +++ /dev/null
> >>>>> @@ -1,17 +0,0 @@
> >>>>> -Exynos True Random Number Generator
> >>>>> -
> >>>>> -Required properties:
> >>>>> -
> >>>>> -- compatible  : Should be "samsung,exynos5250-trng".
> >>>>> -- reg         : Specifies base physical address and size of the registers map.
> >>>>> -- clocks      : Phandle to clock-controller plus clock-specifier pair.
> >>>>> -- clock-names : "secss" as a clock name.
> >>>>> -
> >>>>> -Example:
> >>>>> -
> >>>>> - rng@10830600 {
> >>>>> -         compatible = "samsung,exynos5250-trng";
> >>>>> -         reg = <0x10830600 0x100>;
> >>>>> -         clocks = <&clock CLK_SSS>;
> >>>>> -         clock-names = "secss";
> >>>>> - };
> >>>>> diff --git
> >>>>> a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
> >>>>> b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
> >>>>> new file mode 100644
> >>>>> index 000000000000..a50c34d5d199
> >>>>> --- /dev/null
> >>>>> +++ b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
> >>>>> @@ -0,0 +1,44 @@
> >>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> >>>>> +%YAML 1.2
> >>>>> +---
> >>>>> +$id:
> >>>>> https://protect2.fireeye.com/v1/url?k=f38ca35b-ac179a0d-f38d2814-0cc47a31ce52-1faa1ecb65482b8a&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fschemas%2Frng%2Fsamsung%2Cexynos5250-trng.yaml%23
> >>>>> +$schema:
> >>>>> https://protect2.fireeye.com/v1/url?k=9409519d-cb9268cb-9408dad2-0cc47a31ce52-12394c4409905980&q=1&e=8b3490f9-a5fc-4da0-b2ee-7b0aec781403&u=http%3A%2F%2Fdevicetree.org%2Fmeta-schemas%2Fcore.yaml%23
> >>>>> +
> >>>>> +title: Samsung Exynos SoC True Random Number Generator
> >>>>> +
> >>>>> +maintainers:
> >>>>> +  - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
> >>>>> +  - Łukasz Stelmach <l.stelmach@samsung.com>
> >>>>> +
> >>>>> +properties:
> >>>>> +  compatible:
> >>>>> +    const: samsung,exynos5250-trng
> >>>>> +
> >>>>> +  clocks:
> >>>>> +    maxItems: 1
> >>>>
> >>>> How about copying description from above into the description: property?
> >>>
> >>> But what to copy? There is no description except generic clock bindings.
> >>>
> >>
> >> The description that "was" in the txt file.
> >
> > But there was no description of fields except copy&paste of the core
> > schema. Do you describe C code like:
> >
> > ...
> > /* unsigned int is a integer number greater or equal 0 */
> > unsigned int i;
> > ...
>
> I believe having descriptions for reg and clocks
>
> >>>>> -- reg         : Specifies base physical address and size of the registers map.
> >>>>> -- clocks      : Phandle to clock-controller plus clock-specifier pair.
>
> right next to properties' formal definitions is beneficial for anyone
> browsing the YAML file. If you think otherwise, oh well, I am fine with
> that.

We have 2000 schemas currently (and 2300 still to convert). Of the
~2000, 1646 have 'reg' and 1005 have 'clocks' (I was going to guess
3/4 and 1/2, respectively, but with a nice uniform, parsable format we
don't have to guess). Do we need that many copies of variations of the
same description?

What I would like to have is generated documentation from the schemas.
With that we could either insert a description or a link on all the
common properties. There are already tools that generate documentation
out of json-schema, but I don't have the time to investigate them or
work on any of that.

My other idea is some sort of property grepping utility. While grep
generally works, it would be nice to have some tools aware of the
schema structure where you could just run 'dt-grep clocks' and have it
spit out the description. Another example would be to list all the
valid properties for a given compatible string. Lots of possibilities
with machine readable bindings.

Rob
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
deleted file mode 100644
index 5a613a4ec780..000000000000
--- a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
+++ /dev/null
@@ -1,17 +0,0 @@ 
-Exynos True Random Number Generator
-
-Required properties:
-
-- compatible  : Should be "samsung,exynos5250-trng".
-- reg         : Specifies base physical address and size of the registers map.
-- clocks      : Phandle to clock-controller plus clock-specifier pair.
-- clock-names : "secss" as a clock name.
-
-Example:
-
-	rng@10830600 {
-		compatible = "samsung,exynos5250-trng";
-		reg = <0x10830600 0x100>;
-		clocks = <&clock CLK_SSS>;
-		clock-names = "secss";
-	};
diff --git a/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
new file mode 100644
index 000000000000..a50c34d5d199
--- /dev/null
+++ b/Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
@@ -0,0 +1,44 @@ 
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/rng/samsung,exynos5250-trng.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung Exynos SoC True Random Number Generator
+
+maintainers:
+  - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
+  - Łukasz Stelmach <l.stelmach@samsung.com>
+
+properties:
+  compatible:
+    const: samsung,exynos5250-trng
+
+  clocks:
+    maxItems: 1
+
+  clock-names:
+    items:
+      - const: secss
+
+  reg:
+    maxItems: 1
+
+required:
+  - compatible
+  - clocks
+  - clock-names
+  - reg
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/clock/exynos5250.h>
+
+    rng@10830600 {
+        compatible = "samsung,exynos5250-trng";
+        reg = <0x10830600 0x100>;
+        clocks = <&clock CLK_SSS>;
+        clock-names = "secss";
+    };
diff --git a/MAINTAINERS b/MAINTAINERS
index 4477215ef649..ebdb07a49b02 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -16398,7 +16398,7 @@  SAMSUNG EXYNOS TRUE RANDOM NUMBER GENERATOR (TRNG) DRIVER
 M:	Łukasz Stelmach <l.stelmach@samsung.com>
 L:	linux-samsung-soc@vger.kernel.org
 S:	Maintained
-F:	Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
+F:	Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml
 F:	drivers/char/hw_random/exynos-trng.c
 
 SAMSUNG FRAMEBUFFER DRIVER