[PATCH v3 8/8] firmware: smccc: lfa: add sysfs ABI documentation

[Andre Przywara]

Document the sysfs attribute files as exported by the LFA driver.

Signed-off-by: Andre Przywara <andre.przywara at arm.com>
---
 Documentation/ABI/testing/sysfs-firmware-lfa | 106 +++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-firmware-lfa

diff --git a/Documentation/ABI/testing/sysfs-firmware-lfa b/Documentation/ABI/testing/sysfs-firmware-lfa
new file mode 100644
index 000000000000..afd349af9cf1
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-lfa
@@ -0,0 +1,106 @@
+What:		/sys/firmware/lfa
+Date:		May 2026
+Contact:	Andre Przywara <andre.przywara at arm.com>
+Description:
+		The Arm Live Firmware Activation (LFA) spec describes an
+		interface between platform firmware (an agent) and any user
+		on the non-secure side (like the Linux kernel) to activate
+		pending firmware updates at runtime. The actual firmware
+		update would be provided independently (out-of-band, or
+		via any existing explicit firmware update mechanisms), then,
+		if supported, can be activated immediately, without rebooting
+		the system.
+		This directory contains one directory for each of the LFA
+		capable firmware images supported by the agent, identified by
+		its GUID. Within each directory, the same set of sysfs files
+		provides access to the properties and actions for this
+		particular firmware image.
+
+What:		/sys/firmware/lfa/<GUID>/activate
+Date:		May 2026
+Contact:	Andre Przywara <andre.przywara at arm.com>
+Description:
+		(WO) Write a boolean 'true' value to trigger the
+		activation of that firmware component. An update must be
+		pending for this to be successful.
+
+What:		/sys/firmware/lfa/<GUID>/activation_capable
+Date:		May 2026
+Contact:	Andre Przywara <andre.przywara at arm.com>
+Description:
+		(RO) A boolean value to show whether this firmware image is
+		capable of being activated.
+
+What:		/sys/firmware/lfa/<GUID>/auto_activate
+Date:		May 2026
+Contact:	Andre Przywara <andre.przywara at arm.com>
+Description:
+		(RW) Write a boolean 'true' value to allow a firmware image
+		to be automatically activated once a new firmware update
+		becomes available ("pending"). This depends on a working
+		notification scheme, for instance via an ACPI notification
+		or an interrupt to notify the kernel.
+
+What:		/sys/firmware/lfa/<GUID>/cancel
+Date:		May 2026
+Contact:	Andre Przywara <andre.przywara at arm.com>
+Description:
+		(WO) Write a boolean 'true' value to cancel a recently
+		triggered activation, if that has not finished yet.
+
+What:		/sys/firmware/lfa/<GUID>/cpu_rendezvous
+Date:		May 2026
+Contact:	Andre Przywara <andre.przywara at arm.com>
+Description:
+		(RO) A boolean value to show whether this image requires
+		a CPU rendezvous in firmware to be activated. If true, this
+		means all CPUs will enter the firmware during the activation
+		process, so will not be able to execute kernel code or
+		handle interrupts for a brief moment.
+
+What:		/sys/firmware/lfa/<GUID>/current_version
+Date:		May 2026
+Contact:	Andre Przywara <andre.przywara at arm.com>
+Description:
+		(RO) Shows the currently running version of that firmware
+		image, as reported by the agent (if supported).
+
+What:		/sys/firmware/lfa/<GUID>/force_cpu_rendezvous
+Date:		May 2026
+Contact:	Andre Przywara <andre.przywara at arm.com>
+Description:
+		(RW) Write a boolean 'true' value to force whether the kernel
+		will perform a CPU rendezvous during activation. This has no
+		effect if the firmware already *requires* a CPU rendezvous.
+		Firmware images might provide services to the kernel, at which
+		point is might be unsafe to continue running the kernel while
+		the activation is performed. Sending all CPUs into firmware
+		provides the safest option for the kernel. If you know for
+		certain that there are no services provides by that component
+		or the firmware component can handle requests during the
+		activation, you can write a 0 in here to avoid the brief
+		kernel downtime.
+
+What:		/sys/firmware/lfa/<GUID>/may_reset_cpu
+Date:		May 2026
+Contact:	Andre Przywara <andre.przywara at arm.com>
+Description:
+		(RO) A boolean value to show whether this firmware image
+		requires a CPU reset during the activation.
+		Currently this type of firmware image is not supported by
+		the kernel driver, as we cannot handle a CPU reset yet.
+
+What:		/sys/firmware/lfa/<GUID>/name
+Date:		May 2026
+Contact:	Andre Przywara <andre.przywara at arm.com>
+Description:
+		(RO) Shows a human readable name for that firmware image, if
+		known. Depends on the kernel driver knowing this particular
+		GUID, via a built-in list.
+
+What:		/sys/firmware/lfa/<GUID>/pending_version
+Date:		May 2026
+Contact:	Andre Przywara <andre.przywara at arm.com>
+Description:
+		(RO) Shows the version number of a pending firmware update
+		image, as reported by the agent (if supported).
-- 
2.43.0