How to use system_restart_enhance()???

[Inq720]

I'm developing on a ESP8266 NodeMCU using the Arduino IDE. The documentation is pretty thin. The Espressif 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. BTW - system_get_boot_version() returns 31 on the NodeMCU.

The following Sketch:

• Sreates a file system, a second Sketch has been uploaded (Blink)
• Spits out some details
• Uses an Arduino Core library for OTA updating (Update) installs

As-is, it successfully installs, reboots and runs the new Blink Sketch. This is just to prove that the normal Update usage and second Sketch are valid. If the #define GOOD_TEST line, at the top, is commented out, it will attempt to use system_restart_enhance(). The output for the two runs are below the source code.

Does anyone have any suggestions or know where I can find more details about using system_restart_enhance()???

Thanks.

[Codebox]
#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() {}
[/Codebox]

OUTPUT of working version using #define GOOD_TEST
[Codebox]
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�⸮
[/Codebox]

OUTPUT trying to use system_restart_enhance() #define GOOD_TEST is commented out
[Codebox]
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�⸮
[/Codebox]