power: reset: Introduce Power State Change Reasons Recording (PSCRR) framework

Documentation/ABI/testing/sysfs-kernel-pscrr

@@ -0,0 +1,108 @@
+What:		/sys/kernel/pscrr/
+Date:		July 2026
+KernelVersion:	7.2
+Contact:	Oleksij Rempel <o.rempel@pengutronix.de>
+Description:
+		Root directory of the Power State Change Reason Recording
+		(PSCRR) framework. It contains one subdirectory per registered
+		reason provider, named providerN (N is an arbitrary, stable
+		index assigned at registration).
+
+		A provider is either a hardware reason source (a PMIC, SoC
+		reset controller or watchdog exposing a reset cause) or a
+		recorder that persists the current reason across a power cycle
+		(e.g. an NVMEM or RTC scratch cell). The set of reasons is
+		deliberately not collapsed to a single "winning" cause, since
+		resets are often multi-causal.
+
+What:		/sys/kernel/pscrr/providerN/name
+Date:		July 2026
+KernelVersion:	7.2
+Contact:	Oleksij Rempel <o.rempel@pengutronix.de>
+Description:
+		(RO) Human-readable label identifying the provider, e.g.
+		"pca9450" or "nvmem".
+
+What:		/sys/kernel/pscrr/providerN/device
+Date:		July 2026
+KernelVersion:	7.2
+Contact:	Oleksij Rempel <o.rempel@pengutronix.de>
+Description:
+		Symbolic link to the backing struct device of the provider.
+		Present only for providers that are bound to a device.
+
+What:		/sys/kernel/pscrr/providerN/reason
+Date:		July 2026
+KernelVersion:	7.2
+Contact:	Oleksij Rempel <o.rempel@pengutronix.de>
+Description:
+		The set of power state change reasons observed by this
+		provider, as a space-separated list of reason tokens (an
+		empty line means no reason is recorded).
+
+		The attribute is writable only for providers that can record
+		a reason; for a pure hardware source it is read-only. A write
+		records one reason and accepts either a reason token or its
+		decimal index. The tokens and their stable numeric values are:
+
+		==  =================  ============================================
+		0   unknown            Unknown or unspecified reason
+		1   under-voltage      Supply voltage dropped below a safe level
+		2   over-current       Excessive current draw / possible short
+		3   regulator-failure  Voltage regulator failure
+		4   over-temperature   Unsafe temperature detected
+		5   ec-panic           Embedded controller (EC) panic
+		6   power-on           Regular cold power-on
+		7   watchdog           Watchdog timeout
+		8   software           Software-initiated reset or reboot
+		9   external           External reset input asserted
+		10  rtc                RTC-triggered wake-up or power-on
+		11  reset-button       User reset button
+		12  cpu-clock-failure  CPU clock failure
+		13  crystal-failure    Crystal oscillator failure
+		==  =================  ============================================
+
+		The numeric order is stable ABI: new reasons are only ever
+		appended. A provider may support only a subset of these; see
+		"supported_reasons".
+
+What:		/sys/kernel/pscrr/providerN/caps
+Date:		July 2026
+KernelVersion:	7.2
+Contact:	Oleksij Rempel <o.rempel@pengutronix.de>
+Description:
+		(RO) Space-separated list of the provider's non-default
+		capabilities. Being readable and storing a single reason are
+		the defaults and are not listed. Currently defined:
+
+		========  ==============================================
+		writable  the provider can record a reason (see "reason"
+		          and "record_policy")
+		========  ==============================================
+
+		An empty line therefore denotes a read-only, single-slot
+		provider.
+
+What:		/sys/kernel/pscrr/providerN/supported_reasons
+Date:		July 2026
+KernelVersion:	7.2
+Contact:	Oleksij Rempel <o.rempel@pengutronix.de>
+Description:
+		(RO) Space-separated list of the reason tokens (see "reason")
+		this provider is able to report or record. A provider that
+		supports every reason lists them all.
+
+What:		/sys/kernel/pscrr/providerN/record_policy
+Date:		July 2026
+KernelVersion:	7.2
+Contact:	Oleksij Rempel <o.rempel@pengutronix.de>
+Description:
+		(RW) Policy used when more than one reason is recorded during a
+		single power cycle. Present only for providers that can record
+		(see "caps"). Valid values are:
+
+		=====  =================================================
+		first  keep the first reason recorded this cycle (the
+		       root cause); this is the default
+		last   overwrite with the most recently recorded reason
+		=====  =================================================

Documentation/devicetree/bindings/nvmem/layouts/nvmem-layout.yaml

@@ -21,6 +21,7 @@ oneOf:
   - $ref: fixed-layout.yaml
   - $ref: kontron,sl28-vpd.yaml
   - $ref: onie,tlv-layout.yaml
+  - $ref: pscrr-nvmem.yaml
   - $ref: u-boot,env.yaml
 
 properties:

Documentation/devicetree/bindings/nvmem/layouts/pscrr-nvmem.yaml

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/nvmem/layouts/pscrr-nvmem.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVMEM layout for the Power State Change Reason recorder (PSCRR)
+
+maintainers:
+  - Faruque Ansari <faruque.ansari@oss.qualcomm.com>
+  - Oleksij Rempel <o.rempel@pengutronix.de>
+
+description:
+  An NVMEM layout for a Power State Change Reason (PSCRR) recorder. The
+  reboot or shutdown cause is persisted into a single small NVMEM cell,
+  such as an RTC scratch register, a PMIC SDAM (Scratch Data Access Memory)
+  byte, or an EEPROM byte, so the reason survives a power cycle and can be
+  read back on the next boot.
+
+select: false
+
+properties:
+  compatible:
+    const: pscrr-nvmem
+
+  "#address-cells":
+    const: 1
+
+  "#size-cells":
+    const: 1
+
+patternProperties:
+  "^.*@[0-9a-f]+$":
+    type: object
+    description:
+      The single NVMEM cell used to persist the power state change reason.
+
+    properties:
+      reg:
+        items:
+          - items:
+              - description: Offset, in bytes, of the cell within the
+                  parent NVMEM device.
+              - const: 1
+        description:
+          Offset and size, in bytes, of the cell within the parent NVMEM
+          device. The reason value occupies a single byte, so the size
+          must be 1.
+
+      bits:
+        $ref: /schemas/types.yaml#/definitions/uint32-array
+        items:
+          - minimum: 0
+            maximum: 7
+            description:
+              Bit offset within the byte addressed by reg.
+          - minimum: 1
+            maximum: 8
+            description:
+              Number of bits used to store the reason. Must be wide enough
+              to hold every value of enum psc_reason (currently 4 bits or
+              more).
+        description:
+          Optional. When absent, the whole byte addressed by reg is used.
+
+    required:
+      - reg
+
+    additionalProperties: false
+
+required:
+  - compatible
+
+additionalProperties: false
+
+examples:
+  - |
+    nvmem-layout {
+        compatible = "pscrr-nvmem";
+        #address-cells = <1>;
+        #size-cells = <1>;
+
+        reboot-reason-persist@49 {
+            reg = <0x49 0x1>;
+            bits = <0 4>;
+        };
+    };

MAINTAINERS

@@ -20550,6 +20550,19 @@ F:	Documentation/devicetree/bindings/connector/pcie-m2-e-connector.yaml
 F:	Documentation/devicetree/bindings/connector/pcie-m2-m-connector.yaml
 F:	drivers/power/sequencing/pwrseq-pcie-m2.c
 
+POWER STATE CHANGE REASON RECORDING (PSCRR)
+M:	Oleksij Rempel <o.rempel@pengutronix.de>
+M:	Faruque Ansari <faruque.ansari@oss.qualcomm.com>
+R:	Pengutronix Kernel Team <kernel@pengutronix.de>
+L:	linux-pm@vger.kernel.org
+S:	Maintained
+F:	Documentation/ABI/testing/sysfs-kernel-pscrr
+F:	Documentation/devicetree/bindings/nvmem/layouts/pscrr-nvmem.yaml
+F:	drivers/nvmem/layouts/pscrr-nvmem.c
+F:	drivers/power/reset/pscrr/
+F:	include/linux/pscrr.h
+F:	tools/testing/selftests/pscrr/
+
 POWER STATE COORDINATION INTERFACE (PSCI)
 M:	Mark Rutland <mark.rutland@arm.com>
 M:	Lorenzo Pieralisi <lpieralisi@kernel.org>

arch/arm64/boot/dts/qcom/lemans-pmics.dtsi

@@ -186,6 +186,17 @@
 				reg = <0x48 0x1>;
 				bits = <1 7>;
 			};
+
+			nvmem-layout {
+				compatible = "pscrr-nvmem";
+				#address-cells = <1>;
+				#size-cells = <1>;
+
+				reboot_reason_persist: reboot-reason-persist@49 {
+					reg = <0x49 0x1>;
+					bits = <0 6>;
+				};
+			};
 		};
 	};
 

drivers/nvmem/layouts/Kconfig

@@ -37,6 +37,16 @@ config NVMEM_LAYOUT_U_BOOT_ENV
 
 	  If unsure, say N.
 
+config NVMEM_LAYOUT_PSCRR
+	tristate "PSCRR NVMEM recorder provider"
+	depends on PSCRR
+	help
+	  PSCRR recorder that stores the power state change reason in a
+	  small NVMEM cell (such as an RTC scratch register) and reads it
+	  back on the next boot, so the cause survives a power cycle.
+
+	  If unsure, say N.
+
 endmenu
 
 endif

drivers/nvmem/layouts/Makefile

@@ -7,3 +7,4 @@ obj-$(CONFIG_NVMEM_LAYOUTS) += fixed-layout.o
 obj-$(CONFIG_NVMEM_LAYOUT_SL28_VPD) += sl28vpd.o
 obj-$(CONFIG_NVMEM_LAYOUT_ONIE_TLV) += onie-tlv.o
 obj-$(CONFIG_NVMEM_LAYOUT_U_BOOT_ENV) += u-boot-env.o
+obj-$(CONFIG_NVMEM_LAYOUT_PSCRR) += pscrr-nvmem.o