add monoloithic self-update test case and docs

Author: bigbrett

config/examples/sim-self-update-monolithic.config

@@ -0,0 +1,19 @@
+ARCH=sim
+TARGET=sim
+SIGN?=ED25519
+HASH?=SHA256
+WOLFBOOT_SMALL_STACK?=0
+SPI_FLASH=0
+DEBUG=1
+RAM_CODE=1
+WOLFBOOT_VERSION=1
+
+# sizes should be multiple of system page size
+WOLFBOOT_PARTITION_SIZE=0x40000
+WOLFBOOT_SECTOR_SIZE=0x1000
+WOLFBOOT_PARTITION_BOOT_ADDRESS=0x20000
+WOLFBOOT_PARTITION_UPDATE_ADDRESS=0x60000
+WOLFBOOT_PARTITION_SWAP_ADDRESS=0xA0000
+
+# required for keytools
+WOLFBOOT_FIXED_PARTITIONS=1

docs/firmware_update.md

@@ -200,6 +200,78 @@ regular signed image at the bootloader origin.
 See [Signing.md](Signing.md#header-only-output-wolfboot-self-header) for
 more detail on the `--header-only` sign tool option.
 
+#### Monolithic updates
+
+The self-update mechanism can be used to update both the bootloader
+**and** the application firmware in a single atomic operation. Because
+`wolfBoot_self_update()` copies `fw_size` bytes from the update image to
+`ARCH_FLASH_OFFSET`, a payload that is larger than the bootloader region
+will spill into the contiguous BOOT partition, overwriting whatever
+application image was there previously.
+
+No wolfBoot code changes are required — only the update payload needs to
+be assembled differently. The payload is constructed by concatenating the
+new bootloader binary with the new signed application image and signing
+the result as a wolfBoot self-update:
+
+```
+cat wolfboot.bin image_v1_signed.bin > monolithic_payload.bin
+sign --wolfboot-update monolithic_payload.bin key.der 2
+```
+
+After the self-update completes, flash looks like:
+
+```
+ARCH_FLASH_OFFSET                   BOOT_ADDRESS
+     |                                   |
+     v                                   v
+     [  new bootloader bytes  | padding  |  new signed app image  ]
+     <-------- fw_size ------------------------------------------->
+```
+
+##### Self-header interaction
+
+When `WOLFBOOT_SELF_HEADER` is enabled, the persisted header retains the
+`fw_size`, hash and signature exactly as the signing tool produced them.
+The hash covers the **entire** monolithic payload — both the bootloader
+bytes and the nested application image. Later calls to
+`wolfBoot_open_self()` / `wolfBoot_verify_integrity()` will re-hash
+`fw_size` bytes starting at `ARCH_FLASH_OFFSET`, spanning into the BOOT
+partition.
+
+##### Restrictions
+
+- **Not power-fail safe.** Like all self-updates, a monolithic update
+  erases the bootloader region and writes in-place. An interruption
+  during the write leaves the device unbootable. Additionally, the BOOT
+  partition is written without a prior erase — this relies on the
+  partition being in an erased (0xFF) state, which is only guaranteed
+  when the device has no prior application installed or the partition has
+  been explicitly erased beforehand.
+
+- **Not revertable.** There is no swap or rollback mechanism. The old
+  bootloader and application are destroyed during the update.
+
+- **Locks bootloader verification to a specific application version.**
+  Because the self-header hash covers the full monolithic image, any
+  independent application update will invalidate the persisted
+  self-header. To maintain a valid self-header, both components must
+  always be updated together as a single monolithic payload.
+
+- **Payload must fit in the UPDATE partition.** The signed monolithic
+  image (header + bootloader + signed application) plus the 5-byte
+  `pBOOT` trailer must not exceed `WOLFBOOT_PARTITION_SIZE`.
+
+##### Simulator test
+
+A simulator test is provided in `tools/test.mk` to exercise this use case:
+
+```
+cp config/examples/sim-self-update-monolithic.config .config
+make clean && make
+make test-sim-self-update-monolithic
+```
+
 ### Incremental updates (aka: 'delta' updates)
 
 wolfBoot supports incremental updates, based on a specific older version. The sign tool

tools/test.mk

@@ -266,6 +266,42 @@ test-sim-self-update: wolfboot.bin FORCE
 	@# Verify dummy payload was written to bootloader region, indicating the self update swapped images as expected
 	$(Q)cmp -n $$(wc -c < dummy_update.bin | awk '{print $$1}') dummy_update.bin internal_flash.dd && echo "=== Self-update test PASSED ==="
 
+# Test monolithic self-update mechanism using simulator. A monolithic self-update
+# updates both the bootloader AND the boot partition application image in a single
+# operation by crafting a payload that spans the bootloader region and spills into
+# the contiguous boot partition.
+test-sim-self-update-monolithic: wolfboot.bin test-app/image_v1_signed.bin FORCE
+	@echo "=== Simulator Monolithic Self-Update Test ==="
+	@# Create dummy bootloader (0xAA pattern, exactly BOOTLOADER_PARTITION_SIZE)
+	$(Q)dd if=/dev/zero bs=$$(($(WOLFBOOT_PARTITION_BOOT_ADDRESS) - $(ARCH_FLASH_OFFSET))) count=1 2>/dev/null | tr '\000' '\252' > monolithic_dummy_bl.bin
+	@# Concatenate dummy bootloader + signed app image to form monolithic payload
+	$(Q)cat monolithic_dummy_bl.bin test-app/image_v1_signed.bin > monolithic_payload.bin
+	@# Sign monolithic payload as wolfBoot self-update v2
+	$(Q)$(SIGN_ENV) $(SIGN_TOOL) $(SIGN_OPTIONS) --wolfboot-update monolithic_payload.bin $(PRIVATE_KEY) 2
+	@# Create update partition with signed monolithic image and "pBOOT" trailer
+	$(Q)dd if=/dev/zero bs=$$(($(WOLFBOOT_PARTITION_SIZE))) count=1 2>/dev/null | tr '\000' '\377' > update_part.dd
+	$(Q)dd if=monolithic_payload_v2_signed.bin of=update_part.dd bs=1 conv=notrunc
+	$(Q)printf "pBOOT" | dd of=update_part.dd bs=1 seek=$$(($(WOLFBOOT_PARTITION_SIZE) - 5)) conv=notrunc
+	@# Create erased boot and swap partitions
+	$(Q)dd if=/dev/zero bs=$$(($(WOLFBOOT_PARTITION_SIZE))) count=1 2>/dev/null | tr '\000' '\377' > boot_part.dd
+	$(Q)dd if=/dev/zero bs=$$(($(WOLFBOOT_SECTOR_SIZE))) count=1 2>/dev/null | tr '\000' '\377' > erased_sec.dd
+	@# Assemble flash: wolfboot.bin at 0, empty boot partition, update partition, swap
+	$(Q)$(BINASSEMBLE) internal_flash.dd \
+		0 wolfboot.bin \
+		$$(($(WOLFBOOT_PARTITION_BOOT_ADDRESS) - $(ARCH_FLASH_OFFSET))) boot_part.dd \
+		$$(($(WOLFBOOT_PARTITION_UPDATE_ADDRESS) - $(ARCH_FLASH_OFFSET))) update_part.dd \
+		$$(($(WOLFBOOT_PARTITION_SWAP_ADDRESS) - $(ARCH_FLASH_OFFSET))) erased_sec.dd
+	@# Run simulator - self-update fires, copies monolithic payload to offset 0
+	$(Q)./wolfboot.elf get_version || true
+	@# Verify bootloader region contains 0xAA pattern (dummy bootloader was written)
+	$(Q)cmp -n $$(($(WOLFBOOT_PARTITION_BOOT_ADDRESS) - $(ARCH_FLASH_OFFSET))) monolithic_dummy_bl.bin internal_flash.dd
+	@echo "  Bootloader region 0xAA pattern: PASSED"
+	@# Extract nested app from boot partition and verify it matches original signed app
+	$(Q)dd if=internal_flash.dd bs=1 skip=$$(($(WOLFBOOT_PARTITION_BOOT_ADDRESS) - $(ARCH_FLASH_OFFSET))) count=$$(wc -c < test-app/image_v1_signed.bin | awk '{print $$1}') of=nested_app.dd 2>/dev/null
+	$(Q)cmp nested_app.dd test-app/image_v1_signed.bin
+	@echo "  Nested app at boot partition: PASSED"
+	@echo "=== Monolithic Self-Update Test PASSED ==="
+
 # Test self-header cryptographic verification (hash + signature validation)
 #
 # Verifies that an application can cryptographically verify the bootloader using