* [PATCH v5 0/2] at24: convert the binding document to yaml
@ 2019-09-30 8:59 Bartosz Golaszewski
2019-09-30 8:59 ` [PATCH v5 1/2] dt-bindings: " Bartosz Golaszewski
2019-09-30 8:59 ` [PATCH v5 2/2] dt-bindings: at24: add new compatible Bartosz Golaszewski
0 siblings, 2 replies; 4+ messages in thread
From: Bartosz Golaszewski @ 2019-09-30 8:59 UTC (permalink / raw)
To: Rob Herring, Mark Rutland, Peter Rosin
Cc: devicetree, linux-kernel, linux-i2c, Bartosz Golaszewski
From: Bartosz Golaszewski <bgolaszewski@baylibre.com>
The first patch converts the at24 DT binding to yaml. The second adds a new
compatible special case that's being used undocumented currently.
v1 -> v2:
- modified the compatible property: we now list all possible combinations and
non-standard types with appropriate fallbacks to be as strict as possible
- minor changes to other properties: added constraints, converted to enums
where applicable and referenced the types from schema
v2 -> v3:
(Rob Herring:)
- Here's my reworking of compatible schema and all the other fixes I
found. The inner 'oneOf' is probably a little excessive given the number
of lines. All it does is ensure both compatible strings have the same
part number.
v3 -> v4:
- Add a $nodename definition
- Turns out the compatible schema is too complex for generating a 'select'
schema and only a small subset where getting validated. So we need a
custom 'select' schema. This in turn fixes the issue with the nxp,se97b
binding.
v4 -> v5:
- added a new patch extending the list of special cases of the compatible
property
- added comments explaining the schema for the compatible property
- dropped redundant information from property descriptions (for instance:
there's no need to say "This parameterless property" where it's obvious
from the type that the property is a flag)
Bartosz Golaszewski (2):
dt-bindings: at24: convert the binding document to yaml
dt-bindings: at24: add new compatible
.../devicetree/bindings/eeprom/at24.txt | 90 +--------
.../devicetree/bindings/eeprom/at24.yaml | 182 ++++++++++++++++++
MAINTAINERS | 2 +-
3 files changed, 184 insertions(+), 90 deletions(-)
create mode 100644 Documentation/devicetree/bindings/eeprom/at24.yaml
--
2.23.0
^ permalink raw reply [flat|nested] 4+ messages in thread
* [PATCH v5 1/2] dt-bindings: at24: convert the binding document to yaml
2019-09-30 8:59 [PATCH v5 0/2] at24: convert the binding document to yaml Bartosz Golaszewski
@ 2019-09-30 8:59 ` Bartosz Golaszewski
2019-10-01 13:37 ` Rob Herring
2019-09-30 8:59 ` [PATCH v5 2/2] dt-bindings: at24: add new compatible Bartosz Golaszewski
1 sibling, 1 reply; 4+ messages in thread
From: Bartosz Golaszewski @ 2019-09-30 8:59 UTC (permalink / raw)
To: Rob Herring, Mark Rutland, Peter Rosin
Cc: devicetree, linux-kernel, linux-i2c, Bartosz Golaszewski,
Rob Herring
From: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Convert the binding document for at24 EEPROMs from txt to yaml. The
compatible property uses a regex pattern to address all the possible
combinations of "vendor,model" strings.
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
[robh: rework compatible schema, fix missing allOf for $ref, fix errors in example]
Signed-off-by: Rob Herring <robh@kernel.org>
[Bartosz: added comments explaining the compatible property]
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
---
.../devicetree/bindings/eeprom/at24.txt | 90 +--------
.../devicetree/bindings/eeprom/at24.yaml | 179 ++++++++++++++++++
MAINTAINERS | 2 +-
3 files changed, 181 insertions(+), 90 deletions(-)
create mode 100644 Documentation/devicetree/bindings/eeprom/at24.yaml
diff --git a/Documentation/devicetree/bindings/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt
index 22aead844d0f..c94acbb8cb0c 100644
--- a/Documentation/devicetree/bindings/eeprom/at24.txt
+++ b/Documentation/devicetree/bindings/eeprom/at24.txt
@@ -1,89 +1 @@
-EEPROMs (I2C)
-
-Required properties:
-
- - compatible: Must be a "<manufacturer>,<model>" pair. The following <model>
- values are supported (assuming "atmel" as manufacturer):
-
- "atmel,24c00",
- "atmel,24c01",
- "atmel,24cs01",
- "atmel,24c02",
- "atmel,24cs02",
- "atmel,24mac402",
- "atmel,24mac602",
- "atmel,spd",
- "atmel,24c04",
- "atmel,24cs04",
- "atmel,24c08",
- "atmel,24cs08",
- "atmel,24c16",
- "atmel,24cs16",
- "atmel,24c32",
- "atmel,24cs32",
- "atmel,24c64",
- "atmel,24cs64",
- "atmel,24c128",
- "atmel,24c256",
- "atmel,24c512",
- "atmel,24c1024",
- "atmel,24c2048",
-
- If <manufacturer> is not "atmel", then a fallback must be used
- with the same <model> and "atmel" as manufacturer.
-
- Example:
- compatible = "microchip,24c128", "atmel,24c128";
-
- Supported manufacturers are:
-
- "catalyst",
- "microchip",
- "nxp",
- "ramtron",
- "renesas",
- "rohm",
- "st",
-
- Some vendors use different model names for chips which are just
- variants of the above. Known such exceptions are listed below:
-
- "nxp,se97b" - the fallback is "atmel,24c02",
- "renesas,r1ex24002" - the fallback is "atmel,24c02"
- "renesas,r1ex24016" - the fallback is "atmel,24c16"
- "renesas,r1ex24128" - the fallback is "atmel,24c128"
- "rohm,br24t01" - the fallback is "atmel,24c01"
-
- - reg: The I2C address of the EEPROM.
-
-Optional properties:
-
- - pagesize: The length of the pagesize for writing. Please consult the
- manual of your device, that value varies a lot. A wrong value
- may result in data loss! If not specified, a safety value of
- '1' is used which will be very slow.
-
- - read-only: This parameterless property disables writes to the eeprom.
-
- - size: Total eeprom size in bytes.
-
- - no-read-rollover: This parameterless property indicates that the
- multi-address eeprom does not automatically roll over
- reads to the next slave address. Please consult the
- manual of your device.
-
- - wp-gpios: GPIO to which the write-protect pin of the chip is connected.
-
- - address-width: number of address bits (one of 8, 16).
-
- - num-addresses: total number of i2c slave addresses this device takes
-
-Example:
-
-eeprom@52 {
- compatible = "atmel,24c32";
- reg = <0x52>;
- pagesize = <32>;
- wp-gpios = <&gpio1 3 0>;
- num-addresses = <8>;
-};
+This file has been moved to at24.yaml.
diff --git a/Documentation/devicetree/bindings/eeprom/at24.yaml b/Documentation/devicetree/bindings/eeprom/at24.yaml
new file mode 100644
index 000000000000..aee0890d3b7a
--- /dev/null
+++ b/Documentation/devicetree/bindings/eeprom/at24.yaml
@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: GPL-2.0-only
+# Copyright 2019 BayLibre SAS
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/eeprom/at24.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: I2C EEPROMs compatible with Atmel's AT24
+
+maintainers:
+ - Bartosz Golaszewski <bgolaszewski@baylibre.com>
+
+select:
+ properties:
+ compatible:
+ contains:
+ pattern: "^atmel,(24(c|cs|mac)[0-9]+|spd)$"
+ required:
+ - compatible
+
+properties:
+ $nodename:
+ pattern: "^eeprom@[0-9a-f]{1,2}$"
+
+ # There are multiple known vendors who manufacture EEPROM chips compatible
+ # with Atmel's AT24. The compatible string requires either a single item
+ # if the memory comes from Atmel (in which case the vendor part must be
+ # 'atmel') or two items with the same 'model' part where the vendor part of
+ # the first one is the actual manufacturer and the second item is the
+ # corresponding 'atmel,<model>' from Atmel.
+ #
+ # While the below schema would technically allow the following:
+ #
+ # compatible = "atmel,24c01", "atmel,24c01";
+ #
+ # this obviously must not be used.
+ compatible:
+ oneOf:
+ - allOf:
+ - minItems: 1
+ maxItems: 2
+ items:
+ - pattern: "^(atmel|catalyst|microchip|nxp|ramtron|renesas|rohm|st),(24(c|cs|mac)[0-9]+|spd)$"
+ - pattern: "^atmel,(24(c|cs|mac)[0-9]+|spd)$"
+ - oneOf:
+ - items:
+ pattern: c00$
+ - items:
+ pattern: c01$
+ - items:
+ pattern: c02$
+ - items:
+ pattern: c04$
+ - items:
+ pattern: c08$
+ - items:
+ pattern: c16$
+ - items:
+ pattern: cs16$
+ - items:
+ pattern: c32$
+ - items:
+ pattern: cs32$
+ - items:
+ pattern: c64$
+ - items:
+ pattern: cs64$
+ - items:
+ pattern: c128$
+ - items:
+ pattern: cs128$
+ - items:
+ pattern: c256$
+ - items:
+ pattern: cs256$
+ - items:
+ pattern: c512$
+ - items:
+ pattern: cs512$
+ - items:
+ pattern: c1024$
+ - items:
+ pattern: cs1024$
+ - items:
+ pattern: c2048$
+ - items:
+ pattern: cs2048$
+ - items:
+ pattern: spd$
+ # These are special cases that don't conform to the above pattern.
+ # Each requires a standard at24 model as fallback.
+ - items:
+ - const: rohm,br24t01
+ - const: atmel,24c01
+ - items:
+ - const: nxp,se97b
+ - const: atmel,24c02
+ - items:
+ - const: renesas,r1ex24002
+ - const: atmel,24c02
+ - items:
+ - const: renesas,r1ex24016
+ - const: atmel,24c16
+ - items:
+ - const: renesas,r1ex24128
+ - const: atmel,24c128
+
+ reg:
+ maxItems: 1
+
+ pagesize:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ The length of the pagesize for writing. Please consult the
+ manual of your device, that value varies a lot. A wrong value
+ may result in data loss! If not specified, a safety value of
+ '1' is used which will be very slow.
+ enum: [ 1, 8, 16, 32, 64, 128, 258 ]
+ default: 1
+
+ read-only:
+ $ref: /schemas/types.yaml#definitions/flag
+ description:
+ Disables writes to the eeprom.
+
+ size:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Total eeprom size in bytes.
+
+ no-read-rollover:
+ $ref: /schemas/types.yaml#definitions/flag
+ description:
+ Indicates that the multi-address eeprom does not automatically roll
+ over reads to the next slave address. Please consult the manual of
+ your device.
+
+ wp-gpios:
+ description:
+ GPIO to which the write-protect pin of the chip is connected.
+ maxItems: 1
+
+ address-width:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Number of address bits.
+ default: 8
+ enum: [ 8, 16 ]
+
+ num-addresses:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Total number of i2c slave addresses this device takes.
+ default: 1
+ minimum: 1
+ maximum: 8
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ eeprom@52 {
+ compatible = "microchip,24c32", "atmel,24c32";
+ reg = <0x52>;
+ pagesize = <32>;
+ wp-gpios = <&gpio1 3 0>;
+ num-addresses = <8>;
+ };
+ };
+...
diff --git a/MAINTAINERS b/MAINTAINERS
index 296de2b51c83..320fc8bba872 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2699,7 +2699,7 @@ M: Bartosz Golaszewski <bgolaszewski@baylibre.com>
L: linux-i2c@vger.kernel.org
T: git git://git.kernel.org/pub/scm/linux/kernel/git/brgl/linux.git
S: Maintained
-F: Documentation/devicetree/bindings/eeprom/at24.txt
+F: Documentation/devicetree/bindings/eeprom/at24.yaml
F: drivers/misc/eeprom/at24.c
ATA OVER ETHERNET (AOE) DRIVER
--
2.23.0
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [PATCH v5 2/2] dt-bindings: at24: add new compatible
2019-09-30 8:59 [PATCH v5 0/2] at24: convert the binding document to yaml Bartosz Golaszewski
2019-09-30 8:59 ` [PATCH v5 1/2] dt-bindings: " Bartosz Golaszewski
@ 2019-09-30 8:59 ` Bartosz Golaszewski
1 sibling, 0 replies; 4+ messages in thread
From: Bartosz Golaszewski @ 2019-09-30 8:59 UTC (permalink / raw)
To: Rob Herring, Mark Rutland, Peter Rosin
Cc: devicetree, linux-kernel, linux-i2c, Bartosz Golaszewski,
Rob Herring
From: Bartosz Golaszewski <bgolaszewski@baylibre.com>
arch/arm/boot/dts/at91-dvk_som60.dt.yaml uses the compatible string
'giantec,gt24c32a' for an at24 EEPROM with a fallback to 'atmel,24c32'.
Add this model as a special case to the binding document.
Reported-by: Rob Herring <robh@kernel.org>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
---
Documentation/devicetree/bindings/eeprom/at24.yaml | 3 +++
1 file changed, 3 insertions(+)
diff --git a/Documentation/devicetree/bindings/eeprom/at24.yaml b/Documentation/devicetree/bindings/eeprom/at24.yaml
index aee0890d3b7a..db365e913d3b 100644
--- a/Documentation/devicetree/bindings/eeprom/at24.yaml
+++ b/Documentation/devicetree/bindings/eeprom/at24.yaml
@@ -101,6 +101,9 @@ properties:
- items:
- const: renesas,r1ex24016
- const: atmel,24c16
+ - items:
+ - const: giantec,gt24c32a
+ - const: atmel,24c32
- items:
- const: renesas,r1ex24128
- const: atmel,24c128
--
2.23.0
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH v5 1/2] dt-bindings: at24: convert the binding document to yaml
2019-09-30 8:59 ` [PATCH v5 1/2] dt-bindings: " Bartosz Golaszewski
@ 2019-10-01 13:37 ` Rob Herring
0 siblings, 0 replies; 4+ messages in thread
From: Rob Herring @ 2019-10-01 13:37 UTC (permalink / raw)
To: Bartosz Golaszewski
Cc: Mark Rutland, Peter Rosin, devicetree, linux-kernel, linux-i2c,
Bartosz Golaszewski
On Mon, Sep 30, 2019 at 10:59:56AM +0200, Bartosz Golaszewski wrote:
> From: Bartosz Golaszewski <bgolaszewski@baylibre.com>
>
> Convert the binding document for at24 EEPROMs from txt to yaml. The
> compatible property uses a regex pattern to address all the possible
> combinations of "vendor,model" strings.
>
> Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
> [robh: rework compatible schema, fix missing allOf for $ref, fix errors in example]
> Signed-off-by: Rob Herring <robh@kernel.org>
> [Bartosz: added comments explaining the compatible property]
> Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
> ---
> .../devicetree/bindings/eeprom/at24.txt | 90 +--------
> .../devicetree/bindings/eeprom/at24.yaml | 179 ++++++++++++++++++
> MAINTAINERS | 2 +-
> 3 files changed, 181 insertions(+), 90 deletions(-)
> create mode 100644 Documentation/devicetree/bindings/eeprom/at24.yaml
> diff --git a/Documentation/devicetree/bindings/eeprom/at24.yaml b/Documentation/devicetree/bindings/eeprom/at24.yaml
> new file mode 100644
> index 000000000000..aee0890d3b7a
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/eeprom/at24.yaml
> @@ -0,0 +1,179 @@
> +# SPDX-License-Identifier: GPL-2.0-only
> +# Copyright 2019 BayLibre SAS
> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/eeprom/at24.yaml#"
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> +
> +title: I2C EEPROMs compatible with Atmel's AT24
> +
> +maintainers:
> + - Bartosz Golaszewski <bgolaszewski@baylibre.com>
> +
> +select:
> + properties:
> + compatible:
> + contains:
> + pattern: "^atmel,(24(c|cs|mac)[0-9]+|spd)$"
> + required:
> + - compatible
> +
> +properties:
> + $nodename:
> + pattern: "^eeprom@[0-9a-f]{1,2}$"
> +
> + # There are multiple known vendors who manufacture EEPROM chips compatible
> + # with Atmel's AT24. The compatible string requires either a single item
> + # if the memory comes from Atmel (in which case the vendor part must be
> + # 'atmel') or two items with the same 'model' part where the vendor part of
> + # the first one is the actual manufacturer and the second item is the
> + # corresponding 'atmel,<model>' from Atmel.
> + #
> + # While the below schema would technically allow the following:
> + #
> + # compatible = "atmel,24c01", "atmel,24c01";
This is prevented in the common 'compatible' schema that requires unique
items.
> + #
> + # this obviously must not be used.
> + compatible:
> + oneOf:
> + - allOf:
> + - minItems: 1
> + maxItems: 2
> + items:
> + - pattern: "^(atmel|catalyst|microchip|nxp|ramtron|renesas|rohm|st),(24(c|cs|mac)[0-9]+|spd)$"
> + - pattern: "^atmel,(24(c|cs|mac)[0-9]+|spd)$"
> + - oneOf:
> + - items:
> + pattern: c00$
> + - items:
> + pattern: c01$
> + - items:
> + pattern: c02$
> + - items:
> + pattern: c04$
> + - items:
> + pattern: c08$
Need to add the 'cs' variants I missed.
> + - items:
> + pattern: c16$
> + - items:
> + pattern: cs16$
> + - items:
> + pattern: c32$
> + - items:
> + pattern: cs32$
> + - items:
> + pattern: c64$
> + - items:
> + pattern: cs64$
> + - items:
> + pattern: c128$
> + - items:
> + pattern: cs128$
> + - items:
> + pattern: c256$
> + - items:
> + pattern: cs256$
> + - items:
> + pattern: c512$
> + - items:
> + pattern: cs512$
> + - items:
> + pattern: c1024$
> + - items:
> + pattern: cs1024$
> + - items:
> + pattern: c2048$
> + - items:
> + pattern: cs2048$
> + - items:
> + pattern: spd$
> + # These are special cases that don't conform to the above pattern.
> + # Each requires a standard at24 model as fallback.
> + - items:
> + - const: rohm,br24t01
> + - const: atmel,24c01
> + - items:
> + - const: nxp,se97b
> + - const: atmel,24c02
> + - items:
> + - const: renesas,r1ex24002
> + - const: atmel,24c02
> + - items:
> + - const: renesas,r1ex24016
> + - const: atmel,24c16
> + - items:
> + - const: renesas,r1ex24128
> + - const: atmel,24c128
> +
> + reg:
> + maxItems: 1
> +
> + pagesize:
> + allOf:
> + - $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + The length of the pagesize for writing. Please consult the
> + manual of your device, that value varies a lot. A wrong value
> + may result in data loss! If not specified, a safety value of
> + '1' is used which will be very slow.
> + enum: [ 1, 8, 16, 32, 64, 128, 258 ]
> + default: 1
> +
> + read-only:
> + $ref: /schemas/types.yaml#definitions/flag
> + description:
> + Disables writes to the eeprom.
> +
> + size:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + Total eeprom size in bytes.
> +
> + no-read-rollover:
> + $ref: /schemas/types.yaml#definitions/flag
> + description:
> + Indicates that the multi-address eeprom does not automatically roll
> + over reads to the next slave address. Please consult the manual of
> + your device.
> +
> + wp-gpios:
> + description:
> + GPIO to which the write-protect pin of the chip is connected.
> + maxItems: 1
> +
> + address-width:
> + allOf:
> + - $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + Number of address bits.
> + default: 8
> + enum: [ 8, 16 ]
> +
> + num-addresses:
> + allOf:
> + - $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + Total number of i2c slave addresses this device takes.
> + default: 1
> + minimum: 1
> + maximum: 8
> +
> +required:
> + - compatible
> + - reg
> +
> +examples:
> + - |
> + i2c {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + eeprom@52 {
> + compatible = "microchip,24c32", "atmel,24c32";
> + reg = <0x52>;
> + pagesize = <32>;
> + wp-gpios = <&gpio1 3 0>;
> + num-addresses = <8>;
> + };
> + };
> +...
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 296de2b51c83..320fc8bba872 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2699,7 +2699,7 @@ M: Bartosz Golaszewski <bgolaszewski@baylibre.com>
> L: linux-i2c@vger.kernel.org
> T: git git://git.kernel.org/pub/scm/linux/kernel/git/brgl/linux.git
> S: Maintained
> -F: Documentation/devicetree/bindings/eeprom/at24.txt
> +F: Documentation/devicetree/bindings/eeprom/at24.yaml
> F: drivers/misc/eeprom/at24.c
>
> ATA OVER ETHERNET (AOE) DRIVER
> --
> 2.23.0
>
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2019-10-01 13:37 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-09-30 8:59 [PATCH v5 0/2] at24: convert the binding document to yaml Bartosz Golaszewski
2019-09-30 8:59 ` [PATCH v5 1/2] dt-bindings: " Bartosz Golaszewski
2019-10-01 13:37 ` Rob Herring
2019-09-30 8:59 ` [PATCH v5 2/2] dt-bindings: at24: add new compatible Bartosz Golaszewski
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.