Merge branch 'for-next/doc'

3 files changed, 113 insertions, 0 deletions

diff --git a/Documentation/user/reset-reason.rst b/Documentation/user/reset-reason.rst
new file mode 100644
index 0000000000..26d37f86dd
--- /dev/null
+++ b/Documentation/user/reset-reason.rst
@@ -0,0 +1,47 @@
+.. _reset_reason:
+
+Reset Reason
+------------
+
+To handle a device in a secure and safe 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/system-reset.rst b/Documentation/user/system-reset.rst
new file mode 100644
index 0000000000..e76e3a23c1
--- /dev/null
+++ b/Documentation/user/system-reset.rst
@@ -0,0 +1,64 @@
+.. _system_reset:
+
+System Restart
+--------------
+
+When running the reset command barebox restarts the SoC somehow. Restart can
+be done in software, but a more reliable way is to use a hard reset line, which
+really resets the whole machine.
+The most common way to force such a hard reset is by using a watchdog. Its
+trigger time will be setup as short as possible and after that the software just
+waits for its reset. Very simple and most of the time it does what's expected.
+
+But there are some drawbacks within this simple approach.
+
+* most used watchdogs are built-in units in the SoCs. There is nothing wrong
+  with that, but these units can mostly reset the CPU core and sometimes a little
+  bit more of the SoC. This means this reset is not exactly the same than the
+  real POR (e.g. power on reset). In this case you must still handle different
+  hardware in a special way because it hasn't seen the reset the CPU has seen.
+  Enabled DMA units for example can continue to run and transfer data while the
+  CPU core runs through its reset code. This can trigger very strange failures.
+
+* when interacting with flash memories (mostly NOR types and used to store the
+  root filesystem) it cannot provide data (sometimes called 'array mode') the
+  CPU wants to read after a reset while it is still in some programming mode.
+  And if the software is currently changing some data inside the flash and
+  an internal reset happens the CPU and the flash memory are doing different
+  things and the system hangs until a real POR which also resets the flash
+  memory into the 'array mode'.
+
+* some SoC's boot behaviour gets parametrized by so called 'bootstrap pins'.
+  These pins can have a different meaning at reset time and at run-time later
+  on (multi purpose pins) but their correct values at reset time are very
+  important to boot the SoC sucessfully. If external devices are connected to
+  these multi purpose pins they can disturb the reset values, and so parametrizing
+  the boot behaviour differently and hence crashing the SoC until the next real
+  POR happens which also resets the external devices (and keep them away from the
+  multi purpose pins).
+
+* when power management comes into play another level of failure is
+  possible. To save power the software can lower the clock(s), but to really
+  save power, the power supply voltages must be lowered as well. Most PMICs
+  (e.g. power management controllers) are dedicated external companion devices,
+  loosely connected to their SoC. If the SoC's internal reset source now resets
+  the CPU it may increases its clock(s) back to the frequencies after a POR, but
+  the external PMIC still provides voltages related to lower frequencies. The
+  system isn't consistent any more. If you are in luck, the SoC still works
+  somehow, even if the voltages are out of their specifications for the
+  currently used clock speeds. But don't rely on it.
+
+To workaround these issues the reset signal triggered by a SoC internal source
+must be 'visible' to the external devices to also reset them like a real POR does.
+But many SoCs do not provide such a signal. So you can't use the internal reset
+source if you face one of the above listed issues!
+
+A different solution is to use the PMIC (if available) to trigger the reset.
+Many PMICs provide their own watchdog units and if they trigger a reset they
+also switch their voltages back to the real POR values. This will be a system
+wide reset, like the POR is.
+
+Drawback of the PMIC solution is, you can't use the SoC's internal mechanisms to
+detect the :ref:`reset_reason` anymore. From the SoC point of view it is always
+a POR when the PMIC handles the system reset. If you are in luck the PMIC
+instead can provide this information if you depend on it.
diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index 3d68bbb9ae..0d6daee70e 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -28,6 +28,8 @@ Contents:
    ubi
    booting-linux
    system-setup
+   reset-reason
+   system-reset
 
 * :ref:`search`
 * :ref:`genindex`