[realtek-ambz2] Refactor OTA for better bootloader compatibility (#356)

* [common] Add memory and compile-time check macros

* [realtek-amb] Extract OTA utilities from realtek-ambz

* [realtek-ambz2] Refactor OTA for better bootloader compatibility

* [realtek-ambz2] Fix builder formatting

Author: kuba2k2

builder/family/realtek-ambz2.py

@@ -438,15 +438,18 @@ def encode_public_key(data: bytes) -> str:
 image_part_table = "${BUILD_DIR}/image_part_table.${FLASH_PART_TABLE_OFFSET}.bin"
 image_bootloader = "${BUILD_DIR}/image_bootloader.${FLASH_BOOT_OFFSET}.bin"
 image_firmware_is = "${BUILD_DIR}/image_firmware_is.${FLASH_OTA1_OFFSET}.bin"
+part_firmware_is_header = (
+    "${BUILD_DIR}/part_firmware_is.header.${FLASH_OTA1_OFFSET}.bin"
+)
+part_firmware_is_data = "${BUILD_DIR}/part_firmware_is.data.${FLASH_OTA1_OFFSET}.bin"
 env.Replace(
     # linker command (dual .bin outputs)
     LINK='${LTCHIPTOOL} link2bin ${BOARD_JSON} "" ""',
     # UF2OTA input list
     UF2OTA=[
-        # use unmodified image for flasher
-        f"{image_firmware_is},{image_firmware_is}=flasher:ota1,ota2",
-        # use same image for device OTA
-        f"{image_firmware_is},{image_firmware_is}=device:ota1,ota2",
+        # use the same image for flasher and device, but flash the 1st sector last
+        f"{part_firmware_is_data},{part_firmware_is_data}=device:ota1,ota2;flasher:ota1,ota2",
+        f"{part_firmware_is_header},{part_firmware_is_header}=device:ota1,ota2;flasher:ota1,ota2",
         # having flashed an application image, update the bootloader and partition table (incl. keys)
         f"{image_bootloader},{image_bootloader}=flasher:boot,boot",
         f"{image_part_table},{image_part_table}=flasher:part_table,part_table",

builder/main.py

@@ -18,7 +18,7 @@
 board: PlatformBoardConfig = env.BoardConfig()
 
 python_deps = {
-    "ltchiptool": ">=4.12.2,<5.0",
+    "ltchiptool": ">=4.13.0,<5.0",
 }
 env.SConscript("python-venv.py", exports="env")
 env.ConfigurePythonVenv()

cores/common/base/api/lt_utils.h

@@ -18,6 +18,13 @@
 		_a < _b ? _a : _b;      \
 	})
 
+#define LT_MEM32(addr) (*((volatile uint32_t *)(addr)))
+
+// from https://scaryreasoner.wordpress.com/2009/02/28/checking-sizeof-at-compile-time/
+// (include/linux/kernel.h)
+#define LT_BUILD_BUG_ON(condition) ((void)sizeof(char[1 - 2 * !!(condition)]))
+#define LT_BUILD_CHECK(condition)  ((void)sizeof(char[1 - 2 * !(condition)]))
+
 /**
  * @brief Generate random bytes using rand().
  *

cores/realtek-amb/base/api/lt_ota.c

@@ -0,0 +1,75 @@
+/* Copyright (c) Kuba Szczodrzyński 2026-02-01. */
+
+#include <libretiny.h>
+#include <sdk_private.h>
+
+#define SYSTEM_DATA_LENGTH 128
+
+/**
+ * Convert OTA index (1, 2) into partition offset.
+ */
+bool lt_ota_dual_get_offset(uint8_t index, uint32_t *offset) {
+	switch (index) {
+		case 1:
+			*offset = FLASH_OTA1_OFFSET;
+			break;
+		case 2:
+			*offset = FLASH_OTA2_OFFSET;
+			break;
+		default:
+			return false;
+	}
+	return true;
+}
+
+/**
+ * Check which OTA image is active using the bit flag method.
+ */
+uint8_t lt_ota_dual_get_stored_by_flag() {
+	// find first non-zero bit of the flag in system data:
+	// - even count of zero-bits means OTA1, odd count means OTA2
+	//   this allows to switch OTA images by simply clearing next bits,
+	//   without needing to erase the flash
+	uint32_t ota_counter = LT_MEM32(SPI_FLASH_BASE + FLASH_SYSTEM_OFFSET + 4);
+	uint8_t bitidx;
+	for (bitidx = 0; bitidx < 32; bitidx++) {
+		if (ota_counter & (1 << bitidx))
+			break;
+	}
+	return 1 + (bitidx & 1);
+}
+
+/**
+ * Flip the OTA selection bit flag switch.
+ */
+bool lt_ota_dual_switch_flag() {
+	uint32_t bit_flag = LT_MEM32(SPI_FLASH_BASE + FLASH_SYSTEM_OFFSET + 4);
+
+	if (bit_flag == 0) {
+		// allocate memory and read old system data contents
+		uint32_t *system = malloc(SYSTEM_DATA_LENGTH);
+		if (!system)
+			return false;
+		if (lt_flash_read(FLASH_SYSTEM_OFFSET, (void *)system, SYSTEM_DATA_LENGTH) != SYSTEM_DATA_LENGTH)
+			goto err;
+
+		// set bit flag to OTA 2
+		system[1] = 0xFFFFFFFE;
+
+		// erase and write
+		if (!lt_flash_erase_block(FLASH_SYSTEM_OFFSET))
+			goto err;
+		if (lt_flash_write(FLASH_SYSTEM_OFFSET, (void *)system, SYSTEM_DATA_LENGTH) != SYSTEM_DATA_LENGTH)
+			goto err;
+
+		free(system);
+		return true;
+	err:
+		free(system);
+		return false;
+	}
+
+	// shift the bit flag and write without erasing
+	bit_flag <<= 1;
+	return lt_flash_write(FLASH_SYSTEM_OFFSET + 4, (void *)&bit_flag, 4) == 4;
+}

cores/realtek-ambz/base/api/lt_ota.c

@@ -3,22 +3,19 @@
 #include <libretiny.h>
 #include <sdk_private.h>
 
+// private utilities from realtek-amb core
+extern bool lt_ota_dual_get_offset(uint8_t index, uint32_t *offset);
+extern uint8_t lt_ota_dual_get_stored_by_flag();
+extern bool lt_ota_dual_switch_flag();
+
 lt_ota_type_t lt_ota_get_type() {
 	return OTA_TYPE_DUAL;
 }
 
 bool lt_ota_is_valid(uint8_t index) {
 	uint32_t offset;
-	switch (index) {
-		case 1:
-			offset = FLASH_OTA1_OFFSET;
-			break;
-		case 2:
-			offset = FLASH_OTA2_OFFSET;
-			break;
-		default:
-			return false;
-	}
+	if (!lt_ota_dual_get_offset(index, &offset))
+		return false;
 	uint8_t *address = (uint8_t *)(SPI_FLASH_BASE + offset);
 	return memcmp(address, "81958711", 8) == 0;
 }
@@ -34,16 +31,7 @@ uint8_t lt_ota_dual_get_stored() {
 	uint32_t *ota_address = (uint32_t *)0x8009000;
 	if (*ota_address == 0xFFFFFFFF)
 		return 1;
-	uint32_t ota_counter = *((uint32_t *)0x8009004);
-	// even count of zero-bits means OTA1, odd count means OTA2
-	// this allows to switch OTA images by simply clearing next bits,
-	// without needing to erase the flash
-	uint8_t count = 0;
-	for (uint8_t i = 0; i < 32; i++) {
-		if ((ota_counter & (1 << i)) == 0)
-			count++;
-	}
-	return 1 + (count % 2);
+	return lt_ota_dual_get_stored_by_flag();
 }
 
 bool lt_ota_switch(bool revert) {
@@ -55,24 +43,5 @@ bool lt_ota_switch(bool revert) {
 	if (!lt_ota_is_valid(stored ^ 0b11))
 		return false;
 
-	// - read current OTA switch value from 0x9004
-	// - reset OTA switch to 0xFFFFFFFE if it's 0x0
-	// - else check first non-zero bit of OTA switch
-	// - write OTA switch with first non-zero bit cleared
-
-	uint32_t value = HAL_READ32(SPI_FLASH_BASE, FLASH_SYSTEM_OFFSET + 4);
-	if (value == 0) {
-		uint8_t *system = (uint8_t *)malloc(64);
-		lt_flash_read(FLASH_SYSTEM_OFFSET, system, 64);
-		// reset OTA switch
-		((uint32_t *)system)[1] = -2;
-		lt_flash_erase_block(FLASH_SYSTEM_OFFSET);
-		return lt_flash_write(FLASH_SYSTEM_OFFSET, system, 64);
-	}
-
-	// clear first non-zero bit
-	value <<= 1;
-	// write OTA switch to flash
-	flash_write_word(NULL, FLASH_SYSTEM_OFFSET + 4, value);
-	return true;
+	return lt_ota_dual_switch_flag();
 }