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

[Greg KH <gregkh@linuxfoundation.org>]

On 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