Re: [PATCH v7 3/3] ABI: sysfs: add documentation for ST M24LR EEPROM and control interface

[Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>]

Hi all,

Gentle ping.

On Thu, Jul 17, 2025 at 06:39 +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,
> total sectors, and SSS entries) and EEPROM access via the nvmem subsystem.
>
> Signed-off-by: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
> ---
> Changes in v7:
>  - No changes
>  - Link to v6: https://lore.kernel.org/all/20250706105311.395162-4-abd.masalkhi@gmail.com/
>
> Changes in v6:
>  - No changes
>  - Link to v5: https://lore.kernel.org/all/20250704123914.11216-4-abd.masalkhi@gmail.com/
>
> Changes in v5:
>  - Fix dates and update targeted kernel version.
>  - Link to v4: https://lore.kernel.org/lkml/20250608182714.3359441-4-abd.masalkhi@gmail.com/
>
> Changes in v4:
>  - Replaced 'sss<N>' entries with a single binary 'sss' attribute
>  - Added 'total_sectors' attribute to report the number of valid SSS bytes
>  - removed 'mem_size' attribute
>  - Fix dates and update targeted kernel version.
>  - Link to v3: https://lore.kernel.org/lkml/20250606120631.3140054-4-abd.masalkhi@gmail.com/
>
> Changes in v3:
>  - Updated sysfs entry paths to use <busnum>-<primary-addr> to reflect the
>    control address.
>  - Link to v2: https://lore.kernel.org/lkml/20250601153022.2027919-4-abd.masalkhi@gmail.com/
>
> Changes in v2:
>  - Added initial sysfs ABI documentation.
> ---
>  .../ABI/testing/sysfs-bus-i2c-devices-m24lr   | 100 ++++++++++++++++++
>  1 file changed, 100 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..7c51ce8d38ba
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr
> @@ -0,0 +1,100 @@
> +What:           /sys/bus/i2c/devices/<busnum>-<primary-addr>/unlock
> +Date:           2025-07-04
> +KernelVersion:  6.17
> +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-07-04
> +KernelVersion:  6.17
> +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-07-04
> +KernelVersion:  6.17
> +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>/total_sectors
> +Date:           2025-07-04
> +KernelVersion:  6.17
> +Contact:        Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
> +Description:
> +                Read-only attribute that exposes the total number of EEPROM
> +                sectors available in the M24LR chip.
> +
> +                Format:
> +                  - 1 to 2 hex digits (e.g. "F")
> +                  - No "0x" prefix
> +                  - 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
> +Date:           2025-07-04
> +KernelVersion:  6.17
> +Contact:        Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
> +Description:
> +                Read/write binary attribute representing the Sector Security
> +                Status (SSS) bytes for all EEPROM sectors in STMicroelectronics
> +                M24LR chips.
> +
> +                Each EEPROM sector has one SSS byte, which controls I2C and
> +                RF access through protection bits and optional password
> +                authentication.
> +
> +                Format:
> +                  - The file contains one byte per EEPROM sector
> +                  - Byte at offset N corresponds to sector N
> +                  - Binary access only; use tools like dd, Python, or C that
> +                    support byte-level I/O and offset control.
> +
> +                Notes:
> +                  - The number of valid bytes in this file is equal to the
> +                    value exposed by 'total_sectors' file
> +                  - Write access requires prior password authentication in
> +                    I2C mode
> +                  - Refer to the M24LR datasheet for full SSS bit layout
> -- 
> 2.43.0
>

-- 
Best Regards,
Abd-Alrhman