Add sysfs ABI documentation for the STMicroelectronics M24LR device,
covering both the control interface (e.g., unlock, password update, UID,
memory size, and SSS entries) and EEPROM access via the nvmem subsystem.
Signed-off-by: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
---
Changes in v3:
- Updated sysfs entry paths to use <busnum>-<primary-addr> to reflect the
control address.
Changes in v2:
- Added initial sysfs ABI documentation.
---
.../ABI/testing/sysfs-bus-i2c-devices-m24lr | 96 +++++++++++++++++++
1 file changed, 96 insertions(+)
create mode 100644 Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr b/Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr
new file mode 100644
index 000000000000..53b6fe39162c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr
@@ -0,0 +1,96 @@
+What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/unlock
+Date: 2025-05-31
+KernelVersion: 6.16
+Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
+Description:
+ Write-only attribute used to present a password and unlock
+ access to protected areas of the M24LR chip, including
+ configuration registers such as the Sector Security Status
+ (SSS) bytes. A valid password must be written to enable write
+ access to these regions via the I2C interface.
+
+ Format:
+ - Hexadecimal string representing a 32-bit (4-byte) password
+ - Accepts 1 to 8 hex digits (e.g., "c", "1F", "a1b2c3d4")
+ - No "0x" prefix, whitespace, or trailing newline
+ - Case-insensitive
+
+ Behavior:
+ - If the password matches the internal stored value,
+ access to protected memory/configuration is granted
+ - If the password does not match the internally stored value,
+ it will fail silently
+
+What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/new_pass
+Date: 2025-05-31
+KernelVersion: 6.16
+Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
+Description:
+ Write-only attribute used to update the password required to
+ unlock the M24LR chip.
+
+ Format:
+ - Hexadecimal string representing a new 32-bit password
+ - Accepts 1 to 8 hex digits (e.g., "1A", "ffff", "c0ffee00")
+ - No "0x" prefix, whitespace, or trailing newline
+ - Case-insensitive
+
+ Behavior:
+ - Overwrites the current password stored in the I2C password
+ register
+ - Requires the device to be unlocked before changing the
+ password
+ - If the device is locked, the write silently fails
+
+What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/uid
+Date: 2025-05-31
+KernelVersion: 6.16
+Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
+Description:
+ Read-only attribute that exposes the 8-byte unique identifier
+ programmed into the M24LR chip at the factory.
+
+ Format:
+ - Lowercase hexadecimal string representing a 64-bit value
+ - 1 to 16 hex digits (e.g., "e00204f12345678")
+ - No "0x" prefix
+ - Includes a trailing newline
+
+What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/mem_size
+Date: 2025-05-31
+KernelVersion: 6.16
+Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
+Description:
+ Read-only attribute that exposes the internal memory size code
+ of the M24LR device, as stored in the system register area.
+
+ Format:
+ - Unsigned 8-bit integer
+ - Includes a trailing newline
+
+ Notes:
+ - Value is encoded by the chip and corresponds to the EEPROM
+ size (e.g., 3 = 4 kbit for M24LR04E-R)
+
+What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/sss<N>
+Date: 2025-05-31
+KernelVersion: 6.16
+Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
+Description:
+ Read/write attribute representing the Sector Security Status
+ (SSS) byte for EEPROM sector <N> in the M24LR chips. Each sector
+ has one SSS byte, which defines I2c and RF access control via a
+ combination of protection and password settings.
+
+ Format:
+ - Read: returns a 8-bit hexadecimal value followed by a
+ newline
+ - Write: requires exactly one or two hexadecimal digits
+ - No "0x" prefix, whitespace, or trailing newline
+ - Case-insensitive
+
+ Notes:
+ - Refer to the M24LR chip datasheet for full bit definitions
+ and usage
+ - Write access requires prior password authentication in I2C
+ mode
--
2.43.0On Fri, Jun 06, 2025 at 12:06:31PM +0000, Abd-Alrhman Masalkhi wrote: > Add sysfs ABI documentation for the STMicroelectronics M24LR device, > covering both the control interface (e.g., unlock, password update, UID, > memory size, and SSS entries) and EEPROM access via the nvmem subsystem. > > Signed-off-by: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com> > --- > Changes in v3: > - Updated sysfs entry paths to use <busnum>-<primary-addr> to reflect the > control address. > > Changes in v2: > - Added initial sysfs ABI documentation. > --- > .../ABI/testing/sysfs-bus-i2c-devices-m24lr | 96 +++++++++++++++++++ > 1 file changed, 96 insertions(+) > create mode 100644 Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr > > diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr b/Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr > new file mode 100644 > index 000000000000..53b6fe39162c > --- /dev/null > +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr > @@ -0,0 +1,96 @@ > +What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/unlock > +Date: 2025-05-31 It's later than this. > +KernelVersion: 6.16 This will not be showing up in 6.16, sorry, it's too late for that. > +Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com> > +Description: > + Write-only attribute used to present a password and unlock > + access to protected areas of the M24LR chip, including > + configuration registers such as the Sector Security Status > + (SSS) bytes. A valid password must be written to enable write > + access to these regions via the I2C interface. > + > + Format: > + - Hexadecimal string representing a 32-bit (4-byte) password > + - Accepts 1 to 8 hex digits (e.g., "c", "1F", "a1b2c3d4") > + - No "0x" prefix, whitespace, or trailing newline > + - Case-insensitive > + > + Behavior: > + - If the password matches the internal stored value, > + access to protected memory/configuration is granted > + - If the password does not match the internally stored value, > + it will fail silently Why is the kernel in the business of adding passwords to devices? That feels wrong, and a way to just flood the device with a "try all the values" attempt if needed. > +What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/sss<N> > +Date: 2025-05-31 > +KernelVersion: 6.16 > +Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com> > +Description: > + Read/write attribute representing the Sector Security Status > + (SSS) byte for EEPROM sector <N> in the M24LR chips. Each sector > + has one SSS byte, which defines I2c and RF access control via a > + combination of protection and password settings. > + > + Format: > + - Read: returns a 8-bit hexadecimal value followed by a > + newline > + - Write: requires exactly one or two hexadecimal digits > + - No "0x" prefix, whitespace, or trailing newline > + - Case-insensitive > + > + Notes: > + - Refer to the M24LR chip datasheet for full bit definitions > + and usage > + - Write access requires prior password authentication in I2C > + mode How "deep" does this sysfs tree get here? This feels like the wrong api for read/write to the device, just do it with a single binary file if you really want a "passthrough" way to get to the hardware. thanks, greg k-h
Hi greg, Thanks for the feedback. >> + Behavior: >> + - If the password matches the internal stored value, >> + access to protected memory/configuration is granted >> + - If the password does not match the internally stored value, >> + it will fail silently > > Why is the kernel in the business of adding passwords to devices? That > feels wrong, and a way to just flood the device with a "try all the > values" attempt if needed. You're absolutely right, implementing password-based access in kernel space isn't ideal. However, this behavior is defined by the hardware itself. The M24LR chips require the user to "unlock" the device by writing a password before certain registers become writable (such as the Sector Security Status registors) and unfortunately, the chip does not provide any status or feedback to indicate whether the unlock was successful, which limits what the driver can safely report or validate. >> +What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/sss<N> >> +Date: 2025-05-31 >> +KernelVersion: 6.16 >> +Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com> >> +Description: >> + Read/write attribute representing the Sector Security Status >> + (SSS) byte for EEPROM sector <N> in the M24LR chips. Each sector >> + has one SSS byte, which defines I2c and RF access control via a >> + combination of protection and password settings. >> + Format: >> + - Read: returns a 8-bit hexadecimal value followed by a >> + newline >> + - Write: requires exactly one or two hexadecimal digits >> + - No "0x" prefix, whitespace, or trailing newline >> + - Case-insensitive >> + >> + Notes: >> + - Refer to the M24LR chip datasheet for full bit definitions >> + and usage >> + - Write access requires prior password authentication in I2C >> + mode > > How "deep" does this sysfs tree get here? This feels like the wrong api > for read/write to the device, just do it with a single binary file if > you really want a "passthrough" way to get to the hardware. The depth of the sysfs tree depends on the M24LR variant. For example, the M24LR04E-R has 4 sectors, resulting in 4 entries: sss0 through sss3. I understand the concern about exposing multiple sysfs entries. The reason for this design is that each sector has its own SSS byte, and separating them helps reflect the per-sector nature of the access control. That said, I'm open to refactoring this to expose the SSS area via a single binary file if that's more in line with expected kernel interfaces. Best regards, Abd-Alrhman Masalkhi
On Fri, Jun 06, 2025 at 02:46:57PM +0000, Abd-Alrhman Masalkhi wrote: > Hi greg, > > Thanks for the feedback. > > >> + Behavior: > >> + - If the password matches the internal stored value, > >> + access to protected memory/configuration is granted > >> + - If the password does not match the internally stored value, > >> + it will fail silently > > > > Why is the kernel in the business of adding passwords to devices? That > > feels wrong, and a way to just flood the device with a "try all the > > values" attempt if needed. > > You're absolutely right, implementing password-based access in kernel > space isn't ideal. However, this behavior is defined by the hardware > itself. The M24LR chips require the user to "unlock" the device by writing > a password before certain registers become writable (such as the Sector > Security Status registors) and unfortunately, the chip does not provide > any status or feedback to indicate whether the unlock was successful, > which limits what the driver can safely report or validate. > > >> +What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/sss<N> > >> +Date: 2025-05-31 > >> +KernelVersion: 6.16 > >> +Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com> > >> +Description: > >> + Read/write attribute representing the Sector Security Status > >> + (SSS) byte for EEPROM sector <N> in the M24LR chips. Each sector > >> + has one SSS byte, which defines I2c and RF access control via a > >> + combination of protection and password settings. > >> + Format: > >> + - Read: returns a 8-bit hexadecimal value followed by a > >> + newline > >> + - Write: requires exactly one or two hexadecimal digits > >> + - No "0x" prefix, whitespace, or trailing newline > >> + - Case-insensitive > >> + > >> + Notes: > >> + - Refer to the M24LR chip datasheet for full bit definitions > >> + and usage > >> + - Write access requires prior password authentication in I2C > >> + mode > > > > How "deep" does this sysfs tree get here? This feels like the wrong api > > for read/write to the device, just do it with a single binary file if > > you really want a "passthrough" way to get to the hardware. > > The depth of the sysfs tree depends on the M24LR variant. For example, > the M24LR04E-R has 4 sectors, resulting in 4 entries: sss0 through sss3. > > I understand the concern about exposing multiple sysfs entries. The > reason for this design is that each sector has its own SSS byte, and > separating them helps reflect the per-sector nature of the access > control. That said, I'm open to refactoring this to expose the SSS > area via a single binary file if that's more in line with expected > kernel interfaces. Who and what is going to be talking to this device through this interface? Is this unique and special to ONLY this one chip/device or does it fit in with all other types of this device (i.e. eeproms)? You can't create a userspace api without actually having a user at all, so if there is no userspace code using this, why even have this? thanks, greg k-h
Hi Greg, > > >> +What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/sss<N> > > >> +Date: 2025-05-31 > > >> +KernelVersion: 6.16 > > >> +Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com> > > >> +Description: > > >> + Read/write attribute representing the Sector Security Status > > >> + (SSS) byte for EEPROM sector <N> in the M24LR chips. Each sector > > >> + has one SSS byte, which defines I2c and RF access control via a > > >> + combination of protection and password settings. > > >> + Format: > > >> + - Read: returns a 8-bit hexadecimal value followed by a > > >> + newline > > >> + - Write: requires exactly one or two hexadecimal digits > > >> + - No "0x" prefix, whitespace, or trailing newline > > >> + - Case-insensitive > > >> + > > >> + Notes: > > >> + - Refer to the M24LR chip datasheet for full bit definitions > > >> + and usage > > >> + - Write access requires prior password authentication in I2C > > >> + mode > > > > > > How "deep" does this sysfs tree get here? This feels like the wrong api > > > for read/write to the device, just do it with a single binary file if > > > you really want a "passthrough" way to get to the hardware. > > > > The depth of the sysfs tree depends on the M24LR variant. For example, > > the M24LR04E-R has 4 sectors, resulting in 4 entries: sss0 through sss3. > > > > I understand the concern about exposing multiple sysfs entries. The > > reason for this design is that each sector has its own SSS byte, and > > separating them helps reflect the per-sector nature of the access > > control. That said, I'm open to refactoring this to expose the SSS > > area via a single binary file if that's more in line with expected > > kernel interfaces. > > Who and what is going to be talking to this device through this > interface? Is this unique and special to ONLY this one chip/device or > does it fit in with all other types of this device (i.e. eeproms)? You > can't create a userspace api without actually having a user at all, so > if there is no userspace code using this, why even have this? A userspace application specific to the M24LR series is intended to interface with this driver. The M24LR devices support dual access to the EEPROM: via I2C and over RFID. The purpose of exposing the Sector Security Status (SSS) registers to userspace is to provide dynamic control over when and how the EEPROM is accessible to an RFID reader. This allows userspace to decide whether to permit or deny EEPROM reads/writes via RFID, or to configure protection for specific memory sectors. The SSS registers define per-sector read/write permissions and password protection, directly determining how external RFID readers interact with the tag. By exposing this configuration through sysfs, userspace software can modify RFID access behavior at runtime for example, to enable secure provisioning workflows, implement time-based access, or prevent unauthorized access after setup. Given that this is a per-sector control mechanism unique to the M24LR series, would exposing the entire SSS region via a single binary sysfs file be considered more appropriate than individual attributes per sector? Best regards, Abd-Alrhman Masalkhi
Hi Greg, > > >> +What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/sss<N> > > >> +Date: 2025-05-31 > > >> +KernelVersion: 6.16 > > >> +Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com> > > >> +Description: > > >> + Read/write attribute representing the Sector Security Status > > >> + (SSS) byte for EEPROM sector <N> in the M24LR chips. Each sector > > >> + has one SSS byte, which defines I2c and RF access control via a > > >> + combination of protection and password settings. > > >> + Format: > > >> + - Read: returns a 8-bit hexadecimal value followed by a > > >> + newline > > >> + - Write: requires exactly one or two hexadecimal digits > > >> + - No "0x" prefix, whitespace, or trailing newline > > >> + - Case-insensitive > > >> + > > >> + Notes: > > >> + - Refer to the M24LR chip datasheet for full bit definitions > > >> + and usage > > >> + - Write access requires prior password authentication in I2C > > >> + mode > > > > > > How "deep" does this sysfs tree get here? This feels like the wrong api > > > for read/write to the device, just do it with a single binary file if > > > you really want a "passthrough" way to get to the hardware. > > > > The depth of the sysfs tree depends on the M24LR variant. For example, > > the M24LR04E-R has 4 sectors, resulting in 4 entries: sss0 through sss3. > > > > I understand the concern about exposing multiple sysfs entries. The > > reason for this design is that each sector has its own SSS byte, and > > separating them helps reflect the per-sector nature of the access > > control. That said, I'm open to refactoring this to expose the SSS > > area via a single binary file if that's more in line with expected > > kernel interfaces. > > Who and what is going to be talking to this device through this > interface? Is this unique and special to ONLY this one chip/device or > does it fit in with all other types of this device (i.e. eeproms)? You > can't create a userspace api without actually having a user at all, so > if there is no userspace code using this, why even have this? A userspace application specific to the M24LR series is intended to interface with this driver. The M24LR devices support dual access to the EEPROM: via I2C and over RFID. The purpose of exposing the Sector Security Status (SSS) registers to userspace is to provide dynamic control over when and how the EEPROM is accessible to an RFID reader. This allows userspace to decide whether to permit or deny EEPROM reads/writes via RFID, or to configure protection for specific memory sectors. The SSS registers define per-sector read/write permissions and password protection, directly determining how external RFID readers interact with the tag. By exposing this configuration through sysfs, userspace software can modify RFID access behavior at runtime for example, to enable secure provisioning workflows, implement time-based access, or prevent unauthorized access after setup. Given that this is a per-sector control mechanism unique to the M24LR series, would exposing the entire SSS region via a single binary sysfs file be considered more appropriate than individual attributes per sector? Best regards, Abd-Alrhman Masalkhi
© 2016 - 2025 Red Hat, Inc.