summaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/boards/efi.rst35
-rw-r--r--Documentation/boards/imx/nxp-imx8mq-evk.rst2
-rw-r--r--Documentation/user/bootchooser.rst94
3 files changed, 107 insertions, 24 deletions
diff --git a/Documentation/boards/efi.rst b/Documentation/boards/efi.rst
index f59bb1d..3da2daa 100644
--- a/Documentation/boards/efi.rst
+++ b/Documentation/boards/efi.rst
@@ -216,7 +216,6 @@ has a device parameter ``devpath`` which contains its device path:
barebox:/ echo ${handle-00000000d0012198.devpath}
pci_root(0)/Pci(0x1d,0x0)/Usb(0x1,0x0)/Usb(0x2,0x0)
-
EFI variables
-------------
@@ -327,3 +326,37 @@ compile EDK2.
mov %fs, %rax
pushq %rax
+(U)EFI Watchdog
+---------------
+
+(U)EFI provides basic watchdog support. Depending on the system implementation
+it can be a software or hardware watchdog. Within the (U)EFI specification it
+is described as follows:
+
+.. epigraph::
+
+ If the watchdog timer expires, the event is logged by the firmware. The system
+ may then either reset with the Runtime Service ResetSystem(), or perform a
+ platform specific action that must eventually cause the platform to be reset.
+ The watchdog timer is armed before the firmware's boot manager invokes an EFI
+ boot option. The watchdog must be set to a period of 5 minutes. The EFI Image
+ may reset or disable the watchdog timer as needed. If control is returned to
+ the firmware's boot manager, the watchdog timer must be disabled. The watchdog
+ timer is only used during boot services. On successful completion of
+ ExitBootServices() the watchdog timer is disabled.
+
+See page 186:
+https://uefi.org/sites/default/files/resources/UEFI_Spec_2_1_D.pdf
+
+Current linux kernel (v5.0) will execute ExitBootServices() during the early
+boot stage and thus will automatically disable the (U)EFI watchdog. Since it is
+a proper behavior according to the (U)EFI specification, it is impossible to
+protect full boot chain by using this watchdog only. It is recommended to use
+an alternative hardware watchdog, preferably started before the bootloader. If (U)EFI
+firmware lacks this feature, the bootloader should be able to start an alternative
+hardware watchdog on its own. Before implementing this kind of workaround
+please make sure (U)EFI watchdog is not using the same hardware as the alternative
+watchdog.
+
+Nevertheless, barebox provides access to the (U)EFI SetWatchdogTimer()
+interface over its internal watchdog framework.
diff --git a/Documentation/boards/imx/nxp-imx8mq-evk.rst b/Documentation/boards/imx/nxp-imx8mq-evk.rst
index 8bad945..a862413 100644
--- a/Documentation/boards/imx/nxp-imx8mq-evk.rst
+++ b/Documentation/boards/imx/nxp-imx8mq-evk.rst
@@ -29,7 +29,7 @@ result in the following files:
- lpddr4_pmu_train_2d_imem.bin
As a last step of this process those files need to be placed in
-"firmware/imx/"::
+"firmware/"::
for f in lpddr4_pmu_train_1d_dmem.bin \
lpddr4_pmu_train_1d_imem.bin \
diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index 05725d8..1680ea7 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -3,7 +3,7 @@
Barebox Bootchooser
===================
-In many cases embedded systems are layed out redundantly with multiple
+In many cases embedded systems are laid out redundantly with multiple
kernels and multiple root file systems. The *bootchooser* framework provides
the building blocks to model different use cases without the need to start
from scratch over and over again.
@@ -11,6 +11,22 @@ from scratch over and over again.
The *bootchooser* works on abstract boot targets, each with a set of properties
and implements an algorithm which selects the highest priority target to boot.
+To make the *bootchooser* work requires a fixed set of configuration parameters
+and a storage backend for saving status information.
+Currently supported storage backends are either nv variables or the
+barebox *state* framework.
+
+The *Bootchooser* itself is executed as a normal barebox boot target, i.e. one
+can start it via::
+
+ boot bootchooser
+
+or by e.g. setting ``boot.default`` to ``bootchooser``.
+
+.. note:: As ``boot.default`` accepts multiple values, it can also be used to
+ specify a fallback boot target in case the bootchooser fails booting, e.g.
+ ``bootchooser recovery``.
+
Bootchooser Targets
-------------------
@@ -56,25 +72,58 @@ When booting, *bootchooser* starts the boot target with the highest ``priority``
has a non-zero ``remaining_attempts`` counter. With every start of a boot target the
``remaining_attempts`` counter of this boot target is decremented by one. This means
every boot target's ``remaining_attempts`` counter reaches zero sooner or later and
-the boot target won't be booted anymore. To prevent that, the ``remaining_attempts``
-counter must be reset to its default. There are different flags in the
-*bootchooser* which control resetting the ``remaining_attempts`` counter,
+the boot target won't be booted anymore.
+This behavior assures that one can retry booting a target a limited number of
+times to handle temporary issues (such as power outage) and optionally allows
+booting a fallback in case of a permanent failure.
+To indicate a successful boot, one must explicitly reset the remaining
+attempts counter. See `Marking a Boot as Successful`_.
+
+The bootchooser algorithm aborts when all enabled targets (priority > 0) have
+no remaining attempts left.
+
+To prevent ending up in an unbootable system after a number of failed boot
+attempts, there is a also a built-in mechanism to reset the counters to their defaults,
controlled by the ``global.bootchooser.reset_attempts`` variable. It holds a
-list of space separated flags. Possible values are:
+list of space-separated flags. Possible values are:
- empty: counters will never be reset
-- ``power-on``: The ``remaining_attempts`` counters of all enabled boot targets are reset
- after a ``power-on`` reset (``$global.system.reset="POR"``). This means after a power
- cycle all boot targets will be tried again for the configured number of retries.
-- ``all-zero``: The ``remaining_attempts`` counters of all enabled boot targets are
- reset when none of them has any ``remaining_attempts`` left.
-
-Additionally the ``remaining_attempts`` counter can be reset manually using the
-:ref:`bootchoser command <command_bootchooser>`. This allows for custom conditions
-under which a system is marked as good.
-In case only the booted system itself knows when it is in a good state, the
-barebox-state tool from the dt-utils_ package can be used to reset the
-``remaining_attempts`` counter from the running system.
+- ``power-on``: When the bootchooser starts and a power-on reset
+ (``$global.system.reset="POR"``) is detected, the ``remaining_attempts``
+ counters of all enabled targets are reset to their defaults.
+ This means after a power cycle all boot targets will be tried again for the configured number of retries.
+- ``all-zero``: When the bootchooser starts and the ``remaining_attempts``
+ counters of all enabled targets are zero, the ``remaining_attempts``
+ counters of all enabled targets are reset to their defaults.
+
+If ``global.bootchooser.retry`` is enabled (set to ``1``), the bootchooser
+algorithm will iterate through all valid boot targets (and decrease their
+counters) until one succeeds or none is left.
+If it is disabled only one attempt will be made for each bootchooser call.
+
+Marking a Boot as Successful
+############################
+
+While the bootchooser algorithm handles attempts decrementation, retries and
+selection of the right boot target itself, it cannot decide if the system
+booted successfully on its own.
+
+In case only the booted system itself knows when it is in a good state,
+it can report this to the bootchooser from Linux userspace using the
+*barebox-state* tool from the dt-utils_ package.::
+
+ barebox-state -s bootstate.<target>.remaining_attemps <reset-value>
+
+If instead the bootchooser can detect a failed boot itself using the
+:ref:`reset reason <reset_reason>` (WDG), one can mark the boot successful
+using the barebox :ref:`bootchoser command <command_bootchooser>`::
+
+ bootchooser -s
+
+to mark the last boot successful.
+This will reset the ``remaining_attempts`` counter of the *last chosen* slot to
+its default value (``reset_attempts``).
+
.. _dt-utils: https://git.pengutronix.de/cgit/tools/dt-utils
@@ -97,7 +146,7 @@ options not specific to any boot target.
``global.bootchooser.reset_attempts``
Already described in :ref:`Bootchooser Algorithm <bootchooser,algorithm>`
``global.bootchooser.reset_priorities``
- A space separated list of events that cause *bootchooser* to reset the priorities of
+ A space-separated list of events that cause *bootchooser* to reset the priorities of
all boot targets. Possible values:
* empty: priorities will never be reset
@@ -108,10 +157,11 @@ options not specific to any boot target.
Otherwise the ``boot`` command will return with an error after the first failed
boot target.
``global.bootchooser.state_prefix``
- Variable prefix when *bootchooser* is used with the *state* framework as backend
- for storing run-time data, see below.
+ If set, this makes *bootchooser* use the *state* framework as backend for
+ storing run-time data and defines the name of the state instance to use, see
+ :ref:`below <bootchooser,state_framework>`.
``global.bootchooser.targets``
- Space separated list of boot targets that are used. For each entry in the list
+ Space-separated list of boot targets that are used. For each entry in the list
a corresponding
set of ``global.bootchooser.<targetname>.<variablename>`` variables must exist.
``global.bootchooser.last_chosen``
@@ -125,7 +175,7 @@ Setup Example
We want to set up a redundant machine with two bootable systems within one shared
memory, here a NAND type flash memory with a UBI partition. We have a 512 MiB NAND
type flash, to be used only for the root filesystem. The devicetree doesn't
-define any partition, because we want to run one UBI partition with two volumens
+define any partition, because we want to run one UBI partition with two volumes
for the redundant root filesystems on this flash memory.
.. code-block:: text