mail archive of the barebox mailing list
 help / color / mirror / Atom feed
From: Juergen Borleis <jbe@pengutronix.de>
To: barebox@lists.infradead.org
Subject: [PATCH 1/2] Documentation: add some info about the reset reason framework
Date: Tue, 16 Jun 2015 14:02:24 +0200	[thread overview]
Message-ID: <1434456145-21912-2-git-send-email-jbe@pengutronix.de> (raw)
In-Reply-To: <1434456145-21912-1-git-send-email-jbe@pengutronix.de>

Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
---
 Documentation/user/reset-reason.rst | 47 +++++++++++++++++++++++++++++++++++++
 Documentation/user/user-manual.rst  |  1 +
 2 files changed, 48 insertions(+)
 create mode 100644 Documentation/user/reset-reason.rst

diff --git a/Documentation/user/reset-reason.rst b/Documentation/user/reset-reason.rst
new file mode 100644
index 0000000..a4872fa
--- /dev/null
+++ b/Documentation/user/reset-reason.rst
@@ -0,0 +1,47 @@
+.. _reset_reason:
+
+Reset Reason
+------------
+
+To handle a device in a secure and safty manner many applications are using
+a watchdog or other ways to reset a system to bring it back into life if it
+hangs or crashes somehow.
+
+In these cases the hardware restarts and runs the bootloader again. Depending on
+the root cause of the hang or crash, the bootloader sometimes should not just
+re-start the main system again. Maybe it should do some kind of recovery instead.
+For example it should wait for another update (for the case the cause of a
+crash is a failed update) or should start into a fall back system instead.
+
+In order to handle failing systems gracefully the bootloader needs the
+information why it runs. This is called the "reset reason". It is provided by
+the global variable ``system.reset`` and can be used in scripts via
+``$global.system.reset``.
+
+The following values can help to detect the reason why the bootloader runs:
+
+* ``unknown``: the software wasn't able to detect the reset cause or there
+  isn't support for this feature at all.
+* ``POR`` (Power On Reset): a cold start. The power of the system
+  was switched on. This is a regular state and nothing to worry about.
+* ``RST`` (ReSeT): a warm start. The user has triggered a reset somehow. This
+  is a regular state and nothing to worry about.
+* ``WDG`` (WatchDoG): also some kind of warm start, but triggered by a watchdog
+  unit. It depends on the application if this reason signals a regular state
+  and therefore nothing to worry about, or if this state was entered by a hanging
+  or crashed system and must implicitly be handled.
+* ``WKE`` (WaKEup): a mixture of cold and warm start. The system is woken up
+  from some state of suspend. This is a regular state and nothing to worry
+  about.
+* ``JTAG``: an external JTAG based debugger has triggered the reset.
+* ``THERM`` (THERMal): some SoCs are able to detect if they got reset in
+  response to an overtemperature event. This can be a regular state and nothing
+  to worry about (the reset has brought the system back into a safe state) or
+  must implicitly be handled.
+* ``EXT`` (EXTernal): some SoCs have special device pins for external reset
+  signals other than the ``RST`` one. Application specific how to handle this
+  state.
+
+It depends on your board/SoC and its features if the hardware is able to detect
+these reset reasons. Most of the time only ``POR`` and ``RST`` are supported
+but often ``WDG`` as well.
diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index 3d68bbb..1fc6883 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -28,6 +28,7 @@ Contents:
    ubi
    booting-linux
    system-setup
+   reset-reason
 
 * :ref:`search`
 * :ref:`genindex`
-- 
2.1.4


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

  reply	other threads:[~2015-06-16 12:02 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2015-06-16 12:02 [PATCH] Add some doc Juergen Borleis
2015-06-16 12:02 ` Juergen Borleis [this message]
2015-06-16 12:02 ` [PATCH 2/2] Documentation: add some info about the reset variants Juergen Borleis
2015-06-17  6:19 ` [PATCH] Add some doc Sascha Hauer

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=1434456145-21912-2-git-send-email-jbe@pengutronix.de \
    --to=jbe@pengutronix.de \
    --cc=barebox@lists.infradead.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox