doc: bootloader abstraction, GRUB support

macpijan · sbabic · commit 86b02a0163c5 · 2017-04-26T09:32:45.000+02:00
Adjusted documentation according to bootloader abstraction and GRUB bootloader
support.
A few u-boot -&gt; U-Boot in text

Signed-off-by: Maciej Pijanowski &lt;maciej.pijanowski@3mdeb.com&gt;
diff --git a/doc/source/handlers.rst b/doc/source/handlers.rst
@@ -24,7 +24,7 @@ In mainline there are the handlers for the most common cases. They include:
 	- flash devices in raw mode (both NOR and NAND)
 	- UBI volumes
 	- raw devices, such as a SD Card partition
-	- U-Boot environment
+	- bootloader (U-Boot, GRUB) environment
 	- LUA scripts
 
 For example, if an image is marked to be updated into a UBI volume,
diff --git a/doc/source/overview.rst b/doc/source/overview.rst
@@ -233,6 +233,8 @@ is corrupted or cannot run.
 With U-Boot as boot loader, SWUpdate is able to manage U-Boot's environment
 setting variables to indicate the start and the end of a transaction and
 that the storage contains a valid software.
+Similar feature for GRUB environment block modification has been introduced
+into SWUpdate lately.
 
 SWUpdate is mainly used in this configuration. The recipes for Yocto
 generate an initrd image containing the SWUpdate application, that is
@@ -245,8 +247,8 @@ Something went wrong ?
 
 Many things can go wrong, and it must be guaranteed that the system
 is able to run again and maybe able to reload a new software to fix
-a damaged image. SWUpdate works together with the U-Boot boot loader to
-identify the possible causes of failures.
+a damaged image. SWUpdate works together with the boot loader to identify the
+possible causes of failures. Currently U-Boot and GRUB are supported.
 
 We can at least group some of the common causes:
 
@@ -261,10 +263,10 @@ We can at least group some of the common causes:
 
 - power-failure
 
-SWUpdate works as transaction process. The U-Boot variable "recovery_status" is
-set to signal U-Boot the update's status. Of course, further variables can be added
-to fine tuning and report error causes. recovery_status can have the values "progress",
-"failed", or it can be unset.
+SWUpdate works as transaction process. The boot loader environment variable
+"recovery_status" is set to signal the update's status to the boot loader. Of
+course, further variables can be added to fine tuning and report error causes.
+recovery_status can have the values "progress", "failed", or it can be unset.
 
 When SWUpdate starts, it sets recovery_status to "progress". After an update is
 finished with success, the variable is erased. If the update ends with an
@@ -295,11 +297,12 @@ Generally, the behavior can be split according to the chosen scenario:
 To be completely safe, SWUpdate and the bootloader need to exchange some
 information. The bootloader must detect if an update was interrupted due
 to a power-off, and restart SWUpdate until an update is successful.
-SWUpdate supports the U-Boot bootloader. U-Boot has a power-safe environemnt,
-that SWUpdate is able to change to communicate with U-Boot.
-Setting / Clearing variables let SWUpdate and U-Boot to communicate.
+SWUpdate supports the U-Boot and GRUB bootloaders. U-Boot has a power-safe
+environment, that SWUpdate is able to change to communicate with U-Boot.
+In case of GRUB, fixed 1024-byte environment block file is used.
+Setting / Clearing variables lets SWUpdate and bootloader to communicate.
 SWUpdate sets a variable as flag when it starts to update the system, and
-resets the same variable after completion. U-Boot can detect this flag
+resets the same variable after completion. Bootloader can detect this flag
 to check if an update was running before a power-off.
 
 .. image:: images/SoftwareUpdateU-Boot.png
@@ -324,9 +327,9 @@ upgraded image:
 What about upgrading the Boot loader ?
 --------------------------------------
 
-Updating the boot loader is in most cases a one-way process. On most SOCs, there is no possibility
-to have multiple copies of the boot loader, and when U-Boot is broken,
-the board does not simply boot.
+Updating the boot loader is in most cases a one-way process. On most SOCs,
+there is no possibility to have multiple copies of the boot loader, and when
+boot loader is broken, the board does not simply boot.
 
 Some SOCs allow to have multiple copies of the
 boot loader. But again, there is no general solution for this because it
diff --git a/doc/source/roadmap.rst b/doc/source/roadmap.rst
@@ -111,11 +111,11 @@ backends to be mixed and matched at run-time.
 Filesystem-based Persistent Update Status Storage
 -------------------------------------------------
 
-Currently, `U-Boot`_'s environment is used to persistently store the
-update status across reboots. On systems where U-Boot is not available
-or a different bootloader is used, a filesystem- or raw partition-based
-persistent storage should be made available to support other bootloaders
-such as, e.g., `grub`_.
+Originally, `U-Boot`_'s environment was used to persistently store the
+update status across reboots. Currently, `GRUB`_ environment block has been
+added. On systems where different bootloader is used, a filesystem- or raw
+partition-based persistent storage should be made available to support other
+bootloaders.
 
 .. _grub:   https://www.gnu.org/software/grub/
 .. _U-Boot: http://www.denx.de/wiki/U-Boot/
diff --git a/doc/source/suricatta.rst b/doc/source/suricatta.rst
@@ -11,7 +11,7 @@ name suricatta (engl. meerkat) as it belongs to the mongoose family.
 Suricatta regularly polls a remote server for updates, downloads, and
 installs them. Thereafter, it reboots the system and reports the update
 status to the server, based on an update state variable currently stored
-in U-Boot's environment ensuring persistent storage across reboots. Some
+in bootloader's environment ensuring persistent storage across reboots. Some
 U-Boot script logics or U-Boot's ``bootcount`` feature may be utilized
 to alter this update state variable, e.g., by setting it to reflect
 failure in case booting the newly flashed root file system has failed
diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst
@@ -64,8 +64,8 @@ The following example explains better the implemented tags:
 				volume = "splash";
 			},
 			{
-				filename = "uboot-env";
-				type = "uboot";
+				filename = "bootloader-env";
+				type = "bootloader";
 			},
 			{
 				filename = "uImage.bin";
@@ -97,7 +97,7 @@ The following example explains better the implemented tags:
 			}
 		);
 
-		uboot: (
+		bootenv: (
 			{
 				name = "vram";
 				value = "4M";
@@ -353,22 +353,25 @@ postinstall are shell scripts and called via system command.
 SWUpdate scans for all scripts and calls them after installing the images.
 
 
-uboot
------
+bootloader
+----------
 
-There are two ways to update the bootloader (U-Boot) environment.
+There are two ways to update the bootloader (currently U-Boot, GRUB) environment.
 First way is to add a file with the list of variables to be changed
-and setting "uboot" as type of the image. This inform SWUpdate to
-call the U-Boot handler to manage the file.
+and setting "bootloader" as type of the image. This informs SWUpdate to
+call the bootloader handler to manage the file (requires enabling bootloader
+handler in configuration). There is one bootloader handler for all supported
+bootloaders. Appropriate bootloader must be chosen from bootloader selection
+menu in menuconfig.
 
 ::
 
 		{
-			filename = "uboot-env";
-			type = "uboot";
+			filename = "bootloader-env";
+			type = "bootloader";
 		},
 
-The format of the file is described in u-boot documentation. Each line
+The format of the file is described in U-boot documentation. Each line
 is in the format
 
 ::
@@ -377,21 +380,26 @@ is in the format
 
 if value is missing, the variable is unset.
 
+In current implementation we have inherited above file format for GRUB
+environment modification as well.
+
 The second way is to define in a group setting the variables
 that must be changed:
 
 ::
 
-	uboot: (
+	bootenv: (
 		{
 			name = <Variable name>;
 			value = <Variable value>;
 		},
 	)
 
 SWUpdate will internally generate a script that will be passed to the
-U-Boot handler for adjusting the environment.
+bootloader handler for adjusting the environment.
 
+For backward compatibility with previously built .swu images, "uboot "group name
+is still relevant (as an alias).
 
 Board specific settings
 -----------------------
@@ -412,23 +420,23 @@ and the following description::
 	        version = "0.1.0";
 
 	        my-board = {
-	                uboot: (
+	                bootenv: (
 	                {
 	                        name = "bootpart";
 	                        value = "0:2";
 	                }
 	                );
 	        };
 
-	        uboot: (
+	        bootenv: (
 	        {
 	                name = "bootpart";
 	                value = "0:1";
 	        }
 	        );
 	}
 
-SWUpdate will set `bootpart` to `0:2` in U-Boot's environment for this
+SWUpdate will set `bootpart` to `0:2` in bootloader's environment for this
 board. For all other boards, `bootpart` will be set to `0:1`. Board
 specific settings take precedence over default scoped settings.
 
@@ -444,7 +452,7 @@ stable and unstable images within a single update file.
 
 The mechanism uses a custom user-defined tags placed within `software`
 scope. The tag names must not be any of: `version`,
-`hardware-compatibility`, `uboot`, `files`, `scripts`, `partitions`,
+`hardware-compatibility`, `uboot`, `bootenv`, `files`, `scripts`, `partitions`,
 `images`
 
 An example description file:
@@ -469,7 +477,7 @@ An example description file:
 	                        }
 	                        );
 
-	                        uboot: (
+	                        bootenv: (
 	                        {
 	                                name = "bootpart";
 	                                value = "0:2";
@@ -485,7 +493,7 @@ An example description file:
 	                        }
 	                        );
 
-	                        uboot: (
+	                        bootenv: (
 	                        {
 	                                name = "bootpart";
 	                                value = "0:1";
@@ -552,7 +560,8 @@ There are 4 main sections inside sw-description:
   single files.
 - scripts: all entries are treated as executables, and they will
   be run twice (as pre- and post- install scripts).
-- uboot: entries are pair with U-Boot variable name and its value.
+- bootenv: entries are pair with bootloader environment variable name and its
+  value.
 
 .. table::
 
@@ -609,10 +618,11 @@ There are 4 main sections inside sw-description:
    |             |          |            | temporary copy. Not all handlers      |
    |             |          |            | support streaming.                    |
    +-------------+----------+------------+---------------------------------------+
-   | name        | string   | uboot      | name of the U-Boot variable to be set.|
+   | name        | string   | bootenv    | name of the bootloader variable to be |
+   |             |          |            | set.                                  |
    +-------------+----------+------------+---------------------------------------+
-   | value       | string   | uboot      | value to be assigned to the U-Boot    |
-   |             |          |            | variable                              |
+   | value       | string   | bootenv    | value to be assigned to the           |
+   |             |          |            | bootloader variable                   |
    +-------------+----------+------------+---------------------------------------+
    | name        | string   | images     | name that identifies the sw-component |
    |             |          | files      | it can be any string and it is        |
diff --git a/doc/source/swupdate.rst b/doc/source/swupdate.rst
@@ -270,6 +270,10 @@ List of supported features
 
 - Support for setting / erasing U-Boot variables
 
+.. _GRUB: https://www.gnu.org/software/grub/manual/html_node/Environment-block.html
+
+- Support for setting / erasing `GRUB`_ environment block variables
+
 - Support for preinstall scripts. They run before updating the images
 
 - Support for postinstall scripts. They run after updating the images.
@@ -491,7 +495,7 @@ A run of SWUpdate consists mainly of the following steps:
 - iterates through all images and call the corresponding
   handler for installing on target.
 - runs post-install scripts
-- update u-boot environment, if changes are specified
+- update bootloader environment, if changes are specified
   in sw-description.
 - reports the status to the operator (stdout)
 
