From dd7f48ef4a67ced4e5a3ae6657e494a8b83d192c Mon Sep 17 00:00:00 2001
From: Henrik Brix Andersen <hebad@vestas.com>
Date: Thu, 30 May 2024 11:18:57 +0200
Subject: [PATCH] dts: bindings: mtd: atmel,at2x: improve binding descriptions

Improve the binding descriptions for the atmel,at24 and atmel,at25 EEPROM
compatibles. These compatibles work for a number of different EEPROM
families manufactured by vendors other than Atmel.

Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
---
 dts/bindings/mtd/atmel,at24.yaml | 31 ++++++++++++++++++++++++++++++-
 dts/bindings/mtd/atmel,at25.yaml | 31 ++++++++++++++++++++++++++++++-
 2 files changed, 60 insertions(+), 2 deletions(-)

diff --git a/dts/bindings/mtd/atmel,at24.yaml b/dts/bindings/mtd/atmel,at24.yaml
index da3369ec623..b9dda41cc80 100644
--- a/dts/bindings/mtd/atmel,at24.yaml
+++ b/dts/bindings/mtd/atmel,at24.yaml
@@ -2,7 +2,36 @@
 # Copyright (c) 2018, Nordic Semiconductor
 # SPDX-License-Identifier: Apache-2.0
 
-description: Atmel AT24 (or compatible) I2C EEPROM
+description: |
+  I2C EEPROMs compatible with Atmel's AT24 family
+
+  There are multiple vendors manufacturing I2C EEPROMs compatible with the programming model of the
+  Atmel AT24.
+
+  Examples of compatible EEPROM families:
+  - Microchip AT24xxx
+  - ST M24xxx
+
+  Each of these can be represented by a set of common parameters (EEPROM size, page size, address
+  width, and timeout) available from the datasheet of the specific EEPROM. The compatible string for
+  these can list the specific EEPROM vendor and model along with the vendor EEPROM family as long as
+  the least-specific compatible entry is "atmel,at24".
+
+  Example devicetree node describing a ST M24M01 EEPROM on the i2c0 bus:
+
+    &i2c0 {
+      status = "okay";
+      clock-frequency = <I2C_BITRATE_FAST>;
+
+      eeprom@56 {
+        compatible = "st,m24m01", "st,m24xxx", "atmel,at24";
+        reg = <0x56>;
+        size = <DT_SIZE_K(128)>;
+        pagesize = <256>;
+        address-width = <16>;
+        timeout = <5>;
+     };
+   };
 
 compatible: "atmel,at24"
 
diff --git a/dts/bindings/mtd/atmel,at25.yaml b/dts/bindings/mtd/atmel,at25.yaml
index 9b1977e8dc1..7c887dd1768 100644
--- a/dts/bindings/mtd/atmel,at25.yaml
+++ b/dts/bindings/mtd/atmel,at25.yaml
@@ -1,7 +1,36 @@
 # Copyright (c) 2019 Vestas Wind Systems A/S
 # SPDX-License-Identifier: Apache-2.0
 
-description: Atmel AT25 (or compatible) SPI EEPROM
+description: |
+  SPI EEPROMs compatible with Atmel's AT25 family
+
+  There are multiple vendors manufacturing SPI EEPROMs compatible with the programming model of the
+  Atmel AT25.
+
+  Examples of compatible EEPROM families:
+  - Microchip AT25xxx
+  - ST M95xxx
+
+  Each of these can be represented by a set of common parameters (EEPROM size, page size, address
+  width, and timeout) available from the datasheet of the specific EEPROM. The compatible string for
+  these can list the specific EEPROM vendor and model along with the vendor EEPROM family as long as
+  the least-specific compatible entry is "atmel,at25".
+
+  Example devicetree node describing a ST M95256 EEPROM on the spi0 bus:
+
+    &spi0 {
+      status = "okay";
+
+      eeprom@1 {
+        compatible = "st,m95256", "st,m95xxx", "atmel,at25";
+        reg = <0x1>;
+        size = <DT_SIZE_K(32)>;
+        pagesize = <64>;
+        address-width = <16>;
+        spi-max-frequency = <DT_FREQ_M(20)>;
+        timeout = <5>;
+      };
+   };
 
 compatible: "atmel,at25"