Espressif8266 OOM docs wrong

As per https://community.platformio.org/t/esp8266-error-unknown-opcode-or-format-name-when-compiling-with-include-umm-malloc-umm-malloc-cfg-h/14709.

https://docs.platformio.org/en/latest/platforms/espressif8266.html#debug-level says to basically add

build_flags =
   -DDEBUG_ESP_PORT=Serial
   -DDEBUG_ESP_OOM
   -include "umm_malloc/umm_malloc_cfg.h"

to the platformio.ini of a Arduino-ESP8266 project to enable the out-of-memory detection system in the core.

However, the -include flags leads to a multitude of compile errors the moment an assembly file (cont.S) is compiled. Full platformio.ini of

[env:nodemcuv2]
platform = espressif8266
board = nodemcuv2
framework = arduino
monitor_speed = 74880
build_flags =
   -DDEBUG_ESP_PORT=Serial
   -DDEBUG_ESP_OOM
   -include "umm_malloc/umm_malloc_cfg.h"

Results in

Compiling .pio\build\nodemcuv2\FrameworkArduino\cont.S.o
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h: Assembler messages:
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:22: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:23: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:26: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:27: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:30: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:31: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:34: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:35: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:38: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:39: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:42: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:43: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:46: Error: unknown opcode or format name 'typedef'
c:\users\max\.platformio\packages\toolchain-xtensa@2.100300.210717\xtensa-lx106-elf\include\machine\_default_types.h:47: Error: unknown opcode or format name 'typedef'

This header file is not assembly-file safe.

Removing the -include instruction allows for succesful compilation, and seemingly working OOM detection in a minimal example code

#include <Arduino.h>

void setup() {
  delay(1000);
  Serial.begin(74880);
  Serial.println("Testing out-of-memory...");
}

void loop() {
   Serial.println("Mallocing 5K.."); Serial.flush();
   void* ptr = malloc(5 * 1024);
   Serial.print("Alloced ptr "); Serial.println((unsigned int) ptr, HEX);
   Serial.print("Now free: " );
   Serial.println(ESP.getFreeHeap());
   if(ptr == nullptr) {
        Serial.println("malloc() returned NULL!! Ran out of memory");
        delay(10000); //"halt"
   }
}

with the last few lines of the output being

Now free: 712
Mallocing 5K..
:oom(5120)@main.cpp:11
Alloced ptr 0

which does not come from the sketch code but from the OOM detector.

The documentation should be corrected in regards for activating the out-of-memory detector, or any other features that can be enabled through umm_malloc_cfg.h.

Open the Espressif8266 documentation page at the Debug Level section and compare its build_flags example with the linked PlatformIO report. Reproduce the shown platformio.ini configuration if needed, then update the instructions so the out-of-memory detector guidance does not cause assembly compilation errors; verify that the documented example remains usable.