Automatic stack location selection (SYS or HEAP), enable per library AR-chive in arduino build system (#5018)

Automatic stack location selection (SYS or HEAP), enable per library AR-chive in arduino build system 

* enable dot_a_linkage on internal libraries
* add device tests
* boards generator: deprecate --noextra4k/--allowWPS and fix documentation

Author: d-a-v

cores/esp8266/cont.h

@@ -27,6 +27,10 @@
 #define CONT_STACKSIZE 4096
 #endif
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 typedef struct cont_ {
         void (*pc_ret)(void);
         unsigned* sp_ret;
@@ -45,6 +49,8 @@ typedef struct cont_ {
         unsigned* struct_start;
 } cont_t;
 
+extern cont_t* g_pcont;
+
 // Initialize the cont_t structure before calling cont_run
 void cont_init(cont_t*);
 
@@ -68,4 +74,8 @@ int cont_get_free_stack(cont_t* cont);
 // continuation stack
 bool cont_can_yield(cont_t* cont);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* CONT_H_ */

cores/esp8266/core_esp8266_app_entry_noextra4k.cpp

@@ -0,0 +1,36 @@
+/*
+ *  This is the original app_entry() not providing extra 4K heap, but allowing
+ *  the use of WPS.
+ *
+ *  see comments in core_esp8266_main.cpp's app_entry()
+ *
+ */
+
+#include <c_types.h>
+#include "cont.h"
+#include "coredecls.h"
+
+void disable_extra4k_at_link_time (void)
+{
+    /*
+     * does nothing
+     * allows overriding the core_esp8266_main.cpp's app_entry()
+     * by this one below, at link time
+     *
+     */
+}
+
+/* the following code is linked only if a call to the above function is made somewhere */
+
+extern "C" void call_user_start();
+
+/* this is the default NONOS-SDK user's heap location */
+static cont_t g_cont __attribute__ ((aligned (16)));
+
+extern "C" void ICACHE_RAM_ATTR app_entry_redefinable(void)
+{
+    g_pcont = &g_cont;
+
+    /* Call the entry point of the SDK code. */
+    call_user_start();
+}

cores/esp8266/core_esp8266_main.cpp

@@ -48,7 +48,7 @@ extern void (*__init_array_end)(void);
 /* Not static, used in Esp.cpp */
 struct rst_info resetInfo;
 
-/* Not static, used in core_esp8266_postmortem.c.
+/* Not static, used in core_esp8266_postmortem.c and other places.
  * Placed into noinit section because we assign value to this variable
  * before .bss is zero-filled, and need to preserve the value.
  */
@@ -175,10 +175,15 @@ void init_done() {
 
    WPS beeing flawed by its poor security, or not beeing used by lots of
    users, it has been decided that we are still going to use that memory for
-   user's stack and disable the use of WPS, with an option to revert that
-   back at the user's discretion.  This selection can be done with the
-   global define NO_EXTRA_4K_HEAP.  An option has been added to the board
-   generator script.
+   user's stack and disable the use of WPS.
+
+   app_entry() jumps to app_entry_custom() defined as "weakref" calling
+   itself a weak customizable function, allowing to use another one when
+   this is required (see core_esp8266_app_entry_noextra4k.cpp, used by WPS).
+
+   (note: setting app_entry() itself as "weak" is not sufficient and always
+    ends up with the other "noextra4k" one linked, maybe because it has a
+    default ENTRY(app_entry) value in linker scripts).
 
    References:
    https://github.com/esp8266/Arduino/pull/4553
@@ -188,31 +193,25 @@ void init_done() {
 
 */
 
-#ifdef NO_EXTRA_4K_HEAP
-/* this is the default NONOS-SDK user's heap location */
-cont_t g_cont __attribute__ ((aligned (16)));
-#endif
-
-extern "C" void ICACHE_RAM_ATTR app_entry(void)
+extern "C" void ICACHE_RAM_ATTR app_entry_redefinable(void) __attribute__((weak));
+extern "C" void ICACHE_RAM_ATTR app_entry_redefinable(void)
 {
-#ifdef NO_EXTRA_4K_HEAP
-
-    /* this is the default NONOS-SDK user's heap location */
-    g_pcont = &g_cont;
-
-#else
-
     /* Allocate continuation context on this SYS stack,
        and save pointer to it. */
     cont_t s_cont __attribute__((aligned(16)));
     g_pcont = &s_cont;
 
-#endif
-
     /* Call the entry point of the SDK code. */
     call_user_start();
 }
 
+static void ICACHE_RAM_ATTR app_entry_custom (void) __attribute__((weakref("app_entry_redefinable")));
+
+extern "C" void ICACHE_RAM_ATTR app_entry (void)
+{
+    return app_entry_custom();
+}
+
 extern "C" void user_init(void) {
     struct rst_info *rtc_info_ptr = system_get_rst_info();
     memcpy((void *) &resetInfo, (void *) rtc_info_ptr, sizeof(resetInfo));

cores/esp8266/core_esp8266_postmortem.c

@@ -32,8 +32,6 @@
 
 extern void __real_system_restart_local();
 
-extern cont_t* g_pcont;
-
 // These will be pointers to PROGMEM const strings
 static const char* s_panic_file = 0;
 static int s_panic_line = 0;

cores/esp8266/coredecls.h

@@ -8,10 +8,15 @@ extern "C" {
 
 // TODO: put declarations here, get rid of -Wno-implicit-function-declaration
 
+#include <cont.h> // g_pcont declaration
+
 extern bool timeshift64_is_set;
 
+void esp_yield();
+void esp_schedule();
 void tune_timeshift64 (uint64_t now_us);
 void settimeofday_cb (void (*cb)(void));
+void disable_extra4k_at_link_time (void) __attribute__((noinline));
 
 #ifdef __cplusplus
 }

doc/faq/a05-board-generator.rst

@@ -48,8 +48,6 @@ As of today you can:
 
 * increase available flash space by disabling floats in ``*printf`` functions
 
-* enable WPS which is now disabled by default (at the cost of a smaller heap by ~4KB)
-
 * change led pin ``LED_BUILTIN`` for the two generic boards
 
 * change the default lwIP version (1.4 or 2)

doc/faq/readme.rst

@@ -46,22 +46,29 @@ How can I get some extra KBs in flash ?
 * Using ``*printf()`` with floats is enabled by default.  Some KBs of flash can
   be saved by using the option ``--nofloat`` with the boards generator:
 
-  ``./tools/boards.txt.py --nofloat --allgen``
+  ``./tools/boards.txt.py --nofloat --boardsgen``
 
 * Use the debug level option ``NoAssert-NDEBUG`` (in the Tools menu)
 
 `Read more <a05-board-generator.rst>`__.
 
-Why can't I use WPS ?
-~~~~~~~~~~~~~~~~~~~~~
+About WPS
+~~~~~~~~~
 
-WPS is disabled by default, this offers an extra 4KB in ram/heap.  To enable
-WPS (and lose 4KB of useable ram), use this boards generator option:
+From release 2.4.2 and ahead, not using WPS will give an exra ~4.5KB in
+heap.
 
-``./tools/boards.txt.py --allowWPS --allgen``
+In release 2.4.2 only, WPS is disabled by default and the board generator is
+required to enable it:
+
+``./tools/boards.txt.py --allowWPS --boardsgen``
 
 `Read more <a05-board-generator.rst>`__.
 
+This manual selection is not needed starting from 2.5.0 (and in git
+version).  WPS is always available, and not using it will give an extra
+~4.5KB compared to releases until 2.4.1 included.
+
 This Arduino library doesn't work on ESP. How do I make it work?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

libraries/ArduinoOTA/library.properties

@@ -7,3 +7,4 @@ paragraph=With this library you can enable your sketch to be upgraded over netwo
 category=Communication
 url=
 architectures=esp8266
+dot_a_linkage=true

libraries/DNSServer/library.properties

@@ -7,3 +7,4 @@ paragraph=This library implements a simple DNS server.
 category=Communication
 url=
 architectures=esp8266
+dot_a_linkage=true

libraries/EEPROM/library.properties

@@ -7,3 +7,4 @@ paragraph=
 category=Data Storage
 url=http://arduino.cc/en/Reference/EEPROM
 architectures=esp8266
+dot_a_linkage=true