1. Patchew
  2. linux
  3. [PATCH v6 0/7] Introduction of PSCR Framework and Related Components
  4. View patch

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

Oleksij Rempel posted 7 patches 9 months, 1 week ago
There is a newer version of this series
[PATCH v6 7/7] Documentation: Add sysfs documentation for PSCRR reboot reason tracking
Posted by Oleksij Rempel 9 months, 1 week ago 
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>
---
 .../ABI/testing/sysfs-kernel-reboot-pscrr     | 46 +++++++++++++++++++
 1 file changed, 46 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..7cc643f89675
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-reboot-pscrr
@@ -0,0 +1,46 @@
+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)
+
+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)
+
-- 
2.39.5
Re: [PATCH v6 7/7] Documentation: Add sysfs documentation for PSCRR reboot reason tracking
Posted by Matti Vaittinen 9 months, 1 week ago 
On 14/03/2025 13:36, 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>
> ---
>   .../ABI/testing/sysfs-kernel-reboot-pscrr     | 46 +++++++++++++++++++
>   1 file changed, 46 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..7cc643f89675
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-kernel-reboot-pscrr
> @@ -0,0 +1,46 @@
> +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)

Is it possible to provide the reason (also) as string?

I believe we should fix the meaning of the numbers so the ABI is not 
changing for the users. Hence we could as well document the meaning of 
the values(?) If I read the suggestion right, we will in any case have 
predefined set of reasons in the kernel side.

Or, am I missing something?

> +
> +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)
> +
Re: [PATCH v6 7/7] Documentation: Add sysfs documentation for PSCRR reboot reason tracking
Posted by Oleksij Rempel 9 months, 1 week ago 
On Fri, Mar 14, 2025 at 03:38:55PM +0200, Matti Vaittinen wrote:
> On 14/03/2025 13:36, 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>
> > ---
> >   .../ABI/testing/sysfs-kernel-reboot-pscrr     | 46 +++++++++++++++++++
> >   1 file changed, 46 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..7cc643f89675
> > --- /dev/null
> > +++ b/Documentation/ABI/testing/sysfs-kernel-reboot-pscrr
> > @@ -0,0 +1,46 @@
> > +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)
> 
> Is it possible to provide the reason (also) as string?
> 
> I believe we should fix the meaning of the numbers so the ABI is not
> changing for the users. Hence we could as well document the meaning of the
> values(?) If I read the suggestion right, we will in any case have
> predefined set of reasons in the kernel side.
> 
> Or, am I missing something?

Yes, it is correct, the values should be fixed for user space. Should
they be documented in this documentation too?
-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |
Re: [PATCH v6 7/7] Documentation: Add sysfs documentation for PSCRR reboot reason tracking
Posted by Matti Vaittinen 9 months ago 
On 14/03/2025 16:10, Oleksij Rempel wrote:
> On Fri, Mar 14, 2025 at 03:38:55PM +0200, Matti Vaittinen wrote:
>> On 14/03/2025 13:36, 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>
>>> ---
>>>    .../ABI/testing/sysfs-kernel-reboot-pscrr     | 46 +++++++++++++++++++
>>>    1 file changed, 46 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..7cc643f89675
>>> --- /dev/null
>>> +++ b/Documentation/ABI/testing/sysfs-kernel-reboot-pscrr
>>> @@ -0,0 +1,46 @@
>>> +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)
>>
>> Is it possible to provide the reason (also) as string?
>>
>> I believe we should fix the meaning of the numbers so the ABI is not
>> changing for the users. Hence we could as well document the meaning of the
>> values(?) If I read the suggestion right, we will in any case have
>> predefined set of reasons in the kernel side.
>>
>> Or, am I missing something?
> 
> Yes, it is correct, the values should be fixed for user space. Should
> they be documented in this documentation too?

I believe it could be helpful for both the user-space users and 
potential pscrr provider driver writers. It could also set things to stone.

But, I don't have much experience on the documentation like this so 
please treat this as a suggestion - but do as you see fits best.

Yours,
	-- Matti
Re: [PATCH v6 7/7] Documentation: Add sysfs documentation for PSCRR reboot reason tracking
Posted by Oleksij Rempel 9 months ago 
On Mon, Mar 17, 2025 at 10:46:01AM +0200, Matti Vaittinen wrote:
> On 14/03/2025 16:10, Oleksij Rempel wrote:
> > On Fri, Mar 14, 2025 at 03:38:55PM +0200, Matti Vaittinen wrote:
> > > On 14/03/2025 13:36, 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>
> > > > ---
> > > >    .../ABI/testing/sysfs-kernel-reboot-pscrr     | 46 +++++++++++++++++++
> > > >    1 file changed, 46 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..7cc643f89675
> > > > --- /dev/null
> > > > +++ b/Documentation/ABI/testing/sysfs-kernel-reboot-pscrr
> > > > @@ -0,0 +1,46 @@
> > > > +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)
> > > 
> > > Is it possible to provide the reason (also) as string?
> > > 
> > > I believe we should fix the meaning of the numbers so the ABI is not
> > > changing for the users. Hence we could as well document the meaning of the
> > > values(?) If I read the suggestion right, we will in any case have
> > > predefined set of reasons in the kernel side.
> > > 
> > > Or, am I missing something?
> > 
> > Yes, it is correct, the values should be fixed for user space. Should
> > they be documented in this documentation too?
> 
> I believe it could be helpful for both the user-space users and potential
> pscrr provider driver writers. It could also set things to stone.

Ok, i'll send updated patch set. I'll be happy to have your Reviewed-by
:)

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.