From 0b891067a3132c990df370825ee6ba59ed117ed2 Mon Sep 17 00:00:00 2001
From: mikee47 <mike@sillyhouse.net>
Date: Mon, 25 Nov 2024 12:30:11 +0000
Subject: [PATCH] Update docs

---
 Sming/Arch/Esp32/README.rst       | 34 ++++++++++++++++++++++++++++---
 docs/source/upgrading/5.2-6.0.rst | 12 +++++++++++
 2 files changed, 43 insertions(+), 3 deletions(-)
 create mode 100644 docs/source/upgrading/5.2-6.0.rst

diff --git a/Sming/Arch/Esp32/README.rst b/Sming/Arch/Esp32/README.rst
index f2c60083c6..4c4e21242e 100644
--- a/Sming/Arch/Esp32/README.rst
+++ b/Sming/Arch/Esp32/README.rst
@@ -117,12 +117,11 @@ IDF versions
 ------------
 
 Sming currently supports IDF versions 5.2. This is installed by default.
-Older versions 4.3, 4.4 and 5.0 are no longer officially supported. If you use one of the old versions, please, consider upgrading to 5.2.
-
+Older versions 4.3, 4.4 and 5.0 are no longer supported.
 
 A different version can be installed if necessary::
 
-    INSTALL_IDF_VER=4.4 $SMING_HOME/../Tools/install.sh esp32
+    INSTALL_IDF_VER=5.3 $SMING_HOME/../Tools/install.sh esp32
 
 The installation script creates a soft-link in ``/opt/esp-idf`` pointing to the last version installed.
 Use the `IDF_PATH` environment variable or change the soft-link to select which one to use.
@@ -136,6 +135,35 @@ See `ESP-IDF Versions <https://docs.espressif.com/projects/esp-idf/en/stable/esp
 for the IDF release schedule.
 
 
+Scheduling
+----------
+
+The ESP IDF runs on FreeRTOS which is a pre-emptive multitasking environment.
+However, Sming is a single-threaded framework and applications should not generally have to consider thread safety.
+
+These are the standard tasks created for a networked Sming application:
+
+- **wifi** Deals with wifi hardware communication
+- **tiT** LWIP tcpip task handles traffic from wifi task. Sming code runs in this task.
+- **esp_timer** High-priority task which services hardware timers
+- **sys_evt** Services IDF events, used primarily by wifi
+- **Tmr Svc** FreeRTOS kernel timers
+- **IDLE** Idle task which runs when there's nothing else to do
+
+
+For a non-networked application (e.g. `Basic_Blink`) it's much simpler:
+
+- **esp_timer** As above
+- **Sming** Dedicated task to service the Sming task queue (software timers and callbacks)
+- **IDLE**
+
+
+Watchdog timer
+--------------
+
+The 8 second watchdog is reset by the idle task. This can happen if any other code runs for too long without idling. With Sming this can occur during length flash erase operations which accommodate this by including a call to `system_soft_wdt_feed()`. This is named from the ESP8266 SDK, but for the esp32 this just yields the current task to allow other tasks to run, which should include the IDLE task.
+
+
 Components
 ----------
 
diff --git a/docs/source/upgrading/5.2-6.0.rst b/docs/source/upgrading/5.2-6.0.rst
new file mode 100644
index 0000000000..c6e8182d79
--- /dev/null
+++ b/docs/source/upgrading/5.2-6.0.rst
@@ -0,0 +1,12 @@
+From v5.2 to 6.0
+================
+
+.. highlight:: c++
+
+**Esp32 task scheduling**
+
+Sming is a single-threaded framework, so does not impose any requirements on application code to be thread-safe.
+However, code could be executed from one of several tasks (wifi, tcpip or Sming) which is a reliability concern.
+
+With PR#2913 this has been fixed and all Sming code now runs in the same task context.
+This has largely be achieved by using a separate callback queue for Sming rather than using the IDF mechanism.