Applies to: Jetson AGX Xavier and Jetson TX2 series
Bootloader update process provides a safe Bootloader update and ensures that a workable Bootloader partition remains on boot storage during an update. It achieves this with A/B update, a feature that maintains two sets of Bootloader partitions, Slot A and Slot B, where a slot is a set of partitions that contain boot images.
A/B redundancy is a feature added on top of A/B update to provide Bootloader redundancy. It automatically maintains the same Bootloader image on both Bootloader slots, allowing the system to boot from the unused slot even if the current slot is corrupted.
A/B update and A/B redundancy reduce the risk of boot failure after a Bootloader update and when images on the current Bootloader slot are corrupted.
The principle of shadow copies enables multiple placeholders. All placeholders, but one, holds backup copies. Each copy constitutes a potential candidate to boot from. However, based on runtime decisions, the correct copy of the binary is loaded to continue with the boot process. These two shadow copies are commonly referred to as Slot A and Slot B. This two-slot implementation is as follows:
The following diagram shows the slot implementation layout.
A/B System Update
The A/B slot system updates affects these components:
A/B system updates use two sets of partitions, known as slots. Each slot has several attributes:
• The current slot is the slot that the system, if running, booted from. The other slot is called the unused slot. The system may exchange the roles of the current and unused slot in the course of an update, or when the slot fails repeatedly during or immediately after a boot from the current slot.
• The active slot is the slot that the next boot operation will attempt to boot from. In the normal state the active slot is the same as the bootable slot. When the system is being updated it may be different.
• The Bootable attribute indicates whether the slot contains a correct system that can be used to boot the device. When the system is running the current slot is bootable; the unused slot may have an older, identical, or newer version of the system, and may or may not be bootable.
• The Successful attribute indicates that the system has attempted to boot from the slot, and the most recent attempt succeeded. It is set by the user space Update Engine (UE) the first time a newly updated slot boots successfully to the kernel. It is reset when a slot is updated or a boot attempt fails. This normally happens immediately after a system update when the updated software contains an error.
If a bootable slot fails to boot a certain number of times, Bootloader resets its Bootable attribute and switches the roles of the current and unused slots. The formerly unused, now current slot normally was the current slot before the last update, and contains the boot-related software that was used for the most recent successful boot.
The slot status details are defined in the slot metadata (SMD) structure:
Where:
• magic is a fixed value that identifies an SMD partition.
• version specifies the version number of the software in the slot.
• num_slots specifies the number of slots, which should be 2.
• slot_info is an array of structures which contain information about the slots. In each slot:
• priority is the priority of this slot.
• suffix is a string, either “_a” or “_b,” that is suffixed to the A/B partitions’ names to make them unique.
• retry_count is the number of boot retries remaining before Bootloader resets the current slot’s Successful and Bootable attributes and tries to boot from the unused slot.
• boot_successful is the slot’s Successful attribute.
• The bootable slot is the slot with priority and retry_count both greater than 0.
• The current slot is the slot with the highest priority and a retry_count greater than 0. This slot is booted by the next power cycle.
Update Engine
The A/B system update uses the Update Engine to update A/B slots and to prepare the system to boot an updated version of Bootloader. The Update Engine performs these actions:
• Reads the bl_update_payload and writes data to the unused slot’s partitions as instructed by payload
• Calls the boot_control interface in a pre-defined workflow
• Switches the roles of the current and unused slots
• Reboots the system from the current (updated) slot
• Updates images on the unused, previously current slot to ensure that both slots contain the update
The A/B system uses the boot slot metadata to store the slot status. It communicates between the Update Engine and Bootloader. Bootloader runs the state machine to select the boot slot. It handles the update failure cases as follows:
MB1 uses the slot metadata to find the current slot. It caches the current slot number, 0 (slot A) or 1 (slot B), along with a “valid” flag, in scratch register 99 to be used by MB2, CBoot, or later stage loaders.
Scratch register 99 layout
Bits
31-30
29-26
25-22
21-19
18-16
15-0
Flag
Slot A retry count
Slot B retry count
Maximum slots
Current slot number
Magic pattern café
If MB1 does not find a current slot, the device hangs.
The name of the partition that is being loaded is derived as follows:
partition_name = <base_name>_<slot_value>”
slot value = “” for slot 0
slot value = “_b” for slot 1
Partition Settings
All A/B partitions must be named as follows:
• mb1
• mb1_b
• mb2
• mb2_b
• cboot
• cboot_b
• etc
The empty suffix for Slot A is to ensure backward compatibility with legacy A/B unaware partition loading mechanisms.
Update Engine States
The Update Engine (UE), nv_update_engine, uses the slot metadata to instruct Bootloader what slot to boot from. The following scenarios identify all UE states.
Normal State
• The system has booted from the current slot, which may be Slot A or Slot B.
• No updates have been applied.
• The current slot is Bootable and Successful, and is the active slot.
This table shows the status of a system in the normal state with slot B current. Slot A is the unused slot because its priority is lower than that of slot B.
Slot
Priority
Retry count
Successful
Slot A
14
7
1
Slot B
15
7
1
Update in Progress
• The system booted from the current slot. It is updating the unused slot.
• The current slot is Bootable and Successful, and is the active slot.
• The unused slot is not Bootable because it is being updated and the update is not yet complete.
This table shows the status of a system with slot B current and an update of slot A in progress. If the system must reboot in this state, it reboots from slot B.
Slot
Priority
Retry count
Successful
Slot A
0
0
0
Slot B
15
7
1
Update Applied, Reboot Pending
• The roles of the now-current and unused slots are about to be switched. Thus the system will attempt to boot from the now-unused slot.
• The now-unused slot is marked as Bootable and becomes the active slot, but is not yet marked as Successful.
• Bootloader attempts to boot from the newly updated slot some number of times.
This table shows the status of a system with an update applied to slot A and a reboot pending from slot A.
Slot
Priority
Retry count
Successful
Slot A
15
7
0
Slot B
14
7
1
System Reboot into a New Update
• The system is booting from the newly updated, now current slot for the first time.
• The formerly current, now unused slot is still Bootable and Successful, while the now current slot is Bootable and is the active slot, but is not Successful.
• The Update Engine marks the now current slot Successful after a successful boot and some system checks.
This table shows the status of a system that is booting from a new update on slot A.
Slot
Priority
Retry count
Successful
Slot A
15
6
0
Slot B
14
7
1
Slot Duplication in Progress
• The system has booted from the newly updated slot for the first time.
• The formerly current, now unused slot is marked as not Bootable because it is being updated.
• If the system must reboot in this state it boots from the newly updated, now current slot.
This table shows the status of a system with slot duplication in progress from slot A to slot B.
Slot
Priority
Retry count
Successful
Slot A
15
6
0
Slot B
0
0
0
Slot Duplication Complete
• The system has booted from the current slot for the first time and has duplicated the current slot to the unused slot.
• The current slot is marked as Bootable and Successful. The unused, newly duplicated slot is marked as Bootable and Successful, but with lower priority.
This table shows the status of a system with completed slot duplication from slot A to slot B.
Slot
Priority
Retry count
Successful
Slot A
15
7
1
Slot B
14
7
1
Boot Failure and Recovery
• The system fails to boot from the current slot due to data corruption or I/O errors.
• After some number of failed attempts to boot from the current slot, Bootloader marks the current slot not Bootable and boots from the unused slot.
This table shows the status of a system that failed to boot from slot A and recovered by booting from slot B.
Slot
Priority
Retry count
Successful
Slot A
0
0
0
Slot B
14
7
1
In this state the Update Engine is not allowed to duplicate a slot. Duplication is not allowed until the system updates the now-unused slot and boots from it successfully. The Update Engine also is not allowed to modify the partition table or the contents of partitions not assigned to slot A or B.
When the Update Engine is Launched
The update engine is launched under these scenarios:
1. An explicit launch by the user to update partitions with newer versions, with the command:
$ sudo nv_update_engine --install
The update engine applies Bootloader update payload (BUP) during the update. The BUP must be named bl_update_payload and must be placed under:
/opt/ota_package
2. Update Engine is launched by the boot service during a system boot with the command:
$ sudo nv_update_engine --verify
The update engine loads the slot metadata, evaluates the current state, and runs a pre-defined workflow. In normal boot, the update engine is in normal boot state, where an update is not applied and a duplicate is not required. The update engine simply exits.
Enabling A/B Redundancy
There are two methods for enabling A/B redundancy:
• Creating an SMD image and setting redundancy settings.
• Using the nv_update_engine tool to enable redundancy.
To enable redundancy by creating an SMD image
1. Modify the SMD configuration file smd_info.cfg to enable A/B slots.
2. Run the host tool nv_smd_generator on the x86 system to generate the SMD image with the updated SMD configuration file.
The following NVIDIA tools are provided for ease-of-use of Bootloader update process.
Boot Control
The nvbootctrl tool is intended for debugging purposes to load in the SMD image and dump the slot information. It can also be used to set the active slot to forcefully change the boot slot in the next boot.
To display the command usage
• Enter the command:
$ sudo nvbootctrl
Bootloader Update Payload Generator
The Bootloader Update Payload (BUP) is the payload that is applied by the update engine during an update. The BUP is generated by the host tool build_l4t_bup.sh script that is packaged along with the flash.sh flashing script tool in the Linux for Jetson Board Support Package (BSP).
In the Linux for Jetson Board Support Package, nv_smd_generator, the default SMD configuration file smd_info.cfg, and the default image file slot_metadata.bin, are installed under the directory:
<top>/bootloader
By default, the smd_info.cfg configuration file is set so that Slot A is the only available slot. This effectively disables redundancy:
Use Config 2 to create the SMD image and enable A/B redundancy.
To enable A/B update and A/B redundancy
1. Comment out the configuration that disables A/B update by adding a ‘#’ to the beginning of the parameter line below Config 1:
15 _a 7 1
2. “Uncomment” the configuration that enables A/B update by removing ‘##’ from the beginning of the parameter lines below Config 2:
##15 _a 7 1
##14 _b 7 1
Now the Bootloader-related partitions, the kernel partition, and the kernel-dtb partition all have A/B slots.
3. If you want to enable A/B redundancy as well as A/B update, uncomment the <REDUNDANCY x> statement. Replace x with a number that specifies the type of redundancy support you want:
• 0: Support for redundancy at Bootloader only, i.e, from mb1, mb2, until cboot.
• 1: Support for redundancy at Bootloader, kernel, and kernel-dtb.
Note:
File system redundancy is disabled by default because only one file system partition (APP) is created. NVIDIA can provide guidance on enabling file system redundancy.
Running the Update Engine
Run the update Engine script on the target system.
To enable/disable A/B redundancy
• Enter this command to enable redundancy:
$ sudo nv_update_engine –-enable-ab
• Enter this command to disable redundancy:
$ sudo nv_update_engine –-disable-ab
The command fails if the current boot slot is NOT 0.
To update Bootloader
1. Enter this command to switch to superuser mode:
$ sudo su
2. Enable A/B redundancy (a one-time command):
$ nv_update_engine --enable-ab
3. If a BUP directory does not exist, create one by executing the command:
$ mkdir /opt/ota_package
4. Copy the BUP from the host system to this newly created BUP directory with the command:
• <host_loc:bl_update_payload> is where the BUP is built on the host system. You can also use a USB key to copy the BUP from the host system to the target system.
5. Launch the Update Engine to update Bootloader on the non-current slot with the command:
$ nv_update_engine --install
Update Engine State Machine
The Update Engine state machine flow is as follows:
Manually Modifying Boot Slots
NVIDIA provides the nvbootctrl tool for testing and development purposes. However, you may wish to manually change the boot slots or make modifications to the SMD partition from the userspace.
To manually modify the boot slots
1. Enter this command to switch to superuser mode:
$ sudo su
2. Enter this command:
$ nvbootctrl <command>
Where <command> is as follows:
The default setting for both Slot 0 and Slot 1 is “bootable,” with Slot 0 having higher priority.
The boot slot is selected by MB1. The following sample log shows that Slot 1 is selected as the boot slot. The message displayed from MB1 is available from a debug build of MB1 that has messages enabled. Messages from MB2 are always available.
[0000.040] I> Welcome to MB1-coldboot(dev-version : 14.00.170822-t186-M-00.00-96e265a3)
[0000.048] I> rst_source : 0xb
[0000.051] I> rst_level : 0x1
[0000.053] I> Read lock all AES keyslots
[0000.057] I> Read lock all RSA keyslots
[0000.061] I> Clear SE keyslots left open by BR
[0000.065] I> Last mts-fallback status: 0x00000000
[0000.070] I> Boot-device: eMMC
[0000.094] I> sdmmc ddr50 mode
[0000.098] I> A/B: bin_type (19) slot 0
[0000.102] I> Binary(19) of size 512 is loaded @ 0x40043400
• The target is an original Jetson TX2 board. Contact NVIDIA for assistance in generating the BUP for other boards in the Jetson TX2 series.
• <top> is the location of the parent directory of the PDK installation package, where flash.sh command is located.
• <pkc_key_file>is the RSA private key file for your board. It must be located under the <top>/bootloaderdirectory or be specified by a complete (absolute) pathname.
• Enter these commands to create the PKC signed BUP image for the board connected to the host system:
