Re: [PATCH 1/2] dt-bindings: microchip-otpc: document Microchip OTPC

[Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>]

On 10/05/2022 11:44, Claudiu Beznea wrote:
> Document Microchip OTP controller.
> 
> Signed-off-by: Claudiu Beznea <claudiu.beznea@microchip.com>
> ---
>  .../bindings/nvmem/microchip-otpc.yaml        | 55 +++++++++++++++++++
>  include/dt-bindings/nvmem/microchip,otpc.h    | 18 ++++++
>  2 files changed, 73 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/nvmem/microchip-otpc.yaml
>  create mode 040000 include/dt-bindings/nvmem
>  create mode 100644 include/dt-bindings/nvmem/microchip,otpc.h
> 
> diff --git a/Documentation/devicetree/bindings/nvmem/microchip-otpc.yaml b/Documentation/devicetree/bindings/nvmem/microchip-otpc.yaml
> new file mode 100644
> index 000000000000..a8df7fee5c2b
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/nvmem/microchip-otpc.yaml

vendor,device.yaml
device should not be a wildcard but first compatible, so
microchip,sama7g5-otpc.yaml


> @@ -0,0 +1,55 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/nvmem/microchip-otpc.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Microchip SAMA7G5 OTP Controller (OTPC) device tree bindings

s/device tree bindings//

> +
> +maintainers:
> +  - Claudiu Beznea <claudiu.beznea@microchip.com>
> +
> +description: |
> +  This binding represents the OTP controller found on SAMA7G5 SoC.

Entire description is duplicating title. Please describe the hardware or
skip it.

OTOH, you should mention the header, for example in description.

> +
> +allOf:
> +  - $ref: "nvmem.yaml#"
> +
> +properties:
> +  compatible:
> +    items:
> +      - const: microchip,sama7g5-otpc
> +      - const: syscon
> +
> +  reg:
> +    maxItems: 1
> +
> +  "#address-cells":
> +    const: 1
> +
> +  "#size-cells":
> +    const: 1

These come from nvmem.yaml.

> +
> +required:
> +  - compatible
> +  - reg
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/clock/at91.h>

How the clock is used here?

> +    #include <dt-bindings/nvmem/microchip,otpc.h>
> +
> +    otpc: efuse@e8c00000 {
> +        compatible = "microchip,sama7g5-otpc", "syscon";
> +        reg = <0xe8c00000 0xec>;
> +        #address-cells = <1>;
> +        #size-cells = <1>;
> +
> +        temperature_calib: calib@1 {
> +            reg = <OTP_PKT(1) OTP_PKT_SAMA7G5_TEMP_CALIB_LEN>;
> +        };
> +    };
> +
> +...
> diff --git a/include/dt-bindings/nvmem/microchip,otpc.h b/include/dt-bindings/nvmem/microchip,otpc.h
> new file mode 100644
> index 000000000000..44b6ed3b8f18
> --- /dev/null
> +++ b/include/dt-bindings/nvmem/microchip,otpc.h
> @@ -0,0 +1,18 @@
> +/* SPDX-License-Identifier: GPL-2.0 */

Same license as bindings.

> +
> +#ifndef _DT_BINDINGS_NVMEM_MICROCHIP_OTPC_H
> +#define _DT_BINDINGS_NVMEM_MICROCHIP_OTPC_H
> +
> +/*
> + * Need to have it as a multiple of 4 as NVMEM memory is registered with
> + * stride = 4.
> + */
> +#define OTP_PKT(id)			((id) * 4)

Do I get it correctly - the offset or register address is now part of a
binding? You write here "id", however you use it as part of "reg", so
it's confusing.

> +
> +/*
> + * Temperature calibration packet length for SAMA7G5: 1 words header,
> + * 18 words payload.
> + */
> +#define OTP_PKT_SAMA7G5_TEMP_CALIB_LEN	(19 * 4)

Length of some memory region also does not look like job for bindings.

Best regards,
Krzysztof