Add support for the control interface of STMicroelectronics M24LR
RFID/NFC EEPROM chips.

Signed-off-by: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
---
 .../devicetree/bindings/eeprom/st,m24lr.yaml  | 72 +++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/eeprom/st,m24lr.yaml

diff --git a/Documentation/devicetree/bindings/eeprom/st,m24lr.yaml b/Documentation/devicetree/bindings/eeprom/st,m24lr.yaml
new file mode 100644
index 000000000000..6d72325865d6
--- /dev/null
+++ b/Documentation/devicetree/bindings/eeprom/st,m24lr.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/eeprom/st,m24lr.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics M24LR Series NFC/RFID EEPROM Control Interface
+
+maintainers:
+  - Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
+
+description: |
+  STMicroelectronics M24LR series are dual-interface (RF + I2C)
+  EEPROM chips. These devices support I2C-based access to both
+  memory and a system area that controls authentication and configuration.
+  They expose two I2C addresses: one for EEPROM memory and one for the
+  system control area (e.g., UID, password management).
+
+allOf:
+  - $ref: ../i2c/i2c-mux.yaml#
+
+properties:
+  compatible:
+    enum:
+      - st,m24lr04e-r
+      - st,m24lr16e-r
+      - st,m24lr64e-r
+
+  reg:
+    maxItems: 1
+
+  pagesize:
+    enum: [1, 4, 8, 16, 32, 64, 128, 256]
+    default: 1
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: >
+      Maximum number of bytes that can be written in one I2C transaction.
+      the default is 1.
+
+required:
+  - compatible
+  - reg
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    i2c {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      i2cmux@57 {
+        compatible = "st,m24lr04e-r";
+        reg = <0x57>;
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        i2c@0 {
+          reg = <0x0>;
+          #address-cells = <1>;
+          #size-cells = <0>;
+
+          eeprom@53 {
+            compatible = "atmel,24c04";
+            reg = <0x53>;
+            address-width = <16>;
+            pagesize = <4>;
+          };
+        };
+      };
+    };
+...
-- 
2.43.0

On Sun, 01 Jun 2025 15:30:19 +0000, Abd-Alrhman Masalkhi wrote:
> Add support for the control interface of STMicroelectronics M24LR
> RFID/NFC EEPROM chips.
> 
> Signed-off-by: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
> ---
>  .../devicetree/bindings/eeprom/st,m24lr.yaml  | 72 +++++++++++++++++++
>  1 file changed, 72 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/eeprom/st,m24lr.yaml
> 

My bot found errors running 'make dt_binding_check' on your patch:

yamllint warnings/errors:

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/eeprom/st,m24lr.example.dtb: eeprom@53 (atmel,24c04): pagesize: 4 is not one of [1, 8, 16, 32, 64, 128, 256]
	from schema $id: http://devicetree.org/schemas/eeprom/at24.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/eeprom/st,m24lr.example.dtb: eeprom@53 (atmel,24c04): Unevaluated properties are not allowed ('pagesize' was unexpected)
	from schema $id: http://devicetree.org/schemas/eeprom/at24.yaml#

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20250601153022.2027919-2-abd.masalkhi@gmail.com

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.

Hi Rob,

Thanks for the feedback.

> yamllint warnings/errors:
> 
> dtschema/dtc warnings/errors:
> /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/eeprom/st,m24lr.example.dtb: eeprom@53 > (atmel,24c04): pagesize: 4 is not one of [1, 8, 16, 32, 64, 128, 256]
> 	from schema $id: http://devicetree.org/schemas/eeprom/at24.yaml#
> /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/eeprom/st,m24lr.example.dtb: eeprom@53 > (atmel,24c04): Unevaluated properties are not allowed ('pagesize' was unexpected)
> 	from schema $id: http://devicetree.org/schemas/eeprom/at24.yaml#
> 
> doc reference errors (make refcheckdocs):
> 
> See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20250601153022.2027919-2-abd.masalkhi@gmail.com
> 
> The base for the series is generally the latest rc1. A different dependency
> should be noted in *this* patch.
> 
> If you already ran 'make dt_binding_check' and didn't see the above
> error(s), then make sure 'yamllint' is installed and dt-schema is up to
> date:
> 
> pip3 install dtschema --upgrade

I had already updated dtschema to the latest version and ensured that
yamllint was installed, as advised in the previous version. i have
executed 'make dt_binding_check' as you guided me, but still it did not
emit any errors.

Best regards,
Abd-Alrhman Masalkhi

On 03/06/2025 07:40, Abd-Alrhman Masalkhi wrote:
> Hi Rob,
> 
> Thanks for the feedback.
> 
>> yamllint warnings/errors:
>>
>> dtschema/dtc warnings/errors:
>> /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/eeprom/st,m24lr.example.dtb: eeprom@53 > (atmel,24c04): pagesize: 4 is not one of [1, 8, 16, 32, 64, 128, 256]
>> 	from schema $id: http://devicetree.org/schemas/eeprom/at24.yaml#
>> /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/eeprom/st,m24lr.example.dtb: eeprom@53 > (atmel,24c04): Unevaluated properties are not allowed ('pagesize' was unexpected)
>> 	from schema $id: http://devicetree.org/schemas/eeprom/at24.yaml#
>>
>> doc reference errors (make refcheckdocs):
>>
>> See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20250601153022.2027919-2-abd.masalkhi@gmail.com
>>
>> The base for the series is generally the latest rc1. A different dependency
>> should be noted in *this* patch.
>>
>> If you already ran 'make dt_binding_check' and didn't see the above
>> error(s), then make sure 'yamllint' is installed and dt-schema is up to
>> date:
>>
>> pip3 install dtschema --upgrade
> 
> I had already updated dtschema to the latest version and ensured that
> yamllint was installed, as advised in the previous version. i have
> executed 'make dt_binding_check' as you guided me, but still it did not
> emit any errors.

I doubt that you run it exactly the way as describe here, because you
have obvious error in binding which is nicely reported here - you put
pagesize to wrong node.

Best regards,
Krzysztof

On 01/06/2025 17:30, Abd-Alrhman Masalkhi wrote:
> Add support for the control interface of STMicroelectronics M24LR
> RFID/NFC EEPROM chips.
> 
> Signed-off-by: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
> ---
>  .../devicetree/bindings/eeprom/st,m24lr.yaml  | 72 +++++++++++++++++++

Do not send next version while the discussion is still happening.

>  1 file changed, 72 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/eeprom/st,m24lr.yaml

I still do not understand what is this device exactly. You said this is
not EEPROM, so my advice of putting this in eeprom seems not correct.

> 
> diff --git a/Documentation/devicetree/bindings/eeprom/st,m24lr.yaml b/Documentation/devicetree/bindings/eeprom/st,m24lr.yaml
> new file mode 100644
> index 000000000000..6d72325865d6
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/eeprom/st,m24lr.yaml
> @@ -0,0 +1,72 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/eeprom/st,m24lr.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: STMicroelectronics M24LR Series NFC/RFID EEPROM Control Interface
> +
> +maintainers:
> +  - Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
> +
> +description: |

Do not need '|' unless you need to preserve formatting.

> +  STMicroelectronics M24LR series are dual-interface (RF + I2C)
> +  EEPROM chips. These devices support I2C-based access to both
> +  memory and a system area that controls authentication and configuration.
> +  They expose two I2C addresses: one for EEPROM memory and one for the
> +  system control area (e.g., UID, password management).

e.g., -> e.g.

> +
> +allOf:
> +  - $ref: ../i2c/i2c-mux.yaml#

Full path, so /schemas/i2c/i2c-mux.... but this is not an i2c mux, at
least not in your description, so something feels incomplete or incorrect.

> +
> +properties:
> +  compatible:
> +    enum:
> +      - st,m24lr04e-r
> +      - st,m24lr16e-r
> +      - st,m24lr64e-r

What does "r" stand for?

> +
> +  reg:
> +    maxItems: 1
> +
> +  pagesize:
> +    enum: [1, 4, 8, 16, 32, 64, 128, 256]
> +    default: 1
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: >

Do not need '>' unless you need to preserve formatting.

> +      Maximum number of bytes that can be written in one I2C transaction.
> +      the default is 1.

Don't repeat constraints in free form text. I already asked for this.


> +
> +required:
> +  - compatible
> +  - reg
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    i2c {
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      i2cmux@57 {

Nothing in commit msg or binding description explained why this is
i2c-mux.  i2c-mux is not an eeprom. Exposing two I2C addresses also does
not mean it is mux - we already have such devices and they were never
called mux.

> +        compatible = "st,m24lr04e-r";
> +        reg = <0x57>;

Where is the second address? It is supposed to be here.

> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        i2c@0 {
> +          reg = <0x0>;
> +          #address-cells = <1>;
> +          #size-cells = <0>;
> +
> +          eeprom@53 {
> +            compatible = "atmel,24c04";


And even if there was a mux here, then where is the second device?

> +            reg = <0x53>;
> +            address-width = <16>;
> +            pagesize = <4>;
> +          };
> +        };
> +      };
> +    };
> +...


Best regards,
Krzysztof

Hi Krzysztof,

Thank you for the detailed feedback.

> Do not send next version while the discussion is still happening.

You're right, I sent the updated version too early while discussion was
still ongoing. I'll hold off on sending further revisions until the current
points are fully resolved.

> Full path, so /schemas/i2c/i2c-mux.... but this is not an i2c mux, at
> least not in your description, so something feels incomplete or incorrect.

A Brief Overview of the Device:

The M24LR series is a dual-interface EEPROM with both I2C and ISO/IEC 15693
RF support. While it is technically an EEPROM, it also exposes a control
interface over I2C via a second address, which is used to manage features
such as password protection, energy harvesting configuration, and UID access.
This secondary interface is not memory-mapped like traditional EEPROMs, which
is why I initially considered separating the control aspect in the software.

How to Access the EEPROM and the System Parameter Sector?

According to the datasheet for the M24LR04E-R, the E2 bit must be set
appropriately in the I2C device select code to distinguish between EEPROM
access and control access.

What is E2?
E2 is a bit in the I2C device select code. It determines which internal
function of the chip is being accessed.

Device Select Code Format:
Bit:                b7  b6  b5  b4  b3  b2  b1  b0
Value:              1   0   1   0   E2  1   1   R/W

To access the EEPROM memory, E2 (b3) should be 0:

Device Select Code Format:
Bit:                b7  b6  b5  b4  b3  b2  b1  b0
Value:              1   0   1   0   0  1   1   R/W

To access the system control interface, E2 (b3) should be 1:

Device Select Code Format:
Bit:                b7  b6  b5  b4  b3  b2  b1  b0
Value:              1   0   1   0   0  1   1   R/W

Is This a Gate?
Correct me if I'm wrong, but to me this behavior resembles a form of gate,
instead of using a separate hardware pin to access the EEPROM, the chip
encodes this selection in the I2C device address. However, the datasheet
does not explicitly mention anything about a "gate" or "mux," which is
why I've been careful to not label it as an I2C gate in the binding.

That said, I see it as a kind of implicit I2C mux (of type gate), where
the chip use the 0x57 address as in the example and to select the internal
EEPROM we just reset the b3 in the device select code.

Why This View Matters in my driver design:

Looking at the device from this perspective has helped me keep the driver
design cleaner while keeping the synchronization issue in mind:

1- Avoiding code duplication (such as rewriting parts of the at24 driver).
2- Ensuring concurrent access to EEPROM and control areas is properly
   handled and isolated.
3- Representing the dual-role nature of the chip more explicitly.

> What does "r" stand for?

The r in st,m24lr04e-r stands for RF, these are the RF-enabled variants
of the M24LR series, as specified by STMicroelectronics.

> Do not need '>' unless you need to preserve formatting.

I'll remove the | and > where formatting preservation is not needed.

> Don't repeat constraints in free form text. I already asked for this.

I'll avoid repeating constraints in free-form text.

> Where is the second address? It is supposed to be here.

>> +          #size-cells = <0>;
>> +
>> +          eeprom@53 {
>> +            compatible = "atmel,24c04";
>> +            reg = <0x53>;

Here is the second address is 0x53, to select the EEPROM 

I appreciate your feedback.

Best regards,
Abd-Alrhman Masalkhi

On 02/06/2025 05:48, Abd-Alrhman Masalkhi wrote:
> Hi Krzysztof,
> 
> Thank you for the detailed feedback.
> 
>> Do not send next version while the discussion is still happening.
> 
> You're right, I sent the updated version too early while discussion was
> still ongoing. I'll hold off on sending further revisions until the current
> points are fully resolved.
> 
>> Full path, so /schemas/i2c/i2c-mux.... but this is not an i2c mux, at
>> least not in your description, so something feels incomplete or incorrect.
> 
> A Brief Overview of the Device:
> 
> The M24LR series is a dual-interface EEPROM with both I2C and ISO/IEC 15693
> RF support. While it is technically an EEPROM, it also exposes a control
> interface over I2C via a second address, which is used to manage features
> such as password protection, energy harvesting configuration, and UID access.
> This secondary interface is not memory-mapped like traditional EEPROMs, which
> is why I initially considered separating the control aspect in the software.
> 
> How to Access the EEPROM and the System Parameter Sector?
> 
> According to the datasheet for the M24LR04E-R, the E2 bit must be set
> appropriately in the I2C device select code to distinguish between EEPROM
> access and control access.
> 
> What is E2?
> E2 is a bit in the I2C device select code. It determines which internal
> function of the chip is being accessed.
> 
> Device Select Code Format:
> Bit:                b7  b6  b5  b4  b3  b2  b1  b0
> Value:              1   0   1   0   E2  1   1   R/W
> 
> To access the EEPROM memory, E2 (b3) should be 0:
> 
> Device Select Code Format:
> Bit:                b7  b6  b5  b4  b3  b2  b1  b0
> Value:              1   0   1   0   0  1   1   R/W
> 
> To access the system control interface, E2 (b3) should be 1:

So these are just two different addresses. I already commented on this.
This is not I2C mux but a device with two addresses.

> 
> Device Select Code Format:
> Bit:                b7  b6  b5  b4  b3  b2  b1  b0
> Value:              1   0   1   0   0  1   1   R/W
> 
> Is This a Gate?
> Correct me if I'm wrong, but to me this behavior resembles a form of gate,
> instead of using a separate hardware pin to access the EEPROM, the chip
> encodes this selection in the I2C device address. However, the datasheet
> does not explicitly mention anything about a "gate" or "mux," which is
> why I've been careful to not label it as an I2C gate in the binding.
> 
> That said, I see it as a kind of implicit I2C mux (of type gate), where
> the chip use the 0x57 address as in the example and to select the internal
> EEPROM we just reset the b3 in the device select code.
> 
> Why This View Matters in my driver design:

We do not talk here about driver design but bindings.

> 
> Looking at the device from this perspective has helped me keep the driver
> design cleaner while keeping the synchronization issue in mind:
> 
> 1- Avoiding code duplication (such as rewriting parts of the at24 driver).
> 2- Ensuring concurrent access to EEPROM and control areas is properly
>    handled and isolated.
> 3- Representing the dual-role nature of the chip more explicitly.
> 
>> What does "r" stand for?
> 
> The r in st,m24lr04e-r stands for RF, these are the RF-enabled variants
> of the M24LR series, as specified by STMicroelectronics.

It's fine.

> 
>> Do not need '>' unless you need to preserve formatting.
> 
> I'll remove the | and > where formatting preservation is not needed.

Respond inline, not by removing entire context.

Best regards,
Krzysztof

Hi Krzysztof,

Thank you again for yourfeedback, it's been very helpful in
understanding how best to write the binding file represent
this device.

>> A Brief Overview of the Device:
>> 
>> The M24LR series is a dual-interface EEPROM with both I2C and ISO/IEC 15693
>> RF support. While it is technically an EEPROM, it also exposes a control
>> interface over I2C via a second address, which is used to manage features
>> such as password protection, energy harvesting configuration, and UID access.
>> This secondary interface is not memory-mapped like traditional EEPROMs, which
>> is why I initially considered separating the control aspect in the software.
>> 
>> How to Access the EEPROM and the System Parameter Sector?
>> 
>> According to the datasheet for the M24LR04E-R, the E2 bit must be set
>> appropriately in the I2C device select code to distinguish between EEPROM
>> access and control access.
>> 
>> What is E2?
>> E2 is a bit in the I2C device select code. It determines which internal
>> function of the chip is being accessed.
>> 
>> Device Select Code Format:
>> Bit:                b7  b6  b5  b4  b3  b2  b1  b0
>> Value:              1   0   1   0   E2  1   1   R/W
>> 
>> To access the EEPROM memory, E2 (b3) should be 0:
>> 
>> Device Select Code Format:
>> Bit:                b7  b6  b5  b4  b3  b2  b1  b0
>> Value:              1   0   1   0   0  1   1   R/W
>> 
>> To access the system control interface, E2 (b3) should be 1:
>
> So these are just two different addresses. I already commented on this.
> This is not I2C mux but a device with two addresses.

I'd like to clarify one point before proceeding further, If I remove
the i2c-mux usage from the binding file, as your recommendation, does
this also imply that I should stop using the i2c-mux API in my driver
implementation itself? and treat this as a multi-function device, or
Is it acceptable to keep the current driver logic as-is, while limiting
the change to just fixing the binding and device tree representation?

and if only the binding file, should i represent it as the following:

  eeprom-ctl@57 {
  #address-cells = <1>;
  #size-cells = <0>;
  compatible = "st,m24lr04e-r";
  reg = <0x57>;

  }

Best regards,
Abd-Alrhman Masalkhi

On 02/06/2025 19:23, Abd-Alrhman Masalkhi wrote:
>>>
>>> Device Select Code Format:
>>> Bit:                b7  b6  b5  b4  b3  b2  b1  b0
>>> Value:              1   0   1   0   E2  1   1   R/W
>>>
>>> To access the EEPROM memory, E2 (b3) should be 0:
>>>
>>> Device Select Code Format:
>>> Bit:                b7  b6  b5  b4  b3  b2  b1  b0
>>> Value:              1   0   1   0   0  1   1   R/W
>>>
>>> To access the system control interface, E2 (b3) should be 1:
>>
>> So these are just two different addresses. I already commented on this.
>> This is not I2C mux but a device with two addresses.
> 
> I'd like to clarify one point before proceeding further, If I remove
> the i2c-mux usage from the binding file, as your recommendation, does
> this also imply that I should stop using the i2c-mux API in my driver
> implementation itself? and treat this as a multi-function device, or


Not using i2c-mux schema means only that you cannot use i2c-mux
properties. Maybe this implies that you cannot use i2c-mux API, feels
likely, but not really sure and I don't want to take responsibility for
that decision.

I am commenting here about bindings, not the drivers. Drivers can
implement binding in many different ways, thus discussion about bindings
is independent, except narrowing/restricting the ABI.


> Is it acceptable to keep the current driver logic as-is, while limiting
> the change to just fixing the binding and device tree representation?

Dunno, did not look at your driver. Again, I am here talking about
bindings. How you implement it in the driver is up to you. You have
however one device with two addresses, so you should most likely have
only one device node in DTS with two addresses. In certain cases, like
separate resources and re-usability, children are common, but that was
not really the case here.

Look at ti,pcm6240.yaml, ti,tas2781.yaml and few others (you can git
grep for them for reg with coma).

> 
> and if only the binding file, should i represent it as the following:
> 
>   eeprom-ctl@57 {
>   #address-cells = <1>;
>   #size-cells = <0>;

These two are obviously not used.

>   compatible = "st,m24lr04e-r";
>   reg = <0x57>;

That's only one address, you need two.


> 
>   }
> 
> Best regards,
> Abd-Alrhman Masalkhi


Best regards,
Krzysztof

Hi Krzysztof,

>> Is it acceptable to keep the current driver logic as-is, while limiting
>> the change to just fixing the binding and device tree representation?
>
> Dunno, did not look at your driver. Again, I am here talking about
> bindings. How you implement it in the driver is up to you. You have
> however one device with two addresses, so you should most likely have
> only one device node in DTS with two addresses. In certain cases, like
> separate resources and re-usability, children are common, but that was
> not really the case here.
>
> Look at ti,pcm6240.yaml, ti,tas2781.yaml and few others (you can git
> grep for them for reg with coma).

Okay, I'll rework the pathcs to use a single device node with two
addresses instead of modeling it as an I2C mux. Thanks also for the
hint about ti,pcm6240.yaml and ti,tas2781.yaml, I'll review those
to make sure the structure aligns properly.

I appreciate your guidance.

Best regards,
Abd-Alrhman Masalkhi