improve comments

Improve empty function situation around build option UMM_INFO.

cores/esp8266/Esp-frag.cpp

@@ -23,6 +23,7 @@
 #include "coredecls.h"
 #include "Esp.h"
 
+#if defined(UMM_INFO) || defined(UMM_INFO_EMPTY)
 void EspClass::getHeapStats(uint32_t* hfree, uint32_t* hmax, uint8_t* hfrag)
 {
  // L2 / Euclidean norm of free block sizes.
@@ -60,3 +61,4 @@ uint8_t EspClass::getHeapFragmentation()
 {
  return (uint8_t)umm_fragmentation_metric();
 }
+#endif

cores/esp8266/Esp.cpp

@@ -222,10 +222,12 @@ uint32_t EspClass::getFreeHeap(void)
  return umm_free_heap_size_lw();
 }
 
+#if defined(UMM_INFO) || defined(UMM_INFO_EMPTY)
 uint32_t EspClass::getMaxFreeBlockSize(void)
 {
  return umm_max_block_size();
 }
+#endif
 
 uint32_t EspClass::getFreeContStack()
 {

cores/esp8266/Esp.h

@@ -114,11 +114,17 @@ class EspClass {
  static uint32_t getChipId();
 
  static uint32_t getFreeHeap();
+#if defined(UMM_INFO)
  static uint32_t getMaxFreeBlockSize();
  static uint8_t getHeapFragmentation(); // in %
  static void getHeapStats(uint32_t* free = nullptr, uint16_t* max = nullptr, uint8_t* frag = nullptr) __attribute__((deprecated("Use 'uint32_t*' on max, 2nd argument")));
  static void getHeapStats(uint32_t* free = nullptr, uint32_t* max = nullptr, uint8_t* frag = nullptr);
-
+#elif defined(UMM_INFO_EMPTY)
+ static uint32_t getMaxFreeBlockSize() __attribute__((deprecated("This method is empty use the build option UMM_INFO to complete.")));
+ static uint8_t getHeapFragmentation() __attribute__((deprecated("This method is empty use the build option UMM_INFO to complete.")));
+ static void getHeapStats(uint32_t* free = nullptr, uint16_t* max = nullptr, uint8_t* frag = nullptr) __attribute__((deprecated("This method is empty use the build option UMM_INFO to complete.")));
+ static void getHeapStats(uint32_t* free = nullptr, uint32_t* max = nullptr, uint8_t* frag = nullptr) __attribute__((deprecated("This method is empty use the build option UMM_INFO to complete.")));
+#endif
  static uint32_t getFreeContStack();
  static void resetFreeContStack();
 

cores/esp8266/heap.cpp

@@ -11,7 +11,7 @@ extern "C" size_t umm_umul_sat(const size_t a, const size_t b);
 extern "C" void z2EapFree(void *ptr, const char* file, int line) __attribute__((weak, alias("vPortFree"), nothrow));
 // I don't understand all the compiler noise around this alias.
 // Adding "__attribute__ ((nothrow))" seems to resolve the issue.
-// This may be relevant: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=81824 
+// This may be relevant: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=81824
 
 // Need FORCE_ALWAYS_INLINE to put HeapSelect class constructor/deconstructor in IRAM
 #define FORCE_ALWAYS_INLINE_HEAP_SELECT
@@ -342,8 +342,10 @@ size_t IRAM_ATTR xPortWantedSizeAlign(size_t size)
 
 void system_show_malloc(void)
 {
+#ifdef UMM_INFO
  HeapSelectDram ephemeral;
  umm_info(NULL, true);
+#endif
 }
 
 /*

cores/esp8266/umm_malloc/umm_info.c

@@ -269,6 +269,12 @@ static void umm_fragmentation_metric_remove(umm_heap_context_t *_context, uint16
 #endif // UMM_INLINE_METRICS
 
 /* ------------------------------------------------------------------------ */
+#elif defined(UMM_INFO_EMPTY)
+void *umm_info(void *ptr, bool force) {
+ (void)ptr;
+ (void)force;
+ return NULL;
+}
 #endif
 
 #endif // defined(BUILD_UMM_MALLOC_C)

cores/esp8266/umm_malloc/umm_malloc_cfg.h

@@ -211,8 +211,8 @@ extern ICACHE_FLASH_ATTR int umm_fragmentation_metric(void);
 extern ICACHE_FLASH_ATTR size_t umm_max_block_size_core(umm_heap_context_t *_context);
 extern ICACHE_FLASH_ATTR int umm_usage_metric_core(umm_heap_context_t *_context);
 extern ICACHE_FLASH_ATTR int umm_fragmentation_metric_core(umm_heap_context_t *_context);
-#else
- #define umm_info(p,b)
+#elif defined(UMM_INFO_EMPTY)
+ extern ICACHE_FLASH_ATTR void *umm_info(void *ptr, bool force) __attribute__((deprecated("This method is empty use the build option UMM_INFO to complete.")));
  #define umm_free_heap_size() (0)
  #define umm_max_block_size() (0)
  #define umm_fragmentation_metric() (0)

cores/esp8266/umm_malloc/umm_malloc_cfgport.h

@@ -124,6 +124,11 @@ extern char _heap_start[];
  * If you don't require the methods in EspClass that are dependent on functions
  * from the `-DUMM_INFO` build option, you can use only `-DUMM_STATS` and save
  * on IROM and a little IRAM.
+ *
+ * Build option `-DUMM_INFO_EMPTY` ignored when `-DUMM_INFO` enabled.
+ * `-DUMM_INFO_EMPTY` provides empty versions of the functions supplied by
+ * `UMM_INFO` intended for easing build option experimentation. It will report
+ * noisy depreciation messages until you clean up all references.
  */
 #if defined(UMM_STATS) || defined(UMM_STATS_FULL) || defined(UMM_INLINE_METRICS) || defined(UMM_INFO)
 /*
@@ -138,15 +143,16 @@ extern char _heap_start[];
 #endif
 
 /*
- For `-Dname`, gcc assigns a value of 1 and this works find; however,
+ For `-Dname`, gcc assigns a value of 1 and this works fine; however,
  if `-Dname=0` is used, the intended results will not be obtained.
 
  Make value and valueless defines compliant with their usage in umm_malloc:
  `#define name` => #define name 1
  `#define name 0` => #undef name
 */
 #if ((1 - UMM_BEST_FIT - 1) == 2)
-// Assume 1 for define w/o value
+// When UMM_BEST_FIT is defined w/o value, the computation becomes
+// (1 - - 1) == 2 => (1 + 1) == 2
 #undef UMM_BEST_FIT
 #define UMM_BEST_FIT 1
 #elif ((1 - UMM_BEST_FIT - 1) == 0)