How do I use system_restart_enhance() method?

[InqOnThat]

The documentation is pretty thin. SDK 3.0.2 simply says,

• system_restart_enhance - "Restart system, and enters enhance boot mode.".
• system_get_boot_mode - "Enhance boot mode: can load and run FW at any address."
• system_get_boot_version - "If boot version >=3, it is possible to enable enhanced boot mode..."

The source code doesn't exist in the install or the Internet (that I've been able to find so far). If fact, a Google search of "ESP8266 system_restart_enhance" only finds about a dozen hits in the world with none implying successful use, much less showing code.

I've tried using it... even pointing to the user1.bin or user2.bin locations. It only has a bool return value that is always FALSE. I finally tried adding debug level for CORE... UPDATER... and I get the message: failed: need boot >= 1.3. Doing a search on the entire (installed) code base, I cannot find "need boot" anywhere. Startup output gives a eboot version of 4deb0:

load 0x4010f000, len 3424, room 16 
tail 0
chksum 0x2e
load 0x3fff20b8, len 40, room 8 
tail 0
chksum 0x2b
csum 0x2b
**v0004deb0**
~ld
rf cal sector: 1020
freq trace enable 0
rf[112] : 0⸮
SDK:2.2.2-dev(38a443e)/Core:3.1.2=30102000/lwIP:STABLE-2_1_3_RELEASE/glue:1.2-65-g06164fb/BearSSL:b024386

system_get_boot_version() returns 31 on the NodeMCU, I'm using at the moment.

I'm pretty much stumped on my next thing to pull on. Does anyone have any experience or suggestions using system_restart_enhance()?

Thanks.

[InqOnThat]

In case, someone wants to confirm I'm setting it up right and/or try to re-create it to see what I'm seeing, here is the sketch. I've uploaded to LittleFS a second V0.bin sketch that is simply the Blink sketch.

#include <LittleFS.h>
#include <user_interface.h>
#include <eboot_command.h>

#define GOOD_TEST
  
void setup()
{
  Serial.begin(74880);
  delay(5000);
  Serial.println("");

  // MISC DETAILS --------------------------------------------
  Serial.printf("\nCHIP/IDE SETTINGS\n");
  u8 ver = system_get_boot_version();
  // mode must = 1 normal user1.bin, user2.bin
  u8 mode = system_get_boot_mode();  
  // Which one is running???
  // current running user1.bin, user2.bin
  u32 addr = system_get_userbin_addr(); 
  // Map near worthless
  flash_size_map map = system_get_flash_size_map();
  // from sleep, wd, power-on, etc.
  rst_info* strt = system_get_rst_info();
  Serial.printf("ver=%u  mode=%u  addr=%p  map=%u  reason=%u\n",
    ver, mode, addr, map, strt->reason);
  
  // START FILE SYSTEM -----------------------------------------
  Serial.printf("LittleFS.begin() = %u\n", LittleFS.begin());
  FSInfo i;
  LittleFS.info(i);
  Serial.printf("Total = %u\nUsed = %u\n", i.totalBytes, i.usedBytes);

  Dir dir = LittleFS.openDir("/");
  while (dir.next()) 
  {
    Serial.printf("     %s", dir.fileName());
    if (dir.fileSize()) 
    {
      File f = dir.openFile("r");
      Serial.printf(" %u\n", f.size());
      f.close();
    }
  }

  // OPEN THE FILE AND START STREAMING IT -----------------------
  File f = LittleFS.open("V0.bin", "r");
  Serial.printf("  'V0.bin' writing %u...\n", f.size());

  Update.begin(f.size());
  Update.writeStream(f);

  // TEST 1 - Just to validate second program.  It's simply "Blink"
  // This all works.  
  #ifdef GOOD_TEST
  Update.end();
  system_restart();

  #else   // Not good :)
  // TEST 2 - Here trying what I thought should work.  
  
  // I made the UpdaterClass _startAddress field public to allow this!
  u32 startAddress = Update._startAddress;
  Serial.printf("restart location(%p)\n", startAddress);
 
  Update.end();
  // The UpdaterClass creates eboot command to relocate the
  // bin file to the 0x1000 location after rebooting.  This is
  // is done in end() function.  We clear that command so it stays
  // at the "startAddress".
  eboot_command_clear();
  // Here is where we try to use the function in question.
  system_restart_enhance(SYS_BOOT_NORMAL_BIN, startAddress);
  #endif  
}

void loop() {}

In the first TEST just to prove the second executable works with the standard UpdaterClass, everything works as expected and here is the output (and the LED blinks :)

CHIP/IDE SETTINGS
ver=31  mode=1  addr=0  map=4  reason=6

LittleFS.begin() = 1
Total = 3121152
Used = 598016
     V0.bin 276544
lfs_file_close: fd=0x3ffefc60
     V4.bin 301728
lfs_file_close: fd=0x3ffefc60
  'V0.bin' writing 276544...
sleep disable
[begin] roundedSize:       0x00044000 (278528)
[begin] updateEndAddress:  0x00100000 (1048576)
[begin] currentSketchSize: 0x0004E000 (319488)
[begin] _startAddress:     0x000BC000 (770048)
[begin] _currentAddress:   0x000BC000 (770048)
[begin] _size:             0x00043840 (276544)
Header: 0xE9 2 2 40
Staged: address:0x000BC000, size:0x00043840
lfs_file_close: fd=0x3ffefc60
�@⸮Z-nP���⸮M'γ�	%[�)Q
�⸮O�⸮

Here is the second TEST results. (Simply comment out the #define GOOD_TEST at the top.

CHIP/IDE SETTINGS
ver=31  mode=1  addr=0  map=4  reason=6

LittleFS.begin() = 1
Total = 3121152
Used = 598016
     V0.bin 276544
lfs_file_close: fd=0x3ffefc80
     V4.bin 301728
lfs_file_close: fd=0x3ffefc80
  'V0.bin' writing 276544...
sleep disable
[begin] roundedSize:       0x00044000 (278528)
[begin] updateEndAddress:  0x00100000 (1048576)
[begin] currentSketchSize: 0x0004E000 (319488)
[begin] _startAddress:     0x000BC000 (770048)
[begin] _currentAddress:   0x000BC000 (770048)
[begin] _size:             0x00043840 (276544)
Header: 0xE9 2 2 40
restart location(0xbc000)
Staged: address:0x000BC000, size:0x00043840
failed: need boot >= 1.3
lfs_file_close: fd=0x3ffefc80