[PATCH v2] schemas: chosen: Add reset-reason property

From: Alexander Sverdlin <[email protected]>

Bootloaders such as U-Boot and barebox can populate the /chosen node with
a reset-reason string property indicating the cause of the most recent
system reset.

Define a standardized set of generic reset reason values that bootloaders
map their platform-specific reset sources to:

  unknown    - reset source could not be determined
  cold       - power-on reset
  warm       - warm restart without full power cycle
  watchdog   - watchdog timer expiration
  wakeup     - wake from suspend/sleep
  jtag       - JTAG/debug initiated reset
  thermal    - thermal shutdown/overtemperature
  external   - external reset pin/signal
  brownout   - supply voltage drop
  software   - explicit software-initiated reset
  safety     - hardware fault detection (e.g. error signaling module,
               fault collection and control unit)
  security   - security subsystem (e.g. secure enclave violation)
  pmic       - PMIC-initiated reset

Mapping of platform-specific reset sources to generic values:

  Generic      AM6x              i.MX9            barebox
  -------      ----              -----            -------
  unknown      UNKNOWN           -                unknown
  cold         POR               por              POR
  warm         RST (SW warm)     -                RST
  watchdog     WDOG              wdog             WDG
  wakeup       -                 -                WKE
  jtag         JTAG              jtag             JTAG
  thermal      THERMAL           tempsense        THERM
  external     PIN               -                EXT
  brownout     -                 -                BROWNOUT
  software     -                 sw               -
  safety       ESM               fccu             -
  security     SMS/DMSC          ele              -
  pmic         -                 pmic             -

Note: barebox already populates this property but uses abbreviated
uppercase values (common/reset_source.c). These will need to be adapted
to match the standardized lowercase values defined here.

The list can be extended in the future as needed.

Signed-off-by: Alexander Sverdlin <[email protected]>
---
Changelog:
v2:
- added "|" to the description to preserve the formatting
- added the meaning of each item to the schema
v1:
- https://lore.kernel.org/all/[email protected]/
RFC:
- https://lore.kernel.org/all/[email protected]/

 dtschema/schemas/chosen.yaml | 48 ++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/dtschema/schemas/chosen.yaml b/dtschema/schemas/chosen.yaml
index 63f3c12..f6fad1f 100644
--- a/dtschema/schemas/chosen.yaml
+++ b/dtschema/schemas/chosen.yaml
@@ -183,6 +183,54 @@ properties:
       will assign devices in its usual manner, otherwise it will not try to
       assign devices and instead use them as they are configured already.
 
+  reset-reason:
+    $ref: types.yaml#/definitions/string
+    enum:
+      - unknown
+      - cold
+      - warm
+      - watchdog
+      - wakeup
+      - jtag
+      - thermal
+      - external
+      - brownout
+      - software
+      - safety
+      - security
+      - pmic
+    description: |
+      This property is set by the bootloader to indicate the reason for the
+      most recent system reset. The values are generic categories that
+      bootloaders map their platform-specific reset sources to.
+
+      If multiple reset sources are detected, the bootloader should report
+      the most specific known cause. If the cause cannot be determined,
+      use "unknown". If this property is absent, the bootloader does not
+      support reset reason reporting.
+
+      Values:
+        unknown  - reset source could not be determined
+        cold     - power-on reset
+        warm     - warm restart without full power cycle
+        watchdog - watchdog timer expiration
+        wakeup   - wake from suspend/sleep
+        jtag     - JTAG/debug initiated reset
+        thermal  - thermal shutdown/overtemperature
+        external - external reset pin/signal
+        brownout - supply voltage drop
+        software - explicit software-initiated reset
+        safety   - hardware fault detection (e.g. error signaling module,
+                   fault collection and control unit)
+        security - security subsystem (e.g. secure enclave violation)
+        pmic     - PMIC-initiated reset
+
+      / {
+              chosen {
+                      reset-reason = "watchdog";
+              };
+      };
+
   smbios3-entrypoint:
     $ref: types.yaml#/definitions/address
     maxItems: 1
-- 
2.52.0