| Message ID | 20180201135958.1228-1-christian.storm@siemens.com |
|---|---|
| State | Accepted |
| Headers | show |
| Series | doc: add documentation for EFI Boot Guard | expand |
Hi Christian, On 01/02/2018 14:59, Christian Storm wrote: > Signed-off-by: Christian Storm <christian.storm@siemens.com> > --- > doc/source/handlers.rst | 2 +- > doc/source/overview.rst | 23 ++++++++++++----------- > doc/source/sw-description.rst | 24 +++++++++++++----------- > doc/source/swupdate.rst | 11 +++++++---- > 4 files changed, 33 insertions(+), 27 deletions(-) > > diff --git a/doc/source/handlers.rst b/doc/source/handlers.rst > index a27647f..5bc3dd3 100644 > --- 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 > - - bootloader (U-Boot, GRUB) environment > + - bootloader (U-Boot, GRUB, EFI Boot Guard) 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 > index b651880..3854a7a 100644 > --- a/doc/source/overview.rst > +++ b/doc/source/overview.rst > @@ -233,8 +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. > +A similar feature for GRUB environment block modification as well as for > +EFI Boot Guard has been introduced. > > SWUpdate is mainly used in this configuration. The recipes for Yocto > generate an initrd image containing the SWUpdate application, that is > @@ -248,7 +248,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 boot loader to identify the > -possible causes of failures. Currently U-Boot and GRUB are supported. > +possible causes of failures. Currently U-Boot, GRUB, and EFI Boot Guard > +are supported. > > We can at least group some of the common causes: > > @@ -297,13 +298,13 @@ 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 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. Bootloader can detect this flag > -to check if an update was running before a power-off. > +SWUpdate supports the U-Boot, GRUB, and EFI Boot Guard bootloaders. > +U-Boot and EFI Boot Guard have a power-safe environment which SWUpdate is > +able to read and change in order to communicate with them. In case of GRUB, > +a fixed 1024-byte environment block file is used instead. SWUpdate sets > +a variable as flag when it starts to update the system and resets the same > +variable after completion. The bootloader can read this flag to check if an > +update was running before a power-off. > > .. image:: images/SoftwareUpdateU-Boot.png > > @@ -339,7 +340,7 @@ In my experience, most targets do not allow to update the boot loader. It > is very uncommon that the boot loader must be updated when the product > is ready for production. > > -It is different is if the U-Boot environment must be updated, that is a > +It is different if the U-Boot environment must be updated, that is a > common practice. U-Boot provides a double copy of the whole environment, > and updating the environment from SWUpdate is power-off safe. Other boot loaders > can or cannot have this feature. > diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst > index 06a371e..709febd 100644 > --- a/doc/source/sw-description.rst > +++ b/doc/source/sw-description.rst > @@ -507,13 +507,13 @@ SWUpdate scans for all scripts and calls them after installing the images. > bootloader > ---------- > > -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 "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. > +There are two ways to update the bootloader (currently U-Boot, GRUB, and > +EFI Boot Guard) environment. First way is to add a file with the list of > +variables to be changed 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. The appropriate bootloader > +must be chosen from the bootloader selection menu in `menuconfig`. > > :: > > @@ -531,8 +531,8 @@ 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. > +In the current implementation, the above file format was inherited for > +GRUB and EFI Boot Guard environment modification as well. > > The second way is to define in a group setting the variables > that must be changed: > @@ -549,8 +549,10 @@ that must be changed: > SWUpdate will internally generate a script that will be passed to the > bootloader handler for adjusting the environment. > > -For backward compatibility with previously built .swu images, "uboot "group name > -is still relevant (as an alias). > +For backward compatibility with previously built `.swu` images, the > +"uboot" group name is still supported as an alias. However, its usage > +is deprecated. > + > > Board specific settings > ----------------------- > diff --git a/doc/source/swupdate.rst b/doc/source/swupdate.rst > index 8e5ca40..1df8ad0 100644 > --- a/doc/source/swupdate.rst > +++ b/doc/source/swupdate.rst > @@ -71,8 +71,6 @@ General Overview > using the libconfig_ library as default parser, that uses a > JSON-like description. > > -.. _libconfig: http://www.hyperrealm.com/libconfig/ > - > - use custom's choice for the description of the image. It is > possible to write an own parser using the Lua language. > An example using a XML description in Lua is provided > @@ -80,10 +78,10 @@ General Overview > > - 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 setting / erasing `EFI Boot Guard`_ variables > + > - Support for preinstall scripts. They run before updating the images > > - Support for postinstall scripts. They run after updating the images. > @@ -125,6 +123,10 @@ General Overview > > - Power-Off safe > > +.. _libconfig: http://www.hyperrealm.com/libconfig/ > +.. _GRUB: https://www.gnu.org/software/grub/manual/html_node/Environment-block.html > +.. _EFI Boot Guard: https://github.com/siemens/efibootguard > + > Single image delivery > --------------------- > > @@ -214,6 +216,7 @@ There are only a few libraries that are required to compile SWUpdate. > - libarchive (optional) for archive handler > - libjson (optional) for JSON parser and Hawkbit > - libubootenv (optional) if support for U-Boot is enabled > +- libebgenv (optional) if support for EFI Boot Guard is enabled We need the recipe in OE for it - where is it supposed be stored ? > - libcurl used to communicate with network > > New handlers can add some other libraries to the requirement list - > Reviewed-by: Stefano Babic <sbabic@denx.de> Best regards, Stefano Babic
Hi Stefano, > > [...] > > @@ -214,6 +216,7 @@ There are only a few libraries that are required to compile SWUpdate. > > - libarchive (optional) for archive handler > > - libjson (optional) for JSON parser and Hawkbit > > - libubootenv (optional) if support for U-Boot is enabled > > +- libebgenv (optional) if support for EFI Boot Guard is enabled > > We need the recipe in OE for it - where is it supposed be stored ? Yes, right, that's upcoming and in the works actually, https://github.com/siemens/meta-efibootguard has recently been updated to different Yocto versions. meta-swupdate integration is next. It should land in /usr/{,local}/lib just like it's done in the travis build.. Besten Gruß, Christian
Hi Christian On 02/02/2018 08:20, Christian Storm wrote: > Hi Stefano, > >>> [...] >>> @@ -214,6 +216,7 @@ There are only a few libraries that are required to compile SWUpdate. >>> - libarchive (optional) for archive handler >>> - libjson (optional) for JSON parser and Hawkbit >>> - libubootenv (optional) if support for U-Boot is enabled >>> +- libebgenv (optional) if support for EFI Boot Guard is enabled >> >> We need the recipe in OE for it - where is it supposed be stored ? > > Yes, right, that's upcoming and in the works actually, > https://github.com/siemens/meta-efibootguard has recently > been updated to different Yocto versions. meta-swupdate > integration is next. > > It should land in /usr/{,local}/lib just like it's done > in the travis build.. Fine, we can add later in SWUpdate's doc that the meta-efibootguard layer must be added. Gruß, Stefano
On 01/02/2018 14:59, Christian Storm wrote: > Signed-off-by: Christian Storm <christian.storm@siemens.com> > --- > doc/source/handlers.rst | 2 +- > doc/source/overview.rst | 23 ++++++++++++----------- > doc/source/sw-description.rst | 24 +++++++++++++----------- > doc/source/swupdate.rst | 11 +++++++---- > 4 files changed, 33 insertions(+), 27 deletions(-) > > diff --git a/doc/source/handlers.rst b/doc/source/handlers.rst > index a27647f..5bc3dd3 100644 > --- 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 > - - bootloader (U-Boot, GRUB) environment > + - bootloader (U-Boot, GRUB, EFI Boot Guard) 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 > index b651880..3854a7a 100644 > --- a/doc/source/overview.rst > +++ b/doc/source/overview.rst > @@ -233,8 +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. > +A similar feature for GRUB environment block modification as well as for > +EFI Boot Guard has been introduced. > > SWUpdate is mainly used in this configuration. The recipes for Yocto > generate an initrd image containing the SWUpdate application, that is > @@ -248,7 +248,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 boot loader to identify the > -possible causes of failures. Currently U-Boot and GRUB are supported. > +possible causes of failures. Currently U-Boot, GRUB, and EFI Boot Guard > +are supported. > > We can at least group some of the common causes: > > @@ -297,13 +298,13 @@ 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 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. Bootloader can detect this flag > -to check if an update was running before a power-off. > +SWUpdate supports the U-Boot, GRUB, and EFI Boot Guard bootloaders. > +U-Boot and EFI Boot Guard have a power-safe environment which SWUpdate is > +able to read and change in order to communicate with them. In case of GRUB, > +a fixed 1024-byte environment block file is used instead. SWUpdate sets > +a variable as flag when it starts to update the system and resets the same > +variable after completion. The bootloader can read this flag to check if an > +update was running before a power-off. > > .. image:: images/SoftwareUpdateU-Boot.png > > @@ -339,7 +340,7 @@ In my experience, most targets do not allow to update the boot loader. It > is very uncommon that the boot loader must be updated when the product > is ready for production. > > -It is different is if the U-Boot environment must be updated, that is a > +It is different if the U-Boot environment must be updated, that is a > common practice. U-Boot provides a double copy of the whole environment, > and updating the environment from SWUpdate is power-off safe. Other boot loaders > can or cannot have this feature. > diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst > index 06a371e..709febd 100644 > --- a/doc/source/sw-description.rst > +++ b/doc/source/sw-description.rst > @@ -507,13 +507,13 @@ SWUpdate scans for all scripts and calls them after installing the images. > bootloader > ---------- > > -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 "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. > +There are two ways to update the bootloader (currently U-Boot, GRUB, and > +EFI Boot Guard) environment. First way is to add a file with the list of > +variables to be changed 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. The appropriate bootloader > +must be chosen from the bootloader selection menu in `menuconfig`. > > :: > > @@ -531,8 +531,8 @@ 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. > +In the current implementation, the above file format was inherited for > +GRUB and EFI Boot Guard environment modification as well. > > The second way is to define in a group setting the variables > that must be changed: > @@ -549,8 +549,10 @@ that must be changed: > SWUpdate will internally generate a script that will be passed to the > bootloader handler for adjusting the environment. > > -For backward compatibility with previously built .swu images, "uboot "group name > -is still relevant (as an alias). > +For backward compatibility with previously built `.swu` images, the > +"uboot" group name is still supported as an alias. However, its usage > +is deprecated. > + > > Board specific settings > ----------------------- > diff --git a/doc/source/swupdate.rst b/doc/source/swupdate.rst > index 8e5ca40..1df8ad0 100644 > --- a/doc/source/swupdate.rst > +++ b/doc/source/swupdate.rst > @@ -71,8 +71,6 @@ General Overview > using the libconfig_ library as default parser, that uses a > JSON-like description. > > -.. _libconfig: http://www.hyperrealm.com/libconfig/ > - > - use custom's choice for the description of the image. It is > possible to write an own parser using the Lua language. > An example using a XML description in Lua is provided > @@ -80,10 +78,10 @@ General Overview > > - 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 setting / erasing `EFI Boot Guard`_ variables > + > - Support for preinstall scripts. They run before updating the images > > - Support for postinstall scripts. They run after updating the images. > @@ -125,6 +123,10 @@ General Overview > > - Power-Off safe > > +.. _libconfig: http://www.hyperrealm.com/libconfig/ > +.. _GRUB: https://www.gnu.org/software/grub/manual/html_node/Environment-block.html > +.. _EFI Boot Guard: https://github.com/siemens/efibootguard > + > Single image delivery > --------------------- > > @@ -214,6 +216,7 @@ There are only a few libraries that are required to compile SWUpdate. > - libarchive (optional) for archive handler > - libjson (optional) for JSON parser and Hawkbit > - libubootenv (optional) if support for U-Boot is enabled > +- libebgenv (optional) if support for EFI Boot Guard is enabled > - libcurl used to communicate with network > > New handlers can add some other libraries to the requirement list - > Applied to -master, thanks ! Best regards, Stefano Babic
diff --git a/doc/source/handlers.rst b/doc/source/handlers.rst index a27647f..5bc3dd3 100644 --- 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 - - bootloader (U-Boot, GRUB) environment + - bootloader (U-Boot, GRUB, EFI Boot Guard) 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 index b651880..3854a7a 100644 --- a/doc/source/overview.rst +++ b/doc/source/overview.rst @@ -233,8 +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. +A similar feature for GRUB environment block modification as well as for +EFI Boot Guard has been introduced. SWUpdate is mainly used in this configuration. The recipes for Yocto generate an initrd image containing the SWUpdate application, that is @@ -248,7 +248,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 boot loader to identify the -possible causes of failures. Currently U-Boot and GRUB are supported. +possible causes of failures. Currently U-Boot, GRUB, and EFI Boot Guard +are supported. We can at least group some of the common causes: @@ -297,13 +298,13 @@ 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 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. Bootloader can detect this flag -to check if an update was running before a power-off. +SWUpdate supports the U-Boot, GRUB, and EFI Boot Guard bootloaders. +U-Boot and EFI Boot Guard have a power-safe environment which SWUpdate is +able to read and change in order to communicate with them. In case of GRUB, +a fixed 1024-byte environment block file is used instead. SWUpdate sets +a variable as flag when it starts to update the system and resets the same +variable after completion. The bootloader can read this flag to check if an +update was running before a power-off. .. image:: images/SoftwareUpdateU-Boot.png @@ -339,7 +340,7 @@ In my experience, most targets do not allow to update the boot loader. It is very uncommon that the boot loader must be updated when the product is ready for production. -It is different is if the U-Boot environment must be updated, that is a +It is different if the U-Boot environment must be updated, that is a common practice. U-Boot provides a double copy of the whole environment, and updating the environment from SWUpdate is power-off safe. Other boot loaders can or cannot have this feature. diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst index 06a371e..709febd 100644 --- a/doc/source/sw-description.rst +++ b/doc/source/sw-description.rst @@ -507,13 +507,13 @@ SWUpdate scans for all scripts and calls them after installing the images. bootloader ---------- -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 "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. +There are two ways to update the bootloader (currently U-Boot, GRUB, and +EFI Boot Guard) environment. First way is to add a file with the list of +variables to be changed 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. The appropriate bootloader +must be chosen from the bootloader selection menu in `menuconfig`. :: @@ -531,8 +531,8 @@ 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. +In the current implementation, the above file format was inherited for +GRUB and EFI Boot Guard environment modification as well. The second way is to define in a group setting the variables that must be changed: @@ -549,8 +549,10 @@ that must be changed: SWUpdate will internally generate a script that will be passed to the bootloader handler for adjusting the environment. -For backward compatibility with previously built .swu images, "uboot "group name -is still relevant (as an alias). +For backward compatibility with previously built `.swu` images, the +"uboot" group name is still supported as an alias. However, its usage +is deprecated. + Board specific settings ----------------------- diff --git a/doc/source/swupdate.rst b/doc/source/swupdate.rst index 8e5ca40..1df8ad0 100644 --- a/doc/source/swupdate.rst +++ b/doc/source/swupdate.rst @@ -71,8 +71,6 @@ General Overview using the libconfig_ library as default parser, that uses a JSON-like description. -.. _libconfig: http://www.hyperrealm.com/libconfig/ - - use custom's choice for the description of the image. It is possible to write an own parser using the Lua language. An example using a XML description in Lua is provided @@ -80,10 +78,10 @@ General Overview - 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 setting / erasing `EFI Boot Guard`_ variables + - Support for preinstall scripts. They run before updating the images - Support for postinstall scripts. They run after updating the images. @@ -125,6 +123,10 @@ General Overview - Power-Off safe +.. _libconfig: http://www.hyperrealm.com/libconfig/ +.. _GRUB: https://www.gnu.org/software/grub/manual/html_node/Environment-block.html +.. _EFI Boot Guard: https://github.com/siemens/efibootguard + Single image delivery --------------------- @@ -214,6 +216,7 @@ There are only a few libraries that are required to compile SWUpdate. - libarchive (optional) for archive handler - libjson (optional) for JSON parser and Hawkbit - libubootenv (optional) if support for U-Boot is enabled +- libebgenv (optional) if support for EFI Boot Guard is enabled - libcurl used to communicate with network New handlers can add some other libraries to the requirement list -
Signed-off-by: Christian Storm <christian.storm@siemens.com> --- doc/source/handlers.rst | 2 +- doc/source/overview.rst | 23 ++++++++++++----------- doc/source/sw-description.rst | 24 +++++++++++++----------- doc/source/swupdate.rst | 11 +++++++---- 4 files changed, 33 insertions(+), 27 deletions(-)