Hello all,
Recently I made a few changes to how images are managed in Mynewt.
There were several redundant newtmgr commands, and some functionality
was missing. Below is a description of the changes I made. As always,
please feel free to raise any questions or concerns you may have.
Thanks,
Chris
*** SUMMARY OF CHANGES
1. Augment existing "image list" command; remove "image boot" and "split
status" commands.
2. Support two-stage image confirmation for unified images. Prior to
this change, unified images were automatically confirmed on boot.
*** READ COMMAND
No change in newtmgr usage.
The old "image list" read command elicited a response of the following
form:
[ccollins@ccollins-mac:~]$ newtmgr -c A6009LXU image list
Images:
slot=0
version=3.3.3.3
bootable=true
hash=15451ad3b3841512d75a453fbd66f20d5b308fccc2d601b66d9314a748c48a6f
slot=1
version=4.4.4.4
bootable=true
hash=a40c61cebb6c3b360f751b692bce0d693207615df383d3cb894812f654cf7b65
There was a single flag associated with each slot: bootable. This
change adds three additional flags to each slot:
* pending
* confirmed
* active
The bootable flag is an immutable trait of an image. In contrast, the
three new flags can change in response to either a newtmgr "image"
command or a reboot. The three flags are defined as follows:
* pending: test image on next reboot; absent subsequent write
command, revert to original image on second reboot.
* confirmed: always use image unless excluded by a test image.
* active: image is currently running.
The meaning of these flags are best expressed as a set of tables. I
believe the below tables capture all valid states (this will look awful
without a fixed-width font!).
UNIFIED IMAGE STATES:
| slot-1 | slot-2 |
---------------+--------+--------|
pending | | |
confirmed | X | |
active | X | |
bootable | X | X |
---------------+--------+--------'
Unified image; image 1 confirmed;|
No change on reboot |
---------------------------------'
| slot-1 | slot-2 |
---------------+--------+--------|
pending | | X |
confirmed | X | |
active | X | |
bootable | X | X |
---------------+--------+--------'
Unified image; image 1 confirmed;|
Test image 2 on next reboot |
---------------------------------'
| slot-1 | slot-2 |
---------------+--------+--------|
pending | | |
confirmed | | X |
active | X | |
bootable | X | X |
---------------+--------+--------'
Unified image; testing image 1; |
Revert to image 2 on next reboot |
---------------------------------'
SPLIT IMAGE STATES:
| slot-1 | slot-2 |
---------------+--------+--------|
pending | | |
confirmed | X | |
active | X | |
bootable | X | |
---------------------------------'
Split image; loader only; |
No change on reboot |
---------------------------------'
| slot-1 | slot-2 |
---------------+--------+--------|
pending | | X |
confirmed | X | |
active | X | |
bootable | X | |
---------------------------------'
Split image; loader only; |
Test app on next reboot |
---------------------------------'
| slot-1 | slot-2 |
---------------+--------+--------|
pending | | |
confirmed | X | |
active | X | X |
bootable | X | |
---------------------------------'
Split image; testing app; |
Revert to loader on next reboot |
---------------------------------'
| slot-1 | slot-2 |
---------------+--------+--------|
pending | | |
confirmed | X | X |
active | X | X |
bootable | X | |
---------------------------------'
Split image; loader+app confirmed|
No change on reboot |
---------------------------------'
| slot-1 | slot-2 |
---------------+--------+--------|
pending | X | |
confirmed | | X |
active | X | X |
bootable | X | |
---------------------------------'
Split image; loader+app confirmed|
Test loader-only on next reboot |
---------------------------------'
| slot-1 | slot-2 |
---------------+--------+--------|
pending | | |
confirmed | | X |
active | X | |
bootable | X | |
---------------------------------'
Split image; testing loader; |
Revert to loader+app on next boot|
---------------------------------'
*** WRITE COMMAND
newtmgr usage: newtmgr image boot <op> [hash]
The write command supports two operations:
1. Test image with hash=<...>
2. Confirm current state
* The test image operation (1) has the following semantics for the
specified image:
If confirmed || pending: no-op
Else: set pending
* The confirm operation (2) has the following semantics:
For each image:
If pending: report error [*]
Elif confirmed: no-op
Elif active: set confirmed
[*] A prior write operation cannot be overwritten by a subsequent one.
This restriction comes from the implementation of the boot loader.
An image's pending or confirmed status is written directly to
flash, and cannot be changed without erasing the entire flash
sector.
Similarly, you cannot "undo" a test image operation or confirm
operation. If one of these operations is sent in error, you have no
option but to reboot the device and manage the consequences.
Aside from changes in how image state is reported, this update changes
image management in the following ways:
1. A unified image under test requires an additional confirm step.
Otherwise, the device will revert to the image in slot 2 on the next
reboot.
2. For split images, the transition from loader-and-app to loader-only
can be tested. If a device running loader-and-app receives a test
operation that specifies the loader image's hash, it will test the
loader-only state on its next reboot. If the device reboots again
without receiving additional image write commands, it will revert to
the loader-and-app state.
*** FUTURE ENHANCEMENTS
* Add a "confirm image with hash=<...>" operation to the write command.
This would be similar to the test operation, except it would not
require a subsequent confirm operation. This might be useful for mass
upgrades in large deployments.
