diff mbox series

Add documentation of grub

Message ID 20231011213131.27792-1-m.belouarga@technologyandstrategy.com
State Accepted
Delegated to: Stefano Babic
Headers show
Series Add documentation of grub | expand

Commit Message

Mohamed Belouarga Oct. 11, 2023, 9:31 p.m. UTC 
From: BELOUARGA Mohamed <m.belouarga@technologyandstrategy.com>

Add documentation of how to use swupdate with grub, and how to
include an environment file grubenv.

Signed-off-by: BELOUARGA Mohamed <m.belouarga@technologyandstrategy.com>
---
 doc/source/building-with-yocto.rst | 48 ++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
diff mbox series

Patch

diff --git a/doc/source/building-with-yocto.rst b/doc/source/building-with-yocto.rst
index 49830de..d76bc46 100644
--- a/doc/source/building-with-yocto.rst
+++ b/doc/source/building-with-yocto.rst
@@ -287,3 +287,51 @@  In the simple way, your recipe looks like
 
         SWUPDATE_IMAGES_FSTYPES[<name of your image>] = <fstype to be put into SWU>
         inherit swupdate-image
+
+What about grub ?
+=================
+In order to use swupdate with grub, swupdate needs to be configured to use grub. Some of
+the imporatant configurations are **CONFIG_GRUBENV_PATH="/path/to/grubenv"**,
+where **"/path/to/grubenv"** is thepath to grub environment.
+Example: "/boot/EFI/BOOT/grubenv".
+
+The grubenv file should be created using grub-editenv tool, because it is a **1024-byte file**, therefore,
+any modification using nano or vim will only corrupt the file, and grub will not be able to use it.
+
+You can create a grubenv file using these commands for instance:
+::
+        GRUBENV="/path/to/grubenv"
+        grub-editenv $GRUBENV create
+        grub-editenv $GRUBENV set rootfs=2
+        grub-editenv $GRUBENV set kernel=2
+
+grub-editenv is a tool that is integrated to yocto.
+
+When the grubenv file is created, grub should be configured to use it.
+This configuration should be in the configuration file grub.cfg.
+Here is an example of grub.cfg that loads the environment file before booting:
+::
+        # Take a kernel and a rootfs by default in case grubenv is corrupted
+        rootfs=1
+        kernel=1
+        serial --unit=0 --speed=115200 --word=8 --parity=no --stop=1
+        default=boot
+        # set timeout to zero to boot without timeout
+        timeout=0
+        # load grubenv the environment file that contains the value of rootfs and kernel variables
+        load_env -f "/path/to/grubenv"
+        # detect which memory contains 5 partitions
+        for i in 1 2 3 4 5; do  if [ -d (hd${i},gpt5)/ ]; then drive=${i};fi ; done
+        # detect which rootfs should we boot with
+        if [ ${rootfs} = "1" ]; then rootfs_part=4 ; elif [ ${rootfs} = "2" ]; then rootfs_part=5 ; fi
+        # detect which kernel should we boot with
+        if [ ${kernel} = "1" ]; then kernel_part="(hd${drive},gpt2)" ; elif [ ${kernel} = "2" ]; then kernel_part="(hd${drive},gpt3)" ; fi
+
+        # The menuentry that is used to boot (more can be added if it is wanted)
+        menuentry 'boot'{
+        linux ${kernel_part}/bzImage root=/dev/mmcblk1p${rootfs_part} rw rootwait quiet console=ttyS2,115200 console=tty0 panic=5
+        }
+
+The grub.cfg above is merely an example, and can be modified as the user wants to,
+as long as it loads the environment variables,and it boots correctly using these environment
+variables.