[PATCH v7 7/7] Documentation: Add sysfs documentation for PSCRR reboot reason tracking

[Oleksij Rempel]

Add documentation for the Power State Change Reason Recorder (PSCRR)
sysfs interface, which allows tracking of system shutdown and reboot
reasons. The documentation provides details on available sysfs entries
under `/sys/kernel/pscrr/`, explaining their functionality, example usage,
and how they interact with different backend storage options (e.g., NVMEM).

Signed-off-by: Oleksij Rempel <o.rempel@xxxxxxxxxxxxxx>
---
changes v7:
- document expected values
---
 .../ABI/testing/sysfs-kernel-reboot-pscrr     | 79 +++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-kernel-reboot-pscrr

diff --git a/Documentation/ABI/testing/sysfs-kernel-reboot-pscrr b/Documentation/ABI/testing/sysfs-kernel-reboot-pscrr
new file mode 100644
index 000000000000..9aa3df8f2fc7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-reboot-pscrr
@@ -0,0 +1,79 @@
+What:		/sys/kernel/pscrr/reason
+Date:		April 2025
+KernelVersion:  6.15
+Contact:	Oleksij Rempel <o.rempel@xxxxxxxxxxxxxx>
+Description:
+		This file provides access to the last recorded power state
+		change reason. The storage backend is configurable and, if
+		supported, the reason may be stored persistently in an
+		NVMEM cell or another backend.
+
+		Reading this file returns an integer representing the last
+		recorded shutdown or reboot cause.
+
+		Writing an integer value to this file sets the reason to be
+		stored and recorded for system analysis.
+
+		Example usage (values are for illustration and may not reflect
+		actual reasons used in a given system):
+		  Read:
+			$ cat /sys/kernel/pscrr/reason
+			3   # (Example: Power loss event, may differ per system)
+
+		  Write:
+			$ echo 5 > /sys/kernel/pscrr/reason
+			# Sets the reason to 5 (Example: User-triggered reboot,
+			# this may not be a real value in your system)
+
+		Values are defined in:
+		  - `include/linux/reboot.h` (enum psc_reason)
+
+		Supported Values:
+		Defined in `include/linux/reboot.h` (enum psc_reason):
+
+		+-------+---------------------------+--------------------------+
+		| Value | Symbol                    | Description              |
+		+-------+---------------------------+--------------------------+
+		| 0     | PSCR_UNKNOWN              | Unknown or unspecified   |
+		|       |                           | power state change reason|
+		+-------+---------------------------+--------------------------+
+		| 1     | PSCR_UNDER_VOLTAGE        | Supply voltage drop below|
+		|       |                           | safe threshold.          |
+		+-------+---------------------------+--------------------------+
+		| 2     | PSCR_OVER_CURRENT         | Excessive current draw,  |
+		|       |                           | potential short circuit. |
+		+-------+---------------------------+--------------------------+
+		| 3     | PSCR_REGULATOR_FAILURE    | Failure in voltage       |
+		|       |                           | regulator, preventing    |
+		|       |                           | stable power delivery.   |
+		+-------+---------------------------+--------------------------+
+		| 4     | PSCR_OVER_TEMPERATURE     | Unsafe system temperature|
+		|       |                           | detected by sensors.     |
+		+-------+---------------------------+--------------------------+
+		| 5     | PSCR_EC_PANIC             | Shutdown/reboot triggered|
+		|       |                           | by Embedded Controller   |
+		|       |                           | (EC) panic.              |
+		+-------+---------------------------+--------------------------+
+
+		(Note: The actual reason codes used on a specific system depend
+		on hardware capabilities and configuration.)
+
+What:		/sys/kernel/pscrr/reason_boot
+Date:		April 2025
+KernelVersion:  6.15
+Contact:	Oleksij Rempel <o.rempel@xxxxxxxxxxxxxx>
+Description:
+		This file provides the last recorded power state change reason
+		from before the current system boot. If a supported backend
+		(e.g., NVMEM) is configured, this value is retained across
+		reboots.
+
+		Example usage (values are for illustration and may not reflect
+		actual reasons used in a given system):
+		  Read:
+			$ cat /sys/kernel/pscrr/reason_boot
+			2   # (Example: Over-temperature shutdown, may differ per system)
+
+		Supported Values:
+		Same as `/sys/kernel/pscrr/reason` (see above).
+
-- 
2.39.5