diff mbox series

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

Message ID 20250318094716.3053546-8-o.rempel@pengutronix.de (mailing list archive)
State Handled Elsewhere, archived
Headers show
Series Introduction of PSCR Framework and Related Components | expand

Commit Message

Oleksij Rempel March 18, 2025, 9:47 a.m. UTC 
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@pengutronix.de>
---
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

Comments

Matti Vaittinen March 18, 2025, 11:17 a.m. UTC | #1 
On 18/03/2025 11:47, Oleksij Rempel wrote:
> 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@pengutronix.de>
> ---
> 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@pengutronix.de>
> +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)

nit:
Now that the 'number' <=> 'reason' relation is fixed, we might drop the 
"may differ" etc. Perhaps just:

		Example usage:
		  Read:
			$ cat /sys/kernel/pscrr/reason
			3   # (Example: Power loss event)

		  Write:
			$ echo 5 > /sys/kernel/pscrr/reason
			# Sets the reason to 5 (Example: User-triggered reboot)

Maybe adding a note that not all values are supported on all systems.


> +
> +		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.)

I like this. Nice and clean.

A side note which you can consider if you feel like:
This, as far as I understand, will also make the ABI out of this. So, 
perhaps there should be comments in enum psc_reason and the defines in 
Defined in 'include/linux/reboot.h' that they are part of an ABI, and 
must not be changed? I suppose user-space tools may get unhappy if these 
values change between the kernel versions.

> +
> +What:		/sys/kernel/pscrr/reason_boot
> +Date:		April 2025
> +KernelVersion:  6.15
> +Contact:	Oleksij Rempel <o.rempel@pengutronix.de>
> +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).
> +

All in all, this looks very good to me.

Reviewed-by: Matti Vaittinen <mazziesaccount@gmail.com>

Yours,
	-- Matti
Oleksij Rempel March 18, 2025, 11:24 a.m. UTC | #2 
On Tue, Mar 18, 2025 at 01:17:38PM +0200, Matti Vaittinen wrote:
> On 18/03/2025 11:47, Oleksij Rempel wrote:
> > 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@pengutronix.de>
> > ---
> > 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@pengutronix.de>
> > +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)
> 
> nit:
> Now that the 'number' <=> 'reason' relation is fixed, we might drop the "may
> differ" etc. Perhaps just:
> 
> 		Example usage:
> 		  Read:
> 			$ cat /sys/kernel/pscrr/reason
> 			3   # (Example: Power loss event)
> 
> 		  Write:
> 			$ echo 5 > /sys/kernel/pscrr/reason
> 			# Sets the reason to 5 (Example: User-triggered reboot)

ack

> Maybe adding a note that not all values are supported on all systems.

Yes, there is after supported values.

> 
> > +
> > +		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.)
> 
> I like this. Nice and clean.
> 
> A side note which you can consider if you feel like:
> This, as far as I understand, will also make the ABI out of this. So,
> perhaps there should be comments in enum psc_reason and the defines in
> Defined in 'include/linux/reboot.h' that they are part of an ABI, and must
> not be changed? I suppose user-space tools may get unhappy if these values
> change between the kernel versions.

Yes, there is already: "Importantly, the order of these values **must
remain stable**, as bootloaders, user-space tools, or post-mortem
investigation utilities may rely on their numerical representation for
consistent behavior." :)

> > +
> > +What:		/sys/kernel/pscrr/reason_boot
> > +Date:		April 2025
> > +KernelVersion:  6.15
> > +Contact:	Oleksij Rempel <o.rempel@pengutronix.de>
> > +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).
> > +
> 
> All in all, this looks very good to me.
> 
> Reviewed-by: Matti Vaittinen <mazziesaccount@gmail.com>
> 
> Yours,
> 	-- Matti
> 
>
Matti Vaittinen March 18, 2025, 11:27 a.m. UTC | #3 
On 18/03/2025 13:24, Oleksij Rempel wrote:
> On Tue, Mar 18, 2025 at 01:17:38PM +0200, Matti Vaittinen wrote:
>> On 18/03/2025 11:47, Oleksij Rempel wrote:

>> A side note which you can consider if you feel like:
>> This, as far as I understand, will also make the ABI out of this. So,
>> perhaps there should be comments in enum psc_reason and the defines in
>> Defined in 'include/linux/reboot.h' that they are part of an ABI, and must
>> not be changed? I suppose user-space tools may get unhappy if these values
>> change between the kernel versions.
> 
> Yes, there is already: "Importantly, the order of these values **must
> remain stable**, as bootloaders, user-space tools, or post-mortem
> investigation utilities may rely on their numerical representation for
> consistent behavior." :)

Just noticed this. My bad, I did reviewing in wrong order :)

>>
>> Reviewed-by: Matti Vaittinen <mazziesaccount@gmail.com>
>>
>> Yours,
>> 	-- Matti
>>
>>
>
diff mbox series

Patch

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@pengutronix.de>
+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@pengutronix.de>
+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).
+