On Sun, Aug 02, 2020 at 07:46:26PM +0200, Christian Eggers wrote:
> Convert the binding document for at25 EEPROMs from txt to yaml. The
> compatible property doesn't use a regex pattern (as in at24), because
> the 'vendor' and the 'model' are an "infinite" list (even if only 5
> combinations are found in the current dts files). The settings required
> by a driver are given as separate properties.
>
> Signed-off-by: Christian Eggers <ceggers@xxxxxxx>
> ---
> On Friday, Jul 31 2020, Rob Herring wrote:
> >> On Tue, Jul 28, 2020 at 1:34 AM Christian Eggers <ceggers@xxxxxxx> wrote:
> >> When I specify
> >>
> >> compatible:
> >> enum:
> >> - atmel,at25
> >>
> >> I get an error in dt_binding_check:
> >> ...
> >
> > You can do:
> >
> > items:
> > - {}
> > - const: atmel,at25
> >
> > But really, the possible compatible strings need to be listed out. See
> > at24.yaml as it had similar issues IIRC.
>
> I think that at24 is very diffrent from at25 here (at least the linux
> driver). Whilst the at24 driver extracts parameters of the chip from the
> 'model' part, at25 gets this information from separate properties.
>
> As there is virtually an infinite list of possible vendors and products
> for such type of hardware, is there any value to use expressions like in
> the at24 binding?
Maybe so, but there are only 4 compatible strings to document in the
tree. That's not a lot to cover and we already have some of them in
free-form text. If the infinite number becomes a problem we can always
address that later. I'm sure that less than infinite buyers/products
will prevent infinite producers.
So it is much less a mess compared to at24.
>
> Other question: What is the meaning of the maintainers field in the
> binding?
Someone who knows the h/w and can review binding changes.
> Is it related to the binding itself or the linux driver?
> I am
> not the maintainer of the driver...
Doesn't have to be the same person.
>
>
> .../devicetree/bindings/eeprom/at25.txt | 46 +------
> .../devicetree/bindings/eeprom/at25.yaml | 122 ++++++++++++++++++
> 2 files changed, 123 insertions(+), 45 deletions(-)
> create mode 100644 Documentation/devicetree/bindings/eeprom/at25.yaml
>
> diff --git a/Documentation/devicetree/bindings/eeprom/at25.txt b/Documentation/devicetree/bindings/eeprom/at25.txt
> index fe91ecf1f61b..9b1096fb3826 100644
> --- a/Documentation/devicetree/bindings/eeprom/at25.txt
> +++ b/Documentation/devicetree/bindings/eeprom/at25.txt
> @@ -1,45 +1 @@
> -EEPROMs (SPI) compatible with Atmel at25.
> -
> -Required properties:
> -- compatible : Should be "<vendor>,<type>", and generic value "atmel,at25".
> - Example "<vendor>,<type>" values:
> - "anvo,anv32e61w"
> - "microchip,25lc040"
> - "st,m95m02"
> - "st,m95256"
> -
> -- reg : chip select number
> -- spi-max-frequency : max spi frequency to use
> -- pagesize : size of the eeprom page
> -- size : total eeprom size in bytes
> -- address-width : number of address bits (one of 8, 9, 16, or 24).
> - For 9 bits, the MSB of the address is sent as bit 3 of the instruction
> - byte, before the address byte.
> -
> -Optional properties:
> -- spi-cpha : SPI shifted clock phase, as per spi-bus bindings.
> -- spi-cpol : SPI inverse clock polarity, as per spi-bus bindings.
> -- read-only : this parameter-less property disables writes to the eeprom
> -- wp-gpios : GPIO to which the write-protect pin of the chip is connected
> -
> -Obsolete legacy properties can be used in place of "size", "pagesize",
> -"address-width", and "read-only":
> -- at25,byte-len : total eeprom size in bytes
> -- at25,addr-mode : addr-mode flags, as defined in include/linux/spi/eeprom.h
> -- at25,page-size : size of the eeprom page
> -
> -Additional compatible properties are also allowed.
> -
> -Example:
> - eeprom@0 {
> - compatible = "st,m95256", "atmel,at25";
> - reg = <0>;
> - spi-max-frequency = <5000000>;
> - spi-cpha;
> - spi-cpol;
> - wp-gpios = <&gpio1 3 0>;
> -
> - pagesize = <64>;
> - size = <32768>;
> - address-width = <16>;
> - };
> +This file has been moved to at25.yaml.
> \ No newline at end of file
Fix this.
> diff --git a/Documentation/devicetree/bindings/eeprom/at25.yaml b/Documentation/devicetree/bindings/eeprom/at25.yaml
> new file mode 100644
> index 000000000000..437a28dab6fd
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/eeprom/at25.yaml
> @@ -0,0 +1,122 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/eeprom/at25.yaml#";
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#";
> +
> +title: SPI EEPROMs compatible with Atmel's AT25
> +
> +maintainers:
> + - Christian Eggers <ceggers@xxxxxxx>
> +
> +properties:
> + $nodename:
> + pattern: "^eeprom@[0-9a-f]{1,2}$"
> +
> + # There are multiple known vendors who manufacture EEPROM chips compatible
> + # with Atmel's AT25. The compatible string requires two items where the
> + # 'vendor' and 'model' parts of the first are the actual chip and the second
> + # item is fixed to "atmel,at25".
> + compatible:
> + items:
> + - {}
> + - const: atmel,at25
This doesn't work for 'atmel,at25' alone. You'll need a 'oneOf' with a
single entry.
> + description:
> + 'Should be "<vendor>,<chip>", and generic value "atmel,at25".
> + Example "<vendor>,<chip>" values:
> + "anvo,anv32e61w"
> + "microchip,25lc040"
> + "st,m95m02"
> + "st,m95256"'
> +
> + reg:
> + description:
> + Chip select number.
> +
> + spi-max-frequency:
> + $ref: /schemas/types.yaml#definitions/uint32
This is common and already has a definition. Just need 'true'.
> + description:
> + Maximum SPI frequency to use.
> +
> + pagesize:
> + $ref: /schemas/types.yaml#definitions/uint32
> + description:
> + Size of the eeprom page.
Constraints? I'd assume it's some power of 2 set.
> +
> + size:
> + $ref: /schemas/types.yaml#definitions/uint32
> + description:
> + Total eeprom size in bytes.
> +
> + address-width:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [ 8, 9, 16, 24 ]
> + description:
> + Number of address bits.
> + For 9 bits, the MSB of the address is sent as bit 3 of the instruction
> + byte, before the address byte.
> +
> + spi-cpha: true
> +
> + spi-cpol: true
> +
> + read-only:
> + description:
> + Disable writes to the eeprom.
> + type: boolean
> +
> + wp-gpios:
> + maxItems: 1
> + description:
> + GPIO to which the write-protect pin of the chip is connected.
> +
> + # Deprecated: at25,byte-len, at25,addr-mode, at25,page-size
> + at25,byte-len:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + Total eeprom size in bytes. Deprecated, use "size" property instead.
> + deprecated: true
> +
> + at25,addr-mode:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + Addr-mode flags, as defined in include/linux/spi/eeprom.h.
> + Deprecated, use "address-width" property instead.
> + deprecated: true
> +
> + at25,page-size:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + Size of the eeprom page. Deprecated, use "pagesize" property instead.
> + deprecated: true
> +
> +required:
> + - compatible
> + - reg
> + - spi-max-frequency
> + - pagesize
> + - size
> + - address-width
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + #include <dt-bindings/gpio/gpio.h>
> + spi0 {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + eeprom@0 {
> + compatible = "st,m95256", "atmel,at25";
> + reg = <0>;
> + spi-max-frequency = <5000000>;
> + spi-cpha;
> + spi-cpol;
> + wp-gpios = <&gpio1 3 0>;
> +
> + pagesize = <64>;
> + size = <32768>;
> + address-width = <16>;
> + };
> + };
> --
> Christian Eggers
> Embedded software developer
>
> Arnold & Richter Cine Technik GmbH & Co. Betriebs KG
> Sitz: Muenchen - Registergericht: Amtsgericht Muenchen - Handelsregisternummer: HRA 57918
> Persoenlich haftender Gesellschafter: Arnold & Richter Cine Technik GmbH
> Sitz: Muenchen - Registergericht: Amtsgericht Muenchen - Handelsregisternummer: HRB 54477
> Geschaeftsfuehrer: Dr. Michael Neuhaeuser; Stephan Schenk; Walter Trauninger; Markus Zeiler
>
