eps8266/general: Add known issue of WiFi RX buffers overflow.

1 files changed, 23 insertions, 0 deletions

diff --git a/docs/esp8266/general.rst b/docs/esp8266/general.rst
index 6d186fcd2f..68ed701beb 100644
--- a/docs/esp8266/general.rst
+++ b/docs/esp8266/general.rst
@@ -122,3 +122,26 @@ Due to limitations of the ESP8266 chip the internal real-time clock (RTC)
 will overflow every 7:45h.  If a long-term working RTC time is required then
 ``time()`` or ``localtime()`` must be called at least once within 7 hours.
 MicroPython will then handle the overflow.
+
+Sockets and WiFi buffers overflow
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Socket instances remain active until they are explicitly closed. This has two
+consequences. Firstly they occupy RAM, so an application which opens sockets
+without closing them may eventually run out of memory. Secondly not properly
+closed socket can cause the low-level part of the vendor WiFi stack to emit
+``Lmac`` errors. This occurs if data comes in for a socket and is not
+processed in a timely manner. This can overflow the WiFi stack input queue
+and lead to a deadlock. The only recovery is by a hard reset.
+
+The above may also happen after an application terminates and quits to the REPL
+for any reason including an exception. Subsequent arrival of data provokes the
+failure with the above error message repeatedly issued. So, sockets should be
+closed in any case, regardless whether an application terminates successfully
+or by an exeption, for example using try/finally::
+
+    sock = socket(...)
+    try:
+        # Use sock
+    finally:
+        s.close()