From 19325fff0bcef9bb12379859ffa46b6205db814a Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Tue, 14 Jul 2020 00:21:58 -0700 Subject: [PATCH 01/28] initial version of platform-fw-update hld --- doc/platform-fw-update/platform-fw-update.md | 360 +++++++++++++++++++ 1 file changed, 360 insertions(+) create mode 100644 doc/platform-fw-update/platform-fw-update.md diff --git a/doc/platform-fw-update/platform-fw-update.md b/doc/platform-fw-update/platform-fw-update.md new file mode 100644 index 0000000000..1b2dbbd03d --- /dev/null +++ b/doc/platform-fw-update/platform-fw-update.md @@ -0,0 +1,360 @@ +# SONiC PLATFORM FW UPDATE + +## High Level Design document + +## Table of contents +- [About this manual](#about-this-manual) +- [Revision](#revision) +- [Abbreviations](#abbreviations) +- [1 Introduction](#1-introduction) + - [1.1 Feature overview](#11-feature-overview) + - [1.2 Requirements](#12-requirements) + - [1.2.1 Functionality](#121-functionality) + - [1.2.2 Command interface](#122-command-interface) + - [1.2.3 Error handling](#123-error-handling) + - [1.2.4 Event logging](#124-event-logging) +- [2 Design](#2-design) + - [2.1 Overview](#21-overview) + - [2.2 Platform FW update](#22-platform-fw-update) + - [2.2.1 Platform FW Update Manifest file](#221-platform-fw-update-manifest-file) + - [2.2.2 Platform FW Update from running image](#222-platform-fw-update-running-image) + - [2.2.3 Platform FW Update from next boot image](#223-platform-fw-update-next-boot-image) + - [2.2.4 Platform FW Update from a fw-update file](#224-platform-fw-update-a-fw-update-file) +- [3 Flows](#3-flows) + - [3.1 platform fw update with running image](#31-platform-fw-update-w-running-image) + - [3.2 platform fw update with next boot image](#32-platform-fw-update-w-next-boot-image) + - [3.3 platform fw update with --fw-image option](#33-platform-fw-update-w-next-boot-image) +- [4 Use cases](#3-use-cases) + - [4.1 fast/warm/cold reboot](#41-fast-warm-cold-reboot) + - [4.2 kubernate](#42-kubernate) + - [4.3 sonic image upgrade](#43-sonic-image-upgrade) + - [4.4 query option](#43-query-option) +- [5 Tests](#5-tests) + - [5.1 Unit tests](#51-unit-tests) + +## About this manual + +This document provides the platform component FW update interface requirement in SONiC. + +## Revision + +| Rev | Date | Author | Description | +|:---:|:----------:|:--------------:|:----------------------------------| +| 0.1 | 13/07/2020 | Sujin Kang | Initial version | + +## Abbreviations + +| Term | Meaning | +|:-------|:----------------------------------------------------| +| FW | Firmware | +| SONiC | Software for Open Networking in the Cloud | +| BIOS | Basic Input/Output System | +| CPLD | Complex Programmable Logic Device | +| SSD | Solid State Drive | +| N/A | Not Applicable/Not Available | + +## List of figures + +[Figure 1: platform fw update High Level Design](#figure-1-platform-fw-update-high-level-design) + +## List of tables + + +# 1 Introduction + +## 1.1 Feature overview + +This platform fw update framework will provide a unified way to update the plaform fw on SONiC devices. + +Platform firmware update will check the predefined image path (/usr/share/sonic/device//fw-update/) and parse the Manifest.json file to learn about the file list and perform if any higher version image is available. + +## 1.2 Requirements + +### 1.2.1 Functionality + +**This feature will support the following functionality:** +1. Automatic FW installation for particular platform component in the current image for a specific boot-type if specified +1. Automatic FW installation for all available platform components in the current image for a specific boot-type if specified +2. Automatic FW installation for particular platform component in the next available image for a specific boot-type if specified +1. Automatic FW installation for all available platform components in the next available image for a specific boot-type if specified +3. Querying current FW version of platform components on a SONiC device +4. Querying available platform component FW updates in the current image +4. Querying available platform component FW updates in the next available image +4. Querying available platform component FW updates in a FW image files + +### 1.2.2 Command interface + +platform-fw-update (--sonic-image=next/current|--fw-image=) --reboot=cold/fast/warm/none(default:any) --component=cpld/ssd/abot + +**This feature will support the following options:** +1. --reboot=fast/warm/cold/powercycle/none/{default: any} +2. --sonic-image=current/next => the source image for platform FW update +3. --fw-image= => for nettools/kubernete +4. --components=ssd, cpld, bootloader, (uefi) bios +5. --query => what components fw images are available and what boot-type are supported for each component. +6. --yes(|-y) => + +### 1.2.3 Error handling + +**This feature will provide error handling for the next situations:** +1. Invalid input +2. Incompatible options/parameters + +**Note:** FW binary validation (checksum, format, etc.) should be done by the platform specific component update plugin + +### 1.2.4 Event logging + +**This feature will provide event logging for the next situations:** + +###### Table 1: Event logging + +| Event | Severity | +|:------------------------------------------|:---------| + +**Note:** Some extra information also will be logged: + +# 2 Design + +## 2.1 Overview + +![Platform FW Update High Level Design](images/platform-fw-update-hld.svg "Figure 1: Platform FW Update High Level Design") + +###### Figure 1: Platform FW Update High Level Design + +In order to improve scalability and performance a modern network switches provide different architecture solutions: +### 2.1.2 Steps +1. Option parsing +2. Image parsing + Check fw version and scripts version on current image + Check if scripts & images are available at the expected location (based on --image option) and check the versions +3. For each component + Move to the fw update location + Call each firmware update script with --reboot option + + The image & scripts location : + /usr/share/sonic/device//fw-update// + Example: /usr/share/sonic/device/x86-64_dell-s6100-c2538-r0/fw-update/ssd/ + File list: + Component update script : _fw_update + Image files : .gz + + +## 2.2 Platform FW Update + +### 2.2.1 Platform firmware update Manifest file +This file includes the information of platform components which supports the firmware updates for a specific platform. +It's located at /usr/share/sonic/device//fw-update/ and file name is Manifest.json. +``` +Manifest.json +{ + "component":{ + "cpld":{ + "image":{ + "name":"cpld.gz + "version":"" + "md5sum":"" + } + "script":{ + "name":"cpld_fw_update" + "version":"1.0" + } + "require_reboot":"cold" + } + "aboot":{ + "image":{ + "name":"aboot.gz" + "version":"" + "md5sum":"" + } + "script":{ + "name":"aboot_fw_update" + "version":"1.0" + "md5sum":"" + } + } + } +} +``` + +### 2.2.2 platform fw update from running image + +Platform FW update can update the platform component firmware from running image using the option `--sonic-image=current`. +The image and update script is supposed to be located at /usr/share/sonic/device//fw-update/. + + + +``` +/usr/share/sonic/device//fw-update/ + | + --Manifest.json + --// + | + --/_fw_upgrade + --/ +``` +Example: +``` +/usr/share/sonic/device/x86-64_dell-s6100-c2538-r0/fw-update/ + | + --Manifest.json + --/ssd/ + | + --/ssd_fw_upgrade + --/ + | + --/cpld/ + | + --/cpld_fw_upgrade + --/ +``` + +### 2.2.3 platform firmware update from next boot image + +Platform FW update can update the platform component firmware from next available image using the option `--sonic-image=next`. +The image and update script is supposed to be located at /usr/share/sonic/device//fw-update/. +``` +/usr/share/sonic/device//fw-update/ + | + --Manifest.json + --// + | + --/_fw_upgrade + --/ +``` +Example: +``` +/tmp/image-20191130.40-fs/usr/share/sonic/device/x86-64_dell-s6100-c2538-r0/fw-update/ + | + --Manifest.json + --/ssd/ + | + --/ssd_fw_upgrade + --/ + | + --/cpld/ + | + --/cpld_fw_upgrade + --/ + +``` + +### 2.2.4 platform firmware update from a firmware image file + +Platform FW update can update the platform component firmware from a firmware iamge using the option `--fw-image=`. +The image and update script is supposed to be located at /fw-update/. + +Example: +``` +./fw-update/ + | + --Manifest.json + --/ssd/ + | + --/ssd_fw_upgrade + --/ + | + --/cpld/ + | + --/cpld_fw_upgrade + --/ + +``` + +# 3 Flows + +## 3.1 Platform FW update with current running image + +![Platform FW update flow with current running image](images/platform_fw_update_with_current_image.svg "Figure 1: Platform FW update flow with current running image") + +###### Figure 1: Platform FW update flow from current running image + +## 3.2 Platform FW update with next boot image + +![Platform FW update flow with next boot image](images/platform_fw_update_with_next_image.svg "Figure 2: Platform FW update flow from next boot image") + +###### Figure 2: Platform FW update flow from next boot image + +## 3.3 Platform FW update with --fw-image option + +![Platform FW update with a specific fw update file](images/platform_fw_update_with_fw_image.svg "Figure 3: Platform FW update flow using a specific fw update file") + +###### Figure 3: Platform FW update flow using a specific fw update file + +# 4 Use cases + +## 4.1 Fast/warm/cold reboot + --image=next/current & --reboot=fast + platform_fw_update --reboot=fast --sonic-image=next --component=ssd + + ``` + from sonic_installer.bootloader import get_bootloader + + PLATFORM_FW_UPDATE="/usr/bin/platform-fw-update" + + bootloader = get_bootloader() + curimage = bootloader.get_current_image() + nextimage = bootloader.get_next_image() + If [[ nextimage == curimage ]]; then + NEXT_BOOT_IMAGE=current + else + NEXT_BOOT_IMAGE=next + fi + + if [[ -x ${PLATFORM_FW_UPDATE} ]]; then +    debug "updating platform fw for ${REBOOT_TYPE}" +    ${PLATFORM_FW_UPDATE} --reboot=${REBOOT_TYPE} --image={NEXT_BOOT_IMAGE} --component=[all] + fi +  + if [ -x ${DEVPATH}/${PLATFORM}/${PLAT_REBOOT} ]; then + … + ``` +## 4.2 Kubernete + --fw-image=.gz + Image and script location to be used for fw update + Command to perform the firmware upgrade + platform_fw_update --reboot=none --fw-image= --component=(cpld(,ssd(,abot))) + Example: `platform_fw_update --reboot=none --fw-image=fw-update.gz --component=aboot` + +## 4.3 Sonic_to_Sonic upgrade + --sonic-image=next + Image and script location to be used for fw update + FS_MOUNTPOINT="/tmp/image-${TARGET_FW#SONiC-OS-}-fs" + /$FS_MOUNTPOINT/usr/share/sonic//fw-update// + Command to perform the firmware upgrade + platform_fw_update --reboot= --sonic-image=next --component=(cpld(,ssd(,aboot)))` + Example - cold reboot case: `platform_fw_update --reboot=cold --sonic-image=next --component=cpld, ssd` + Example - fast/warm reboot case: `platform_fw_update --reboot=fast --sonic-image=next --component=ssd` +## 4.4 Query option + --query + Command to query the fw update information + Query all available fw image version and reboot required type from current running image: + `platform_fw_update --sonic-image=current --query` + Query all available fw image version and reboot required type from next boot image: + `platform_fw_update --sonic-image=next --query` + Query the available fw image version and reboot required type from manual fw-update image: + `platform_fw_update --fw-image=fw-update.gz --query` + Query the specific component fw image version and reboot required type from next boot image: + `platform_fw_update --sonic-image=next --component=cpld,ssd --query` + Query the installed fw image version information on the device: + `platform_fw_update --query` + + Output format : + : + FW version available : + Required reboot : + Example : + cpld: + FW version available : 5 + Required reboot : cold + +# 5 Tests + +## 5.1 Unit tests + +1. Query available fw version and scripts in the current running image +2. Query available fw version and scripts in the next boot image +3. Query available fw version and scripts in a specific fw image +4. Query current fw version +5. Update Platform FW images from the current running image +6. Update Platform FW images from the next boot image +7. Update Platform FW images from a specific fw-update file From fc6ea86ba7b4a0f3a116dba69e95c8a3fad53333 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Sun, 26 Jul 2020 15:10:50 -0700 Subject: [PATCH 02/28] Update fwutil to support the automatic fw update instead of having a separate utility to perform similar job --- doc/fwutil/fwutil.md | 90 ++++- doc/platform-fw-update/platform-fw-update.md | 360 ------------------- 2 files changed, 81 insertions(+), 369 deletions(-) delete mode 100644 doc/platform-fw-update/platform-fw-update.md diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index 05084bb99b..ed44a6039f 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -340,7 +340,7 @@ The purpose of the update commands group is to provide an interface for automatic FW installation of various platform components. Automatic FW installation requires platform_components.json to be created and placed at: -_sonic-buildimage/device///platform_components.json_ +_sonic-buildimage/device///platform_fw_updatecomponents.json_ **Example:** 1. Non modular chassis platform @@ -350,15 +350,15 @@ _sonic-buildimage/device///platform_components.jso "Chassis1": { "component": { "BIOS": { - "firmware": "/etc//fw//chassis1/bios.bin", + "firmware": "/usr/share/sonic///fw_update/bios.bin", "version": "0ACLH003_02.02.010" }, "CPLD": { - "firmware": "/etc//fw//chassis1/cpld.bin", + "firmware": "/usr/share/sonic///fw_update/cpld.bin", "version": "10" }, "FPGA": { - "firmware": "/etc//fw//chassis1/fpga.bin", + "firmware": "/usr/share/sonic///fw_update/fpga.bin", "version": "5" } } @@ -374,15 +374,15 @@ _sonic-buildimage/device///platform_components.jso "Chassis1": { "component": { "BIOS": { - "firmware": "/etc//fw//chassis1/bios.bin", + "firmware": "/usr/share/sonic///fw_update/bios.bin", "version": "0ACLH003_02.02.010" }, "CPLD": { - "firmware": "/etc//fw//chassis1/cpld.bin", + "firmware": "/usr/share/sonic///fw_update/cpld.bin", "version": "10" }, "FPGA": { - "firmware": "/etc//fw//chassis1/fpga.bin", + "firmware": "/usr/share/sonic///fw_update/fpga.bin", "version": "5" } } @@ -392,11 +392,11 @@ _sonic-buildimage/device///platform_components.jso "Module1": { "component": { "CPLD": { - "firmware": "/etc//fw//module1/cpld.bin", + "firmware": "/usr/share/sonic///fw_update/cpld.bin", "version": "10" }, "FPGA": { - "firmware": "/etc//fw//module1/fpga.bin", + "firmware": "/usr/share/sonic///fw_update/fpga.bin", "version": "5" } } @@ -404,6 +404,38 @@ _sonic-buildimage/device///platform_components.jso } } ``` +3. Platform component fw update configuration with platform specific script and boot options +```json +{ + "chassis": { + "Chassis1": { + "component": { + "BIOS": { + "firmware": "/usr/share/sonic///fw_update/bios.bin", + "script": "/usr/share/sonic///fw_update/bios_fw_update", + "version": "0ACLH003_02.02.010" + "required_reboot": "None" + "immediate_action": "No" + }, + "CPLD": { + "firmware": "/usr/share/sonic///fw_update/cpld.bin", + "script": "/usr/share/sonic///fw_update/cpld_fw_update", + "version": "10" + "required_reboot": "powercycle" + "immediate_action": "No" + }, + "FPGA": { + "firmware": "/usr/share/sonic///fw_update/fpga.bin", + "script": "/usr/share/sonic///fw_update/fpga_fw_update", + "version": "5" + "required_reboot": "cold" + "immediate_action": "Yes" + } + } + } + } +} +``` **Note:** 1. FW update will be disabled if component definition is not provided (e.g., 'BIOS': { }) @@ -454,6 +486,24 @@ Warning: New FW will be installed, continue? [y/N]: N Aborted! ``` +3. Non modular chassis platform +```bash +root@sonic:~# fwutil --yes --image=next --boot=cold --immediate=yes +Warning: +... +FW update in progress ... +... +root@sonic:~# fwutil --yes --image=next --boot=any --immediate=no +Warning: +... +FW update in progress ... +... +root@sonic:~# fwutil --yes --image=next --boot=any --immediate=yes --component=ssd +Warning: +... +FW update in progress ... +... +``` **Supported options:** 1. -y|--yes - automatic yes to prompts. Assume "yes" as answer to all prompts and run non-interactively @@ -490,6 +540,27 @@ Aborted! ###### Figure 5: FW install (modular) flow +## 3.4 Update component FW + +### 3.4.1 Non modular chassis platform + +![FW update (non modular) flow](images/update_non_modular_flow.svg "Figure 4: FW update (non modular) flow") + +###### Figure 6: FW update (non modular) flow + +### 3.4.2 Modular chassis platform + +![FW update (modular) flow](images/update_modular_flow.svg "Figure 5: FW update (modular) flow") + +###### Figure 7: FW update (modular) flow + +### 3.4.3 Modular chassis platform + +![Automatic FW update flow with boot and action option](images/update_w_boot_action_flow.svg "Figure 5: FW update with boot and action flow") + +###### Figure 8: Automatic FW update with boot and action flow + + # 4 Tests ## 4.1 Unit tests @@ -501,3 +572,4 @@ Aborted! 5. Install BIOS/CPLD/FPGA FW on modular chassis 6. Update BIOS/CPLD/FPGA FW on non modular chassis 7. Update BIOS/CPLD/FPGA FW on modular chassis +8. Auto Update BIOS/CPLD/FPGA FW with boot and action options diff --git a/doc/platform-fw-update/platform-fw-update.md b/doc/platform-fw-update/platform-fw-update.md deleted file mode 100644 index 1b2dbbd03d..0000000000 --- a/doc/platform-fw-update/platform-fw-update.md +++ /dev/null @@ -1,360 +0,0 @@ -# SONiC PLATFORM FW UPDATE - -## High Level Design document - -## Table of contents -- [About this manual](#about-this-manual) -- [Revision](#revision) -- [Abbreviations](#abbreviations) -- [1 Introduction](#1-introduction) - - [1.1 Feature overview](#11-feature-overview) - - [1.2 Requirements](#12-requirements) - - [1.2.1 Functionality](#121-functionality) - - [1.2.2 Command interface](#122-command-interface) - - [1.2.3 Error handling](#123-error-handling) - - [1.2.4 Event logging](#124-event-logging) -- [2 Design](#2-design) - - [2.1 Overview](#21-overview) - - [2.2 Platform FW update](#22-platform-fw-update) - - [2.2.1 Platform FW Update Manifest file](#221-platform-fw-update-manifest-file) - - [2.2.2 Platform FW Update from running image](#222-platform-fw-update-running-image) - - [2.2.3 Platform FW Update from next boot image](#223-platform-fw-update-next-boot-image) - - [2.2.4 Platform FW Update from a fw-update file](#224-platform-fw-update-a-fw-update-file) -- [3 Flows](#3-flows) - - [3.1 platform fw update with running image](#31-platform-fw-update-w-running-image) - - [3.2 platform fw update with next boot image](#32-platform-fw-update-w-next-boot-image) - - [3.3 platform fw update with --fw-image option](#33-platform-fw-update-w-next-boot-image) -- [4 Use cases](#3-use-cases) - - [4.1 fast/warm/cold reboot](#41-fast-warm-cold-reboot) - - [4.2 kubernate](#42-kubernate) - - [4.3 sonic image upgrade](#43-sonic-image-upgrade) - - [4.4 query option](#43-query-option) -- [5 Tests](#5-tests) - - [5.1 Unit tests](#51-unit-tests) - -## About this manual - -This document provides the platform component FW update interface requirement in SONiC. - -## Revision - -| Rev | Date | Author | Description | -|:---:|:----------:|:--------------:|:----------------------------------| -| 0.1 | 13/07/2020 | Sujin Kang | Initial version | - -## Abbreviations - -| Term | Meaning | -|:-------|:----------------------------------------------------| -| FW | Firmware | -| SONiC | Software for Open Networking in the Cloud | -| BIOS | Basic Input/Output System | -| CPLD | Complex Programmable Logic Device | -| SSD | Solid State Drive | -| N/A | Not Applicable/Not Available | - -## List of figures - -[Figure 1: platform fw update High Level Design](#figure-1-platform-fw-update-high-level-design) - -## List of tables - - -# 1 Introduction - -## 1.1 Feature overview - -This platform fw update framework will provide a unified way to update the plaform fw on SONiC devices. - -Platform firmware update will check the predefined image path (/usr/share/sonic/device//fw-update/) and parse the Manifest.json file to learn about the file list and perform if any higher version image is available. - -## 1.2 Requirements - -### 1.2.1 Functionality - -**This feature will support the following functionality:** -1. Automatic FW installation for particular platform component in the current image for a specific boot-type if specified -1. Automatic FW installation for all available platform components in the current image for a specific boot-type if specified -2. Automatic FW installation for particular platform component in the next available image for a specific boot-type if specified -1. Automatic FW installation for all available platform components in the next available image for a specific boot-type if specified -3. Querying current FW version of platform components on a SONiC device -4. Querying available platform component FW updates in the current image -4. Querying available platform component FW updates in the next available image -4. Querying available platform component FW updates in a FW image files - -### 1.2.2 Command interface - -platform-fw-update (--sonic-image=next/current|--fw-image=) --reboot=cold/fast/warm/none(default:any) --component=cpld/ssd/abot - -**This feature will support the following options:** -1. --reboot=fast/warm/cold/powercycle/none/{default: any} -2. --sonic-image=current/next => the source image for platform FW update -3. --fw-image= => for nettools/kubernete -4. --components=ssd, cpld, bootloader, (uefi) bios -5. --query => what components fw images are available and what boot-type are supported for each component. -6. --yes(|-y) => - -### 1.2.3 Error handling - -**This feature will provide error handling for the next situations:** -1. Invalid input -2. Incompatible options/parameters - -**Note:** FW binary validation (checksum, format, etc.) should be done by the platform specific component update plugin - -### 1.2.4 Event logging - -**This feature will provide event logging for the next situations:** - -###### Table 1: Event logging - -| Event | Severity | -|:------------------------------------------|:---------| - -**Note:** Some extra information also will be logged: - -# 2 Design - -## 2.1 Overview - -![Platform FW Update High Level Design](images/platform-fw-update-hld.svg "Figure 1: Platform FW Update High Level Design") - -###### Figure 1: Platform FW Update High Level Design - -In order to improve scalability and performance a modern network switches provide different architecture solutions: -### 2.1.2 Steps -1. Option parsing -2. Image parsing - Check fw version and scripts version on current image - Check if scripts & images are available at the expected location (based on --image option) and check the versions -3. For each component - Move to the fw update location - Call each firmware update script with --reboot option - - The image & scripts location : - /usr/share/sonic/device//fw-update// - Example: /usr/share/sonic/device/x86-64_dell-s6100-c2538-r0/fw-update/ssd/ - File list: - Component update script : _fw_update - Image files : .gz - - -## 2.2 Platform FW Update - -### 2.2.1 Platform firmware update Manifest file -This file includes the information of platform components which supports the firmware updates for a specific platform. -It's located at /usr/share/sonic/device//fw-update/ and file name is Manifest.json. -``` -Manifest.json -{ - "component":{ - "cpld":{ - "image":{ - "name":"cpld.gz - "version":"" - "md5sum":"" - } - "script":{ - "name":"cpld_fw_update" - "version":"1.0" - } - "require_reboot":"cold" - } - "aboot":{ - "image":{ - "name":"aboot.gz" - "version":"" - "md5sum":"" - } - "script":{ - "name":"aboot_fw_update" - "version":"1.0" - "md5sum":"" - } - } - } -} -``` - -### 2.2.2 platform fw update from running image - -Platform FW update can update the platform component firmware from running image using the option `--sonic-image=current`. -The image and update script is supposed to be located at /usr/share/sonic/device//fw-update/. - - - -``` -/usr/share/sonic/device//fw-update/ - | - --Manifest.json - --// - | - --/_fw_upgrade - --/ -``` -Example: -``` -/usr/share/sonic/device/x86-64_dell-s6100-c2538-r0/fw-update/ - | - --Manifest.json - --/ssd/ - | - --/ssd_fw_upgrade - --/ - | - --/cpld/ - | - --/cpld_fw_upgrade - --/ -``` - -### 2.2.3 platform firmware update from next boot image - -Platform FW update can update the platform component firmware from next available image using the option `--sonic-image=next`. -The image and update script is supposed to be located at /usr/share/sonic/device//fw-update/. -``` -/usr/share/sonic/device//fw-update/ - | - --Manifest.json - --// - | - --/_fw_upgrade - --/ -``` -Example: -``` -/tmp/image-20191130.40-fs/usr/share/sonic/device/x86-64_dell-s6100-c2538-r0/fw-update/ - | - --Manifest.json - --/ssd/ - | - --/ssd_fw_upgrade - --/ - | - --/cpld/ - | - --/cpld_fw_upgrade - --/ - -``` - -### 2.2.4 platform firmware update from a firmware image file - -Platform FW update can update the platform component firmware from a firmware iamge using the option `--fw-image=`. -The image and update script is supposed to be located at /fw-update/. - -Example: -``` -./fw-update/ - | - --Manifest.json - --/ssd/ - | - --/ssd_fw_upgrade - --/ - | - --/cpld/ - | - --/cpld_fw_upgrade - --/ - -``` - -# 3 Flows - -## 3.1 Platform FW update with current running image - -![Platform FW update flow with current running image](images/platform_fw_update_with_current_image.svg "Figure 1: Platform FW update flow with current running image") - -###### Figure 1: Platform FW update flow from current running image - -## 3.2 Platform FW update with next boot image - -![Platform FW update flow with next boot image](images/platform_fw_update_with_next_image.svg "Figure 2: Platform FW update flow from next boot image") - -###### Figure 2: Platform FW update flow from next boot image - -## 3.3 Platform FW update with --fw-image option - -![Platform FW update with a specific fw update file](images/platform_fw_update_with_fw_image.svg "Figure 3: Platform FW update flow using a specific fw update file") - -###### Figure 3: Platform FW update flow using a specific fw update file - -# 4 Use cases - -## 4.1 Fast/warm/cold reboot - --image=next/current & --reboot=fast - platform_fw_update --reboot=fast --sonic-image=next --component=ssd - - ``` - from sonic_installer.bootloader import get_bootloader - - PLATFORM_FW_UPDATE="/usr/bin/platform-fw-update" - - bootloader = get_bootloader() - curimage = bootloader.get_current_image() - nextimage = bootloader.get_next_image() - If [[ nextimage == curimage ]]; then - NEXT_BOOT_IMAGE=current - else - NEXT_BOOT_IMAGE=next - fi - - if [[ -x ${PLATFORM_FW_UPDATE} ]]; then -    debug "updating platform fw for ${REBOOT_TYPE}" -    ${PLATFORM_FW_UPDATE} --reboot=${REBOOT_TYPE} --image={NEXT_BOOT_IMAGE} --component=[all] - fi -  - if [ -x ${DEVPATH}/${PLATFORM}/${PLAT_REBOOT} ]; then - … - ``` -## 4.2 Kubernete - --fw-image=.gz - Image and script location to be used for fw update - Command to perform the firmware upgrade - platform_fw_update --reboot=none --fw-image= --component=(cpld(,ssd(,abot))) - Example: `platform_fw_update --reboot=none --fw-image=fw-update.gz --component=aboot` - -## 4.3 Sonic_to_Sonic upgrade - --sonic-image=next - Image and script location to be used for fw update - FS_MOUNTPOINT="/tmp/image-${TARGET_FW#SONiC-OS-}-fs" - /$FS_MOUNTPOINT/usr/share/sonic//fw-update// - Command to perform the firmware upgrade - platform_fw_update --reboot= --sonic-image=next --component=(cpld(,ssd(,aboot)))` - Example - cold reboot case: `platform_fw_update --reboot=cold --sonic-image=next --component=cpld, ssd` - Example - fast/warm reboot case: `platform_fw_update --reboot=fast --sonic-image=next --component=ssd` -## 4.4 Query option - --query - Command to query the fw update information - Query all available fw image version and reboot required type from current running image: - `platform_fw_update --sonic-image=current --query` - Query all available fw image version and reboot required type from next boot image: - `platform_fw_update --sonic-image=next --query` - Query the available fw image version and reboot required type from manual fw-update image: - `platform_fw_update --fw-image=fw-update.gz --query` - Query the specific component fw image version and reboot required type from next boot image: - `platform_fw_update --sonic-image=next --component=cpld,ssd --query` - Query the installed fw image version information on the device: - `platform_fw_update --query` - - Output format : - : - FW version available : - Required reboot : - Example : - cpld: - FW version available : 5 - Required reboot : cold - -# 5 Tests - -## 5.1 Unit tests - -1. Query available fw version and scripts in the current running image -2. Query available fw version and scripts in the next boot image -3. Query available fw version and scripts in a specific fw image -4. Query current fw version -5. Update Platform FW images from the current running image -6. Update Platform FW images from the next boot image -7. Update Platform FW images from a specific fw-update file From 16ed6f286185bd6373f78b05ee94ff0309785f53 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Mon, 27 Jul 2020 11:52:35 -0700 Subject: [PATCH 03/28] Auto fw update --- doc/fwutil/fwutil.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index ed44a6039f..b066bf3d5e 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -544,21 +544,18 @@ FW update in progress ... ### 3.4.1 Non modular chassis platform -![FW update (non modular) flow](images/update_non_modular_flow.svg "Figure 4: FW update (non modular) flow") - -###### Figure 6: FW update (non modular) flow +TBD ### 3.4.2 Modular chassis platform -![FW update (modular) flow](images/update_modular_flow.svg "Figure 5: FW update (modular) flow") - -###### Figure 7: FW update (modular) flow - -### 3.4.3 Modular chassis platform +TBD -![Automatic FW update flow with boot and action option](images/update_w_boot_action_flow.svg "Figure 5: FW update with boot and action flow") +### 3.4.3 Auto FW update based on the configuration file -###### Figure 8: Automatic FW update with boot and action flow +1. Find the available firmware based on boot type and immediate action type from platform specific fw update configuration file. + Exit if no configuration file exists. +2. Update the firmware using the script if it's specified in the configuration. Otherwise, fwutil will use the platform api to update the firmware. + Exit if the update fails in any step. # 4 Tests From e7cf6367eb80817f2151e09c27ea11ea34bf4b1c Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Mon, 3 Aug 2020 16:23:45 -0700 Subject: [PATCH 04/28] update --- doc/fwutil/fwutil.md | 101 ++++++++++++++++++++++++++++--------------- 1 file changed, 66 insertions(+), 35 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index b066bf3d5e..b87a52db06 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -33,6 +33,7 @@ - [3.3 Install component FW](#33-install-component-fw) - [3.3.1 Non modular chassis platform](#331-non-modular-chassis-platform) - [3.3.2 Modular chassis platform](#332-modular-chassis-platform) + - [3.4 Update component FW](#34-update-component-fw) - [4 Tests](#4-tests) - [4.1 Unit tests](#41-unit-tests) @@ -49,6 +50,8 @@ This document provides general information about FW utility implementation in SO | 0.3 | 17/09/2019 | Nazarii Hnydyn | Align flows with the platform API | | 0.4 | 18/12/2019 | Nazarii Hnydyn | CLI review feedback | | 0.5 | 05/05/2020 | Nazarii Hnydyn | Automatic FW update per component | +| 0.6 | 08/03/2020 | Sujin Kang | Automatic FW update based on fw | +| | | | update configuration file | ## Abbreviations @@ -200,8 +203,16 @@ fwutil | |--- fw -y|--yes -f|--force -i|--image= | |--- module - |--- component - |--- fw -y|--yes -f|--force -i|--image= + | |--- component + | |--- fw -y|--yes -f|--force -i|--image= + |--- chassis + | |--- component + | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= -a|--action= + |--- module + | |--- component + | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= -a|--action= + |--- fw -y|--yes -f|--force -z|--fw-image= --b|--boot= -a|--action= + ``` **Note:** can be absolute path or URL @@ -252,23 +263,25 @@ Chassis1 BIOS 0ACLH004_02.02.007 Chassis BIOS 1. Non modular chassis platform ```bash root@sonic:~# fwutil show updates --image=next -Chassis Module Component Firmware Version (current/available) Status --------- ------- ---------- --------------------- --------------------------------------- ------------------ -Chassis1 N/A BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required - CPLD /cpld.bin 5 / 10 update is required - FPGA /fpga.bin 5 / 5 up-to-date +Chassis Module Component Firmware Version (current/available) Status Required Boot Action +-------- ------- ---------- --------------------- --------------------------------------- ------------------ ----------------------- +Chassis1 N/A BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required None + CPLD /cpld.bin 5 / 10 update is required Power cycle + FPGA /fpga.bin 5 / 5 up-to-date Cold reboot + SSD /ssd.bin 4 / 5 update is required Immediate Cold/Fast reboot ``` 2. Modular chassis platform ```bash root@sonic:~# fwutil show updates --image=next -Chassis Module Component Firmware Version (current/available) Status --------- ------- ---------- --------------------- --------------------------------------- ------------------ -Chassis1 BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required - CPLD /cpld.bin 5 / 10 update is required - FPGA /fpga.bin 5 / 5 up-to-date - Module1 CPLD /cpld.bin 5 / 10 update is required - FPGA /fpga.bin 5 / 5 up-to-date +Chassis Module Component Firmware Version (current/available) Status Required Boot Action +-------- ------- ---------- --------------------- --------------------------------------- ------------------ ----------------------- +Chassis1 BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required None + CPLD /cpld.bin 5 / 10 update is required Power cycle + FPGA /fpga.bin 5 / 5 up-to-date Cold reboot + SSD /ssd.bin 4 / 5 update is required Immediate Cold/Fast reboot + Module1 CPLD /cpld.bin 5 / 10 update is required Power cycle + FPGA /fpga.bin 5 / 5 up-to-date Cold reboot ``` **Supported options:** @@ -340,7 +353,8 @@ The purpose of the update commands group is to provide an interface for automatic FW installation of various platform components. Automatic FW installation requires platform_components.json to be created and placed at: -_sonic-buildimage/device///platform_fw_updatecomponents.json_ +_sonic-buildimage/device///platform_fw_update.json_ +default image path = /usr/share/sonic///fw_update/ **Example:** 1. Non modular chassis platform @@ -404,6 +418,7 @@ _sonic-buildimage/device///platform_fw_updatecompo } } ``` + 3. Platform component fw update configuration with platform specific script and boot options ```json { @@ -414,27 +429,43 @@ _sonic-buildimage/device///platform_fw_updatecompo "firmware": "/usr/share/sonic///fw_update/bios.bin", "script": "/usr/share/sonic///fw_update/bios_fw_update", "version": "0ACLH003_02.02.010" - "required_reboot": "None" - "immediate_action": "No" }, "CPLD": { "firmware": "/usr/share/sonic///fw_update/cpld.bin", "script": "/usr/share/sonic///fw_update/cpld_fw_update", "version": "10" - "required_reboot": "powercycle" - "immediate_action": "No" }, "FPGA": { "firmware": "/usr/share/sonic///fw_update/fpga.bin", "script": "/usr/share/sonic///fw_update/fpga_fw_update", "version": "5" - "required_reboot": "cold" - "immediate_action": "Yes" } } } } } + +3. Platform component fw update configuration with platform specific script and boot options with --fw-image command line option +```json +{ + "component": { + "BIOS": { + "firmware": "bios.bin", + "script": "bios_fw_update", + "version": "0ACLH003_02.02.010" + }, + "CPLD": { + "firmware": "cpld.bin", + "script": "cpld_fw_update", + "version": "10" + }, + "FPGA": { + "firmware": "fpga.bin", + "script": "fpga_fw_update", + "version": "5" + } + } +} ``` **Note:** @@ -488,17 +519,22 @@ Aborted! ``` 3. Non modular chassis platform ```bash -root@sonic:~# fwutil --yes --image=next --boot=cold --immediate=yes +root@sonic:~# fwutil --yes --image=next --boot=cold --action=immediate +Warning: +... +FW update in progress ... +... +root@sonic:~# fwutil --yes --image=next --boot=any --action=none Warning: ... FW update in progress ... ... -root@sonic:~# fwutil --yes --image=next --boot=any --immediate=no +root@sonic:~# fwutil --yes --image=next --boot=fast --action=immediate --component=ssd Warning: ... FW update in progress ... ... -root@sonic:~# fwutil --yes --image=next --boot=any --immediate=yes --component=ssd +root@sonic:~# fwutil --yes --fw-image= --boot=cold --action=immediate --commponent=ssd Warning: ... FW update in progress ... @@ -509,8 +545,11 @@ FW update in progress ... 1. -y|--yes - automatic yes to prompts. Assume "yes" as answer to all prompts and run non-interactively 2. -f|--force - install FW regardless the current version 3. -i|--image - update FW using current/next SONiC image +4. -b|--boot - following boot option after the upgrade +5. -a|--action - immediate (optional) +6. -z|--fw-image - firmware package downloaded during run time -**Note:** the default option is _--image=current_ +**Note:** the default option is _--image=current_, _--boot=any_,and _--action=none_ # 3 Flows @@ -542,22 +581,14 @@ FW update in progress ... ## 3.4 Update component FW -### 3.4.1 Non modular chassis platform - -TBD - -### 3.4.2 Modular chassis platform - -TBD - -### 3.4.3 Auto FW update based on the configuration file +### 3.4.1 Auto FW update based on the configuration file +![Auto FW update flow with downloaded firmware package](images/update_w_fw_package.svg "Figure 6: Auto FW update flow with downloaded firmware package") 1. Find the available firmware based on boot type and immediate action type from platform specific fw update configuration file. Exit if no configuration file exists. 2. Update the firmware using the script if it's specified in the configuration. Otherwise, fwutil will use the platform api to update the firmware. Exit if the update fails in any step. - # 4 Tests ## 4.1 Unit tests From 15b74f0f812663adb60bcacdb1482b74e1580679 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Tue, 11 Aug 2020 22:40:55 -0700 Subject: [PATCH 05/28] add auto-update command to support automatic firmware update --- doc/fwutil/fwutil.md | 355 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 288 insertions(+), 67 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index b87a52db06..31912098cc 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -27,13 +27,20 @@ - [2.2.2.3 Update commands](#2223-update-commands) - [2.2.2.3.1 Overview](#22231-overview) - [2.2.2.3.2 Description](#22232-description) + - [2.2.2.4 Auto-Update commands](#2224-auto-update-commands) + - [2.2.2.4.1 Overview](#22241-overview) + - [2.2.2.4.2 Description](#22242-description) + - [2.2.2.4.3 Custom FW Update Script](#22243-custon-fw-update-script) + - [2.2.2.4.4 Auto-update Use Cases](#22243-auto-update-use-cases) - [3 Flows](#3-flows) - [3.1 Show components status](#31-show-components-status) - [3.2 Show available updates](#32-show-available-updates) - [3.3 Install component FW](#33-install-component-fw) - [3.3.1 Non modular chassis platform](#331-non-modular-chassis-platform) - [3.3.2 Modular chassis platform](#332-modular-chassis-platform) - - [3.4 Update component FW](#34-update-component-fw) + - [3.4 Auto-update component FW](#34-auto-update-component-fw) + - [3.4.1 Auto-update Platform API](#331-auto-update-w-platform-api) + - [3.4.2 Auto-update with Custom FW Update script](#332-auto-update-w-custom-fw-update-script) - [4 Tests](#4-tests) - [4.1 Unit tests](#41-unit-tests) @@ -50,8 +57,9 @@ This document provides general information about FW utility implementation in SO | 0.3 | 17/09/2019 | Nazarii Hnydyn | Align flows with the platform API | | 0.4 | 18/12/2019 | Nazarii Hnydyn | CLI review feedback | | 0.5 | 05/05/2020 | Nazarii Hnydyn | Automatic FW update per component | -| 0.6 | 08/03/2020 | Sujin Kang | Automatic FW update based on fw | -| | | | update configuration file | +| 0.6 | 08/03/2020 | Sujin Kang | Add firmware auto-update command | +| | | | based on platform-fw-update.json, | +| | | | support custom component fw script| ## Abbreviations @@ -68,6 +76,7 @@ This document provides general information about FW utility implementation in SO | BIOS | Basic Input/Output System | | CPLD | Complex Programmable Logic Device | | FPGA | Field-Programmable Gate Array | +| SSD | Solid State Drive | | URL | Uniform Resource Locator | | API | Application Programming Interface | | N/A | Not Applicable/Not Available | @@ -198,13 +207,15 @@ fwutil | |--- fw -y|--yes | |--- update - |--- chassis - | |--- component - | |--- fw -y|--yes -f|--force -i|--image= - | - |--- module - | |--- component - | |--- fw -y|--yes -f|--force -i|--image= +| |--- chassis +| | |--- component +| | |--- fw -y|--yes -f|--force -i|--image= +| | +| |--- module +| |--- component +| |--- fw -y|--yes -f|--force -i|--image= +| +|--- auto-update |--- chassis | |--- component | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= -a|--action= @@ -284,8 +295,20 @@ Chassis1 BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH FPGA /fpga.bin 5 / 5 up-to-date Cold reboot ``` +3. Custom FW Package +```bash +root@sonic:~# fwutil show updates --fw-image=fw_update.tar.gz +Component Firmware Version (current/available) Status Required Boot Action +---------- --------------------- --------------------------------------- ------------------ ----------------------- +BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required None +CPLD /cpld.bin 5 / 10 update is required Power cycle +FPGA /fpga.bin 5 / 5 up-to-date Cold reboot +SSD /ssd.bin 4 / 5 update is required Immediate Cold/Fast reboot +``` + **Supported options:** 1. -i|--image - show updates using current/next SONiC image +2. -z|--fw-image - show updates using custom FW package **Note:** the default option is _--image=current_ @@ -419,55 +442,6 @@ default image path = /usr/share/sonic///fw_update/ } ``` -3. Platform component fw update configuration with platform specific script and boot options -```json -{ - "chassis": { - "Chassis1": { - "component": { - "BIOS": { - "firmware": "/usr/share/sonic///fw_update/bios.bin", - "script": "/usr/share/sonic///fw_update/bios_fw_update", - "version": "0ACLH003_02.02.010" - }, - "CPLD": { - "firmware": "/usr/share/sonic///fw_update/cpld.bin", - "script": "/usr/share/sonic///fw_update/cpld_fw_update", - "version": "10" - }, - "FPGA": { - "firmware": "/usr/share/sonic///fw_update/fpga.bin", - "script": "/usr/share/sonic///fw_update/fpga_fw_update", - "version": "5" - } - } - } - } -} - -3. Platform component fw update configuration with platform specific script and boot options with --fw-image command line option -```json -{ - "component": { - "BIOS": { - "firmware": "bios.bin", - "script": "bios_fw_update", - "version": "0ACLH003_02.02.010" - }, - "CPLD": { - "firmware": "cpld.bin", - "script": "cpld_fw_update", - "version": "10" - }, - "FPGA": { - "firmware": "fpga.bin", - "script": "fpga_fw_update", - "version": "5" - } - } -} -``` - **Note:** 1. FW update will be disabled if component definition is not provided (e.g., 'BIOS': { }) 2. FW version will be read from image if `version` field is not provided @@ -517,24 +491,142 @@ Warning: New FW will be installed, continue? [y/N]: N Aborted! ``` -3. Non modular chassis platform + +**Supported options:** +1. -y|--yes - automatic yes to prompts. Assume "yes" as answer to all prompts and run non-interactively +2. -f|--force - install FW regardless the current version +3. -i|--image - update FW using current/next SONiC image + +**Note:** the default option is _--image=current_ + +#### 2.2.2.4 Auto-update commands + +##### 2.2.2.4.1 Overview + +The purpose of the auto-update commands group is to provide an interface +for automatic FW installation of various platform components. + +Automatic FW installation requires default platform_components.json to be created and placed at: +_sonic-buildimage/device///platform_fw_update.json_ +default image path = /usr/share/sonic///fw_update/ + +Auto-update command can also support the standalone custom firmware image package with --fw-image option. +The package can be any format between `.tar` or `.tar.gz`. +The `fwutil` commands uncompress the package and parse the `platform_fw_update.json` to retrieve the firmware information. + +If the script path is available for the component firmware configuration in the `platform_fw_update.json`, it means that the specific component firmware upgrade shall use the script to process the fwutil commands. +`2.2.2.4.3 Component Firmware Update Script Interface Requirement` explains the requirement of the component firmware upgrade script to interfere with the fwutil to support the auto-update command - mainly status and install. + +**Example:** + +1. Platform component fw update configuration with boot options +```json +{ + "chassis": { + "Chassis1": { + "component": { + "BIOS": { + "firmware": "/usr/share/sonic///fw_update/bios.bin", + "version": "0ACLH003_02.02.010", + "boot-action": "any" + }, + "CPLD": { + "firmware": "/usr/share/sonic///fw_update/cpld.bin", + "version": "10", + "boot-action": "power" + }, + "FPGA": { + "firmware": "/usr/share/sonic///fw_update/fpga.bin", + "version": "5", + "boot-action": "cold" + } + } + } + } +} +``` + +2. Platform component fw update configuration with platform specific script and boot options +```json +{ + "chassis": { + "Chassis1": { + "component": { + "BIOS": { + "firmware": "/usr/share/sonic///fw_update/bios.bin", + "script": "/usr/share/sonic///fw_update/bios_fw_update", + "version": "0ACLH003_02.02.010" + "boot-action": "any", + }, + "CPLD": { + "firmware": "/usr/share/sonic///fw_update/cpld.bin", + "script": "/usr/share/sonic///fw_update/cpld_fw_update", + "version": "10", + "boot-action": "power" + }, + "FPGA": { + "firmware": "/usr/share/sonic///fw_update/fpga.bin", + "script": "/usr/share/sonic///fw_update/fpga_fw_update", + "version": "5", + "boot-action": "cold" + } + } + } + } +} +``` + +3. Platform component fw update configuration with platform specific script and boot options with --fw-image command line option +```json +{ + "component": { + "BIOS": { + "firmware": "bios.bin", + "script": "bios_fw_update", + "version": "0ACLH003_02.02.010", + "boot-action": "any" + }, + "CPLD": { + "firmware": "cpld.bin", + "script": "cpld_fw_update", + "version": "10", + "boot-action": "power" + }, + "FPGA": { + "firmware": "fpga.bin", + "script": "fpga_fw_update", + "version": "5", + "boot-action": "cold" + } + } +} +``` + +**Note:** +1. FW update will be disabled if component definition is not provided (e.g., 'BIOS': { }) +2. FW version will be read from image if `version` field is not provided + +##### 2.2.2.4.2 Description + +**The following command updates FW automatically based on the fw update configuration file:** +1. Non modular chassis platform ```bash -root@sonic:~# fwutil --yes --image=next --boot=cold --action=immediate +root@sonic:~# fwutil auto-update --yes --image=next --boot=immediate_cold Warning: ... FW update in progress ... ... -root@sonic:~# fwutil --yes --image=next --boot=any --action=none +root@sonic:~# fwutil auto-update --yes --image=next --boot=any Warning: ... FW update in progress ... ... -root@sonic:~# fwutil --yes --image=next --boot=fast --action=immediate --component=ssd +root@sonic:~# fwutil auto-update --yes --image=next --boot=immediate_fast --component=ssd Warning: ... FW update in progress ... ... -root@sonic:~# fwutil --yes --fw-image= --boot=cold --action=immediate --commponent=ssd +root@sonic:~# fwutil auto-update --yes --fw-image= --boot=immediate_cold --commponent=ssd Warning: ... FW update in progress ... @@ -547,10 +639,138 @@ FW update in progress ... 3. -i|--image - update FW using current/next SONiC image 4. -b|--boot - following boot option after the upgrade 5. -a|--action - immediate (optional) -6. -z|--fw-image - firmware package downloaded during run time +6. -z|--fw-image - firmware package downloaded during run time (this is an exclusive option from --image) **Note:** the default option is _--image=current_, _--boot=any_,and _--action=none_ +##### 2.2.2.4.3 Component Firmware Update Script requirement + +##### 2.2.2.4.3.1 Overview + +The purpose of the _fw_upgrade commands group is to provide an interface for: +1. The specific platform component related information query (version, description, etc.) +2. Available component FW update related information query (fw, version, status, etc.) +2. Update the component firmware based on the following boot-action + +##### 2.2.2.4.3.1.1 Description + +**The following command displays FW utility version:** + +```bash +root@sonic:~# ssd_fw_upgrade show version +ssd_fw_upgrade version 1.0.0.0 +``` + +**The following command displays platform component name and FW version:** +```bash +root@sonic:~# ssd_fw_upgrade show status +Component Version Description +--------- ------------------ ------------ +SSD 5 / +``` + +**The following command displays available FW updates:** +```bash +root@sonic:~# ssd_fw_update show updates ./ssd_fw.bin +Component Firmware Version (current/available) Status Required Boot Action +--------- --------------------- --------------------------------------- ------------------ ----------------------- +SSD /ssd.bin 4 / 5 update is required Immediate Cold/Fast reboot +``` + +**The following command performs the component FW update:** +```bash +root@sonic:~# ssd_fw_update --boot=immediate_cold ./ssd_fw.bin +Warning: +... +FW update in progress ... +... +``` + +**Supported options:** +1. -b|--boot - following boot option after the upgrade + +**Note:** the default option is _--boot=any_ + +##### 2.2.2.4.4 Auto-update Use Cases + +##### 2.2.2.4.4.1 FW-UPDATE-PLUGIN for reboot scripts - reboot/fast-reboot/warm-reboot +During any reboot, device can update with any available firmware image if the reboot type is applicable for the firmware update. +```bash +root@sonic:~# fwutil auto-update --yes --image=next --boot=immediate_fast +``` +Example : Reboot script changes to support automatic firmware update during a reboot + + ``` + ... + from sonic_installer.bootloader import get_bootloader + ... + PLATFORM_FW_UPDATE="/usr/bin/fwutil" + ... + bootloader = get_bootloader() + curimage = bootloader.get_current_image() + nextimage = bootloader.get_next_image() + If [[ nextimage == curimage ]]; then + NEXT_BOOT_IMAGE=current + else + NEXT_BOOT_IMAGE=next + fi + ... + if [[ -x ${PLATFORM_FW_UPDATE} ]]; then +    debug "updating platform fw for ${REBOOT_TYPE}" +    ${PLATFORM_FW_UPDATE} auto-update --yes --image={NEXT_BOOT_IMAGE} --boot=${REBOOT_TYPE} + fi +  + if [ -x ${DEVPATH}/${PLATFORM}/${PLAT_REBOOT} ]; then + ... + ``` + +##### 2.2.2.4.4.2 Run time firmware update - Ex) Kubernete +During the run time, SONiC device can have a component firmware updated without interrupting the data plan if the component firmware update doesn't need any boot action. +```bash +root@sonic:~# fwutil auto-update --yes --fw-image=aboot-fw-update.tar.gz --boot=none +``` +Or, device can be updated only a specific firmware update with a possible boot option that can be supported on a certain topology. +```bash +root@sonic:~# fwutil auto-update --yes --fw-image=ssd-fw-update.tar.gz --boot=fast +``` + +##### 2.2.2.4.4.3 Sonic_to_Sonic upgrade +During the sonic image upgrade, all available platform component firmware can be upgraded. +```bash +root@sonic:~# fwutil auto-update --yes --image=next --boot=fast +``` +Also +```bash +root@sonic:~# fwutil auto-update --yes --image=next --boot=cold --component=cpld,ssd +``` +Example : SONiC firmware upgrade script changes to support automatic firmware update + + ``` + PLATFORM_FW_UPDATE="/usr/bin/fwutil" + + CURRENT_FW=`sonic_installer list |grep "Current" |awk '{print $2}'` + + if grep -q aboot /host/machine.conf; then + TARGET_FW=`unzip -p /tmp/$FILENAME boot0 |grep -m 1 "image_name" |sed -n "s/.*image-\(.*\)\".*/\1/p"` + else + TARGET_FW=`cat -v /tmp/$FILENAME |grep -m 1 "image_version" | sed -n "s/.*image_version=\"\(.*\)\".*/\1/p"` + fi + + sonic_installer install -y /tmp/$FILENAME || FAILED=1 + sync;sync;sync || exit 14 + + + if [[ -x ${PLATFORM_FW_UPDATE} ]]; then + FS_PATH="/host/image-${TARGET_FW#SONiC-OS-}/fs.squashfs" + FS_MOUNTPOINT="/tmp/image-${TARGET_FW#SONiC-OS-}-fs" + + mkdir -p "${FS_MOUNTPOINT}" + mount -t squashfs "${FS_PATH}" "${FS_MOUNTPOINT}" || exit 111 + +    ${PLATFORM_FW_UPDATE} auto-update --yes --image=next --boot=${REBOOT_TYPE} + fi + ``` + # 3 Flows ## 3.1 Show components status @@ -579,11 +799,12 @@ FW update in progress ... ###### Figure 5: FW install (modular) flow -## 3.4 Update component FW +## 3.4 Auto FW Update ### 3.4.1 Auto FW update based on the configuration file ![Auto FW update flow with downloaded firmware package](images/update_w_fw_package.svg "Figure 6: Auto FW update flow with downloaded firmware package") + 1. Find the available firmware based on boot type and immediate action type from platform specific fw update configuration file. Exit if no configuration file exists. 2. Update the firmware using the script if it's specified in the configuration. Otherwise, fwutil will use the platform api to update the firmware. @@ -600,4 +821,4 @@ FW update in progress ... 5. Install BIOS/CPLD/FPGA FW on modular chassis 6. Update BIOS/CPLD/FPGA FW on non modular chassis 7. Update BIOS/CPLD/FPGA FW on modular chassis -8. Auto Update BIOS/CPLD/FPGA FW with boot and action options +8. Auto Update BIOS/CPLD/FPGA FW with boot-action options From a16ee4373cad1c0de90a525ca6a1fd2aa5e237f4 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Tue, 11 Aug 2020 22:54:05 -0700 Subject: [PATCH 06/28] fix some command options --- doc/fwutil/fwutil.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index 31912098cc..2e2882ad46 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -218,16 +218,15 @@ fwutil |--- auto-update |--- chassis | |--- component - | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= -a|--action= + | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= |--- module | |--- component - | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= -a|--action= - |--- fw -y|--yes -f|--force -z|--fw-image= --b|--boot= -a|--action= + | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= + |--- fw -y|--yes -f|--force -i|--image= --b|--boot= + |--- fw -y|--yes -f|--force -z|--fw-image= --b|--boot= ``` -**Note:** can be absolute path or URL - ### 2.2.2 Command interface #### 2.2.2.1 Show commands From 04cc424239c72f013f1b43008978771537d3000f Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Tue, 18 Aug 2020 21:00:56 -0700 Subject: [PATCH 07/28] platform_componenets.json --- doc/fwutil/fwutil.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index 2e2882ad46..cbc9edc7bd 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -375,7 +375,7 @@ The purpose of the update commands group is to provide an interface for automatic FW installation of various platform components. Automatic FW installation requires platform_components.json to be created and placed at: -_sonic-buildimage/device///platform_fw_update.json_ +_sonic-buildimage/device///platform_components.json_ default image path = /usr/share/sonic///fw_update/ **Example:** @@ -506,14 +506,14 @@ The purpose of the auto-update commands group is to provide an interface for automatic FW installation of various platform components. Automatic FW installation requires default platform_components.json to be created and placed at: -_sonic-buildimage/device///platform_fw_update.json_ +_sonic-buildimage/device///platform_components.json_ default image path = /usr/share/sonic///fw_update/ Auto-update command can also support the standalone custom firmware image package with --fw-image option. The package can be any format between `.tar` or `.tar.gz`. -The `fwutil` commands uncompress the package and parse the `platform_fw_update.json` to retrieve the firmware information. +The `fwutil` commands uncompress the package and parse the `platform_components.json` to retrieve the firmware information. -If the script path is available for the component firmware configuration in the `platform_fw_update.json`, it means that the specific component firmware upgrade shall use the script to process the fwutil commands. +If the script path is available for the component firmware configuration in the `platform_components.json`, it means that the specific component firmware upgrade shall use the script to process the fwutil commands. `2.2.2.4.3 Component Firmware Update Script Interface Requirement` explains the requirement of the component firmware upgrade script to interfere with the fwutil to support the auto-update command - mainly status and install. **Example:** From e8c8a15ba1758224cff8d3d0d0e731ebb712146c Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Fri, 21 Aug 2020 00:06:11 -0700 Subject: [PATCH 08/28] add more custom scripts details and fw_update_reboot_plugin --- doc/fwutil/fwutil.md | 220 ++++++++++++++++++++++++++++--------------- 1 file changed, 145 insertions(+), 75 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index cbc9edc7bd..8dc52fc1a5 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -58,7 +58,7 @@ This document provides general information about FW utility implementation in SO | 0.4 | 18/12/2019 | Nazarii Hnydyn | CLI review feedback | | 0.5 | 05/05/2020 | Nazarii Hnydyn | Automatic FW update per component | | 0.6 | 08/03/2020 | Sujin Kang | Add firmware auto-update command | -| | | | based on platform-fw-update.json, | +| | | | based on platform-components.json, | | | | | support custom component fw script| ## Abbreviations @@ -218,12 +218,12 @@ fwutil |--- auto-update |--- chassis | |--- component - | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= + | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= |--- module | |--- component - | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= - |--- fw -y|--yes -f|--force -i|--image= --b|--boot= - |--- fw -y|--yes -f|--force -z|--fw-image= --b|--boot= + | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= + |--- fw -y|--yes -f|--force -i|--image= --b|--boot= + |--- fw -y|--yes -f|--force -z|--fw-image= --b|--boot= ``` @@ -278,7 +278,7 @@ Chassis Module Component Firmware Version (current/available Chassis1 N/A BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required None CPLD /cpld.bin 5 / 10 update is required Power cycle FPGA /fpga.bin 5 / 5 up-to-date Cold reboot - SSD /ssd.bin 4 / 5 update is required Immediate Cold/Fast reboot + SSD /ssd.bin 4 / 5 update is required Cold rebot, Fast reboot ``` 2. Modular chassis platform @@ -289,7 +289,7 @@ Chassis Module Component Firmware Version (current/available Chassis1 BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required None CPLD /cpld.bin 5 / 10 update is required Power cycle FPGA /fpga.bin 5 / 5 up-to-date Cold reboot - SSD /ssd.bin 4 / 5 update is required Immediate Cold/Fast reboot + SSD /ssd.bin 4 / 5 update is required Cold rebot, Fast reboot Module1 CPLD /cpld.bin 5 / 10 update is required Power cycle FPGA /fpga.bin 5 / 5 up-to-date Cold reboot ``` @@ -299,10 +299,10 @@ Chassis1 BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH root@sonic:~# fwutil show updates --fw-image=fw_update.tar.gz Component Firmware Version (current/available) Status Required Boot Action ---------- --------------------- --------------------------------------- ------------------ ----------------------- -BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required None +BIOS /bios.bin 0ACLH004_02.02.007 / NA update is required None CPLD /cpld.bin 5 / 10 update is required Power cycle -FPGA /fpga.bin 5 / 5 up-to-date Cold reboot -SSD /ssd.bin 4 / 5 update is required Immediate Cold/Fast reboot +FPGA /fpga.bin 5 / NA up-to-date Cold reboot +SSD /ssd.bin 4 / 5 update is required Cold reboot, Fast reboot ``` **Supported options:** @@ -553,21 +553,24 @@ If the script path is available for the component firmware configuration in the "component": { "BIOS": { "firmware": "/usr/share/sonic///fw_update/bios.bin", - "script": "/usr/share/sonic///fw_update/bios_fw_update", "version": "0ACLH003_02.02.010" "boot-action": "any", }, "CPLD": { "firmware": "/usr/share/sonic///fw_update/cpld.bin", - "script": "/usr/share/sonic///fw_update/cpld_fw_update", "version": "10", "boot-action": "power" }, "FPGA": { "firmware": "/usr/share/sonic///fw_update/fpga.bin", - "script": "/usr/share/sonic///fw_update/fpga_fw_update", "version": "5", "boot-action": "cold" + }, + "SSD": { + "firmware": "/usr/share/sonic///fw_update/ssd.bin", + "script": "/usr/share/sonic///fw_update/ssd_fw_update", + "version": "5", + "boot-action": "cold, fast" } } } @@ -576,24 +579,23 @@ If the script path is available for the component firmware configuration in the ``` 3. Platform component fw update configuration with platform specific script and boot options with --fw-image command line option +The firmware image ```json { "component": { "BIOS": { "firmware": "bios.bin", - "script": "bios_fw_update", "version": "0ACLH003_02.02.010", "boot-action": "any" }, "CPLD": { "firmware": "cpld.bin", - "script": "cpld_fw_update", "version": "10", "boot-action": "power" }, - "FPGA": { - "firmware": "fpga.bin", - "script": "fpga_fw_update", + "SSD": { + "firmware": "SSD.bin", + "script": "ssd_fw_update", "version": "5", "boot-action": "cold" } @@ -610,7 +612,7 @@ If the script path is available for the component firmware configuration in the **The following command updates FW automatically based on the fw update configuration file:** 1. Non modular chassis platform ```bash -root@sonic:~# fwutil auto-update --yes --image=next --boot=immediate_cold +root@sonic:~# fwutil auto-update --yes --image=next --boot=cold Warning: ... FW update in progress ... @@ -620,12 +622,12 @@ Warning: ... FW update in progress ... ... -root@sonic:~# fwutil auto-update --yes --image=next --boot=immediate_fast --component=ssd -Warning: +root@sonic:~# fwutil auto-update --yes --image=next --boot=fast --component=ssd +Warning: SSD firmware update will be performed during Fast-reboot! +Logged ... -FW update in progress ... ... -root@sonic:~# fwutil auto-update --yes --fw-image= --boot=immediate_cold --commponent=ssd +root@sonic:~# fwutil auto-update --yes --fw-image= --boot=cold --commponent=ssd Warning: ... FW update in progress ... @@ -637,7 +639,6 @@ FW update in progress ... 2. -f|--force - install FW regardless the current version 3. -i|--image - update FW using current/next SONiC image 4. -b|--boot - following boot option after the upgrade -5. -a|--action - immediate (optional) 6. -z|--fw-image - firmware package downloaded during run time (this is an exclusive option from --image) **Note:** the default option is _--image=current_, _--boot=any_,and _--action=none_ @@ -653,35 +654,55 @@ The purpose of the _fw_upgrade commands group is to provide an interf ##### 2.2.2.4.3.1.1 Description -**The following command displays FW utility version:** - +1. _fw_update show status --fw-image= +**This command displays platform component name and FW version:** ```bash -root@sonic:~# ssd_fw_upgrade show version -ssd_fw_upgrade version 1.0.0.0 +root@sonic:~# fwutil show status +Warning : doesn't support for the component platform API ``` - -**The following command displays platform component name and FW version:** ```bash -root@sonic:~# ssd_fw_upgrade show status -Component Version Description ---------- ------------------ ------------ -SSD 5 / +root@sonic:~# fwutil show status --fw-image= +=>> Fwutil will perform this command to retrieve the current component firmware installation status using the script available in the firmware update package. + `_fw_update show status --fw-image=` ``` -**The following command displays available FW updates:** +2. _fw_update show updates --fw-image= +**This command displays available FW updates:** +```bash +root@sonic:~# fwutil show updates --fw-image= +Component Firmware Version (current/available) Status Required Boot Action +--------- --------------------- --------------------------------------- ------------------ ----------------------- + .bin / + update is required> +``` +Example of show updates command with when the fw update package has only ssd firmware image. ```bash -root@sonic:~# ssd_fw_update show updates ./ssd_fw.bin +root@sonic:~# fwutil show updates --fw-image=fw_update.tar.gz +=>> Fwutil will perform this command to retrieve all available component firmware information based on platform_components.json in the firmware update package. + `_fw_update show updates --fw-image=` Component Firmware Version (current/available) Status Required Boot Action --------- --------------------- --------------------------------------- ------------------ ----------------------- -SSD /ssd.bin 4 / 5 update is required Immediate Cold/Fast reboot +SSD ssd.bin 4 / 5 update is required Cold/Fast reboot ``` -**The following command performs the component FW update:** +3. _fw_update auto-updates --fw-image= --boot=cold +**This command performs the component FW update:** ```bash -root@sonic:~# ssd_fw_update --boot=immediate_cold ./ssd_fw.bin -Warning: +root@sonic:~# fwutil auto-update --fw-image= --boot=cold +=>> Fwutil would perform the following command to perform the firmware upgrade using the available script and firmware image in the firmware update package. + `_fw_update auto-update --fw-image= --boot=cold` +Warning: <> ... -FW update in progress ... + FW update in progress ... +... +``` +Example of ssd_fw_update script interfaces for SSD FW Updates +```bash +root@sonic:~# fwutil auto-update --fw-image=fw_update.tar.gz --boot=cold +=>> this cli calls `ssd_fw_update auto-update --boot=cold ./ssd_fw.bin` +Warning: SSD FW update is starting ... +... +SSD FW update in progress ... ... ``` @@ -692,38 +713,7 @@ FW update in progress ... ##### 2.2.2.4.4 Auto-update Use Cases -##### 2.2.2.4.4.1 FW-UPDATE-PLUGIN for reboot scripts - reboot/fast-reboot/warm-reboot -During any reboot, device can update with any available firmware image if the reboot type is applicable for the firmware update. -```bash -root@sonic:~# fwutil auto-update --yes --image=next --boot=immediate_fast -``` -Example : Reboot script changes to support automatic firmware update during a reboot - - ``` - ... - from sonic_installer.bootloader import get_bootloader - ... - PLATFORM_FW_UPDATE="/usr/bin/fwutil" - ... - bootloader = get_bootloader() - curimage = bootloader.get_current_image() - nextimage = bootloader.get_next_image() - If [[ nextimage == curimage ]]; then - NEXT_BOOT_IMAGE=current - else - NEXT_BOOT_IMAGE=next - fi - ... - if [[ -x ${PLATFORM_FW_UPDATE} ]]; then -    debug "updating platform fw for ${REBOOT_TYPE}" -    ${PLATFORM_FW_UPDATE} auto-update --yes --image={NEXT_BOOT_IMAGE} --boot=${REBOOT_TYPE} - fi -  - if [ -x ${DEVPATH}/${PLATFORM}/${PLAT_REBOOT} ]; then - ... - ``` - -##### 2.2.2.4.4.2 Run time firmware update - Ex) Kubernete +##### 2.2.2.4.4.1 Run time firmware update - Ex) Kubernete During the run time, SONiC device can have a component firmware updated without interrupting the data plan if the component firmware update doesn't need any boot action. ```bash root@sonic:~# fwutil auto-update --yes --fw-image=aboot-fw-update.tar.gz --boot=none @@ -733,7 +723,7 @@ Or, device can be updated only a specific firmware update with a possible boot o root@sonic:~# fwutil auto-update --yes --fw-image=ssd-fw-update.tar.gz --boot=fast ``` -##### 2.2.2.4.4.3 Sonic_to_Sonic upgrade +##### 2.2.2.4.4.2 Sonic_to_Sonic upgrade During the sonic image upgrade, all available platform component firmware can be upgraded. ```bash root@sonic:~# fwutil auto-update --yes --image=next --boot=fast @@ -770,6 +760,86 @@ Example : SONiC firmware upgrade script changes to support automatic firmware up fi ``` +##### 2.2.2.4.4.3 FW-UPDATE-PLUGIN for reboot scripts - reboot/fast-reboot/warm-reboot +If any firmware needs to be done during the reboot, which needs to be done only after any service or +docker stops and/or disk unmounting is done, then each component platform update needs to log the firmware update detail +in _fw_update_.log which can be read by fw_update_reboot_plugin during reboot. + +```bash +root@sonic:~# fwutil auto-update --yes --image= --boot= +Available FW updates with from boot image : COMPONENT1 + firmware update will be done during with version <#new_version> (current version #current_version) + firmware update has been logged in _fw_update_.log +... + firmware update is starting with version <#new_version2> (current version #current_version2) +... + firmware update is in progress with version <#new_version2> (current version #current_version2) +... + firmware update is done during with version <#new_version> (current version #current_version) +... + firmware update has been logged in _fw_update_.log +All firmware update has been completed. +``` +Example 1: SSD firmware update is available for fast-reboot upgrade path. +SSD firmware update is logged in _fw_update_fast-reboot.log file and it will be updated during fast-reboot. +```bash +root@sonic:~# fwutil auto-update --yes --image=next --boot=fast +Available FW updates with fast-reboot from next boot image : SSD +SSD firmware update will be done during fastreboot with version 5 (current version 4) +SSD firmware update is logged in _fw_update_fast-reboot.log +All firmware update has been completed. +``` +Example 2: SSD and CPLD update is available for cold reboot upgrade path. +SSD firmware update is logged in _fw_update_cold-reboot.log and it will be updated during cold-reboot. +CPLD firmware update is going to be done with this command and the firmware update completion's also logged +```bash +root@sonic:~# fwutil auto-update --yes --image=next --boot=cold +SSD firmware update will be done during cold-reboot with version 5 (current version 4) +SSD firmware update is logged in _fw_update_cold-reboot.log +... +CPLD firmware update is starting with version 5 (current version 4) +... +CPLD firmware update is in progress with version 5 (current version 4) +... +CPLD firmware update is completed with version 5 (current version 4) +... +CPLD firmware update has been logged in _fw_update_cold-reboot.log +All firmware update has been completed. +``` + +Now _fw_update_.log has been created to log the firmware update that need to be run duirng reboot. +Example of _fw_update_fast-reboot.log with SSD firmware update which needs to run during fast-reboot. +```bash +SSD firmware update needs to be run in fast-reboot. +CMD : ssd_fw_update auto-update --boot=fast ./ssd_fw.bin +``` +Example of _fw_update_cold-reboot.log with SSD firmware update which needs to be run during cold reboot. +```bash +SSD firmware update needs to be run in cold-reboot. +CMD : ssd_fw_update auto-update --boot=cold ./ssd_fw.bin +CPLD firmware update needs to be run in cold-reboot. +``` + +To support the automatic firmware upgrade during reboot based on the /tmp/_fw_update_.log, +`fw_update_reboot_plugin` needs to be added to parse the log file and perform the component firmware updates using the command in the log file. +`fw_update_reboot_plugin` parses /tmp/_fw_update_.log based on the --boot option passing to the plugin. +And it searches for the firmware update command from the log file and performs the firmware updates if needed. + +Example : Reboot script changes to support the automatic firmware update during a reboot using the fw_update_reboot_plugin. +```bash + ... + FW_UPDATE_REBOOT_PLUGIN="/usr/bin/fw_update_reboot_plugin" + ... + ... + if [[ -x ${FW_UPDATE_REBOOT_PLUGIN} ]]; then +    debug "updating platform fw for ${REBOOT_TYPE}" +    ${FW_UPDATE_REBOOT_PLUGIN} --boot=${REBOOT_TYPE} + fi +  + if [ -x ${DEVPATH}/${PLATFORM}/${PLAT_REBOOT} ]; then + ... +``` + # 3 Flows ## 3.1 Show components status @@ -804,7 +874,7 @@ Example : SONiC firmware upgrade script changes to support automatic firmware up ![Auto FW update flow with downloaded firmware package](images/update_w_fw_package.svg "Figure 6: Auto FW update flow with downloaded firmware package") -1. Find the available firmware based on boot type and immediate action type from platform specific fw update configuration file. +1. Find the available firmware based on boot type from platform specific fw update configuration file. Exit if no configuration file exists. 2. Update the firmware using the script if it's specified in the configuration. Otherwise, fwutil will use the platform api to update the firmware. Exit if the update fails in any step. From 503c3e85b8ad9804e34a95fffd43737c93eaad23 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Thu, 10 Sep 2020 00:23:27 -0700 Subject: [PATCH 09/28] Update --- doc/fwutil/fwutil.md | 404 +++++++++++++------------------------------ 1 file changed, 122 insertions(+), 282 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index 8dc52fc1a5..a0765fb045 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -31,16 +31,14 @@ - [2.2.2.4.1 Overview](#22241-overview) - [2.2.2.4.2 Description](#22242-description) - [2.2.2.4.3 Custom FW Update Script](#22243-custon-fw-update-script) - - [2.2.2.4.4 Auto-update Use Cases](#22243-auto-update-use-cases) + - [2.2.2.4.4 Platform FW Update Reboot Plugin](#22244-plarform-fw-update-reboot-plugin) + - [2.2.2.4.5 Auto-update Use Cases](#22245-auto-update-use-cases) - [3 Flows](#3-flows) - [3.1 Show components status](#31-show-components-status) - [3.2 Show available updates](#32-show-available-updates) - [3.3 Install component FW](#33-install-component-fw) - [3.3.1 Non modular chassis platform](#331-non-modular-chassis-platform) - [3.3.2 Modular chassis platform](#332-modular-chassis-platform) - - [3.4 Auto-update component FW](#34-auto-update-component-fw) - - [3.4.1 Auto-update Platform API](#331-auto-update-w-platform-api) - - [3.4.2 Auto-update with Custom FW Update script](#332-auto-update-w-custom-fw-update-script) - [4 Tests](#4-tests) - [4.1 Unit tests](#41-unit-tests) @@ -58,8 +56,6 @@ This document provides general information about FW utility implementation in SO | 0.4 | 18/12/2019 | Nazarii Hnydyn | CLI review feedback | | 0.5 | 05/05/2020 | Nazarii Hnydyn | Automatic FW update per component | | 0.6 | 08/03/2020 | Sujin Kang | Add firmware auto-update command | -| | | | based on platform-components.json, | -| | | | support custom component fw script| ## Abbreviations @@ -117,16 +113,18 @@ we might need a dedicated FW utility. **This feature will support the following functionality:** 1. Manual FW installation for particular platform component -2. Automatic FW installation for particular platform component +2. Complete FW installation for particular platform component 3. Querying platform components and FW versions 4. Querying available FW updates for all platform components +5. Automatic FW updates for all available platform components ### 1.2.2 Command interface **This feature will support the following commands:** -1. show: display FW versions/updates -2. install: manual FW installation -3. update: automatic FW installation +1. show: Display FW versions/updates +2. install: Manual FW installation +3. update: Complete FW installation +3. auto-update: Automatic FW updates ### 1.2.3 Error handling @@ -153,10 +151,13 @@ we might need a dedicated FW utility. | FW binary downloading over URL: error | ERROR | | FW binary installation: start/end | INFO | | FW binary installation: error | ERROR | +| Auto-update reboot task creation: creat | INFO | +| Auto-update reboot task creation: error | ERROR | **Note:** Some extra information also will be logged: 1. Component location (e.g., Chassis1/Module1/BIOS) 2. Operation result (e.g., success/failure) +3. FW binary source location (e.g., current/next/custom) # 2 Design @@ -184,6 +185,7 @@ non modular chassis platforms. Both modular and non modular chassis platforms sh but may have different implementation. SONiC FW utility uses platform API to interact with the various platform components. +SONiC FW utility extends to support for the automatic firmware update based on _components.json and next reboot option. ## 2.2 FW utility @@ -216,13 +218,7 @@ fwutil | |--- fw -y|--yes -f|--force -i|--image= | |--- auto-update - |--- chassis - | |--- component - | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= - |--- module - | |--- component - | |--- fw -y|--yes -f|--force -i|--image= --b|--boot= - |--- fw -y|--yes -f|--force -i|--image= --b|--boot= + |--- fw -y|--yes -f|--force -z|--image= --b|--boot= |--- fw -y|--yes -f|--force -z|--fw-image= --b|--boot= ``` @@ -305,6 +301,15 @@ FPGA /fpga.bin 5 / NA up-t SSD /ssd.bin 4 / 5 update is required Cold reboot, Fast reboot ``` +4. Auto-update status +```bash +root@sonic:~# fwutil show auto-updates status +Component Firmware Version (current/available) Status +---------- --------------------- --------------------------------------- ------------------------- +CPLD /cpld.bin 5 / 10 updated but need a power-cycle +SSD /ssd.bin 4 / 5 scheduled in cold reboot +``` + **Supported options:** 1. -i|--image - show updates using current/next SONiC image 2. -z|--fw-image - show updates using custom FW package @@ -501,84 +506,31 @@ Aborted! #### 2.2.2.4 Auto-update commands ##### 2.2.2.4.1 Overview +The purpose of the auto-update commands group is to provide and interface for automatic fw updates of various platform components +based on the boot option and the platform firmwareupdate configuration file - platform_components.json. -The purpose of the auto-update commands group is to provide an interface -for automatic FW installation of various platform components. +The existing FWutil infra supports the upgrade of platform components which can be performed during run time. +The SSD upgrade for certain platforms requires the unmount of the filesystems and this needs to be incorporated as part of the reboot scripts. +To integrate the upgrade of these platform components which can’t be performed during run time, +the FWutil requires few more enhancements that specifies the reboot-type during which the user expects the upgrade to happen. +The fwutil infra section below indicates the necessary changes to add support for auto update during reboot. +The Platform plugins section describes the plugins that a platform must implement to support auto updates when the platform component APIs are not available. Automatic FW installation requires default platform_components.json to be created and placed at: _sonic-buildimage/device///platform_components.json_ default image path = /usr/share/sonic///fw_update/ -Auto-update command can also support the standalone custom firmware image package with --fw-image option. +Auto-update command can support the standalone custom firmware image package with --fw-image option. The package can be any format between `.tar` or `.tar.gz`. -The `fwutil` commands uncompress the package and parse the `platform_components.json` to retrieve the firmware information. +The `fwutil auto-update` commands uncompress the package and parse the `platform_components.json` to retrieve the firmware information. -If the script path is available for the component firmware configuration in the `platform_components.json`, it means that the specific component firmware upgrade shall use the script to process the fwutil commands. -`2.2.2.4.3 Component Firmware Update Script Interface Requirement` explains the requirement of the component firmware upgrade script to interfere with the fwutil to support the auto-update command - mainly status and install. +If the script path is available for the component firmware configuration in the `platform_components.json`, +it means that the specific component firmware upgrade shall use the script to process the fwutil commands. +`2.2.2.4.3 Component Firmware Update Script Interface Requirement` explains the requirement of the component firmware upgrade script +to interfere with the fwutil to support the auto-update command - mainly status and install. **Example:** - -1. Platform component fw update configuration with boot options -```json -{ - "chassis": { - "Chassis1": { - "component": { - "BIOS": { - "firmware": "/usr/share/sonic///fw_update/bios.bin", - "version": "0ACLH003_02.02.010", - "boot-action": "any" - }, - "CPLD": { - "firmware": "/usr/share/sonic///fw_update/cpld.bin", - "version": "10", - "boot-action": "power" - }, - "FPGA": { - "firmware": "/usr/share/sonic///fw_update/fpga.bin", - "version": "5", - "boot-action": "cold" - } - } - } - } -} -``` - -2. Platform component fw update configuration with platform specific script and boot options -```json -{ - "chassis": { - "Chassis1": { - "component": { - "BIOS": { - "firmware": "/usr/share/sonic///fw_update/bios.bin", - "version": "0ACLH003_02.02.010" - "boot-action": "any", - }, - "CPLD": { - "firmware": "/usr/share/sonic///fw_update/cpld.bin", - "version": "10", - "boot-action": "power" - }, - "FPGA": { - "firmware": "/usr/share/sonic///fw_update/fpga.bin", - "version": "5", - "boot-action": "cold" - }, - "SSD": { - "firmware": "/usr/share/sonic///fw_update/ssd.bin", - "script": "/usr/share/sonic///fw_update/ssd_fw_update", - "version": "5", - "boot-action": "cold, fast" - } - } - } - } -} -``` - -3. Platform component fw update configuration with platform specific script and boot options with --fw-image command line option +1. Platform component fw update configuration with platform specific script and boot options with --fw-image command line option The firmware image ```json { @@ -586,18 +538,15 @@ The firmware image "BIOS": { "firmware": "bios.bin", "version": "0ACLH003_02.02.010", - "boot-action": "any" }, "CPLD": { "firmware": "cpld.bin", "version": "10", - "boot-action": "power" }, "SSD": { "firmware": "SSD.bin", "script": "ssd_fw_update", "version": "5", - "boot-action": "cold" } } } @@ -609,29 +558,47 @@ The firmware image ##### 2.2.2.4.2 Description -**The following command updates FW automatically based on the fw update configuration file:** -1. Non modular chassis platform +**The following command updates FW Automatically with installing the available component firmware, creating task(s) for update during reboot:** +1. auto-update command for installation and reboot task creation ```bash -root@sonic:~# fwutil auto-update --yes --image=next --boot=cold -Warning: -... -FW update in progress ... +root@sonic:~# fwutil auto-update --yes --image= --boot= +Available FW updates with from boot image : COMPONENT1 (and COMPONENT2) + firmware update will be done during with version <#new_version> (current version #current_version) ... -root@sonic:~# fwutil auto-update --yes --image=next --boot=any -Warning: + firmware update is starting with version <#new_version2> (current version #current_version2) ... -FW update in progress ... + firmware update is in progress with version <#new_version2> (current version #current_version2) ... -root@sonic:~# fwutil auto-update --yes --image=next --boot=fast --component=ssd -Warning: SSD firmware update will be performed during Fast-reboot! -Logged + firmware update is done during with version <#new_version> (current version #current_version) ... +All firmware update has been completed. +``` + +This is examples of a platform which supports the SSD firmware update during fast reboot and cold reboot with different commands +along with CPLD firmware update available only for the cold reboot which can perform a power cycle triggered by some register setting. + +Example 1: SSD firmware update is available for fast-reboot upgrade path. +SSD firmware update is logged in a platform defined designated file and it will be updated during fast-reboot. +```bash +root@sonic:~# fwutil auto-update --yes --image=next --boot=fast +Available FW updates with fast-reboot from next boot image : SSD +SSD firmware update will be done during fastreboot with version 5 (current version 4) +All firmware update has been completed. +``` +Example 2: SSD and CPLD update is available for cold reboot upgrade path. +SSD firmware update is logged in a platform defined designated file and it will be updated during cold reboot. +CPLD firmware update is going to be done with this command and the CPLD completion activity will be performed during cold reboot +once all reboot processes are finished. The CPLD completion activity for this case is a power cycle triggered by the hw register setting. +```bash +root@sonic:~# fwutil auto-update --yes --image=next --boot=cold +Available FW updates with fast-reboot from next boot image : SSD and CPLD +SSD firmware update will be done during cold-reboot with version 5 (current version 4) ... -root@sonic:~# fwutil auto-update --yes --fw-image= --boot=cold --commponent=ssd -Warning: +CPLD firmware update is in progress with version 5 (current version 4) ... -FW update in progress ... +CPLD firmware update is completed with version 5 (current version 4) ... +All firmware update has been completed. ``` **Supported options:** @@ -641,79 +608,42 @@ FW update in progress ... 4. -b|--boot - following boot option after the upgrade 6. -z|--fw-image - firmware package downloaded during run time (this is an exclusive option from --image) -**Note:** the default option is _--image=current_, _--boot=any_,and _--action=none_ - -##### 2.2.2.4.3 Component Firmware Update Script requirement +**Note:** the default option is _--image=current_ and _--boot=any_ -##### 2.2.2.4.3.1 Overview +##### 2.2.2.4.4.3 PLATFORM-FW-UPDATE-REBOOT-PLUGIN to support the platform specific fw update support for different reboot types +When Vendor doesn't have platform API ready to suppport all platform component APIs to support the auto-update interfaces, +PLATFORM-FW-UPDATE-REBOOT-PLUGIN will do the equivalent thing of auto-update platform component APIs +This plugin will create a task file for specified reboot type issued through the FWutil command. +This file will include the components that needs to be upgraded during individual reboot. +The task file will be platform dependent. It is up to the platform plugin to determine the order of upgrade. -The purpose of the _fw_upgrade commands group is to provide an interface for: -1. The specific platform component related information query (version, description, etc.) -2. Available component FW update related information query (fw, version, status, etc.) -2. Update the component firmware based on the following boot-action +Platform Plugin 1: +The platform plugin 1 will unpack the below files presented in tar in appropriate place +1. Firmware +2. Update-utility (if provided) -##### 2.2.2.4.3.1.1 Description - -1. _fw_update show status --fw-image= -**This command displays platform component name and FW version:** -```bash -root@sonic:~# fwutil show status -Warning : doesn't support for the component platform API -``` -```bash -root@sonic:~# fwutil show status --fw-image= -=>> Fwutil will perform this command to retrieve the current component firmware installation status using the script available in the firmware update package. - `_fw_update show status --fw-image=` -``` - -2. _fw_update show updates --fw-image= -**This command displays available FW updates:** -```bash -root@sonic:~# fwutil show updates --fw-image= -Component Firmware Version (current/available) Status Required Boot Action ---------- --------------------- --------------------------------------- ------------------ ----------------------- - .bin / - update is required> -``` -Example of show updates command with when the fw update package has only ssd firmware image. -```bash -root@sonic:~# fwutil show updates --fw-image=fw_update.tar.gz -=>> Fwutil will perform this command to retrieve all available component firmware information based on platform_components.json in the firmware update package. - `_fw_update show updates --fw-image=` -Component Firmware Version (current/available) Status Required Boot Action ---------- --------------------- --------------------------------------- ------------------ ----------------------- -SSD ssd.bin 4 / 5 update is required Cold/Fast reboot -``` +This plugin will create a task file for specified reboot type issued through the FWutil command. +This file will include the components that needs to be upgraded during individual reboot. +The task file will be platform dependent. It is up to the platform plugin to determine the order of upgrade. +The below plugin needs to be called by the FWutil command. +if [[ -x ${ PLATFORM_FWUTIL_CREATE_AUTO_UPDATE_TASK } ]]; then + debug "Creating task file for boot type ${boot-option}”” + ${ PLATFORM_FWUTIL_CREATE_AUTO_UPDATE_TASK } ${tar file/firmware path} ${boot-option} ${update-utility} +fi -3. _fw_update auto-updates --fw-image= --boot=cold -**This command performs the component FW update:** -```bash -root@sonic:~# fwutil auto-update --fw-image= --boot=cold -=>> Fwutil would perform the following command to perform the firmware upgrade using the available script and firmware image in the firmware update package. - `_fw_update auto-update --fw-image= --boot=cold` -Warning: <> -... - FW update in progress ... -... -``` -Example of ssd_fw_update script interfaces for SSD FW Updates -```bash -root@sonic:~# fwutil auto-update --fw-image=fw_update.tar.gz --boot=cold -=>> this cli calls `ssd_fw_update auto-update --boot=cold ./ssd_fw.bin` -Warning: SSD FW update is starting ... -... -SSD FW update in progress ... -... -``` +Platform Plugin 2: +The reboot scripts will invoke the below plugin which will analyze the corresponding task file and +execute the upgrade commands for the components present in task file. -**Supported options:** -1. -b|--boot - following boot option after the upgrade + if [[ -x ${ PLATFORM_FWUTIL_HANDLE_AUTO_UPDATE_TASK } ]]; then + debug "Handling task file for boot type ${REBOOT_TYPE}” + ${ PLATFORM_FWUTIL_HANDLE_AUTO_UPDATE_TASK } ${REBOOT_TYPE} +fi -**Note:** the default option is _--boot=any_ ##### 2.2.2.4.4 Auto-update Use Cases -##### 2.2.2.4.4.1 Run time firmware update - Ex) Kubernete +##### 2.2.2.4.4.1 Standalone firmware update during run time During the run time, SONiC device can have a component firmware updated without interrupting the data plan if the component firmware update doesn't need any boot action. ```bash root@sonic:~# fwutil auto-update --yes --fw-image=aboot-fw-update.tar.gz --boot=none @@ -723,121 +653,42 @@ Or, device can be updated only a specific firmware update with a possible boot o root@sonic:~# fwutil auto-update --yes --fw-image=ssd-fw-update.tar.gz --boot=fast ``` -##### 2.2.2.4.4.2 Sonic_to_Sonic upgrade -During the sonic image upgrade, all available platform component firmware can be upgraded. +##### 2.2.2.4.4.2 Firmware upgrade during Sonic_to_Sonic upgrade +During the sonic image upgrade, all available platform component firmware can be upgraded for the specific following boot option. ```bash -root@sonic:~# fwutil auto-update --yes --image=next --boot=fast -``` -Also -```bash -root@sonic:~# fwutil auto-update --yes --image=next --boot=cold --component=cpld,ssd -``` -Example : SONiC firmware upgrade script changes to support automatic firmware update - - ``` - PLATFORM_FW_UPDATE="/usr/bin/fwutil" - - CURRENT_FW=`sonic_installer list |grep "Current" |awk '{print $2}'` +PLATFORM_FW_UPDATE="/usr/bin/fwutil" - if grep -q aboot /host/machine.conf; then - TARGET_FW=`unzip -p /tmp/$FILENAME boot0 |grep -m 1 "image_name" |sed -n "s/.*image-\(.*\)\".*/\1/p"` - else - TARGET_FW=`cat -v /tmp/$FILENAME |grep -m 1 "image_version" | sed -n "s/.*image_version=\"\(.*\)\".*/\1/p"` - fi +CURRENT_FW=`sonic_installer list |grep "Current" |awk '{print $2}'` - sonic_installer install -y /tmp/$FILENAME || FAILED=1 - sync;sync;sync || exit 14 +if grep -q aboot /host/machine.conf; then + TARGET_FW=`unzip -p /tmp/$FILENAME boot0 |grep -m 1 "image_name" |sed -n "s/.*image-\(.*\)\".*/\1/p"` +else + TARGET_FW=`cat -v /tmp/$FILENAME |grep -m 1 "image_version" | sed -n "s/.*image_version=\"\(.*\)\".*/\1/p"` +fi +sonic_installer install -y /tmp/$FILENAME || FAILED=1 +sync;sync;sync || exit 14 - if [[ -x ${PLATFORM_FW_UPDATE} ]]; then - FS_PATH="/host/image-${TARGET_FW#SONiC-OS-}/fs.squashfs" - FS_MOUNTPOINT="/tmp/image-${TARGET_FW#SONiC-OS-}-fs" - mkdir -p "${FS_MOUNTPOINT}" - mount -t squashfs "${FS_PATH}" "${FS_MOUNTPOINT}" || exit 111 +if [[ -x ${PLATFORM_FW_UPDATE} ]]; then + FS_PATH="/host/image-${TARGET_FW#SONiC-OS-}/fs.squashfs" + FS_MOUNTPOINT="/tmp/image-${TARGET_FW#SONiC-OS-}-fs" -    ${PLATFORM_FW_UPDATE} auto-update --yes --image=next --boot=${REBOOT_TYPE} - fi - ``` + mkdir -p "${FS_MOUNTPOINT}" + mount -t squashfs "${FS_PATH}" "${FS_MOUNTPOINT}" || exit 111 -##### 2.2.2.4.4.3 FW-UPDATE-PLUGIN for reboot scripts - reboot/fast-reboot/warm-reboot -If any firmware needs to be done during the reboot, which needs to be done only after any service or -docker stops and/or disk unmounting is done, then each component platform update needs to log the firmware update detail -in _fw_update_.log which can be read by fw_update_reboot_plugin during reboot. - -```bash -root@sonic:~# fwutil auto-update --yes --image= --boot= -Available FW updates with from boot image : COMPONENT1 - firmware update will be done during with version <#new_version> (current version #current_version) - firmware update has been logged in _fw_update_.log -... - firmware update is starting with version <#new_version2> (current version #current_version2) -... - firmware update is in progress with version <#new_version2> (current version #current_version2) -... - firmware update is done during with version <#new_version> (current version #current_version) -... - firmware update has been logged in _fw_update_.log -All firmware update has been completed. + ${PLATFORM_FW_UPDATE} auto-update --yes --image=next --boot=${REBOOT_TYPE} +fi ``` -Example 1: SSD firmware update is available for fast-reboot upgrade path. -SSD firmware update is logged in _fw_update_fast-reboot.log file and it will be updated during fast-reboot. -```bash -root@sonic:~# fwutil auto-update --yes --image=next --boot=fast -Available FW updates with fast-reboot from next boot image : SSD -SSD firmware update will be done during fastreboot with version 5 (current version 4) -SSD firmware update is logged in _fw_update_fast-reboot.log -All firmware update has been completed. -``` -Example 2: SSD and CPLD update is available for cold reboot upgrade path. -SSD firmware update is logged in _fw_update_cold-reboot.log and it will be updated during cold-reboot. -CPLD firmware update is going to be done with this command and the firmware update completion's also logged -```bash -root@sonic:~# fwutil auto-update --yes --image=next --boot=cold -SSD firmware update will be done during cold-reboot with version 5 (current version 4) -SSD firmware update is logged in _fw_update_cold-reboot.log -... -CPLD firmware update is starting with version 5 (current version 4) -... -CPLD firmware update is in progress with version 5 (current version 4) -... -CPLD firmware update is completed with version 5 (current version 4) -... -CPLD firmware update has been logged in _fw_update_cold-reboot.log -All firmware update has been completed. -``` - -Now _fw_update_.log has been created to log the firmware update that need to be run duirng reboot. -Example of _fw_update_fast-reboot.log with SSD firmware update which needs to run during fast-reboot. -```bash -SSD firmware update needs to be run in fast-reboot. -CMD : ssd_fw_update auto-update --boot=fast ./ssd_fw.bin -``` -Example of _fw_update_cold-reboot.log with SSD firmware update which needs to be run during cold reboot. -```bash -SSD firmware update needs to be run in cold-reboot. -CMD : ssd_fw_update auto-update --boot=cold ./ssd_fw.bin -CPLD firmware update needs to be run in cold-reboot. -``` - -To support the automatic firmware upgrade during reboot based on the /tmp/_fw_update_.log, -`fw_update_reboot_plugin` needs to be added to parse the log file and perform the component firmware updates using the command in the log file. -`fw_update_reboot_plugin` parses /tmp/_fw_update_.log based on the --boot option passing to the plugin. -And it searches for the firmware update command from the log file and performs the firmware updates if needed. -Example : Reboot script changes to support the automatic firmware update during a reboot using the fw_update_reboot_plugin. +##### 2.2.2.4.4.3 Firmware upgrade during a reboot +During the reboot, the created task(s) needs to be performed for each component firmware updates. ```bash - ... - FW_UPDATE_REBOOT_PLUGIN="/usr/bin/fw_update_reboot_plugin" - ... - ... - if [[ -x ${FW_UPDATE_REBOOT_PLUGIN} ]]; then -    debug "updating platform fw for ${REBOOT_TYPE}" -    ${FW_UPDATE_REBOOT_PLUGIN} --boot=${REBOOT_TYPE} - fi -  - if [ -x ${DEVPATH}/${PLATFORM}/${PLAT_REBOOT} ]; then - ... +PLATFORM_FWUTIL="/usr/bin/fwutil" +if [[ -x ${ PLATFORM_FWUTIL } ]]; then + debug "Platform components firmware update for boot type ${boot-option}”” + ${ PLATFORM_FWUTIL } --yes --boot={BOOT_TYPE} +fi ``` # 3 Flows @@ -868,17 +719,6 @@ Example : Reboot script changes to support the automatic firmware update during ###### Figure 5: FW install (modular) flow -## 3.4 Auto FW Update - -### 3.4.1 Auto FW update based on the configuration file - -![Auto FW update flow with downloaded firmware package](images/update_w_fw_package.svg "Figure 6: Auto FW update flow with downloaded firmware package") - -1. Find the available firmware based on boot type from platform specific fw update configuration file. - Exit if no configuration file exists. -2. Update the firmware using the script if it's specified in the configuration. Otherwise, fwutil will use the platform api to update the firmware. - Exit if the update fails in any step. - # 4 Tests ## 4.1 Unit tests From 4a7454fdc85099eca7b46cb55927b68fa43b243b Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Thu, 10 Sep 2020 12:30:06 -0700 Subject: [PATCH 10/28] typo --- doc/fwutil/fwutil.md | 124 ++++++++++++++++++++++++++++--------------- 1 file changed, 82 insertions(+), 42 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index a0765fb045..40fadb6b12 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -30,9 +30,8 @@ - [2.2.2.4 Auto-Update commands](#2224-auto-update-commands) - [2.2.2.4.1 Overview](#22241-overview) - [2.2.2.4.2 Description](#22242-description) - - [2.2.2.4.3 Custom FW Update Script](#22243-custon-fw-update-script) - - [2.2.2.4.4 Platform FW Update Reboot Plugin](#22244-plarform-fw-update-reboot-plugin) - - [2.2.2.4.5 Auto-update Use Cases](#22245-auto-update-use-cases) + - [2.2.2.4.3 Platform FW Update Reboot Plugin](#22243-plarform-fw-update-reboot-plugin) + - [2.2.2.4.4 Auto-update Use Cases](#22244-auto-update-use-cases) - [3 Flows](#3-flows) - [3.1 Show components status](#31-show-components-status) - [3.2 Show available updates](#32-show-available-updates) @@ -271,26 +270,37 @@ Chassis1 BIOS 0ACLH004_02.02.007 Chassis BIOS root@sonic:~# fwutil show updates --image=next Chassis Module Component Firmware Version (current/available) Status Required Boot Action -------- ------- ---------- --------------------- --------------------------------------- ------------------ ----------------------- +Chassis1 N/A BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required N/A + CPLD /cpld.bin 5 / 10 update is required N/A + FPGA /fpga.bin 5 / 5 up-to-date N/A + SSD /ssd.bin 4 / 5 update is required N/A +``` + +2. Non modular chassis platform when the "boot" key and value are available in `platform_components.json` +```bash +root@sonic:~# fwutil show updates --image=next +Chassis Module Component Firmware Version (current/available) Status Required Boot Action +-------- ------- ---------- --------------------- --------------------------------------- ------------------ ----------------------- Chassis1 N/A BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required None CPLD /cpld.bin 5 / 10 update is required Power cycle FPGA /fpga.bin 5 / 5 up-to-date Cold reboot SSD /ssd.bin 4 / 5 update is required Cold rebot, Fast reboot ``` -2. Modular chassis platform +3. Modular chassis platform ```bash root@sonic:~# fwutil show updates --image=next Chassis Module Component Firmware Version (current/available) Status Required Boot Action -------- ------- ---------- --------------------- --------------------------------------- ------------------ ----------------------- -Chassis1 BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required None - CPLD /cpld.bin 5 / 10 update is required Power cycle - FPGA /fpga.bin 5 / 5 up-to-date Cold reboot - SSD /ssd.bin 4 / 5 update is required Cold rebot, Fast reboot - Module1 CPLD /cpld.bin 5 / 10 update is required Power cycle - FPGA /fpga.bin 5 / 5 up-to-date Cold reboot +Chassis1 BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required N/A + CPLD /cpld.bin 5 / 10 update is required N/A + FPGA /fpga.bin 5 / 5 up-to-date N/A + SSD /ssd.bin 4 / 5 update is required N/A + Module1 CPLD /cpld.bin 5 / 10 update is required N/A + FPGA /fpga.bin 5 / 5 up-to-date N/A ``` -3. Custom FW Package +4. Custom FW Package when the "boot" key and value are available in `platform_components.json` ```bash root@sonic:~# fwutil show updates --fw-image=fw_update.tar.gz Component Firmware Version (current/available) Status Required Boot Action @@ -301,7 +311,7 @@ FPGA /fpga.bin 5 / NA up-t SSD /ssd.bin 4 / 5 update is required Cold reboot, Fast reboot ``` -4. Auto-update status +5. Auto-update status ```bash root@sonic:~# fwutil show auto-updates status Component Firmware Version (current/available) Status @@ -381,7 +391,7 @@ for automatic FW installation of various platform components. Automatic FW installation requires platform_components.json to be created and placed at: _sonic-buildimage/device///platform_components.json_ -default image path = /usr/share/sonic///fw_update/ +default image path = /usr/share/sonic/device//fw_update/ **Example:** 1. Non modular chassis platform @@ -446,6 +456,33 @@ default image path = /usr/share/sonic///fw_update/ } ``` +3. Non modular chassis platform with Boot action +```json +{ + "chassis": { + "Chassis1": { + "component": { + "BIOS": { + "firmware": "/usr/share/sonic///fw_update/bios.bin", + "version": "0ACLH003_02.02.010", + "boot": "cold" + }, + "CPLD": { + "firmware": "/usr/share/sonic///fw_update/cpld.bin", + "version": "10", + "boot": "powercycle" + }, + "FPGA": { + "firmware": "/usr/share/sonic///fw_update/fpga.bin", + "version": "5", + "boot": "cold" + } + } + } + } +} +``` + **Note:** 1. FW update will be disabled if component definition is not provided (e.g., 'BIOS': { }) 2. FW version will be read from image if `version` field is not provided @@ -506,22 +543,23 @@ Aborted! #### 2.2.2.4 Auto-update commands ##### 2.2.2.4.1 Overview -The purpose of the auto-update commands group is to provide and interface for automatic fw updates of various platform components -based on the boot option and the platform firmwareupdate configuration file - platform_components.json. +The purpose of the auto-update commands group is to provide and interface for automatic fw updates of various platform components based on the boot option and the platform firmwareupdate configuration file - platform_components.json. The existing FWutil infra supports the upgrade of platform components which can be performed during run time. The SSD upgrade for certain platforms requires the unmount of the filesystems and this needs to be incorporated as part of the reboot scripts. To integrate the upgrade of these platform components which can’t be performed during run time, the FWutil requires few more enhancements that specifies the reboot-type during which the user expects the upgrade to happen. -The fwutil infra section below indicates the necessary changes to add support for auto update during reboot. +The FWutil infra section below indicates the necessary changes to add support for auto update during reboot. The Platform plugins section describes the plugins that a platform must implement to support auto updates when the platform component APIs are not available. Automatic FW installation requires default platform_components.json to be created and placed at: _sonic-buildimage/device///platform_components.json_ -default image path = /usr/share/sonic///fw_update/ +default image path = /usr/share/sonic/device// Auto-update command can support the standalone custom firmware image package with --fw-image option. -The package can be any format between `.tar` or `.tar.gz`. +The package can be any format between `.tar` or `.tar.gz` and should have the `platform_components.json`, the firmware image(s). +The package can have the auto-update plugin if the platform doesn't support platform api or if plugin needs to be updatedplugin. +The package can also have the component upgrade utility(script) and the utility will be used for the component firmware upgrade if it's specified in `platform_compnents.json`. The `fwutil auto-update` commands uncompress the package and parse the `platform_components.json` to retrieve the firmware information. If the script path is available for the component firmware configuration in the `platform_components.json`, @@ -610,47 +648,48 @@ All firmware update has been completed. **Note:** the default option is _--image=current_ and _--boot=any_ -##### 2.2.2.4.4.3 PLATFORM-FW-UPDATE-REBOOT-PLUGIN to support the platform specific fw update support for different reboot types -When Vendor doesn't have platform API ready to suppport all platform component APIs to support the auto-update interfaces, -PLATFORM-FW-UPDATE-REBOOT-PLUGIN will do the equivalent thing of auto-update platform component APIs +##### 2.2.2.4.4.3 PLATFORM-FWUTIL-AUTO-UPDATE-PLUGIN to support the platform specific fw update support for different reboot types +When Vendor doesn't have platform API ready to support all platform component APIs to support the auto-update interfaces, PLATFORM-FWUTIL-AUTO-UPDATE-PLUGIN will do the equivalent thing of auto-update platform component APIs. This plugin will create a task file for specified reboot type issued through the FWutil command. This file will include the components that needs to be upgraded during individual reboot. The task file will be platform dependent. It is up to the platform plugin to determine the order of upgrade. -Platform Plugin 1: -The platform plugin 1 will unpack the below files presented in tar in appropriate place +The platform plugin can have three passing arguments from fwutil. 1. Firmware -2. Update-utility (if provided) +2. Boot-option for creating a reboot fwupdate task /Boot-type for completing the task +3. Update-utility (if provided) -This plugin will create a task file for specified reboot type issued through the FWutil command. -This file will include the components that needs to be upgraded during individual reboot. -The task file will be platform dependent. It is up to the platform plugin to determine the order of upgrade. -The below plugin needs to be called by the FWutil command. -if [[ -x ${ PLATFORM_FWUTIL_CREATE_AUTO_UPDATE_TASK } ]]; then +The plugin needs to be called by the FWutil command to perform the firmware update . +```bash +if [[ -x ${PLATFORM_FWUTIL_CREATE_HANDLE_AUTO_UPDATE_TASK} ]]; then debug "Creating task file for boot type ${boot-option}”” - ${ PLATFORM_FWUTIL_CREATE_AUTO_UPDATE_TASK } ${tar file/firmware path} ${boot-option} ${update-utility} + ${PLATFORM_FWUTIL_CREATE_HANDLE_AUTO_UPDATE_TASK} ${tar file/firmware path} ${boot-option} ${update-utility} fi - -Platform Plugin 2: -The reboot scripts will invoke the below plugin which will analyze the corresponding task file and -execute the upgrade commands for the components present in task file. - - if [[ -x ${ PLATFORM_FWUTIL_HANDLE_AUTO_UPDATE_TASK } ]]; then +``` +The reboot scripts will invoke the FWutil and the FWutil will invoke the plugin with boot-type, which will analyze the corresponding task file and execute the upgrade commands for the components present in task file. +```bash +if [[ -x ${PLATFORM_FWUTIL_CREATE_HANDLE_AUTO_UPDATE_TASK} ]]; then debug "Handling task file for boot type ${REBOOT_TYPE}” - ${ PLATFORM_FWUTIL_HANDLE_AUTO_UPDATE_TASK } ${REBOOT_TYPE} + ${PLATFORM_FWUTIL_CREATE_HANDLE_AUTO_UPDATE_TASK} ${REBOOT_TYPE} fi - +``` ##### 2.2.2.4.4 Auto-update Use Cases ##### 2.2.2.4.4.1 Standalone firmware update during run time -During the run time, SONiC device can have a component firmware updated without interrupting the data plan if the component firmware update doesn't need any boot action. +Since FWutil auto-update can support the firmware update using a custom firmware package, this will allow the firmware update to be available during run time. + +SONiC device can have a component firmware updated without interrupting the data plan if the component firmware update doesn't need any boot action. ```bash root@sonic:~# fwutil auto-update --yes --fw-image=aboot-fw-update.tar.gz --boot=none ``` -Or, device can be updated only a specific firmware update with a possible boot option that can be supported on a certain topology. + +SONiC device can also be updated only a specific firmware update with a possible boot option that can be supported on a certain topology. +But in this case, the firmware update can be completed by following reboot which is indicated in the boot option of fwutil auto-update command. ```bash root@sonic:~# fwutil auto-update --yes --fw-image=ssd-fw-update.tar.gz --boot=fast +... +root@sonic:~# sudo fast-reboot ``` ##### 2.2.2.4.4.2 Firmware upgrade during Sonic_to_Sonic upgrade @@ -683,11 +722,12 @@ fi ##### 2.2.2.4.4.3 Firmware upgrade during a reboot During the reboot, the created task(s) needs to be performed for each component firmware updates. +This fwutil call needs to be performed right before calling the platform specific reboot plugin. ```bash PLATFORM_FWUTIL="/usr/bin/fwutil" -if [[ -x ${ PLATFORM_FWUTIL } ]]; then +if [[ -x ${PLATFORM_FWUTIL} ]]; then debug "Platform components firmware update for boot type ${boot-option}”” - ${ PLATFORM_FWUTIL } --yes --boot={BOOT_TYPE} + ${PLATFORM_FWUTIL} auto-update --yes --boot={BOOT_TYPE} fi ``` From 72a0845dc176729877e7d9a7acfd59b84938b9a0 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Tue, 15 Sep 2020 01:24:46 -0700 Subject: [PATCH 11/28] review comment --- doc/fwutil/fwutil.md | 16 +- doc/fwutil/images/fwutil_hld.svg | 710 ++++++++++++++++--------------- 2 files changed, 371 insertions(+), 355 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index 40fadb6b12..d15d19d90b 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -666,11 +666,12 @@ if [[ -x ${PLATFORM_FWUTIL_CREATE_HANDLE_AUTO_UPDATE_TASK} ]]; then ${PLATFORM_FWUTIL_CREATE_HANDLE_AUTO_UPDATE_TASK} ${tar file/firmware path} ${boot-option} ${update-utility} fi ``` -The reboot scripts will invoke the FWutil and the FWutil will invoke the plugin with boot-type, which will analyze the corresponding task file and execute the upgrade commands for the components present in task file. +The reboot scripts will invoke the platform firmware update reboot plugin with boot-type, which will analyze the reboot firmware task file and execute the upgrade commands for the components present in task file. ```bash -if [[ -x ${PLATFORM_FWUTIL_CREATE_HANDLE_AUTO_UPDATE_TASK} ]]; then +PLATFORM_FWUTIL_AU_REBOOT_HANDL="platform_fw_au_reboot_handle" +if [[ -x ${DEVPATH}/${PLATFORM}/${PLATFORM_FWUTIL_AU_REBOOT_HANDLE} ]]; then debug "Handling task file for boot type ${REBOOT_TYPE}” - ${PLATFORM_FWUTIL_CREATE_HANDLE_AUTO_UPDATE_TASK} ${REBOOT_TYPE} + ${DEVPATH}/${PLATFORM}/${PLATFORM_FWUTIL_AU_REBOOT_HANDLE} ${REBOOT_TYPE} fi ``` @@ -721,15 +722,6 @@ fi ``` ##### 2.2.2.4.4.3 Firmware upgrade during a reboot -During the reboot, the created task(s) needs to be performed for each component firmware updates. -This fwutil call needs to be performed right before calling the platform specific reboot plugin. -```bash -PLATFORM_FWUTIL="/usr/bin/fwutil" -if [[ -x ${PLATFORM_FWUTIL} ]]; then - debug "Platform components firmware update for boot type ${boot-option}”” - ${PLATFORM_FWUTIL} auto-update --yes --boot={BOOT_TYPE} -fi -``` # 3 Flows diff --git a/doc/fwutil/images/fwutil_hld.svg b/doc/fwutil/images/fwutil_hld.svg index 50a7c8a2fe..91fa2c5ca2 100755 --- a/doc/fwutil/images/fwutil_hld.svg +++ b/doc/fwutil/images/fwutil_hld.svg @@ -1,15 +1,11 @@ - + - - - - - - + xmlns:v="http://schemas.microsoft.com/visio/2003/SVGExtensions/" width="34.7012in" height="35.8823in" + viewBox="0 0 2498.49 2583.53" xml:space="preserve" color-interpolation-filters="sRGB" class="st11"> + fwutil hld + - - - - Page-11 - - - Rectangle.127 - - - - - - + Page-1 + + Rectangle - + - + Rounded Rectangle.42 DEVICE API @@ -58,105 +45,109 @@ - - - - + + + + - - - - - DEVICE API - + + + + + + + + + DEVICE API + Rectangle.43 get_name - - - - get_name - - Rectangle.4 + + + + get_name + + Rectangle.44 get_presence - - - - get_presence - - Rectangle.5 + + + + get_presence + + Rectangle.45 get_model - - - - get_model - + + + + get_model + Rectangle.49 get_serial - - - - get_serial - + + + + get_serial + Rectangle.50 get_status - - - - get_status - + + + + get_status + Rectangle.105 FW Utility - - - - FW Utility - + + + + FW Utility + Simple Double Arrow.106 - + - - Rectangle.10 + + Rectangle.39 - + - - Rectangle.11 + + Rectangle.40 platform_base.py - - - - platform_base.py - + + + + platform_base.py + Rounded Rectangle.52 CHASSIS API @@ -167,36 +158,40 @@ - - - - + + + + - - - - - CHASSIS API - + + + + + + + + + CHASSIS API + Rectangle.53 get_chassis - - - - get_chassis - + + + + get_chassis + Rectangle.64 - + - + Rounded Rectangle.70 DEVICE API @@ -207,79 +202,83 @@ - - - - + + + + - - - - - DEVICE API - + + + + + + + + + DEVICE API + Rectangle.71 get_name - - - - get_name - + + + + get_name + Rectangle.72 get_presence - - - - get_presence - + + + + get_presence + Rectangle.73 get_model - - - - get_model - + + + + get_model + Rectangle.74 get_serial - - - - get_serial - + + + + get_serial + Rectangle.75 get_status - - - - get_status - + + + + get_status + Rectangle.113 chassis_base.py - - - - chassis_base.py - + + + + chassis_base.py + Rounded Rectangle.123 COMPONENT API @@ -290,86 +289,174 @@ - - - - + + + + - - - - - COMPONENT API - + + + + + + + + + COMPONENT API + Rectangle.124 get_num_components - - - - get_num_components - + + + + get_num_components + Rectangle.125 get_all_component - - - - get_all_component - + + + + get_all_component + Rectangle.126 get_component - - - - get_component - + + + + get_component + + Rectangle.127 + + + + + + + Rounded Rectangle.128 + API + + + + + + + + + + + + + + + + + + + + + + API + + Rectangle.129 + get_name + + + + + + + get_name + + Rectangle.130 + get_description + + + + + + + get_description + + Rectangle.131 + get_firmware_version + + + + + + + get_firmware_version + + Rectangle.132 + component_base.py + + + + + + + component_base.py + Rectangle.134 HW - - - - HW - + + + + HW + Simple Double Arrow.138 - + - + Simple Double Arrow.139 - + - + + Rectangle.143 + install_firmware + + + + + + + install_firmware + Simple Double Arrow.154 - + - + Rounded Rectangle.155 COMPONENT API @@ -380,67 +467,71 @@ - - - - + + + + - - - - - COMPONENT API - + + + + + + + + + COMPONENT API + Rectangle.156 get_num_components - - - - get_num_components - + + + + get_num_components + Rectangle.157 get_all_component - - - - get_all_component - + + + + get_all_component + Rectangle.158 get_component - - - - get_component - + + + + get_component + Simple Double Arrow.160 - + - + Simple Double Arrow.161 - + - + Rounded Rectangle.72 MODULE API @@ -451,160 +542,93 @@ - - - - + + + + - - - - - MODULE API - + + + + + + + + + MODULE API + Rectangle.16 get_num_modules - - - - get_num_modules - + + + + get_num_modules + Rectangle.17 get_all_modules - - - - get_all_modules - + + + + get_all_modules + Rectangle.18 get_module - - - - get_module - + + + + get_module + Rectangle.65 module_base.py - - - - module_base.py - - Rounded Rectangle.128 - API - - - - - - - - - - - - - - - - - - API - - Rectangle.129 - get_name - - - - - - - get_name - - Rectangle.130 - get_description - - - - - - - get_description - - Rectangle.131 - get_firmware_version + + + + module_base.py + + Rectangle.162 + update_firmware - - - - get_firmware_version - - Rectangle.143 - install_firmware + + + + update_firmware + + Rectangle.163 + auto_update_firmware - - - - install_firmware - - Sheet.50 - install_firmware - - - - - - - update_firmware - - Rectangle.54 - install_firmware - - - - - - - get_available_firmware_version - - Sheet.55 - install_firmware - - - - - - - get_firmware_update_notification - - Rectangle.132 - component_base.py + + + + auto_update_firmware + + Rectangle.164 + auto_update_status - - - - component_base.py + + + + auto_update_status From ff5441b2ec713862a5cefb64f3c9888d35abf843 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Mon, 28 Sep 2020 01:23:31 -0700 Subject: [PATCH 12/28] more auto-update utility requirement --- doc/fwutil/fwutil.md | 187 ++++++++++++++++++++++--------------------- 1 file changed, 94 insertions(+), 93 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index d15d19d90b..e3dfba23bb 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -30,7 +30,7 @@ - [2.2.2.4 Auto-Update commands](#2224-auto-update-commands) - [2.2.2.4.1 Overview](#22241-overview) - [2.2.2.4.2 Description](#22242-description) - - [2.2.2.4.3 Platform FW Update Reboot Plugin](#22243-plarform-fw-update-reboot-plugin) + - [2.2.2.4.3 Platform FW Update utility](#22243-plarform-fw-update-utility) - [2.2.2.4.4 Auto-update Use Cases](#22244-auto-update-use-cases) - [3 Flows](#3-flows) - [3.1 Show components status](#31-show-components-status) @@ -78,11 +78,11 @@ This document provides general information about FW utility implementation in SO ## List of figures -[Figure 1: FW utility High Level Design](#figure-1-fw-utility-high-level-design) -[Figure 2: Show components status flow](#figure-2-show-components-status-flow) -[Figure 3: Show available updates flow](#figure-3-show-available-updates-flow) -[Figure 4: FW install (non modular) flow](#figure-4-fw-install-non-modular-flow) -[Figure 5: FW install (modular) flow](#figure-5-fw-install-modular-flow) +[Figure 1: FW utility High Level Design](#figure-1-fw-utility-high-level-design) +[Figure 2: Show components status flow](#figure-2-show-components-status-flow) +[Figure 3: Show available updates flow](#figure-3-show-available-updates-flow) +[Figure 4: FW install (non modular) flow](#figure-4-fw-install-non-modular-flow) +[Figure 5: FW install (modular) flow](#figure-5-fw-install-modular-flow) ## List of tables @@ -92,18 +92,18 @@ This document provides general information about FW utility implementation in SO ## 1.1 Feature overview -A modern network switch is a sophisticated equipment which consists of many auxiliary components -which are responsible for managing different subsystems (e.g., PSU/FAN/QSFP/EEPROM/THERMAL) +A modern network switch is a sophisticated equipment which consists of many auxiliary components +which are responsible for managing different subsystems (e.g., PSU/FAN/QSFP/EEPROM/THERMAL) and providing necessary interfaces (e.g., I2C/SPI/JTAG). -Basically these components are complex programmable logic devices with it's own HW architecture +Basically these components are complex programmable logic devices with it's own HW architecture and software. The most important are BIOS/CPLD/FPGA etc. -It is very important to always have the latest recommended software version to improve device stability, +It is very important to always have the latest recommended software version to improve device stability, security and performance. Also, software updates can add new features and remove outdated ones. -In order to make software update as simple as possible and to provide a nice user frindly -interface for various maintenance operations (e.g., install a new FW or query current version) +In order to make software update as simple as possible and to provide a nice user frindly +interface for various maintenance operations (e.g., install a new FW or query current version) we might need a dedicated FW utility. ## 1.2 Requirements @@ -150,8 +150,8 @@ we might need a dedicated FW utility. | FW binary downloading over URL: error | ERROR | | FW binary installation: start/end | INFO | | FW binary installation: error | ERROR | -| Auto-update reboot task creation: creat | INFO | -| Auto-update reboot task creation: error | ERROR | +| FW binary auto-update : start/end | INFO | +| FW binary auto-update : error | ERROR | **Note:** Some extra information also will be logged: 1. Component location (e.g., Chassis1/Module1/BIOS) @@ -170,17 +170,17 @@ In order to improve scalability and performance a modern network switches provid 1. Non modular chassis platforms 2. Modular chassis platforms -Non modular chassis platforms may contain only one chassis. +Non modular chassis platforms may contain only one chassis. A chassis may contain it's own set of components. -Modular chassis platforms may contain only one chassis. -A chassis may contain one or more modules and it's own set of components. +Modular chassis platforms may contain only one chassis. +A chassis may contain one or more modules and it's own set of components. Each module may contain it's own set of components. Basically each chassis/module may contain one or more components (e.g., BIOS/CPLD/FPGA). -SONiC platform API provides an interface for FW maintenance operations for both modular and -non modular chassis platforms. Both modular and non modular chassis platforms share the same platform API, +SONiC platform API provides an interface for FW maintenance operations for both modular and +non modular chassis platforms. Both modular and non modular chassis platforms share the same platform API, but may have different implementation. SONiC FW utility uses platform API to interact with the various platform components. @@ -217,9 +217,9 @@ fwutil | |--- fw -y|--yes -f|--force -i|--image= | |--- auto-update - |--- fw -y|--yes -f|--force -z|--image= --b|--boot= - |--- fw -y|--yes -f|--force -z|--fw-image= --b|--boot= - + |--- fw -z|--image= --b|--boot= + |--- fw -z|--fw-image= --b|--boot= + ``` ### 2.2.2 Command interface @@ -276,7 +276,7 @@ Chassis1 N/A BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH SSD /ssd.bin 4 / 5 update is required N/A ``` -2. Non modular chassis platform when the "boot" key and value are available in `platform_components.json` +2. Non modular chassis platform when the "boot" key and value are available in `platform_components.json` ```bash root@sonic:~# fwutil show updates --image=next Chassis Module Component Firmware Version (current/available) Status Required Boot Action @@ -315,7 +315,7 @@ SSD /ssd.bin 4 / 5 upda ```bash root@sonic:~# fwutil show auto-updates status Component Firmware Version (current/available) Status ----------- --------------------- --------------------------------------- ------------------------- +---------- --------------------- --------------------------------------- ------------------------- CPLD /cpld.bin 5 / 10 updated but need a power-cycle SSD /ssd.bin 4 / 5 scheduled in cold reboot ``` @@ -330,7 +330,7 @@ SSD /ssd.bin 4 / 5 sche ##### 2.2.2.2.1 Overview -The purpose of the install commands group is to provide an interface +The purpose of the install commands group is to provide an interface for manual FW installation of various platform components. ##### 2.2.2.2.2 Description @@ -386,10 +386,10 @@ Aborted! ##### 2.2.2.3.1 Overview -The purpose of the update commands group is to provide an interface +The purpose of the update commands group is to provide an interface for automatic FW installation of various platform components. -Automatic FW installation requires platform_components.json to be created and placed at: +Automatic FW installation requires platform_components.json to be created and placed at: _sonic-buildimage/device///platform_components.json_ default image path = /usr/share/sonic/device//fw_update/ @@ -547,49 +547,26 @@ The purpose of the auto-update commands group is to provide and interface for au The existing FWutil infra supports the upgrade of platform components which can be performed during run time. The SSD upgrade for certain platforms requires the unmount of the filesystems and this needs to be incorporated as part of the reboot scripts. -To integrate the upgrade of these platform components which can’t be performed during run time, +To integrate the upgrade of these platform components which can’t be performed during run time, the FWutil requires few more enhancements that specifies the reboot-type during which the user expects the upgrade to happen. -The FWutil infra section below indicates the necessary changes to add support for auto update during reboot. +The FWutil infra section below indicates the necessary changes to add support for auto update during reboot. The Platform plugins section describes the plugins that a platform must implement to support auto updates when the platform component APIs are not available. -Automatic FW installation requires default platform_components.json to be created and placed at: +Automatic FW installation requires default platform_components.json to be created and placed at: _sonic-buildimage/device///platform_components.json_ default image path = /usr/share/sonic/device// -Auto-update command can support the standalone custom firmware image package with --fw-image option. +Auto-update command can support the standalone custom firmware image package with --fw-image option. The package can be any format between `.tar` or `.tar.gz` and should have the `platform_components.json`, the firmware image(s). The package can have the auto-update plugin if the platform doesn't support platform api or if plugin needs to be updatedplugin. The package can also have the component upgrade utility(script) and the utility will be used for the component firmware upgrade if it's specified in `platform_compnents.json`. The `fwutil auto-update` commands uncompress the package and parse the `platform_components.json` to retrieve the firmware information. -If the script path is available for the component firmware configuration in the `platform_components.json`, +If the script path is available for the component firmware configuration in the `platform_components.json`, it means that the specific component firmware upgrade shall use the script to process the fwutil commands. -`2.2.2.4.3 Component Firmware Update Script Interface Requirement` explains the requirement of the component firmware upgrade script +`2.2.2.4.3 Platform Component Firmware Update Utility` explains the requirement of the component firmware upgrade utility to interfere with the fwutil to support the auto-update command - mainly status and install. -**Example:** -1. Platform component fw update configuration with platform specific script and boot options with --fw-image command line option -The firmware image -```json -{ - "component": { - "BIOS": { - "firmware": "bios.bin", - "version": "0ACLH003_02.02.010", - }, - "CPLD": { - "firmware": "cpld.bin", - "version": "10", - }, - "SSD": { - "firmware": "SSD.bin", - "script": "ssd_fw_update", - "version": "5", - } - } -} -``` - **Note:** 1. FW update will be disabled if component definition is not provided (e.g., 'BIOS': { }) 2. FW version will be read from image if `version` field is not provided @@ -599,7 +576,7 @@ The firmware image **The following command updates FW Automatically with installing the available component firmware, creating task(s) for update during reboot:** 1. auto-update command for installation and reboot task creation ```bash -root@sonic:~# fwutil auto-update --yes --image= --boot= +root@sonic:~# fwutil auto-update fw --yes --image= --boot= Available FW updates with from boot image : COMPONENT1 (and COMPONENT2) firmware update will be done during with version <#new_version> (current version #current_version) ... @@ -612,23 +589,23 @@ Available FW updates with from boot image : COMPONEN All firmware update has been completed. ``` -This is examples of a platform which supports the SSD firmware update during fast reboot and cold reboot with different commands +This is examples of a platform which supports the SSD firmware update during fast reboot and cold reboot with different commands along with CPLD firmware update available only for the cold reboot which can perform a power cycle triggered by some register setting. -Example 1: SSD firmware update is available for fast-reboot upgrade path. +Example 1: SSD firmware update is available for fast-reboot upgrade path. SSD firmware update is logged in a platform defined designated file and it will be updated during fast-reboot. ```bash -root@sonic:~# fwutil auto-update --yes --image=next --boot=fast +root@sonic:~# fwutil auto-update fw --yes --image=next --boot=fast Available FW updates with fast-reboot from next boot image : SSD SSD firmware update will be done during fastreboot with version 5 (current version 4) All firmware update has been completed. ``` -Example 2: SSD and CPLD update is available for cold reboot upgrade path. +Example 2: SSD and CPLD update is available for cold reboot upgrade path. SSD firmware update is logged in a platform defined designated file and it will be updated during cold reboot. -CPLD firmware update is going to be done with this command and the CPLD completion activity will be performed during cold reboot +CPLD firmware update is going to be done with this command and the CPLD completion activity will be performed during cold reboot once all reboot processes are finished. The CPLD completion activity for this case is a power cycle triggered by the hw register setting. ```bash -root@sonic:~# fwutil auto-update --yes --image=next --boot=cold +root@sonic:~# fwutil auto-update fw --yes --image=next --boot=cold Available FW updates with fast-reboot from next boot image : SSD and CPLD SSD firmware update will be done during cold-reboot with version 5 (current version 4) ... @@ -640,39 +617,71 @@ All firmware update has been completed. ``` **Supported options:** -1. -y|--yes - automatic yes to prompts. Assume "yes" as answer to all prompts and run non-interactively -2. -f|--force - install FW regardless the current version 3. -i|--image - update FW using current/next SONiC image 4. -b|--boot - following boot option after the upgrade 6. -z|--fw-image - firmware package downloaded during run time (this is an exclusive option from --image) **Note:** the default option is _--image=current_ and _--boot=any_ -##### 2.2.2.4.4.3 PLATFORM-FWUTIL-AUTO-UPDATE-PLUGIN to support the platform specific fw update support for different reboot types -When Vendor doesn't have platform API ready to support all platform component APIs to support the auto-update interfaces, PLATFORM-FWUTIL-AUTO-UPDATE-PLUGIN will do the equivalent thing of auto-update platform component APIs. -This plugin will create a task file for specified reboot type issued through the FWutil command. -This file will include the components that needs to be upgraded during individual reboot. -The task file will be platform dependent. It is up to the platform plugin to determine the order of upgrade. +##### 2.2.2.4.3 Platform Component Firmware Update Utility +When Vendor doesn't have platform API ready to support all platform component APIs including the auto-update interface, +the platform component utility will perform the equivalent process of `auto-update` platform component api. +The component utility can perform the firmware update if the firmware update doesn't need any boot action required after the update. +Otherwise, it will create a task file if any process or handling for the component firmware update needs to be done during the reboot +and also if the update can be done for the specified reboot type. +The componenet utility should be defined with key value `utility` in the component object of `platform_component.json` to be called by fwutil instead of the platform api. +The task file will be platform-specific. -The platform plugin can have three passing arguments from fwutil. +**Example:** +1. `platform_component.json` with platform specific utility. +```json +{ + "component": { + "BIOS": { + "firmware": "bios.bin", + "version": "0ACLH003_02.02.010", + }, + "CPLD": { + "firmware": "cpld.bin", + "utility": "cpldupdate", + "version": "10", + }, + "SSD": { + "firmware": "SSD.bin", + "utility": "ssd_fw_update", + "version": "5", + } + } +} +``` + +The Utility can have two passing arguments and one option for actions from fwutil. 1. Firmware -2. Boot-option for creating a reboot fwupdate task /Boot-type for completing the task -3. Update-utility (if provided) +2. Boot action following after the firmware auto-update process +3. Fwutil action : -a(--autoupdate) +**Utility can be supported for other platform api substitues like `compoenent_update` and `compoenent_install` with |-u(--update)|-i(--install)** -The plugin needs to be called by the FWutil command to perform the firmware update . +The plugin needs to be called by the FWutil command to perform the firmware auto-update process. ```bash -if [[ -x ${PLATFORM_FWUTIL_CREATE_HANDLE_AUTO_UPDATE_TASK} ]]; then - debug "Creating task file for boot type ${boot-option}”” - ${PLATFORM_FWUTIL_CREATE_HANDLE_AUTO_UPDATE_TASK} ${tar file/firmware path} ${boot-option} ${update-utility} -fi +... +firmware_path = parser[self.__pcp.FIRMWARE_KEY] +utility_path = parser[self.__pcp.UTILITY_KEY] +if os.path.isfile(utility_path) and os.access(utility_path, os.X_OK): + cmd = "{} -a {} {}".format( + utility_path, + firmware_path, + boot + ) + output = subprocess.check_output(cmd, stderr=subprocess.STDOUT, shell=True) +... ``` The reboot scripts will invoke the platform firmware update reboot plugin with boot-type, which will analyze the reboot firmware task file and execute the upgrade commands for the components present in task file. ```bash -PLATFORM_FWUTIL_AU_REBOOT_HANDL="platform_fw_au_reboot_handle" +PLATFORM_FWUTIL_AU_REBOOT_HANDLE="platform_fwutil_au_reboot_handle" if [[ -x ${DEVPATH}/${PLATFORM}/${PLATFORM_FWUTIL_AU_REBOOT_HANDLE} ]]; then debug "Handling task file for boot type ${REBOOT_TYPE}” ${DEVPATH}/${PLATFORM}/${PLATFORM_FWUTIL_AU_REBOOT_HANDLE} ${REBOOT_TYPE} -fi +fi ``` ##### 2.2.2.4.4 Auto-update Use Cases @@ -682,18 +691,18 @@ Since FWutil auto-update can support the firmware update using a custom firmware SONiC device can have a component firmware updated without interrupting the data plan if the component firmware update doesn't need any boot action. ```bash -root@sonic:~# fwutil auto-update --yes --fw-image=aboot-fw-update.tar.gz --boot=none +root@sonic:~# fwutil auto-update fw --fw-image=aboot-fw-update.tar.gz --boot=none ``` SONiC device can also be updated only a specific firmware update with a possible boot option that can be supported on a certain topology. But in this case, the firmware update can be completed by following reboot which is indicated in the boot option of fwutil auto-update command. ```bash -root@sonic:~# fwutil auto-update --yes --fw-image=ssd-fw-update.tar.gz --boot=fast +root@sonic:~# fwutil auto-update fw --fw-image=ssd-fw-update.tar.gz --boot=fast ... root@sonic:~# sudo fast-reboot ``` -##### 2.2.2.4.4.2 Firmware upgrade during Sonic_to_Sonic upgrade +##### 2.2.2.4.4.2 Firmware upgrade during Sonic_to_Sonic upgrade During the sonic image upgrade, all available platform component firmware can be upgraded for the specific following boot option. ```bash PLATFORM_FW_UPDATE="/usr/bin/fwutil" @@ -711,18 +720,10 @@ sync;sync;sync || exit 14 if [[ -x ${PLATFORM_FW_UPDATE} ]]; then - FS_PATH="/host/image-${TARGET_FW#SONiC-OS-}/fs.squashfs" - FS_MOUNTPOINT="/tmp/image-${TARGET_FW#SONiC-OS-}-fs" - - mkdir -p "${FS_MOUNTPOINT}" - mount -t squashfs "${FS_PATH}" "${FS_MOUNTPOINT}" || exit 111 - - ${PLATFORM_FW_UPDATE} auto-update --yes --image=next --boot=${REBOOT_TYPE} + ${PLATFORM_FW_UPDATE} auto-update fw --yes --image=next --boot=${REBOOT_TYPE} fi ``` -##### 2.2.2.4.4.3 Firmware upgrade during a reboot - # 3 Flows ## 3.1 Show components status @@ -762,4 +763,4 @@ fi 5. Install BIOS/CPLD/FPGA FW on modular chassis 6. Update BIOS/CPLD/FPGA FW on non modular chassis 7. Update BIOS/CPLD/FPGA FW on modular chassis -8. Auto Update BIOS/CPLD/FPGA FW with boot-action options +8. Auto Update BIOS/CPLD/FPGA FW with boot-action options From ac2bc843a288a645546fd20c663df00c37b05910 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Mon, 28 Sep 2020 01:36:08 -0700 Subject: [PATCH 13/28] add utility commandline example --- doc/fwutil/fwutil.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index e3dfba23bb..7186238244 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -675,6 +675,9 @@ if os.path.isfile(utility_path) and os.access(utility_path, os.X_OK): output = subprocess.check_output(cmd, stderr=subprocess.STDOUT, shell=True) ... ``` +From the above `platform_component.json` example, if the platform needs the SSD firmware update, then the auto-update can be triggered with following command. +`$PWD/ssd_fw_update -a $PWD/SSD.bin fast` + The reboot scripts will invoke the platform firmware update reboot plugin with boot-type, which will analyze the reboot firmware task file and execute the upgrade commands for the components present in task file. ```bash PLATFORM_FWUTIL_AU_REBOOT_HANDLE="platform_fwutil_au_reboot_handle" From 4b14a2604d0a66234d8279e6d50675f9c6b22ad5 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Tue, 29 Sep 2020 07:55:16 -0700 Subject: [PATCH 14/28] utility response --- doc/fwutil/fwutil.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index 7186238244..a3bd2fa668 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -661,6 +661,13 @@ The Utility can have two passing arguments and one option for actions from fwuti 3. Fwutil action : -a(--autoupdate) **Utility can be supported for other platform api substitues like `compoenent_update` and `compoenent_install` with |-u(--update)|-i(--install)** +The expected utility response can be as follows. +```json +"True" : "completed" +"True" : "scheduled" +"False" : Error +``` + The plugin needs to be called by the FWutil command to perform the firmware auto-update process. ```bash ... From c4aed033bf1e86fed8be5515ad787cf1065219ff Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Mon, 5 Oct 2020 22:14:05 -0700 Subject: [PATCH 15/28] address review comments --- doc/fwutil/fwutil.md | 95 ++- .../images/autoupdate_component_api_flow.svg | 670 +++++++++++++++ .../autoupdate_platform_utility_flow.svg | 784 ++++++++++++++++++ 3 files changed, 1519 insertions(+), 30 deletions(-) create mode 100644 doc/fwutil/images/autoupdate_component_api_flow.svg create mode 100644 doc/fwutil/images/autoupdate_platform_utility_flow.svg diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index a3bd2fa668..e6538a56b6 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -38,6 +38,9 @@ - [3.3 Install component FW](#33-install-component-fw) - [3.3.1 Non modular chassis platform](#331-non-modular-chassis-platform) - [3.3.2 Modular chassis platform](#332-modular-chassis-platform) + - [3.4 Auto-update platform component firmwares](#33-Auto-update-platform-component-firmwares) + - [3.4.1 Auto-update platform component firmwares](#331-Auto-update-platform-component-firmwares) + - [3.4.2 Auto-update using platform utility](#332-Auto-update-using-platform-utility) - [4 Tests](#4-tests) - [4.1 Unit tests](#41-unit-tests) @@ -401,7 +404,7 @@ default image path = /usr/share/sonic/device//fw_update/ "Chassis1": { "component": { "BIOS": { - "firmware": "/usr/share/sonic///fw_update/bios.bin", + "firmware": "/usr/share///fw_update/bios.bin", "version": "0ACLH003_02.02.010" }, "CPLD": { @@ -636,39 +639,56 @@ The task file will be platform-specific. 1. `platform_component.json` with platform specific utility. ```json { - "component": { - "BIOS": { - "firmware": "bios.bin", - "version": "0ACLH003_02.02.010", - }, - "CPLD": { - "firmware": "cpld.bin", - "utility": "cpldupdate", - "version": "10", - }, - "SSD": { - "firmware": "SSD.bin", - "utility": "ssd_fw_update", - "version": "5", + "chassis": { + "Chassis1": { + "component": { + "BIOS": { + "firmware": "bios.bin", + "version": "0ACLH003_02.02.010", + }, + "CPLD": { + "firmware": "cpld.bin", + "utility": "cpldupdate", + "version": "10", + }, + "SSD": { + "firmware": "SSD.bin", + "utility": "ssd_fw_update", + "version": "5", + } + } } } } ``` -The Utility can have two passing arguments and one option for actions from fwutil. -1. Firmware -2. Boot action following after the firmware auto-update process -3. Fwutil action : -a(--autoupdate) -**Utility can be supported for other platform api substitues like `compoenent_update` and `compoenent_install` with |-u(--update)|-i(--install)** - -The expected utility response can be as follows. -```json -"True" : "completed" -"True" : "scheduled" -"False" : Error -``` - -The plugin needs to be called by the FWutil command to perform the firmware auto-update process. +##### 2.2.2.4.3.1 Platform Component Firmware Update Utility Interface Requirement + +The Utility should support the minimum requirements to perform the fwutil auto-update interface. +The minimum requirement is that the component api's get_frimware_version, get_firmware_update_notification(), and auto_update_firmware() needs to be supported by the utility. +Here are the interface requirements to support them. +1. {utility} -s(--status) : able to retrieve the current firmware version: + - equivalent to the component api's get_firmware_version() + - response : installed firmware version +2. {utility} -n(--notification) : able to provide the update complete action : + - equivalent to the component api's get_firmware_update_notification(image_path) + - response : the required action to complete the component installation +3. {utility} -a(--autoupdate) : able to perform the auto-update action : + - equivalent to the component api's auto_update_firmware(image_path, boot_type) + - auto-update interface needs two arguments : image_path and boot_type + - response : the result of auto-update as follows + ```json + "True" : "completed" + "True" : "scheduled" + "True" : "need_action" + "False" : ${ErrorCode} + ``` + +**Optional) The utility can be supported for other platform api substitues like `compoenent_update` and `compoenent_install` with |-u(--update)|-i(--install)** + +The component utility needs to be called by the FWutil command to perform the firmware auto-update process if it's defined in the `platform_component.json`, otherwise, the platform component api will be called. +The componet utility path will be pased from the `platform_component.json` and be executed by fwutil. +Below shows how the utility can be executed for the auto-update interface. ```bash ... firmware_path = parser[self.__pcp.FIRMWARE_KEY] @@ -677,7 +697,7 @@ if os.path.isfile(utility_path) and os.access(utility_path, os.X_OK): cmd = "{} -a {} {}".format( utility_path, firmware_path, - boot + boot_type ) output = subprocess.check_output(cmd, stderr=subprocess.STDOUT, shell=True) ... @@ -685,6 +705,7 @@ if os.path.isfile(utility_path) and os.access(utility_path, os.X_OK): From the above `platform_component.json` example, if the platform needs the SSD firmware update, then the auto-update can be triggered with following command. `$PWD/ssd_fw_update -a $PWD/SSD.bin fast` +##### 2.2.2.4.3.2 Platform Firmware Update Reboot Handle Plugin The reboot scripts will invoke the platform firmware update reboot plugin with boot-type, which will analyze the reboot firmware task file and execute the upgrade commands for the components present in task file. ```bash PLATFORM_FWUTIL_AU_REBOOT_HANDLE="platform_fwutil_au_reboot_handle" @@ -762,6 +783,20 @@ fi ###### Figure 5: FW install (modular) flow +## 3.4 Auto-update platform component firmwares + +### 3.4.1 Auto-update using platform component apis + +![FW Auto-update platform compoenent api flow](images/autoupdate_component_api_flow.svg "Figure 6: Platform Component FW Auto-update flow") + +###### Figure 6: Platform Component FW Auto-update flow + +### 3.4.2 Auto-update using platform utility + +![FW Auto-update platform utility flow](images/autoupdate_platform_utility_flow.svg "Figure 7: Platform Component FW Auto-update with platform utility flow") + +###### Figure 7: Platform Component FW Auto-update with platform utility flow + # 4 Tests ## 4.1 Unit tests diff --git a/doc/fwutil/images/autoupdate_component_api_flow.svg b/doc/fwutil/images/autoupdate_component_api_flow.svg new file mode 100644 index 0000000000..5d12356a77 --- /dev/null +++ b/doc/fwutil/images/autoupdate_component_api_flow.svg @@ -0,0 +1,670 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + + + + + + + + Actor lifeline.474 + FW Utility + + Sheet.185 + + + + Sheet.186 + + + + Sheet.187 + + + Sheet.188 + + + + + + + FW Utility + + + + + + + + + Object lifeline.484 + Platform_component.json + + Sheet.195 + + + + Sheet.196 + + + + Sheet.197 + + + Sheet.198 + + + + + + + Platform_component.json + + + Sheet.210 + Fwutil auto-update fw using platform component apis + + + + + + + Fwutil auto-update fw using platform component apis + + + + + + Optional fragment.932 + + + + + Sheet.216 + opt + + + + + + + + + + + + + + + opt + + Sheet.217 + [ if <image_path> not exists ] ] + + + + + + [ if <image_path> not exists ] ] + + + Activation.935 + + + + + + + + Self Message.936 + handle_error() + + + + + + + + + + + + handle_error() + + Activation.937 + + + + + + + + Message.938 + <component>.auto_update_firmware(<image_path>,<boot_type>) + + + + + + + + + + + + <component>.auto_update_firmware(<image_path>,<boot_type>) + + Return Message.940 + return <result> + + + + + + + + + + + + return <result> + + Activation.995 + + + + + + + + Self Message.996 + show_result(<chassis_name>,<component_name>,<image_path>,<res... + + + + + + + + + + + + show_result(<chassis_name>,<component_name>,<image_path>,<result>) + + + + + + + + Object lifeline.999 + сomponent : ComponentBase<Object> + + Sheet.231 + + + + Sheet.232 + + + + Sheet.233 + + + Sheet.234 + + + + + + + сomponent : ComponentBase<Object> + + + + + + + Loop fragment.1006 + + + + + Sheet.236 + loop + + + + + + + + + + + + + + + loop + + Sheet.237 + [ for component in <component_list> ] + + + + + + [ for component in <component_list> ] + + + Message.1011 + <component>.get_name() + + + + + + + + + + + + <component>.get_name() + + Return Message.1012 + return <component_name> + + + + + + + + + + + + return <component_name> + + Activation.1013 + + + + + + + + Activation.1014 + + + + + + + + + + + + Optional fragment.1017 + + + + + Sheet.243 + opt + + + + + + + + + + + + + + + opt + + Sheet.244 + [ if <component_name> is found ] + + + + + + [ if <component_name> is found ] + + + Activation.939 + + + + + + + + Activation.1100 + + + + + + + + Message.1101 + <component>.get_firmware_update_notification<image_path>) + + + + + + + + + + + + <component>.get_firmware_update_notification<image_path>) + + Return Message.1102 + return <update_notification> + + + + + + + + + + + + return <update_notification> + + Activation.1103 + + + + + + + + + + + + Optional fragment.1105 + + + + + Sheet.256 + opt + + + + + + + + + + + + + + + opt + + Sheet.257 + [ if <update_notification> not empty ] ] + + + + + + [ if <update_notification> not empty ] ] + + + Activation.1108 + + + + + + + + Self Message.1109 + show_notification(<update_notification>) + + + + + + + + + + + + show_notification(<update_notification>) + + Message.262 + get_update_available_components + + + + + + + + + + + + get_update_available_components + + Return Message.263 + return <component_list> + + + + + + + + + + + + return <component_list> + + Activation.264 + + + + + + + + Activation.265 + + + + + + + + Return Message.266 + component_map + + + + + + + + + + + + component_map + + Activation.270 + + + + + + + + + + + + Loop fragment.271 + + + + + Sheet.272 + loop + + + + + + + + + + + + + + + loop + + Sheet.273 + [ for component in <component_map> ] + + + + + + [ for component in <component_map> ] + + + Message.274 + <component>.get_firmware_version() + + + + + + + + + + + + <component>.get_firmware_version() + + Return Message.275 + return <firmware_version> + + + + + + + + + + + + return <firmware_version> + + diff --git a/doc/fwutil/images/autoupdate_platform_utility_flow.svg b/doc/fwutil/images/autoupdate_platform_utility_flow.svg new file mode 100644 index 0000000000..04648d42da --- /dev/null +++ b/doc/fwutil/images/autoupdate_platform_utility_flow.svg @@ -0,0 +1,784 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + + + + + + + + + Actor lifeline.474 + FW Utility + + Sheet.3 + + + + Sheet.4 + + + + Sheet.5 + + + Sheet.6 + + + + + + + FW Utility + + + + + + + + + Object lifeline.484 + Platform_component.json + + Sheet.8 + + + + Sheet.9 + + + + Sheet.10 + + + Sheet.11 + + + + + + + Platform_component.json + + + Sheet.12 + Fwutil auto-update fw using platform utilities + + + + + + + Fwutil auto-update fw using platform utilities + + + + + + Optional fragment.932 + + + + + Sheet.14 + opt + + + + + + + + + + + + + + + opt + + Sheet.15 + [ if <image_path> not exists ] ] + + + + + + [ if <image_path> not exists ] ] + + + Activation.935 + + + + + + + + Self Message.936 + handle_error() + + + + + + + + + + + + handle_error() + + Activation.937 + + + + + + + + Message.938 + ${component_utility} -a <image_path> <boot_type> + + + + + + + + + + + + ${component_utility} -a <image_path> <boot_type> + + Return Message.940 + return <result> + + + + + + + + + + + + return <result> + + Activation.995 + + + + + + + + Self Message.996 + show_result(<chassis_name>,<component_name>,<image_path>,<res... + + + + + + + + + + + + show_result(<chassis_name>,<component_name>,<image_path>,<result>) + + + + + + Loop fragment.1006 + + + + + Sheet.29 + loop + + + + + + + + + + + + + + + loop + + Sheet.30 + [ for component in <component_list> ] + + + + + + [ for component in <component_list> ] + + + Message.1011 + ${component_utility} -n + + + + + + + + + + + + ${component_utility} -n + + Return Message.1012 + return <component_name> + + + + + + + + + + + + return <component_name> + + Activation.1013 + + + + + + + + Activation.1014 + + + + + + + + + + + + Optional fragment.1017 + + + + + Sheet.36 + opt + + + + + + + + + + + + + + + opt + + Sheet.37 + [ if <component_name> is found ] + + + + + + [ if <component_name> is found ] + + + Activation.939 + + + + + + + + Activation.1100 + + + + + + + + Message.1101 + ${component_utility} -f + + + + + + + + + + + + ${component_utility} -f + + Return Message.1102 + return <update_notification> + + + + + + + + + + + + return <update_notification> + + Activation.1103 + + + + + + + + + + + + Optional fragment.1105 + + + + + Sheet.44 + opt + + + + + + + + + + + + + + + opt + + Sheet.45 + [ if <update_notification> not empty ] ] + + + + + + [ if <update_notification> not empty ] ] + + + Activation.1108 + + + + + + + + Self Message.1109 + show_notification(<update_notification>) + + + + + + + + + + + + show_notification(<update_notification>) + + Message.262 + get_update_available_components + + + + + + + + + + + + get_update_available_components + + Return Message.263 + return <component_list> + + + + + + + + + + + + return <component_list> + + Activation.264 + + + + + + + + Activation.265 + + + + + + + + Return Message.266 + component_map + + + + + + + + + + + + component_map + + Activation.270 + + + + + + + + + + + + Loop fragment.271 + + + + + Sheet.55 + loop + + + + + + + + + + + + + + + loop + + Sheet.56 + [ for component in <component_map> ] + + + + + + [ for component in <component_map> ] + + + Message.274 + ${component_utility} -s + + + + + + + + + + + + ${component_utility} -s + + Return Message.275 + return <firmware_version> + + + + + + + + + + + + return <firmware_version> + + + + + + + + Object lifeline.72 + platform component utility + + Sheet.73 + + + + Sheet.74 + + + + Sheet.75 + + + + + + platform component utility + + + + + + + + + Object lifeline.62 + platform component utility + + Sheet.63 + + + + Sheet.64 + + + + Sheet.65 + + + + + + platform component utility + + + + + + + + + Object lifeline.999 + platform component utility + + Sheet.24 + + + + Sheet.25 + + + + Sheet.26 + + + Sheet.27 + + + + + + + platform component utility + + + From fbaf6f49be5f5367e049262e820aa9d12dee758b Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Wed, 7 Oct 2020 17:51:18 -0700 Subject: [PATCH 16/28] update the flow of auto-update --- doc/fwutil/fwutil.md | 27 -- .../images/autoupdate_component_api_flow.svg | 402 +++++++----------- .../autoupdate_platform_utility_flow.svg | 211 +++------ 3 files changed, 200 insertions(+), 440 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index e6538a56b6..25d28fc153 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -459,33 +459,6 @@ default image path = /usr/share/sonic/device//fw_update/ } ``` -3. Non modular chassis platform with Boot action -```json -{ - "chassis": { - "Chassis1": { - "component": { - "BIOS": { - "firmware": "/usr/share/sonic///fw_update/bios.bin", - "version": "0ACLH003_02.02.010", - "boot": "cold" - }, - "CPLD": { - "firmware": "/usr/share/sonic///fw_update/cpld.bin", - "version": "10", - "boot": "powercycle" - }, - "FPGA": { - "firmware": "/usr/share/sonic///fw_update/fpga.bin", - "version": "5", - "boot": "cold" - } - } - } - } -} -``` - **Note:** 1. FW update will be disabled if component definition is not provided (e.g., 'BIOS': { }) 2. FW version will be read from image if `version` field is not provided diff --git a/doc/fwutil/images/autoupdate_component_api_flow.svg b/doc/fwutil/images/autoupdate_component_api_flow.svg index 5d12356a77..660a8b81e6 100644 --- a/doc/fwutil/images/autoupdate_component_api_flow.svg +++ b/doc/fwutil/images/autoupdate_component_api_flow.svg @@ -2,9 +2,13 @@ - + xmlns:v="http://schemas.microsoft.com/visio/2003/SVGExtensions/" width="16.5in" height="21.5in" viewBox="0 0 1188 1548" + xml:space="preserve" color-interpolation-filters="sRGB" class="st21"> + + + + + diff --git a/doc/fwutil/images/autoupdate_platform_utility_flow.svg b/doc/fwutil/images/autoupdate_platform_utility_flow.svg index 04648d42da..827a2c733f 100644 --- a/doc/fwutil/images/autoupdate_platform_utility_flow.svg +++ b/doc/fwutil/images/autoupdate_platform_utility_flow.svg @@ -1,9 +1,9 @@ - + + xml:space="preserve" color-interpolation-filters="sRGB" class="st21"> @@ -34,8 +34,7 @@ .st18 {marker-end:url(#mrkr3-68);stroke:#af5200;stroke-dasharray:7,5;stroke-linecap:round;stroke-linejoin:round;stroke-width:1} .st19 {fill:#813b00;font-family:Segoe UI;font-size:1em} .st20 {fill:#994700;font-size:1em} - .st21 {fill:#ffffff;stroke:none;stroke-linecap:butt} - .st22 {fill:none;fill-rule:evenodd;font-size:12px;overflow:visible;stroke-linecap:square;stroke-miterlimit:3} + .st21 {fill:none;fill-rule:evenodd;font-size:12px;overflow:visible;stroke-linecap:square;stroke-miterlimit:3} ]]> @@ -143,12 +142,12 @@ Sheet.4 - + Sheet.5 Sheet.6 - + @@ -173,12 +172,12 @@ Sheet.9 - + Sheet.10 Sheet.11 - + @@ -259,7 +258,7 @@ handle_error() - + Activation.937 @@ -267,7 +266,7 @@ - + Message.938 ${component_utility} -a <image_path> <boot_type> @@ -283,7 +282,7 @@ ${component_utility} -a <image_path> <boot_type> - + Return Message.940 return <result> @@ -298,7 +297,7 @@ return <result> - + Activation.995 @@ -306,7 +305,7 @@ - + Self Message.996 show_result(<chassis_name>,<component_name>,<image_path>,<res... @@ -321,16 +320,16 @@ show_result(<chassis_name>,<component_name>,<image_path>,<result>) - + Loop fragment.1006 - + - + Sheet.29 loop @@ -348,7 +347,7 @@ loop - + Sheet.30 [ for component in <component_list> ] @@ -406,16 +405,16 @@ - + Optional fragment.1017 - + - + Sheet.36 opt @@ -433,7 +432,7 @@ opt - + Sheet.37 [ if <component_name> is found ] @@ -443,7 +442,7 @@ [ if <component_name> is found ] - + Activation.939 @@ -451,115 +450,7 @@ - - Activation.1100 - - - - - - - - Message.1101 - ${component_utility} -f - - - - - - - - - - - - ${component_utility} -f - - Return Message.1102 - return <update_notification> - - - - - - - - - - - - return <update_notification> - - Activation.1103 - - - - - - - - - - - - Optional fragment.1105 - - - - - Sheet.44 - opt - - - - - - - - - - - - - - - opt - - Sheet.45 - [ if <update_notification> not empty ] ] - - - - - - [ if <update_notification> not empty ] ] - - - Activation.1108 - - - - - - - - Self Message.1109 - show_notification(<update_notification>) - - - - - - - - - - - - show_notification(<update_notification>) - + Message.262 get_update_available_components @@ -574,7 +465,7 @@ get_update_available_components - + Return Message.263 return <component_list> @@ -587,10 +478,10 @@ - + return <component_list> - + Activation.264 @@ -598,7 +489,7 @@ - + Activation.265 @@ -606,7 +497,7 @@ - + Return Message.266 component_map @@ -621,7 +512,7 @@ component_map - + Activation.270 @@ -629,16 +520,16 @@ - + Loop fragment.271 - + - + Sheet.55 loop @@ -656,7 +547,7 @@ loop - + Sheet.56 [ for component in <component_map> ] @@ -667,7 +558,7 @@ [ for component in <component_map> ] - + Message.274 ${component_utility} -s @@ -682,7 +573,7 @@ ${component_utility} -s - + Return Message.275 return <firmware_version> @@ -698,7 +589,7 @@ return <firmware_version> - + @@ -707,24 +598,24 @@ Object lifeline.72 platform component utility - + Sheet.73 - + Sheet.74 - + Sheet.75 - + platform component utility - + @@ -733,24 +624,24 @@ Object lifeline.62 platform component utility - + Sheet.63 - + Sheet.64 - + Sheet.65 - + platform component utility - + @@ -759,22 +650,22 @@ Object lifeline.999 platform component utility - + Sheet.24 - + Sheet.25 - + Sheet.26 - + Sheet.27 - + - + From d1a8e93b7399f1659817241381d936aec76a7fb8 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Thu, 29 Oct 2020 11:59:10 -0700 Subject: [PATCH 17/28] address review comments --- doc/fwutil/fwutil.md | 207 ++++++++++++++++++++++++++----------------- 1 file changed, 124 insertions(+), 83 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index 25d28fc153..bebebf6328 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -81,11 +81,11 @@ This document provides general information about FW utility implementation in SO ## List of figures -[Figure 1: FW utility High Level Design](#figure-1-fw-utility-high-level-design) -[Figure 2: Show components status flow](#figure-2-show-components-status-flow) -[Figure 3: Show available updates flow](#figure-3-show-available-updates-flow) -[Figure 4: FW install (non modular) flow](#figure-4-fw-install-non-modular-flow) -[Figure 5: FW install (modular) flow](#figure-5-fw-install-modular-flow) +[Figure 1: FW utility High Level Design](#figure-1-fw-utility-high-level-design) +[Figure 2: Show components status flow](#figure-2-show-components-status-flow) +[Figure 3: Show available updates flow](#figure-3-show-available-updates-flow) +[Figure 4: FW install (non modular) flow](#figure-4-fw-install-non-modular-flow) +[Figure 5: FW install (modular) flow](#figure-5-fw-install-modular-flow) ## List of tables @@ -95,18 +95,18 @@ This document provides general information about FW utility implementation in SO ## 1.1 Feature overview -A modern network switch is a sophisticated equipment which consists of many auxiliary components -which are responsible for managing different subsystems (e.g., PSU/FAN/QSFP/EEPROM/THERMAL) +A modern network switch is a sophisticated equipment which consists of many auxiliary components +which are responsible for managing different subsystems (e.g., PSU/FAN/QSFP/EEPROM/THERMAL) and providing necessary interfaces (e.g., I2C/SPI/JTAG). -Basically these components are complex programmable logic devices with it's own HW architecture +Basically these components are complex programmable logic devices with it's own HW architecture and software. The most important are BIOS/CPLD/FPGA etc. -It is very important to always have the latest recommended software version to improve device stability, +It is very important to always have the latest recommended software version to improve device stability, security and performance. Also, software updates can add new features and remove outdated ones. -In order to make software update as simple as possible and to provide a nice user frindly -interface for various maintenance operations (e.g., install a new FW or query current version) +In order to make software update as simple as possible and to provide a nice user frindly +interface for various maintenance operations (e.g., install a new FW or query current version) we might need a dedicated FW utility. ## 1.2 Requirements @@ -173,21 +173,22 @@ In order to improve scalability and performance a modern network switches provid 1. Non modular chassis platforms 2. Modular chassis platforms -Non modular chassis platforms may contain only one chassis. +Non modular chassis platforms may contain only one chassis. A chassis may contain it's own set of components. -Modular chassis platforms may contain only one chassis. -A chassis may contain one or more modules and it's own set of components. +Modular chassis platforms may contain only one chassis. +A chassis may contain one or more modules and it's own set of components. Each module may contain it's own set of components. Basically each chassis/module may contain one or more components (e.g., BIOS/CPLD/FPGA). -SONiC platform API provides an interface for FW maintenance operations for both modular and -non modular chassis platforms. Both modular and non modular chassis platforms share the same platform API, +SONiC platform API provides an interface for FW maintenance operations for both modular and +non modular chassis platforms. Both modular and non modular chassis platforms share the same platform API, but may have different implementation. SONiC FW utility uses platform API to interact with the various platform components. -SONiC FW utility extends to support for the automatic firmware update based on _components.json and next reboot option. +SONiC FW utility extends to support for the automatic firmware update based on "platform_components.json" under platform directory and next reboot option which is passed as a option for `fwutil autoupdate fw` command. +SONiC FW utility also extends to support for the automatic firmware update with a custom firmware package that can include any firmware update tool and the firmware update tool will be used for the firmware update if it's specified in the "platform_components.json". ## 2.2 FW utility @@ -223,6 +224,7 @@ fwutil |--- fw -z|--image= --b|--boot= |--- fw -z|--fw-image= --b|--boot= +**Note:** can be absolute path or URL ``` ### 2.2.2 Command interface @@ -271,47 +273,45 @@ Chassis1 BIOS 0ACLH004_02.02.007 Chassis BIOS 1. Non modular chassis platform ```bash root@sonic:~# fwutil show updates --image=next -Chassis Module Component Firmware Version (current/available) Status Required Boot Action --------- ------- ---------- --------------------- --------------------------------------- ------------------ ----------------------- -Chassis1 N/A BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required N/A - CPLD /cpld.bin 5 / 10 update is required N/A - FPGA /fpga.bin 5 / 5 up-to-date N/A - SSD /ssd.bin 4 / 5 update is required N/A +Chassis Module Component Firmware Version (current/available) Status +-------- ------- ---------- --------------------- --------------------------------------- ------------------ +Chassis1 N/A BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required + CPLD /cpld.bin 5 / 10 update is required + FPGA /fpga.bin 5 / 5 up-to-date + SSD /ssd.bin 4 / 5 update is required ``` 2. Non modular chassis platform when the "boot" key and value are available in `platform_components.json` ```bash root@sonic:~# fwutil show updates --image=next -Chassis Module Component Firmware Version (current/available) Status Required Boot Action --------- ------- ---------- --------------------- --------------------------------------- ------------------ ----------------------- -Chassis1 N/A BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required None - CPLD /cpld.bin 5 / 10 update is required Power cycle - FPGA /fpga.bin 5 / 5 up-to-date Cold reboot - SSD /ssd.bin 4 / 5 update is required Cold rebot, Fast reboot +Chassis Module Component Firmware Version (current/available) Status +-------- ------- ---------- --------------------- --------------------------------------- ------------------ +Chassis1 N/A BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required + CPLD /cpld.bin 5 / 10 update is required + FPGA /fpga.bin 5 / 5 up-to-date + SSD /ssd.bin 4 / 5 update is required ``` 3. Modular chassis platform ```bash root@sonic:~# fwutil show updates --image=next -Chassis Module Component Firmware Version (current/available) Status Required Boot Action --------- ------- ---------- --------------------- --------------------------------------- ------------------ ----------------------- -Chassis1 BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required N/A - CPLD /cpld.bin 5 / 10 update is required N/A - FPGA /fpga.bin 5 / 5 up-to-date N/A - SSD /ssd.bin 4 / 5 update is required N/A - Module1 CPLD /cpld.bin 5 / 10 update is required N/A - FPGA /fpga.bin 5 / 5 up-to-date N/A +Chassis Module Component Firmware Version (current/available) Status +-------- ------- ---------- --------------------- --------------------------------------- ------------------ +Chassis1 BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required + CPLD /cpld.bin 5 / 10 update is required + FPGA /fpga.bin 5 / 5 up-to-date + SSD /ssd.bin 4 / 5 update is required + Module1 CPLD /cpld.bin 5 / 10 update is required + FPGA /fpga.bin 5 / 5 up-to-date ``` 4. Custom FW Package when the "boot" key and value are available in `platform_components.json` ```bash root@sonic:~# fwutil show updates --fw-image=fw_update.tar.gz -Component Firmware Version (current/available) Status Required Boot Action ----------- --------------------- --------------------------------------- ------------------ ----------------------- -BIOS /bios.bin 0ACLH004_02.02.007 / NA update is required None -CPLD /cpld.bin 5 / 10 update is required Power cycle -FPGA /fpga.bin 5 / NA up-to-date Cold reboot -SSD /ssd.bin 4 / 5 update is required Cold reboot, Fast reboot +Component Firmware Version (current/available) Status +---------- --------------------- --------------------------------------- ------------------ +CPLD cpld.bin 5 / 10 update is required +SSD ssd.bin 4 / 5 update is required ``` 5. Auto-update status @@ -333,7 +333,7 @@ SSD /ssd.bin 4 / 5 sche ##### 2.2.2.2.1 Overview -The purpose of the install commands group is to provide an interface +The purpose of the install commands group is to provide an interface for manual FW installation of various platform components. ##### 2.2.2.2.2 Description @@ -389,12 +389,12 @@ Aborted! ##### 2.2.2.3.1 Overview -The purpose of the update commands group is to provide an interface +The purpose of the update commands group is to provide an interface for automatic FW installation of various platform components. -Automatic FW installation requires platform_components.json to be created and placed at: +Automatic FW installation requires "platform_components.json" to be created and placed at: _sonic-buildimage/device///platform_components.json_ -default image path = /usr/share/sonic/device//fw_update/ +Recommanded image path = /lib/firmware// **Example:** 1. Non modular chassis platform @@ -404,15 +404,15 @@ default image path = /usr/share/sonic/device//fw_update/ "Chassis1": { "component": { "BIOS": { - "firmware": "/usr/share///fw_update/bios.bin", + "firmware": "/lib/firmware//bios.bin", "version": "0ACLH003_02.02.010" }, "CPLD": { - "firmware": "/usr/share/sonic///fw_update/cpld.bin", + "firmware": "/lib/firmware//cpld.bin", "version": "10" }, "FPGA": { - "firmware": "/usr/share/sonic///fw_update/fpga.bin", + "firmware": "/lib/firmware//fpga.bin", "version": "5" } } @@ -428,15 +428,15 @@ default image path = /usr/share/sonic/device//fw_update/ "Chassis1": { "component": { "BIOS": { - "firmware": "/usr/share/sonic///fw_update/bios.bin", + "firmware": "/lib/firmware//bios.bin", "version": "0ACLH003_02.02.010" }, "CPLD": { - "firmware": "/usr/share/sonic///fw_update/cpld.bin", + "firmware": "/lib/firmware//cpld.bin", "version": "10" }, "FPGA": { - "firmware": "/usr/share/sonic///fw_update/fpga.bin", + "firmware": "/lib/firmware//fpga.bin", "version": "5" } } @@ -446,11 +446,11 @@ default image path = /usr/share/sonic/device//fw_update/ "Module1": { "component": { "CPLD": { - "firmware": "/usr/share/sonic///fw_update/cpld.bin", + "firmware": "/lib/firmware//cpld.bin", "version": "10" }, "FPGA": { - "firmware": "/usr/share/sonic///fw_update/fpga.bin", + "firmware": "/lib/firmware//fpga.bin", "version": "5" } } @@ -519,26 +519,55 @@ Aborted! #### 2.2.2.4 Auto-update commands ##### 2.2.2.4.1 Overview -The purpose of the auto-update commands group is to provide and interface for automatic fw updates of various platform components based on the boot option and the platform firmwareupdate configuration file - platform_components.json. +The purpose of the auto-update commands group is to provide and interface for automatic fw updates of various platform components based on the boot option and the platform firmwareupdate configuration file - "platform_components.json". The existing FWutil infra supports the upgrade of platform components which can be performed during run time. The SSD upgrade for certain platforms requires the unmount of the filesystems and this needs to be incorporated as part of the reboot scripts. To integrate the upgrade of these platform components which can’t be performed during run time, the FWutil requires few more enhancements that specifies the reboot-type during which the user expects the upgrade to happen. +New component api is introduced to support the component firmware auto-update as follows. +``` + def auto_update_firmware(self, image_path, boot_action): + """ + Updates firmware of the component + + This API performs firmware update automatically based on boot_action: it assumes firmware installation + and/or creating a loading task during a boot action, if needed, in a single call. + In case platform component requires some extra steps (apart from calling Low Level Utility) + to load the installed firmware (e.g, reboot, power cycle, etc.) - this will be done automatically during the reboot. + The loading task will be created by API. + + Args: + image_path: A string, path to firmware image + boot_action: A string, boot action following the upgrade + + Returns: + Output: A string, status and info + status: True or False, firmware auto-update status + info: The detail information of the firmware auto-update status. + "updated"/"installed"(which needs a reboot for the firmware to be active)/"scheduled" + + Raises: + RuntimeError: auto-update failure cause + """ + raise NotImplementedError +``` +The installed and updated firmware information and scheduled task should be logged in "_fw_auto_update" under "/tmp/fwupdate/" directory. This allows that fwutil to recognize the firmware auto-update status and handle any further firmware auto-update request. + The FWutil infra section below indicates the necessary changes to add support for auto update during reboot. The Platform plugins section describes the plugins that a platform must implement to support auto updates when the platform component APIs are not available. Automatic FW installation requires default platform_components.json to be created and placed at: _sonic-buildimage/device///platform_components.json_ -default image path = /usr/share/sonic/device// +Recommended image path is "/lib/firmware/". Auto-update command can support the standalone custom firmware image package with --fw-image option. -The package can be any format between `.tar` or `.tar.gz` and should have the `platform_components.json`, the firmware image(s). +The package can be any format between ".tar" or ".tar.gz" and should have the "platform_components.json", the firmware image(s). The package can have the auto-update plugin if the platform doesn't support platform api or if plugin needs to be updatedplugin. -The package can also have the component upgrade utility(script) and the utility will be used for the component firmware upgrade if it's specified in `platform_compnents.json`. -The `fwutil auto-update` commands uncompress the package and parse the `platform_components.json` to retrieve the firmware information. +The package can also have the component upgrade utility(script) and the utility will be used for the component firmware upgrade if it's specified in "platform_compnents.json". +The `fwutil auto-update` commands uncompress the package and parse the "platform_components.json" to retrieve the firmware information. -If the script path is available for the component firmware configuration in the `platform_components.json`, +If the script path is available for the component firmware configuration in the "platform_components.json", it means that the specific component firmware upgrade shall use the script to process the fwutil commands. `2.2.2.4.3 Platform Component Firmware Update Utility` explains the requirement of the component firmware upgrade utility to interfere with the fwutil to support the auto-update command - mainly status and install. @@ -553,14 +582,13 @@ to interfere with the fwutil to support the auto-update command - mainly status 1. auto-update command for installation and reboot task creation ```bash root@sonic:~# fwutil auto-update fw --yes --image= --boot= -Available FW updates with from boot image : COMPONENT1 (and COMPONENT2) - firmware update will be done during with version <#new_version> (current version #current_version) + firmware auto-update starting: with ... - firmware update is starting with version <#new_version2> (current version #current_version2) + firmware auto-update status: with ... - firmware update is in progress with version <#new_version2> (current version #current_version2) + firmware auto-update starting: with ... - firmware update is done during with version <#new_version> (current version #current_version) + firmware auto-update status: with ... All firmware update has been completed. ``` @@ -568,26 +596,39 @@ All firmware update has been completed. This is examples of a platform which supports the SSD firmware update during fast reboot and cold reboot with different commands along with CPLD firmware update available only for the cold reboot which can perform a power cycle triggered by some register setting. -Example 1: SSD firmware update is available for fast-reboot upgrade path. +Example 1: BIOS and SSD firmware update is available for fast-reboot upgrade path. +BIOS firmware update is going to be updated and no further task is needed during reboot. SSD firmware update is logged in a platform defined designated file and it will be updated during fast-reboot. ```bash root@sonic:~# fwutil auto-update fw --yes --image=next --boot=fast -Available FW updates with fast-reboot from next boot image : SSD -SSD firmware update will be done during fastreboot with version 5 (current version 4) +BIOS firmware auto-update starting: bios.bin with fast +... +BIOS firmware auto-update status: True with Updated +... +SSD firmware auto-update starting: ssd.bin with fast +... +SSD firmware auto-update status: True with Scheduled +... All firmware update has been completed. ``` -Example 2: SSD and CPLD update is available for cold reboot upgrade path. +Example 2: BIOS, SSD and CPLD update is available for cold reboot upgrade path. +BIOS firmware update is going to be updated and no further task is needed during reboot. SSD firmware update is logged in a platform defined designated file and it will be updated during cold reboot. CPLD firmware update is going to be done with this command and the CPLD completion activity will be performed during cold reboot once all reboot processes are finished. The CPLD completion activity for this case is a power cycle triggered by the hw register setting. ```bash root@sonic:~# fwutil auto-update fw --yes --image=next --boot=cold -Available FW updates with fast-reboot from next boot image : SSD and CPLD -SSD firmware update will be done during cold-reboot with version 5 (current version 4) +BIOS firmware auto-update starting: bios.bin with cold +... +BIOS firmware auto-update status: True with Updated +... +SSD firmware auto-update starting: ssd.bin with cold +... +SSD firmware auto-update status: True with Scheduled ... -CPLD firmware update is in progress with version 5 (current version 4) +CPLD firmware auto-update starting: cpld.bin with cold ... -CPLD firmware update is completed with version 5 (current version 4) +CPLD firmware auto-update status: True with Installed ... All firmware update has been completed. ``` @@ -605,11 +646,11 @@ the platform component utility will perform the equivalent process of `auto-upda The component utility can perform the firmware update if the firmware update doesn't need any boot action required after the update. Otherwise, it will create a task file if any process or handling for the component firmware update needs to be done during the reboot and also if the update can be done for the specified reboot type. -The componenet utility should be defined with key value `utility` in the component object of `platform_component.json` to be called by fwutil instead of the platform api. +The componenet utility should be defined with key value `utility` in the component object of `platform_components.json` to be called by fwutil instead of the platform api. The task file will be platform-specific. **Example:** -1. `platform_component.json` with platform specific utility. +1. `platform_components.json` with platform specific utility. ```json { "chassis": { @@ -651,16 +692,16 @@ Here are the interface requirements to support them. - auto-update interface needs two arguments : image_path and boot_type - response : the result of auto-update as follows ```json - "True" : "completed" - "True" : "scheduled" - "True" : "need_action" - "False" : ${ErrorCode} + "True : updated" + "True : scheduled" + "True : installed" + "False : ${ErrorCode}" ``` **Optional) The utility can be supported for other platform api substitues like `compoenent_update` and `compoenent_install` with |-u(--update)|-i(--install)** -The component utility needs to be called by the FWutil command to perform the firmware auto-update process if it's defined in the `platform_component.json`, otherwise, the platform component api will be called. -The componet utility path will be pased from the `platform_component.json` and be executed by fwutil. +The component utility needs to be called by the FWutil command to perform the firmware auto-update process if it's defined in the `platform_components.json`, otherwise, the platform component api will be called. +The componet utility path will be pased from the `platform_components.json` and be executed by fwutil. Below shows how the utility can be executed for the auto-update interface. ```bash ... @@ -675,7 +716,7 @@ if os.path.isfile(utility_path) and os.access(utility_path, os.X_OK): output = subprocess.check_output(cmd, stderr=subprocess.STDOUT, shell=True) ... ``` -From the above `platform_component.json` example, if the platform needs the SSD firmware update, then the auto-update can be triggered with following command. +From the above `platform_components.json` example, if the platform needs the SSD firmware update, then the auto-update can be triggered with following command. `$PWD/ssd_fw_update -a $PWD/SSD.bin fast` ##### 2.2.2.4.3.2 Platform Firmware Update Reboot Handle Plugin From 314cc367aa013d50ad2ef3514fbc340800c6688b Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Fri, 6 Nov 2020 11:42:55 -0800 Subject: [PATCH 18/28] address review comments about the task file definition --- doc/fwutil/fwutil.md | 46 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index bebebf6328..75ea867cca 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -553,6 +553,52 @@ New component api is introduced to support the component firmware auto-update as raise NotImplementedError ``` The installed and updated firmware information and scheduled task should be logged in "_fw_auto_update" under "/tmp/fwupdate/" directory. This allows that fwutil to recognize the firmware auto-update status and handle any further firmware auto-update request. +The "_fw_auto_update" is expected to be formatted as below. +``` +{ + "chassis": { + "Chassis1": { + "component": { + "COMPONENT1": { + "status": "", + "task": "" + }, + "COMPONENT2": { + "status": "", + "task": "" + }, + } + } + }, +} +``` +Here is the example of the firmware update task file with cold reboot as boot_type action. +And the components available for the update are BIOS, CPLD, and SSD. +In this example, BIOS firmware got updated, CPLD firmware got installed but powercycle* is needed, and SSD firmware update is scheduled during boot. +*powercycle can be triggered by cold reboot script in this case. +``` +{ + "chassis": { + "Chassis1": { + "component": { + "BIOS": { + "status": "updated", + "task": "N/A" + }, + "CPLD": { + "status": "installed", + "task": "powercycle" + }, + "SSD": { + "status": "scheduled", + "task": "update" + } + } + } + }, +} +``` + The FWutil infra section below indicates the necessary changes to add support for auto update during reboot. The Platform plugins section describes the plugins that a platform must implement to support auto updates when the platform component APIs are not available. From 0acc4c972808c933038fdff5dc5b88bd35234d95 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Sun, 8 Nov 2020 23:31:30 -0800 Subject: [PATCH 19/28] review comments --- doc/fwutil/fwutil.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index 75ea867cca..635efc9ddf 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -201,6 +201,8 @@ fwutil | |--- version | |--- status | |--- updates -i|--image= +| |--- updates -z|--fw-image= +| |--- auto-update status | |--- install | |--- chassis @@ -221,7 +223,7 @@ fwutil | |--- fw -y|--yes -f|--force -i|--image= | |--- auto-update - |--- fw -z|--image= --b|--boot= + |--- fw -i|--image= --b|--boot= |--- fw -z|--fw-image= --b|--boot= **Note:** can be absolute path or URL @@ -316,7 +318,7 @@ SSD ssd.bin 4 / 5 upda 5. Auto-update status ```bash -root@sonic:~# fwutil show auto-updates status +root@sonic:~# fwutil show auto-update status Component Firmware Version (current/available) Status ---------- --------------------- --------------------------------------- ------------------------- CPLD /cpld.bin 5 / 10 updated but need a power-cycle From 5a2324e991c40ec831e3af11fd7c3e9315ee662c Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Wed, 11 Nov 2020 17:44:31 -0800 Subject: [PATCH 20/28] review comments --- doc/fwutil/fwutil.md | 129 ++++++++++++++++++++++++------------------- 1 file changed, 73 insertions(+), 56 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index 635efc9ddf..26a16b1636 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -202,7 +202,7 @@ fwutil | |--- status | |--- updates -i|--image= | |--- updates -z|--fw-image= -| |--- auto-update status +| |--- auto_update_status | |--- install | |--- chassis @@ -222,7 +222,7 @@ fwutil | |--- component | |--- fw -y|--yes -f|--force -i|--image= | -|--- auto-update +|--- auto_update |--- fw -i|--image= --b|--boot= |--- fw -z|--fw-image= --b|--boot= @@ -310,19 +310,20 @@ Chassis1 BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH 4. Custom FW Package when the "boot" key and value are available in `platform_components.json` ```bash root@sonic:~# fwutil show updates --fw-image=fw_update.tar.gz -Component Firmware Version (current/available) Status ----------- --------------------- --------------------------------------- ------------------ -CPLD cpld.bin 5 / 10 update is required -SSD ssd.bin 4 / 5 update is required +Chassis Module Component Firmware Version (current/available) Status +-------- ------- ---------- ----------------------------- --------------------------------------- ------------------ +Chassis1 N/A CPLD /cpld.bin 5 / 10 update is required + SSD /ssd.bin 4 / 5 update is required ``` 5. Auto-update status ```bash -root@sonic:~# fwutil show auto-update status -Component Firmware Version (current/available) Status ----------- --------------------- --------------------------------------- ------------------------- -CPLD /cpld.bin 5 / 10 updated but need a power-cycle -SSD /ssd.bin 4 / 5 scheduled in cold reboot +root@sonic:~# fwutil show auto_update_status +Firmware auto-update performed for cold reboot +Component Status Info +------------- -------- --------- +MSN2700/SSD True installed +MSN2700/CPLD1 True installed ``` **Supported options:** @@ -554,50 +555,51 @@ New component api is introduced to support the component firmware auto-update as """ raise NotImplementedError ``` -The installed and updated firmware information and scheduled task should be logged in "_fw_auto_update" under "/tmp/fwupdate/" directory. This allows that fwutil to recognize the firmware auto-update status and handle any further firmware auto-update request. -The "_fw_auto_update" is expected to be formatted as below. +The installed and updated firmware information and scheduled task should be logged in "_fw_auto_update" under "/tmp/firmwareupdate/" directory. Since each platform plugin will parse the _auto_update file to perform the update during the reboot, the contents can be defined and used by the platform vendors. + +This allows that fwutil to recognize the firmware auto-update status and handle any further firmware auto-update request along with fw_auto_updated_status which contains the performed auto-updated status information. +The "fw_auto_updated_status" is located at /tmp/firmwareupdate/ directory same as reboot task file and it will be formatted and contains the component's firmware auto-updated status information as below and parsed for `fwutil show auto_updated_status` command. + ``` { - "chassis": { - "Chassis1": { - "component": { - "COMPONENT1": { - "status": "", - "task": "" - }, - "COMPONENT2": { - "status": "", - "task": "" - }, - } + "": [ + { + "status": , + "comp": "", + "info": "" + }, + { + "status": , + "comp": "", + "info": "" } - }, + ] } ``` -Here is the example of the firmware update task file with cold reboot as boot_type action. +Here is the example of the firmware update status file with cold reboot as boot_type action. And the components available for the update are BIOS, CPLD, and SSD. In this example, BIOS firmware got updated, CPLD firmware got installed but powercycle* is needed, and SSD firmware update is scheduled during boot. *powercycle can be triggered by cold reboot script in this case. ``` +admin@sonic:~/fwutil$ cat /tmp/firmwareupdate/fw_auto_update_status { - "chassis": { - "Chassis1": { - "component": { - "BIOS": { - "status": "updated", - "task": "N/A" - }, - "CPLD": { - "status": "installed", - "task": "powercycle" - }, - "SSD": { - "status": "scheduled", - "task": "update" - } - } + "cold": [ + { + "status": true, + "comp": "MSN2700/BIOS", + "info": "updated" + }, + { + "status": true, + "comp": "MSN2700/SSD", + "info": "scheduled" + }, + { + "status": true, + "comp": "MSN2700/CPLD1", + "info": "installed" } - }, + ] } ``` @@ -630,15 +632,15 @@ to interfere with the fwutil to support the auto-update command - mainly status 1. auto-update command for installation and reboot task creation ```bash root@sonic:~# fwutil auto-update fw --yes --image= --boot= - firmware auto-update starting: with + firmware auto-update starting: with ... - firmware auto-update status: with + firmware auto-update status: with ... - firmware auto-update starting: with + firmware auto-update starting: with ... - firmware auto-update status: with + firmware auto-update status: with ... -All firmware update has been completed. +All firmware auto-update has been performed. ``` This is examples of a platform which supports the SSD firmware update during fast reboot and cold reboot with different commands @@ -649,15 +651,16 @@ BIOS firmware update is going to be updated and no further task is needed during SSD firmware update is logged in a platform defined designated file and it will be updated during fast-reboot. ```bash root@sonic:~# fwutil auto-update fw --yes --image=next --boot=fast -BIOS firmware auto-update starting: bios.bin with fast +Firmware auto-update for boot_type fast is allowed +MSN2700/BIOS firmware auto-update starting: /lib/firmware/mlnx/bios.bin with fast ... BIOS firmware auto-update status: True with Updated ... -SSD firmware auto-update starting: ssd.bin with fast +MSN2700/SSD firmware auto-update starting: /lib/firmware/mlnx/ssd.bin with fast ... SSD firmware auto-update status: True with Scheduled ... -All firmware update has been completed. +All firmware auto-update has been performed. ``` Example 2: BIOS, SSD and CPLD update is available for cold reboot upgrade path. BIOS firmware update is going to be updated and no further task is needed during reboot. @@ -666,19 +669,33 @@ CPLD firmware update is going to be done with this command and the CPLD completi once all reboot processes are finished. The CPLD completion activity for this case is a power cycle triggered by the hw register setting. ```bash root@sonic:~# fwutil auto-update fw --yes --image=next --boot=cold -BIOS firmware auto-update starting: bios.bin with cold +Firmware auto-update for boot_type cold is allowed +MSN2700/BIOS firmware auto-update starting: /lib/firmware/mlnx/bios.bin with cold ... BIOS firmware auto-update status: True with Updated ... -SSD firmware auto-update starting: ssd.bin with cold +MSN2700/SSD firmware auto-update starting: /lib/firmware/mlnx/ssd.bin with cold ... SSD firmware auto-update status: True with Scheduled ... -CPLD firmware auto-update starting: cpld.bin with cold +MSN2700/CPLD firmware auto-update starting: /lib/firware/mlnx/cpld.bin with cold ... CPLD firmware auto-update status: True with Installed +All firmware auto-update has been performed. +``` + +Example 3: SSD and CPLD update is available for cold reboot upgrade path. +BIOS firmware update is going to be updated and no further task is needed during reboot. +SSD firmware update is logged in a platform defined designated file and it will be updated during cold reboot. +CPLD firmware update is going to be done with this command and the CPLD completion activity will be performed during cold reboot +once all reboot processes are finished. The CPLD completion activity for this case is a power cycle triggered by the hw register setting. +``` +admin@sonic:~# sudo fwutil auto_update fw --fw_image=fwpackage.tar.gz --boot=cold +Firmware auto-update for boot_type cold is allowed +MSN2700/CPLD1 firmware auto-update starting: /tmp/firmwareupdate/fwpackage/fwpackage/sn2700_cpld.mpfa with boot_type cold ... -All firmware update has been completed. +CPLD1 firmware auto-update status: True with installed +All firmware auto-update has been performed. ``` **Supported options:** From 44afb41b7e3875b4851d110205609383bfc72bb4 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Fri, 20 Nov 2020 01:43:28 -0800 Subject: [PATCH 21/28] review comments --- doc/fwutil/fwutil.md | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index 26a16b1636..ce8cab6830 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -222,7 +222,7 @@ fwutil | |--- component | |--- fw -y|--yes -f|--force -i|--image= | -|--- auto_update +|--- auto-update |--- fw -i|--image= --b|--boot= |--- fw -z|--fw-image= --b|--boot= @@ -283,18 +283,7 @@ Chassis1 N/A BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH SSD /ssd.bin 4 / 5 update is required ``` -2. Non modular chassis platform when the "boot" key and value are available in `platform_components.json` -```bash -root@sonic:~# fwutil show updates --image=next -Chassis Module Component Firmware Version (current/available) Status --------- ------- ---------- --------------------- --------------------------------------- ------------------ -Chassis1 N/A BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH004_02.02.010 update is required - CPLD /cpld.bin 5 / 10 update is required - FPGA /fpga.bin 5 / 5 up-to-date - SSD /ssd.bin 4 / 5 update is required -``` - -3. Modular chassis platform +2. Modular chassis platform ```bash root@sonic:~# fwutil show updates --image=next Chassis Module Component Firmware Version (current/available) Status @@ -307,7 +296,7 @@ Chassis1 BIOS /bios.bin 0ACLH004_02.02.007 / 0ACLH FPGA /fpga.bin 5 / 5 up-to-date ``` -4. Custom FW Package when the "boot" key and value are available in `platform_components.json` +3. Custom FW Package ```bash root@sonic:~# fwutil show updates --fw-image=fw_update.tar.gz Chassis Module Component Firmware Version (current/available) Status @@ -316,7 +305,8 @@ Chassis1 N/A CPLD /cpld.bin 5 / 10 SSD /ssd.bin 4 / 5 update is required ``` -5. Auto-update status +**The following command displays the Component FW auto-update satus:** +1. Auto-update status ```bash root@sonic:~# fwutil show auto_update_status Firmware auto-update performed for cold reboot @@ -543,12 +533,14 @@ New component api is introduced to support the component firmware auto-update as Args: image_path: A string, path to firmware image boot_action: A string, boot action following the upgrade + - none/fast/warm/cold Returns: Output: A string, status and info status: True or False, firmware auto-update status info: The detail information of the firmware auto-update status. - "updated"/"installed"(which needs a reboot for the firmware to be active)/"scheduled" + - True : "updated"/"installed"(which needs a reboot for the firmware to be active)/"scheduled" + - False : "ns_boot_type/image_error/exec_fail" Raises: RuntimeError: auto-update failure cause From 289263ed37c9f0485d9c60d5c1ece65b19b1cc38 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Mon, 23 Nov 2020 00:11:51 -0800 Subject: [PATCH 22/28] review comments --- doc/fwutil/fwutil.md | 50 ++++++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 20 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index ce8cab6830..3b66bc730b 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -536,21 +536,28 @@ New component api is introduced to support the component firmware auto-update as - none/fast/warm/cold Returns: - Output: A string, status and info - status: True or False, firmware auto-update status - info: The detail information of the firmware auto-update status. - - True : "updated"/"installed"(which needs a reboot for the firmware to be active)/"scheduled" - - False : "ns_boot_type/image_error/exec_fail" + Output: A return code + return_code: An integer number, status of component firmware auto-update + - return code of a positive number indicates successful auto-update + - status_installed = 1 + - status_updated = 2 + - status_scheduled = 3 + - return_code of a negative number indicates failed auto-update + - status_err_image = -1 + - status_err_others = -2 + - return_code of zero indicates the boot_type not supported for the component firmware auto-update Raises: RuntimeError: auto-update failure cause """ raise NotImplementedError ``` -The installed and updated firmware information and scheduled task should be logged in "_fw_auto_update" under "/tmp/firmwareupdate/" directory. Since each platform plugin will parse the _auto_update file to perform the update during the reboot, the contents can be defined and used by the platform vendors. +The return_code of auto_update_firmware() which indicates the firmware auto-update status, will be logged in "fw_au_status" under "/tmp/firmwareupdate/" directory by fwutil and the status file will be used for the `fwutil show auto_update_status` command. -This allows that fwutil to recognize the firmware auto-update status and handle any further firmware auto-update request along with fw_auto_updated_status which contains the performed auto-updated status information. -The "fw_auto_updated_status" is located at /tmp/firmwareupdate/ directory same as reboot task file and it will be formatted and contains the component's firmware auto-updated status information as below and parsed for `fwutil show auto_updated_status` command. +Any scheduled component firmware update needs to be logged in "_fw_au_task". +Each vendor needs to implement the reboot auto-update task handler plugin which is platform specific plugin and is expected to be named as "platform_fw_au_reboot_handle". +The plugin will parse the "_fw_au_task" file and perform the update during the reboot if needed. +The contents of the task file can be defined by the platform vendors and be utilized by the platform specific reboot plugin. ``` { @@ -573,7 +580,7 @@ And the components available for the update are BIOS, CPLD, and SSD. In this example, BIOS firmware got updated, CPLD firmware got installed but powercycle* is needed, and SSD firmware update is scheduled during boot. *powercycle can be triggered by cold reboot script in this case. ``` -admin@sonic:~/fwutil$ cat /tmp/firmwareupdate/fw_auto_update_status +admin@sonic:~/fwutil$ cat /tmp/firmwareupdate/fw_au_status { "cold": [ { @@ -747,13 +754,7 @@ Here are the interface requirements to support them. 3. {utility} -a(--autoupdate) : able to perform the auto-update action : - equivalent to the component api's auto_update_firmware(image_path, boot_type) - auto-update interface needs two arguments : image_path and boot_type - - response : the result of auto-update as follows - ```json - "True : updated" - "True : scheduled" - "True : installed" - "False : ${ErrorCode}" - ``` + - response : the return_code that indicates the status of auto-update (please refer to section 2.2.2.4.1) **Optional) The utility can be supported for other platform api substitues like `compoenent_update` and `compoenent_install` with |-u(--update)|-i(--install)** @@ -777,12 +778,21 @@ From the above `platform_components.json` example, if the platform needs the SSD `$PWD/ssd_fw_update -a $PWD/SSD.bin fast` ##### 2.2.2.4.3.2 Platform Firmware Update Reboot Handle Plugin -The reboot scripts will invoke the platform firmware update reboot plugin with boot-type, which will analyze the reboot firmware task file and execute the upgrade commands for the components present in task file. +If any specific component firmware update needs to be done only during the reboot, auto_update_firmware() api will log the firmware update to the "_fw_au_task as explained in 2.2.2.4.1. +Platform firmware update reboot plugin will handle the task during the rebooot and will be invoked by the reboot script with its reboot-type. +The plugin is expected to analyze the task file to understand what component firmware update has been scheduled for which reboot and determine if the component firmware update can be performed for the reboot or not. +After the determination, firmware update will be done by the plugin if any firmware update is scheduled for the reboot. +If the passed reboot_type to the plugin is different than the boot_type of task file, the pluin should exit with error code so that the reboot script can fail for the error case. + ```bash -PLATFORM_FWUTIL_AU_REBOOT_HANDLE="platform_fwutil_au_reboot_handle" -if [[ -x ${DEVPATH}/${PLATFORM}/${PLATFORM_FWUTIL_AU_REBOOT_HANDLE} ]]; then +PLATFORM_FW_AU_REBOOT_HANDLE="platform_fw_au_reboot_handle" +if [[ -x ${DEVPATH}/${PLATFORM}/${PLATFORM_FW_AU_REBOOT_HANDLE} ]]; then debug "Handling task file for boot type ${REBOOT_TYPE}” - ${DEVPATH}/${PLATFORM}/${PLATFORM_FWUTIL_AU_REBOOT_HANDLE} ${REBOOT_TYPE} + ${DEVPATH}/${PLATFORM}/${PLATFORM_FW_AU_REBOOT_HANDLE} ${REBOOT_TYPE} || PLATFORM_FW_AU_RC=$? + if [[ $PLATFORM_FW_AU_RC -ne 0 ]]; then + error "Failed to handle the platform firmware auto-update for ${REBOOT_TYPE} Exit code: $PLATFORM_FW_AU_RC" + exit "${EXIT_PLATFORM_FW_AU_FAILURE}" + fi fi ``` From 8700f977e8f61f4faa9f1a11789ccf7a64900f3a Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Tue, 24 Nov 2020 00:05:12 -0800 Subject: [PATCH 23/28] review comments --- doc/fwutil/fwutil.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index 3b66bc730b..d0495179ae 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -543,9 +543,9 @@ New component api is introduced to support the component firmware auto-update as - status_updated = 2 - status_scheduled = 3 - return_code of a negative number indicates failed auto-update - - status_err_image = -1 - - status_err_others = -2 - - return_code of zero indicates the boot_type not supported for the component firmware auto-update + - status_err_boot_type = -1 + - status_err_image = -2 + - status_err_others = -3 Raises: RuntimeError: auto-update failure cause From efca3bf03a80920d74e343d0dc46636555e24b26 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Mon, 30 Nov 2020 00:21:02 -0800 Subject: [PATCH 24/28] add more detail about FW package --- doc/fwutil/fwutil.md | 51 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 48 insertions(+), 3 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index d0495179ae..befd59fbe0 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -223,8 +223,8 @@ fwutil | |--- fw -y|--yes -f|--force -i|--image= | |--- auto-update - |--- fw -i|--image= --b|--boot= - |--- fw -z|--fw-image= --b|--boot= + |--- fw -i|--image= --b|--boot= + |--- fw -z|--fw-image= --b|--boot= **Note:** can be absolute path or URL ``` @@ -512,7 +512,7 @@ Aborted! #### 2.2.2.4 Auto-update commands ##### 2.2.2.4.1 Overview -The purpose of the auto-update commands group is to provide and interface for automatic fw updates of various platform components based on the boot option and the platform firmwareupdate configuration file - "platform_components.json". +The purpose of the auto-update commands group is to provide and interface for automatic fw updates of various platform components based on the boot option and the platform firmware update configuration file - "platform_components.json". The existing FWutil infra supports the upgrade of platform components which can be performed during run time. The SSD upgrade for certain platforms requires the unmount of the filesystems and this needs to be incorporated as part of the reboot scripts. @@ -616,6 +616,51 @@ The package can have the auto-update plugin if the platform doesn't support plat The package can also have the component upgrade utility(script) and the utility will be used for the component firmware upgrade if it's specified in "platform_compnents.json". The `fwutil auto-update` commands uncompress the package and parse the "platform_components.json" to retrieve the firmware information. + +Here is the firmwareupdate directory structure while fwutil handles the `fwutil auto-update fw` and `fwutil show auto_update_status` command. +``` +/tmp/firmwareupdate/ + |--- fw_au_status + |--- _fw_au_task* + |--- fwpackage** + |--- platform_components.json + |--- + |--- *** +``` +*: _fw_au_task can be generated by the auto_update_firmware() api only if the firmware update needs to be scheduled during the action. +**: the custom firmware image package provided with --fw-image option, will be extracted under fwpackage directory. +***: can be used if it's defined in platform_components.json in the custom firmware image package. + +Here is the example of platform_components.json in the firmware image package. +```json +{ + "chassis": { + "Chassis1": { + "component": { + "BIOS": { + }, + "CPLD": { + "firmware": "cpld.bin", + "version": "10" + }, + "SSD": { + "firmware": "ssd.bin", + "version": "5" + } + } + } + } +} +``` + +Here is the example of firmware image package contents with the platform_components.json shown above. +```bash +root@sonic:~$ tar tvf fwpackage.tar +-rw-r--r-- root/root 551 2020-11-18 17:05 platform_components.json +-rwxr-xr-x root/root 1436 2020-11-15 19:05 cpld.bin +-rw-r--r-- root/root 546141 2020-11-17 20:35 ssd.bin +``` + If the script path is available for the component firmware configuration in the "platform_components.json", it means that the specific component firmware upgrade shall use the script to process the fwutil commands. `2.2.2.4.3 Platform Component Firmware Update Utility` explains the requirement of the component firmware upgrade utility From 8cbf6273075046c5f30721af19e60cb10435ef9d Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Wed, 2 Dec 2020 15:27:31 -0800 Subject: [PATCH 25/28] Add more information about firmware image package and platform api return code: installed --- doc/fwutil/fwutil.md | 210 ++++++++++++++++++++++++++----------------- 1 file changed, 127 insertions(+), 83 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index befd59fbe0..4041049e12 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -195,6 +195,7 @@ SONiC FW utility also extends to support for the automatic firmware update with ### 2.2.1 Command structure **User interface**: + ``` fwutil |--- show @@ -226,8 +227,11 @@ fwutil |--- fw -i|--image= --b|--boot= |--- fw -z|--fw-image= --b|--boot= -**Note:** can be absolute path or URL ``` +**Note:** +- can be absolute path or URL +- --image and --fw-image can not be supported at the same time + ### 2.2.2 Command interface @@ -308,19 +312,21 @@ Chassis1 N/A CPLD /cpld.bin 5 / 10 **The following command displays the Component FW auto-update satus:** 1. Auto-update status ```bash -root@sonic:~# fwutil show auto_update_status +root@sonic:~# fwutil show auto-update status Firmware auto-update performed for cold reboot -Component Status Info -------------- -------- --------- -MSN2700/SSD True installed -MSN2700/CPLD1 True installed +Component Status Info +------------- --------- -------------------------------------- +MSN2700/SSD scheduled installation scheduled for cold reboot +MSN2700/CPLD1 installed need cold reboot to be completed ``` **Supported options:** 1. -i|--image - show updates using current/next SONiC image 2. -z|--fw-image - show updates using custom FW package -**Note:** the default option is _--image=current_ +**Note:** +- the default option is _--image=current_ +- --image and --fw-image can not be supported at the same time #### 2.2.2.2 Install commands @@ -519,7 +525,8 @@ The SSD upgrade for certain platforms requires the unmount of the filesystems an To integrate the upgrade of these platform components which can’t be performed during run time, the FWutil requires few more enhancements that specifies the reboot-type during which the user expects the upgrade to happen. New component api is introduced to support the component firmware auto-update as follows. -``` + +```bash def auto_update_firmware(self, image_path, boot_action): """ Updates firmware of the component @@ -554,49 +561,71 @@ New component api is introduced to support the component firmware auto-update as ``` The return_code of auto_update_firmware() which indicates the firmware auto-update status, will be logged in "fw_au_status" under "/tmp/firmwareupdate/" directory by fwutil and the status file will be used for the `fwutil show auto_update_status` command. +In case that a firmware update needs any additional step to complete the firmware update but the installation time is longer than the boot time requirement, auto-update platform api is expected to install the firmware and perform the complete action during the reboot via `platform_fw_au_reboot_handle` or `platform_reboot` plugin. +For example, some cpld update needs a power cycle to complete the firmware update and some cpld update needs a register triggered power-cycle to give some refresh time for the new firmware to be effective on the system. + Any scheduled component firmware update needs to be logged in "_fw_au_task". Each vendor needs to implement the reboot auto-update task handler plugin which is platform specific plugin and is expected to be named as "platform_fw_au_reboot_handle". The plugin will parse the "_fw_au_task" file and perform the update during the reboot if needed. The contents of the task file can be defined by the platform vendors and be utilized by the platform specific reboot plugin. -``` +```json { - "": [ - { - "status": , - "comp": "", - "info": "" + "": { + "status": "" + "info": " reboot to be completed/completed/installation scheduled for reboot/\ reboot not supported for auto-update/ErrorMsg>" }, - { - "status": , - "comp": "", - "info": "" - } - ] } ``` + Here is the example of the firmware update status file with cold reboot as boot_type action. And the components available for the update are BIOS, CPLD, and SSD. In this example, BIOS firmware got updated, CPLD firmware got installed but powercycle* is needed, and SSD firmware update is scheduled during boot. *powercycle can be triggered by cold reboot script in this case. + +```bash +admin@sonic:~/fwutil$ cat /tmp/firmwareupdate/fw_au_status +{ + "MSN2700/BIOS": + { + "status": "updated", + "info": "completed" + }, + "MSN2700/SSD": + { + "status": "scheduled", + "info": "installation scheduled for cold reboot" + }, + "MSN2700/CPLD1": + { + "status": "installed", + "info": "need cold reboot to be completed" + } + ] +} ``` + +Here is the example of the firmware update status file with warm reboot as boot_type action. +And the components available for the update are BIOS, and SSD. +In this example, BIOS firmware got updated, CPLD firmware update was skipped since the update completion can not be done for warm, and SSD firmware update is scheduled during warm boot. + +```bash admin@sonic:~/fwutil$ cat /tmp/firmwareupdate/fw_au_status { - "cold": [ + "MSN2700/BIOS": { - "status": true, - "comp": "MSN2700/BIOS", - "info": "updated" + "status": "updated", + "info": "completed" }, + "MSN2700/SSD": { - "status": true, - "comp": "MSN2700/SSD", - "info": "scheduled" + "status": "scheduled", + "info": "installation scheduled for warm reboot" }, + "MSN2700/CPLD1": { - "status": true, - "comp": "MSN2700/CPLD1", - "info": "installed" + "status": "skipped", + "info": "warm reboot not supported for auto-update" } ] } @@ -610,61 +639,19 @@ Automatic FW installation requires default platform_components.json to be create _sonic-buildimage/device///platform_components.json_ Recommended image path is "/lib/firmware/". -Auto-update command can support the standalone custom firmware image package with --fw-image option. -The package can be any format between ".tar" or ".tar.gz" and should have the "platform_components.json", the firmware image(s). -The package can have the auto-update plugin if the platform doesn't support platform api or if plugin needs to be updatedplugin. -The package can also have the component upgrade utility(script) and the utility will be used for the component firmware upgrade if it's specified in "platform_compnents.json". -The `fwutil auto-update` commands uncompress the package and parse the "platform_components.json" to retrieve the firmware information. - - Here is the firmwareupdate directory structure while fwutil handles the `fwutil auto-update fw` and `fwutil show auto_update_status` command. ``` /tmp/firmwareupdate/ |--- fw_au_status |--- _fw_au_task* - |--- fwpackage** - |--- platform_components.json - |--- - |--- *** ``` -*: _fw_au_task can be generated by the auto_update_firmware() api only if the firmware update needs to be scheduled during the action. -**: the custom firmware image package provided with --fw-image option, will be extracted under fwpackage directory. -***: can be used if it's defined in platform_components.json in the custom firmware image package. -Here is the example of platform_components.json in the firmware image package. -```json -{ - "chassis": { - "Chassis1": { - "component": { - "BIOS": { - }, - "CPLD": { - "firmware": "cpld.bin", - "version": "10" - }, - "SSD": { - "firmware": "ssd.bin", - "version": "5" - } - } - } - } -} -``` - -Here is the example of firmware image package contents with the platform_components.json shown above. -```bash -root@sonic:~$ tar tvf fwpackage.tar --rw-r--r-- root/root 551 2020-11-18 17:05 platform_components.json --rwxr-xr-x root/root 1436 2020-11-15 19:05 cpld.bin --rw-r--r-- root/root 546141 2020-11-17 20:35 ssd.bin -``` - -If the script path is available for the component firmware configuration in the "platform_components.json", -it means that the specific component firmware upgrade shall use the script to process the fwutil commands. -`2.2.2.4.3 Platform Component Firmware Update Utility` explains the requirement of the component firmware upgrade utility -to interfere with the fwutil to support the auto-update command - mainly status and install. +Auto-update command can support the standalone custom firmware image package with --fw-image option. +`2.2.2.4.3 Custom Firmware Package option with --fw-image` explains the requirement of the custom firmware image package. +The custom firmware image package should have the platform_components.json which indicates which component's firmware image is available +and the relative location of the image file. +Fwutil will search for the platform_components.json first to get the firmware image information - version and the relative location +from the platform_componenets.json. **Note:** 1. FW update will be disabled if component definition is not provided (e.g., 'BIOS': { }) @@ -743,13 +730,70 @@ All firmware auto-update has been performed. ``` **Supported options:** -3. -i|--image - update FW using current/next SONiC image -4. -b|--boot - following boot option after the upgrade -6. -z|--fw-image - firmware package downloaded during run time (this is an exclusive option from --image) +1. -i|--image - update FW using current/next SONiC image +2. -b|--boot - following boot option after the upgrade +3. -z|--fw-image - firmware package downloaded during run time (this is an exclusive option from --image) + +**Note:** +- the default option is _--image=current_ and _--boot=any_ +- --image and --fw-image can not be supported at the same time + +##### 2.2.2.4.3 Custom Firmware Package option with --fw-image + +Auto-update command can support the standalone custom firmware image package with --fw-image option. +The package can be any format between ".tar" or ".tar.gz" and should have the "platform_components.json", the firmware image(s). +The package can have the auto-update plugin if the platform doesn't support platform api or if plugin needs to be updatedplugin. +The package can also have the component upgrade utility(script) and the utility will be used for the component firmware upgrade if it's specified in "platform_compnents.json". +The `fwutil auto-update` commands uncompress the package and parse the "platform_components.json" to retrieve the firmware information. + + +Here is the firmwareupdate directory structure with the extract of firmware image package. +``` +/tmp/firmwareupdate/fwpackage/ + |--- platform_components.json + |--- + |--- * +``` +The custom firmware image package provided with --fw-image option, will be extracted under fwpackage directory. +*: can be used if it's defined in platform_components.json in the custom firmware image package. + +Here is the example of platform_components.json in the firmware image package. +```json +{ + "chassis": { + "Chassis1": { + "component": { + "BIOS": { + }, + "CPLD": { + "firmware": "cpld.bin", + "version": "10" + }, + "SSD": { + "firmware": "ssd.bin", + "version": "5" + } + } + } + } +} +``` -**Note:** the default option is _--image=current_ and _--boot=any_ +Here is the example of firmware image package contents with the platform_components.json shown above. +```bash +root@sonic:~$ tar tvf fwpackage.tar +-rw-r--r-- root/root 551 2020-11-18 17:05 platform_components.json +-rwxr-xr-x root/root 1436 2020-11-15 19:05 cpld.bin +-rw-r--r-- root/root 546141 2020-11-17 20:35 ssd.bin +``` + +Custom firmware package can also support the utility option for the components which doesn't have the platform api support yet. +If the script path is available for the component firmware configuration in the "platform_components.json", +it means that the specific component firmware upgrade shall need to use the script to process the fwutil commands. +`2.2.2.4.4 Platform Component Firmware Update Utility` explains the requirement of the component firmware upgrade utility +to interfere with the fwutil to support the auto-update command - mainly status and install. -##### 2.2.2.4.3 Platform Component Firmware Update Utility +##### 2.2.2.4.4 Platform Component Firmware Update Utility When Vendor doesn't have platform API ready to support all platform component APIs including the auto-update interface, the platform component utility will perform the equivalent process of `auto-update` platform component api. The component utility can perform the firmware update if the firmware update doesn't need any boot action required after the update. From 93416e56805056b9db9a5da2e531e1637b77f355 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Thu, 17 Dec 2020 13:20:54 -0800 Subject: [PATCH 26/28] update with review comments --- doc/fwutil/fwutil.md | 114 +++++++++++++++++++++++++------------------ 1 file changed, 66 insertions(+), 48 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index 4041049e12..f05fcd17da 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -27,20 +27,20 @@ - [2.2.2.3 Update commands](#2223-update-commands) - [2.2.2.3.1 Overview](#22231-overview) - [2.2.2.3.2 Description](#22232-description) - - [2.2.2.4 Auto-Update commands](#2224-auto-update-commands) + - [2.2.2.4 Update All commands](#2224-update-all-commands) - [2.2.2.4.1 Overview](#22241-overview) - [2.2.2.4.2 Description](#22242-description) - [2.2.2.4.3 Platform FW Update utility](#22243-plarform-fw-update-utility) - - [2.2.2.4.4 Auto-update Use Cases](#22244-auto-update-use-cases) + - [2.2.2.4.4 Update All Use Cases](#22244-update-all-use-cases) - [3 Flows](#3-flows) - [3.1 Show components status](#31-show-components-status) - [3.2 Show available updates](#32-show-available-updates) - [3.3 Install component FW](#33-install-component-fw) - [3.3.1 Non modular chassis platform](#331-non-modular-chassis-platform) - [3.3.2 Modular chassis platform](#332-modular-chassis-platform) - - [3.4 Auto-update platform component firmwares](#33-Auto-update-platform-component-firmwares) - - [3.4.1 Auto-update platform component firmwares](#331-Auto-update-platform-component-firmwares) - - [3.4.2 Auto-update using platform utility](#332-Auto-update-using-platform-utility) + - [3.4 FW update all platform components](#33-FW-update-all-platform-components) + - [3.4.1 FW update all using platform component api](#331-FW-update-all-using-platform-component-api) + - [3.4.2 FW update all using platform utility](#332-FW-update-all-using-platform-utility) - [4 Tests](#4-tests) - [4.1 Unit tests](#41-unit-tests) @@ -309,6 +309,17 @@ Chassis1 N/A CPLD /cpld.bin 5 / 10 SSD /ssd.bin 4 / 5 update is required ``` +``` +**Supported options:** +1. -i|--image - show updates using current/next SONiC image +2. -z|--fw-image - show updates using custom FW package + +**Note:** +- the default option is _--image=current_ +- --image and --fw-image can not be supported at the same time +- `fwutil show updates` command only displays for the components which have the firmware image path available in platform_components.json +``` + **The following command displays the Component FW auto-update satus:** 1. Auto-update status ```bash @@ -320,14 +331,6 @@ MSN2700/SSD scheduled installation scheduled for cold reboot MSN2700/CPLD1 installed need cold reboot to be completed ``` -**Supported options:** -1. -i|--image - show updates using current/next SONiC image -2. -z|--fw-image - show updates using custom FW package - -**Note:** -- the default option is _--image=current_ -- --image and --fw-image can not be supported at the same time - #### 2.2.2.2 Install commands ##### 2.2.2.2.1 Overview @@ -515,10 +518,10 @@ Aborted! **Note:** the default option is _--image=current_ -#### 2.2.2.4 Auto-update commands +#### 2.2.2.4 `update all` commands ##### 2.2.2.4.1 Overview -The purpose of the auto-update commands group is to provide and interface for automatic fw updates of various platform components based on the boot option and the platform firmware update configuration file - "platform_components.json". +The purpose of the `update all` commands group is to provide and interface for automatic fw updates of various platform components based on the boot option and the platform firmware update configuration file - "platform_components.json". The existing FWutil infra supports the upgrade of platform components which can be performed during run time. The SSD upgrade for certain platforms requires the unmount of the filesystems and this needs to be incorporated as part of the reboot scripts. @@ -559,12 +562,13 @@ New component api is introduced to support the component firmware auto-update as """ raise NotImplementedError ``` -The return_code of auto_update_firmware() which indicates the firmware auto-update status, will be logged in "fw_au_status" under "/tmp/firmwareupdate/" directory by fwutil and the status file will be used for the `fwutil show auto_update_status` command. +The return_code of auto_update_firmware() which indicates the firmware auto-update status, will be logged in "fw_au_status" under "/var/platform/" directory by fwutil and the status file will be used for the `fwutil show auto_update_status` command. In case that a firmware update needs any additional step to complete the firmware update but the installation time is longer than the boot time requirement, auto-update platform api is expected to install the firmware and perform the complete action during the reboot via `platform_fw_au_reboot_handle` or `platform_reboot` plugin. For example, some cpld update needs a power cycle to complete the firmware update and some cpld update needs a register triggered power-cycle to give some refresh time for the new firmware to be effective on the system. Any scheduled component firmware update needs to be logged in "_fw_au_task". +The reboot script will prevent from performing the reboot if the of the scheduled task is different than the current reboot type. Each vendor needs to implement the reboot auto-update task handler plugin which is platform specific plugin and is expected to be named as "platform_fw_au_reboot_handle". The plugin will parse the "_fw_au_task" file and perform the update during the reboot if needed. The contents of the task file can be defined by the platform vendors and be utilized by the platform specific reboot plugin. @@ -584,21 +588,27 @@ In this example, BIOS firmware got updated, CPLD firmware got installed but powe *powercycle can be triggered by cold reboot script in this case. ```bash -admin@sonic:~/fwutil$ cat /tmp/firmwareupdate/fw_au_status +admin@sonic:~/fwutil$ cat /var/platform/fw_au_status { "MSN2700/BIOS": { "status": "updated", + "from": "0ACLH004_02.02.007", + "to": "0ACLH004_02.02.010", "info": "completed" }, "MSN2700/SSD": { "status": "scheduled", + "from": "4", + "to": "5", "info": "installation scheduled for cold reboot" }, "MSN2700/CPLD1": { "status": "installed", + "from": "5", + "to": "10", "info": "need cold reboot to be completed" } ] @@ -610,28 +620,33 @@ And the components available for the update are BIOS, and SSD. In this example, BIOS firmware got updated, CPLD firmware update was skipped since the update completion can not be done for warm, and SSD firmware update is scheduled during warm boot. ```bash -admin@sonic:~/fwutil$ cat /tmp/firmwareupdate/fw_au_status +admin@sonic:~/fwutil$ cat /var/platform/fw_au_status { "MSN2700/BIOS": { "status": "updated", + "from": "0ACLH004_02.02.007", + "to": "0ACLH004_02.02.010", "info": "completed" }, "MSN2700/SSD": { "status": "scheduled", + "from": "4", + "to": "5", "info": "installation scheduled for warm reboot" }, "MSN2700/CPLD1": { "status": "skipped", + "from": "5", + "to": "10", "info": "warm reboot not supported for auto-update" } ] } ``` - The FWutil infra section below indicates the necessary changes to add support for auto update during reboot. The Platform plugins section describes the plugins that a platform must implement to support auto updates when the platform component APIs are not available. @@ -639,9 +654,9 @@ Automatic FW installation requires default platform_components.json to be create _sonic-buildimage/device///platform_components.json_ Recommended image path is "/lib/firmware/". -Here is the firmwareupdate directory structure while fwutil handles the `fwutil auto-update fw` and `fwutil show auto_update_status` command. +Here is the /var/platform directory structure while fwutil handles the `fwutil auto-update fw` and `fwutil show auto_update_status` command. ``` -/tmp/firmwareupdate/ +/var/platform/ |--- fw_au_status |--- _fw_au_task* ``` @@ -660,16 +675,16 @@ from the platform_componenets.json. ##### 2.2.2.4.2 Description **The following command updates FW Automatically with installing the available component firmware, creating task(s) for update during reboot:** -1. auto-update command for installation and reboot task creation +1. `update all` command for installation and reboot task creation ```bash -root@sonic:~# fwutil auto-update fw --yes --image= --boot= +root@sonic:~# fwutil update all fw --yes --image= --boot= firmware auto-update starting: with ... - firmware auto-update status: with + firmware auto-update status from to : - ... firmware auto-update starting: with ... - firmware auto-update status: with + firmware auto-update status from to : - ... All firmware auto-update has been performed. ``` @@ -681,16 +696,19 @@ Example 1: BIOS and SSD firmware update is available for fast-reboot upgrade pat BIOS firmware update is going to be updated and no further task is needed during reboot. SSD firmware update is logged in a platform defined designated file and it will be updated during fast-reboot. ```bash -root@sonic:~# fwutil auto-update fw --yes --image=next --boot=fast +root@sonic:~# fwutil update all fw --yes --image=next --boot=fast Firmware auto-update for boot_type fast is allowed MSN2700/BIOS firmware auto-update starting: /lib/firmware/mlnx/bios.bin with fast ... -BIOS firmware auto-update status: True with Updated +BIOS firmware auto-update status from 0ACLH004_02.02.007 to 0ACLH004_02.02.010: updated - completed ... MSN2700/SSD firmware auto-update starting: /lib/firmware/mlnx/ssd.bin with fast ... -SSD firmware auto-update status: True with Scheduled +SSD firmware auto-update status from 4 to 5: scheduled - installation scheduled for fast reboot ... +MSN2700/CPLD firmware auto-update starting: /lib/firware/mlnx/cpld.bin with fast +... +CPLD firmware auto-update status from 5 to 10: skipped - warm reboot not supported for auto-update All firmware auto-update has been performed. ``` Example 2: BIOS, SSD and CPLD update is available for cold reboot upgrade path. @@ -699,19 +717,19 @@ SSD firmware update is logged in a platform defined designated file and it will CPLD firmware update is going to be done with this command and the CPLD completion activity will be performed during cold reboot once all reboot processes are finished. The CPLD completion activity for this case is a power cycle triggered by the hw register setting. ```bash -root@sonic:~# fwutil auto-update fw --yes --image=next --boot=cold +root@sonic:~# fwutil update all fw --yes --image=next --boot=cold Firmware auto-update for boot_type cold is allowed MSN2700/BIOS firmware auto-update starting: /lib/firmware/mlnx/bios.bin with cold ... -BIOS firmware auto-update status: True with Updated +BIOS firmware auto-update status from 0ACLH004_02.02.007 to 0ACLH004_02.02.010: updated - completed ... MSN2700/SSD firmware auto-update starting: /lib/firmware/mlnx/ssd.bin with cold ... -SSD firmware auto-update status: True with Scheduled +SSD firmware auto-update status from 4 to 5: scheduled - installation scheduled for cold reboot ... MSN2700/CPLD firmware auto-update starting: /lib/firware/mlnx/cpld.bin with cold ... -CPLD firmware auto-update status: True with Installed +CPLD firmware auto-update status from 5 to 10: installed - need cold reboot to be completed All firmware auto-update has been performed. ``` @@ -725,7 +743,7 @@ admin@sonic:~# sudo fwutil auto_update fw --fw_image=fwpackage.tar.gz --boot=col Firmware auto-update for boot_type cold is allowed MSN2700/CPLD1 firmware auto-update starting: /tmp/firmwareupdate/fwpackage/fwpackage/sn2700_cpld.mpfa with boot_type cold ... -CPLD1 firmware auto-update status: True with installed +CPLD1 firmware auto-update status: installed - need cold reboot to be completed All firmware auto-update has been performed. ``` @@ -735,16 +753,16 @@ All firmware auto-update has been performed. 3. -z|--fw-image - firmware package downloaded during run time (this is an exclusive option from --image) **Note:** -- the default option is _--image=current_ and _--boot=any_ +- the default option is _--image=current_ and _--boot=none_ - --image and --fw-image can not be supported at the same time ##### 2.2.2.4.3 Custom Firmware Package option with --fw-image -Auto-update command can support the standalone custom firmware image package with --fw-image option. +The `update all` command can support the standalone custom firmware image package with --fw-image option. The package can be any format between ".tar" or ".tar.gz" and should have the "platform_components.json", the firmware image(s). The package can have the auto-update plugin if the platform doesn't support platform api or if plugin needs to be updatedplugin. The package can also have the component upgrade utility(script) and the utility will be used for the component firmware upgrade if it's specified in "platform_compnents.json". -The `fwutil auto-update` commands uncompress the package and parse the "platform_components.json" to retrieve the firmware information. +The `fwutil update all` commands uncompress the package and parse the "platform_components.json" to retrieve the firmware information. Here is the firmwareupdate directory structure with the extract of firmware image package. @@ -885,20 +903,20 @@ if [[ -x ${DEVPATH}/${PLATFORM}/${PLATFORM_FW_AU_REBOOT_HANDLE} ]]; then fi ``` -##### 2.2.2.4.4 Auto-update Use Cases +##### 2.2.2.4.4 Update All Use Cases ##### 2.2.2.4.4.1 Standalone firmware update during run time -Since FWutil auto-update can support the firmware update using a custom firmware package, this will allow the firmware update to be available during run time. +Since `fwutil update all` can support the firmware update using a custom firmware package, this will allow the firmware update to be available during run time. SONiC device can have a component firmware updated without interrupting the data plan if the component firmware update doesn't need any boot action. ```bash -root@sonic:~# fwutil auto-update fw --fw-image=aboot-fw-update.tar.gz --boot=none +root@sonic:~# fwutil update all fw --fw-image=aboot-fw-update.tar.gz --boot=none ``` SONiC device can also be updated only a specific firmware update with a possible boot option that can be supported on a certain topology. But in this case, the firmware update can be completed by following reboot which is indicated in the boot option of fwutil auto-update command. ```bash -root@sonic:~# fwutil auto-update fw --fw-image=ssd-fw-update.tar.gz --boot=fast +root@sonic:~# fwutil update all fw --fw-image=ssd-fw-update.tar.gz --boot=fast ... root@sonic:~# sudo fast-reboot ``` @@ -921,7 +939,7 @@ sync;sync;sync || exit 14 if [[ -x ${PLATFORM_FW_UPDATE} ]]; then - ${PLATFORM_FW_UPDATE} auto-update fw --yes --image=next --boot=${REBOOT_TYPE} + ${PLATFORM_FW_UPDATE} update all fw --yes --image=next --boot=${REBOOT_TYPE} fi ``` @@ -953,19 +971,19 @@ fi ###### Figure 5: FW install (modular) flow -## 3.4 Auto-update platform component firmwares +## 3.4 FW update all platform components -### 3.4.1 Auto-update using platform component apis +### 3.4.1 FW update all using platform component api -![FW Auto-update platform compoenent api flow](images/autoupdate_component_api_flow.svg "Figure 6: Platform Component FW Auto-update flow") +![FW update all with platform compoenent api flow](images/autoupdate_component_api_flow.svg "Figure 6: FW update all with platform component api flow") -###### Figure 6: Platform Component FW Auto-update flow +###### Figure 6: FW update all with platform component api flow -### 3.4.2 Auto-update using platform utility +### 3.4.2 FW update all using platform utility -![FW Auto-update platform utility flow](images/autoupdate_platform_utility_flow.svg "Figure 7: Platform Component FW Auto-update with platform utility flow") +![FW update all with platform utility flow](images/autoupdate_platform_utility_flow.svg "Figure 7: FW update all with platform utility flow") -###### Figure 7: Platform Component FW Auto-update with platform utility flow +###### Figure 7: FW update all with platform utility flow # 4 Tests From 4c76c142f15ad49d81d1b5cd70c02ed67c98452b Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Fri, 18 Dec 2020 14:27:16 -0800 Subject: [PATCH 27/28] additional review comments --- doc/fwutil/fwutil.md | 51 ++++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 26 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index f05fcd17da..affc1ed83d 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -57,7 +57,7 @@ This document provides general information about FW utility implementation in SO | 0.3 | 17/09/2019 | Nazarii Hnydyn | Align flows with the platform API | | 0.4 | 18/12/2019 | Nazarii Hnydyn | CLI review feedback | | 0.5 | 05/05/2020 | Nazarii Hnydyn | Automatic FW update per component | -| 0.6 | 08/03/2020 | Sujin Kang | Add firmware auto-update command | +| 0.6 | 08/03/2020 | Sujin Kang | Add firmware `update all` command | ## Abbreviations @@ -126,7 +126,7 @@ we might need a dedicated FW utility. 1. show: Display FW versions/updates 2. install: Manual FW installation 3. update: Complete FW installation -3. auto-update: Automatic FW updates +4. update all: Automatic updates of all available FWs for any specific boot type ### 1.2.3 Error handling @@ -153,8 +153,8 @@ we might need a dedicated FW utility. | FW binary downloading over URL: error | ERROR | | FW binary installation: start/end | INFO | | FW binary installation: error | ERROR | -| FW binary auto-update : start/end | INFO | -| FW binary auto-update : error | ERROR | +| FW binary update : start/end | INFO | +| FW binary update : error | ERROR | **Note:** Some extra information also will be logged: 1. Component location (e.g., Chassis1/Module1/BIOS) @@ -203,7 +203,7 @@ fwutil | |--- status | |--- updates -i|--image= | |--- updates -z|--fw-image= -| |--- auto_update_status +| |--- update status | |--- install | |--- chassis @@ -215,17 +215,16 @@ fwutil | |--- fw -y|--yes | |--- update -| |--- chassis -| | |--- component -| | |--- fw -y|--yes -f|--force -i|--image= -| | -| |--- module -| |--- component -| |--- fw -y|--yes -f|--force -i|--image= -| -|--- auto-update - |--- fw -i|--image= --b|--boot= - |--- fw -z|--fw-image= --b|--boot= + |--- chassis + | |--- component + | |--- fw -y|--yes -f|--force -i|--image= + | + |--- module + | |--- component + | |--- fw -y|--yes -f|--force -i|--image= + |--- all + |--- fw -i|--image= --b|--boot= + |--- fw -z|--fw-image= --b|--boot= ``` **Note:** @@ -320,15 +319,15 @@ Chassis1 N/A CPLD /cpld.bin 5 / 10 - `fwutil show updates` command only displays for the components which have the firmware image path available in platform_components.json ``` -**The following command displays the Component FW auto-update satus:** -1. Auto-update status +**The following command displays the Component FW update satus (only available for `fwutil update all` command):** +1. update status ```bash -root@sonic:~# fwutil show auto-update status +root@sonic:~# fwutil show update status Firmware auto-update performed for cold reboot -Component Status Info -------------- --------- -------------------------------------- -MSN2700/SSD scheduled installation scheduled for cold reboot -MSN2700/CPLD1 installed need cold reboot to be completed +Component Version Status Info +------------- --------- --------- -------------------------------------- +MSN2700/SSD 4/5 scheduled installation scheduled for cold reboot +MSN2700/CPLD1 5/10 installed need cold reboot to be completed ``` #### 2.2.2.2 Install commands @@ -562,7 +561,7 @@ New component api is introduced to support the component firmware auto-update as """ raise NotImplementedError ``` -The return_code of auto_update_firmware() which indicates the firmware auto-update status, will be logged in "fw_au_status" under "/var/platform/" directory by fwutil and the status file will be used for the `fwutil show auto_update_status` command. +The return_code of auto_update_firmware() which indicates the firmware auto-update status, will be logged in "fw_au_status" under "/var/platform/" directory by fwutil and the status file will be used for the `fwutil show update status` command. In case that a firmware update needs any additional step to complete the firmware update but the installation time is longer than the boot time requirement, auto-update platform api is expected to install the firmware and perform the complete action during the reboot via `platform_fw_au_reboot_handle` or `platform_reboot` plugin. For example, some cpld update needs a power cycle to complete the firmware update and some cpld update needs a register triggered power-cycle to give some refresh time for the new firmware to be effective on the system. @@ -654,7 +653,7 @@ Automatic FW installation requires default platform_components.json to be create _sonic-buildimage/device///platform_components.json_ Recommended image path is "/lib/firmware/". -Here is the /var/platform directory structure while fwutil handles the `fwutil auto-update fw` and `fwutil show auto_update_status` command. +Here is the /var/platform directory structure while fwutil handles the `fwutil update all fw` and `fwutil show update status` command. ``` /var/platform/ |--- fw_au_status @@ -739,7 +738,7 @@ SSD firmware update is logged in a platform defined designated file and it will CPLD firmware update is going to be done with this command and the CPLD completion activity will be performed during cold reboot once all reboot processes are finished. The CPLD completion activity for this case is a power cycle triggered by the hw register setting. ``` -admin@sonic:~# sudo fwutil auto_update fw --fw_image=fwpackage.tar.gz --boot=cold +admin@sonic:~# sudo fwutil update all fw --fw_image=fwpackage.tar.gz --boot=cold Firmware auto-update for boot_type cold is allowed MSN2700/CPLD1 firmware auto-update starting: /tmp/firmwareupdate/fwpackage/fwpackage/sn2700_cpld.mpfa with boot_type cold ... From 357485991d768a9fa78873bb083e3979fbc5cf71 Mon Sep 17 00:00:00 2001 From: sujinmkang Date: Tue, 12 Jan 2021 13:19:07 -0800 Subject: [PATCH 28/28] Add more requirements for auto-update --- doc/fwutil/fwutil.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/doc/fwutil/fwutil.md b/doc/fwutil/fwutil.md index affc1ed83d..82a871b569 100755 --- a/doc/fwutil/fwutil.md +++ b/doc/fwutil/fwutil.md @@ -118,7 +118,22 @@ we might need a dedicated FW utility. 2. Complete FW installation for particular platform component 3. Querying platform components and FW versions 4. Querying available FW updates for all platform components -5. Automatic FW updates for all available platform components +5. Automatic FW updates for all available platform components listed in platform_components.json + for any specific boot type. Automatic FW updates expects to be followed by the reboot + that was specified by the fwutil automatic fw update command, unless the boot type was none. +6. Automatic FW updates can have two phases for the components which firmware update needs + the complete action to be performed and the first phase is done by platform api and the + second phase can be done by the fwupdate reboot plugin. The heavy time consuming firmware + update is expected to be done during the first phase. +7. Automatic FW updates can have another two phases for any firmware update which needs + any system intervention like process stop or disk unmount, the firmware update task should + be scheduled by platform api during the first phase and the actual firmware update should + be performed by the fwupdate reboot plugin during the second phase with timing restriction*. + *In the real network situation, long device reboot timing could interrupt any services + running on the servers under the network device. Based on the reboot type, the platform vendor + needs to measure the reboot timing including the firmware update and diagonize the firmware update + is applicable for the autoupdate and the auto_update_firmware() platform api should return + "status_err_boot_type" if the reboot timing doesn't meet for any reboot requirement. ### 1.2.2 Command interface @@ -187,7 +202,7 @@ non modular chassis platforms. Both modular and non modular chassis platforms sh but may have different implementation. SONiC FW utility uses platform API to interact with the various platform components. -SONiC FW utility extends to support for the automatic firmware update based on "platform_components.json" under platform directory and next reboot option which is passed as a option for `fwutil autoupdate fw` command. +SONiC FW utility extends to support for the automatic firmware update based on "platform_components.json" under platform directory and next reboot option which is passed as a option for `fwutil update all fw` command. SONiC FW utility also extends to support for the automatic firmware update with a custom firmware package that can include any firmware update tool and the firmware update tool will be used for the firmware update if it's specified in the "platform_components.json". ## 2.2 FW utility @@ -737,7 +752,7 @@ BIOS firmware update is going to be updated and no further task is needed during SSD firmware update is logged in a platform defined designated file and it will be updated during cold reboot. CPLD firmware update is going to be done with this command and the CPLD completion activity will be performed during cold reboot once all reboot processes are finished. The CPLD completion activity for this case is a power cycle triggered by the hw register setting. -``` +```bash admin@sonic:~# sudo fwutil update all fw --fw_image=fwpackage.tar.gz --boot=cold Firmware auto-update for boot_type cold is allowed MSN2700/CPLD1 firmware auto-update starting: /tmp/firmwareupdate/fwpackage/fwpackage/sn2700_cpld.mpfa with boot_type cold @@ -848,7 +863,7 @@ The task file will be platform-specific. ##### 2.2.2.4.3.1 Platform Component Firmware Update Utility Interface Requirement -The Utility should support the minimum requirements to perform the fwutil auto-update interface. +The Utility should support the minimum requirements to perform the fwutil's automatic update interface. The minimum requirement is that the component api's get_frimware_version, get_firmware_update_notification(), and auto_update_firmware() needs to be supported by the utility. Here are the interface requirements to support them. 1. {utility} -s(--status) : able to retrieve the current firmware version: @@ -913,7 +928,7 @@ root@sonic:~# fwutil update all fw --fw-image=aboot-fw-update.tar.gz --boot=none ``` SONiC device can also be updated only a specific firmware update with a possible boot option that can be supported on a certain topology. -But in this case, the firmware update can be completed by following reboot which is indicated in the boot option of fwutil auto-update command. +But in this case, the firmware update can be completed by following reboot which is indicated in the boot option of `fwutil update all` command. ```bash root@sonic:~# fwutil update all fw --fw-image=ssd-fw-update.tar.gz --boot=fast ...