| Message ID | 20250314113604.1776201-8-o.rempel@pengutronix.de (mailing list archive) |
|---|---|
| State | Handled Elsewhere, archived |
| Headers | show |
| Series | Introduction of PSCR Framework and Related Components | expand |
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) > +
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?
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
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 :)
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) +
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