From patchwork Thu Feb 1 13:59:58 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Storm, Christian" X-Patchwork-Id: 868253 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=googlegroups.com (client-ip=2a00:1450:4010:c07::240; helo=mail-lf0-x240.google.com; envelope-from=swupdate+bncbdd6bwv65qpbbzv2ztjqkgqe4abbbla@googlegroups.com; receiver=) Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=googlegroups.com header.i=@googlegroups.com header.b="OsxfPmOB"; dkim-atps=neutral Received: from mail-lf0-x240.google.com (mail-lf0-x240.google.com [IPv6:2a00:1450:4010:c07::240]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3zXMFR5Jxyz9t3v for ; Fri, 2 Feb 2018 01:00:10 +1100 (AEDT) Received: by mail-lf0-x240.google.com with SMTP id r27sf7749638lfi.11 for ; Thu, 01 Feb 2018 06:00:10 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1517493606; cv=pass; d=google.com; s=arc-20160816; b=XSFT7NM1lNusJB/LN0rTtugForCylHkK9I/Tz57/w/vorG6sDlga6IXFjIFHgU9yNW AIRwFfqz38pCDHcSJ+zLaqIJY0anzR0vEnwu3VQoqJ6lYNlHBMs0RMiyEkCQ8EfhJWQA V8sW/1j0M5so38KN66oSCbtnEGqgwSN6q9iT3se1EoM2ef8iLeiqo4muhtFGPXAgdfu2 BHO7Dp4uajezdBgnW6ajVDANSRB3B9tQg7WYDTkYWJkHP3Q6GrGmQR+of4Y9IhFzh0iM Ni3pH+dzfEYY6HFNtu/8TqvR59fhztoz3sZybhMtEof3ubhEZREXV7MGq+wkTLV4sz+Y 5mug== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:message-id:date:subject:cc:to:from :arc-authentication-results:arc-message-signature:mime-version :sender:dkim-signature:arc-authentication-results; bh=xnjMEUINErHhqE4aDT6T5wj/xAFMYvQhH+kY/jDkXdI=; b=Wk9zf6gCvqJKZU9cPWTDle+zOV9G+ivIVDIkz8NpucCrPnXOZGvx8J44j1SNKeGBBk y05uZq3lG4PGlS/1QEJNHlNMFLfxYOknIZwp5lqO9sxhPXqIJN5wrQlcXtrf3je5RGfz Yhgx2eOnkEqexEnLkQTHA74fyLMb5Pk/qLFqyqrV7h8OtjDThUuj2yIF6te9z+0UAU5L WwbmA++/fx5Dvhocbbv6/SEvw9ZrXfzjr/hAq+qBwqygqtDjZnK53iNB+rRXPRGlw2kb LTbRm4RRBjKyITaMzPSfSvK6zI+kDyRYSVM6uFk+gMYW3ThcEj86eahcihml7Gyel5cu cF5g== ARC-Authentication-Results: i=2; gmr-mx.google.com; spf=pass (google.com: domain of christian.storm@siemens.com designates 192.35.17.2 as permitted sender) smtp.mailfrom=christian.storm@siemens.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=20161025; h=sender:mime-version:from:to:cc:subject:date:message-id :x-original-sender:x-original-authentication-results:precedence :mailing-list:list-id:list-post:list-help:list-archive :list-subscribe:list-unsubscribe; bh=xnjMEUINErHhqE4aDT6T5wj/xAFMYvQhH+kY/jDkXdI=; b=OsxfPmOBWHZeEkShNrKc/bxB/XkH3j2kLqKk2RmOk3Drgie/pxx8yOgsFeR7tXIK+b pHw5oc+L0CIyT7KI1RC4k2mQpsLI7bzFYlA7wqWxdi1ikXsa1q3clORBeEM7xGYkH0Ng IPdF/6K2RHtwUIj3LbtxxLAipMEuj6yxbuyf3g6qQKUhsuR96SdY+now5Bkl1apK7g1A rPxoPg+ZamIYP8FYQ4SWHZZs6RCDiKnr7GTQ0QnVxjUDW21GQ6nJ4mfcss+Mb+QZboqE WxCWRrAcmGMM7N5iAvxcGp37GXUOvSpDM07CkyOeqctg+PmmboBwvRL61Us1tzdrpSqk 6zGQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=sender:x-gm-message-state:mime-version:from:to:cc:subject:date :message-id:x-original-sender:x-original-authentication-results :precedence:mailing-list:list-id:x-spam-checked-in-group:list-post :list-help:list-archive:list-subscribe:list-unsubscribe; bh=xnjMEUINErHhqE4aDT6T5wj/xAFMYvQhH+kY/jDkXdI=; b=rDCG9/QxJIOxcwQcsrnP7mQXoeTnfjhXStN6Tunit74HBewnNxatSgJM1lZ1pY7H90 tex62hd8OK+/VjojwLUgHROVUUfH/vG9FZRA3ltc9MjcnGY2paQzFz2tgEY4fr72jhyZ 8tKDQP23GKZqDF85mHYpOQVaxPELOveOTl6tGlVxB/2b2mlVYcxNqheQbJz5+OggEvkL IfGwSnOM/8yQ/IhM6YDqH2rYAMtADqwpBPqoo73ZSmWhASFTe4EI8+J0NKK6bobwYEEI NluxtDZPwK+YR2iqg7VJDLJ2VTyItapJ+1C1BM+4Ph8DViZlYxJYpix7hbCW+kAa8wes lvvg== Sender: swupdate@googlegroups.com X-Gm-Message-State: AKwxyteOkVbOiQ0cBJbmP26MFNwwhFG2CA7pi9WIDZRScWfs12d+/+e4 Blpp1wyH9/e2pWtfRI4s7as= X-Google-Smtp-Source: AH8x226dMzAjN1pOdjyWv+q/tL2GWLaFbFc5UUUxSSG/bHGIT2GP/Gb+uWpSuFuNdjLqXnaBXnb8Cg== X-Received: by 10.46.124.7 with SMTP id x7mr74980ljc.10.1517493606704; Thu, 01 Feb 2018 06:00:06 -0800 (PST) MIME-Version: 1.0 X-BeenThere: swupdate@googlegroups.com Received: by 10.25.219.92 with SMTP id s89ls1106645lfg.8.gmail; Thu, 01 Feb 2018 06:00:05 -0800 (PST) X-Received: by 10.25.41.140 with SMTP id p134mr2828425lfp.17.1517493605932; Thu, 01 Feb 2018 06:00:05 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1517493605; cv=none; d=google.com; s=arc-20160816; b=f5ewMIAPHNwDt1qFuuNc7Ety3vW3vZbYDSzlMAfhmf1TEJWJPekH1TeevPFjTVxF3g CRgB3OzlBrvNCDgKejZe7bMRKT1RR+wpQP926NxRHI4HQFZs1mHiFJsmy5fvBEMcfM4g AoA349pb0OzUKUmeF35NJzMDnBuKvalqc0G0sLP1QxCg9J78m0/cwHp5sb5Z8IjHhrtj x2I049r3Nvu3cIx8y6DAvhGbhwojdTRMwYmAD4EAHI7tJwblGsXM8XOti70Ywh9DNizh wZJFh/3CFHQM12FTchhODQkjpeNFHfxMaujqpxWMRNshuDqn92RMP7SBjFFtDRSnTkVD TPGw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=message-id:date:subject:cc:to:from:arc-authentication-results; bh=loyDTXTKRN/UloPqVGzcNPSwFoU2AIfzsQjmTlgEjvQ=; b=bCLC/3+PlFjgp4vDW7QDjXpz4aHQjFfsTxhHNH8GN79Zt3gNixII/MiNJl8wa52Sk2 zEMnUaSFswjMYBVmsUGnSfdxPDR77pS1iM6fcHLssxVvLEzNAWYPJi9v+Otb1I6w2uxa zjGNp28XBLExXATEkqh067S4vbQ0gVc041PUMKksRNXypIYvVvWQPPecxNCY1LuaMQyp +h88W7WVvsgMl3lIajvwKvYYuj/vKlCrcZcYde7FmrtFQCF0RPy2YYru3lIAEcdBJySI QuKQnI7lUuutg89f9eJ6iXyMSaSraTS4DxvLr4b65y/LSxEryY8h+mnFfn/6VFIniHBV 7Cyg== ARC-Authentication-Results: i=1; gmr-mx.google.com; spf=pass (google.com: domain of christian.storm@siemens.com designates 192.35.17.2 as permitted sender) smtp.mailfrom=christian.storm@siemens.com Received: from thoth.sbs.de (thoth.sbs.de. [192.35.17.2]) by gmr-mx.google.com with ESMTPS id n69si920171lje.4.2018.02.01.06.00.05 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 01 Feb 2018 06:00:05 -0800 (PST) Received-SPF: pass (google.com: domain of christian.storm@siemens.com designates 192.35.17.2 as permitted sender) client-ip=192.35.17.2; Received: from mail3.siemens.de (mail3.siemens.de [139.25.208.14]) by thoth.sbs.de (8.15.2/8.15.2) with ESMTPS id w11E05Fv017135 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Thu, 1 Feb 2018 15:00:05 +0100 Received: from MD1KR9XC.ww002.siemens.net ([139.25.69.251]) by mail3.siemens.de (8.15.2/8.15.2) with ESMTP id w11E05Tw003066; Thu, 1 Feb 2018 15:00:05 +0100 From: Christian Storm To: swupdate@googlegroups.com Cc: Christian Storm Subject: [swupdate] [PATCH] doc: add documentation for EFI Boot Guard Date: Thu, 1 Feb 2018 14:59:58 +0100 Message-Id: <20180201135958.1228-1-christian.storm@siemens.com> X-Mailer: git-send-email 2.16.1 X-Original-Sender: christian.storm@siemens.com X-Original-Authentication-Results: gmr-mx.google.com; spf=pass (google.com: domain of christian.storm@siemens.com designates 192.35.17.2 as permitted sender) smtp.mailfrom=christian.storm@siemens.com Precedence: list Mailing-list: list swupdate@googlegroups.com; contact swupdate+owners@googlegroups.com List-ID: X-Spam-Checked-In-Group: swupdate@googlegroups.com X-Google-Group-Id: 605343134186 List-Post: , List-Help: , List-Archive: , List-Unsubscribe: , Signed-off-by: Christian Storm Reviewed-by: Stefano Babic --- 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 -