Add documentation

diff --git a/components/esp32/include/esp_int_wdt.h b/components/esp32/include/esp_int_wdt.h
index 4387400396b353464fffee829abeb85a7b0db8aa..b32d0219fb14272be72bdb7aa930c35ebed4b2d6 100644 (file)
--- a/components/esp32/include/esp_int_wdt.h
+++ b/components/esp32/include/esp_int_wdt.h
@@ -41,9 +41,6 @@ This uses the TIMERG1 WDT.
   * @brief  Initialize the interrupt watchdog. This is called in the init code if
   *         the interrupt watchdog is enabled in menuconfig.
   *
-  * @param  null
-  *
-  * @return null
   */
 void esp_int_wdt_init();
 

diff --git a/components/esp32/include/esp_task_wdt.h b/components/esp32/include/esp_task_wdt.h
index bbc499567451fe6a316fc2a8e3df404d08b18cd4..eb773770096c5b58083c6de188454c0c4249b9b0 100644 (file)
--- a/components/esp32/include/esp_task_wdt.h
+++ b/components/esp32/include/esp_task_wdt.h
@@ -42,9 +42,6 @@ This uses the TIMERG0 WDT.
   * @brief  Initialize the task watchdog. This is called in the init code, if the
   *         task watchdog is enabled in menuconfig.
   *
-  * @param  null
-  *
-  * @return null
   */
 void esp_task_wdt_init();
 
@@ -52,9 +49,6 @@ void esp_task_wdt_init();
   * @brief  Feed the watchdog. After the first feeding session, the watchdog will expect the calling
   *         task to keep feeding the watchdog until task_wdt_delete() is called.
   *
-  * @param  null
-  *
-  * @return null
   */
 
 void esp_task_wdt_feed();
@@ -63,9 +57,6 @@ void esp_task_wdt_feed();
 /**
   * @brief  Delete the watchdog for the current task.
   *
-  * @param  null
-  *
-  * @return null
   */
 void esp_task_wdt_delete();
 

diff --git a/docs/Doxyfile b/docs/Doxyfile
index 6ff4c458601b7a0c3e6923f8479f46286bb57b94..d5970ee5e908aec30e00df458dcc8ba5d9c1ed2a 100644 (file)
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -1,6 +1,8 @@
 PROJECT_NAME = "ESP32 Programming Guide"
 
-INPUT = ../components/esp32/include/esp_wifi.h ../components/driver/include/driver ../components/bt/include ../components/nvs_flash/include ../components/log/include ../components/vfs/include
+INPUT = ../components/esp32/include/esp_wifi.h ../components/driver/include/driver ../components/bt/include \
+               ../components/nvs_flash/include ../components/log/include ../components/vfs/include \
+               ../components/esp32/include/esp_int_wdt.h ../components/esp32/include/esp_task_wdt.h
 
 WARN_NO_PARAMDOC       = YES
 

diff --git a/docs/api/wdts.rst b/docs/api/wdts.rst
new file mode 100644 (file)
index 0000000..1b476f2
--- /dev/null
+++ b/docs/api/wdts.rst
@@ -0,0 +1,72 @@
+Watchdogs
+=========
+
+Overview
+--------
+
+Esp-idf has support for two types of watchdogs: a task watchdog as well as an interrupt watchdog. Both can be
+enabled using ``make menuconfig`` and selecting the appropriate options.
+
+Interrupt watchdog
+^^^^^^^^^^^^^^^^^^
+
+The interrupt watchdog makes sure the FreeRTOS task switching interrupt isn't blocked for a long time. This
+is bad because no other tasks, including potentially important ones like the WiFi task and the idle task,
+can't get any CPU runtime. A blocked task switching interrupt can happen because a program runs into an 
+infinite loop with interrupts disabled or hangs in an interrupt.
+
+The default action of the interrupt watchdog is to invoke the panic handler. causing a register dump and an opportunity
+for the programmer to find out, using either OpenOCD or gdbstub, what bit of code is stuck with interrupts 
+disabled. Depending on the configuration of the panic handler, it can also blindly reset the CPU, which may be
+preferred in a production environment.
+
+The interrupt watchdog is built around the hardware watchdog in timer group 1. If this watchdog for some reason
+cannot execute the NMI handler that invokes the panic handler (e.g. because IRAM is overwritten by garbage),
+it will hard-reset the SOC.
+
+Task watchdog
+^^^^^^^^^^^^^
+
+Any tasks can elect to be watched by the task watchdog. If such a task does not feed the watchdog within the time
+specified by the task watchdog timeout (which is configurable using ``make menuconfig``), the watchdog will
+print out a warning with information about which processes are running on the ESP32 CPUs and which processes
+failed to feed the watchdog.
+
+By default, the task watchdog watches the idle tasks. The usual cause of idle tasks not feeding the watchdog 
+is a higher-priority process looping without yielding to the lower-priority processes, and can be an indicator
+of badly-written code that spinloops on a peripheral or a task that is stuck in an infinite loop.
+
+Other task can elect to be watched by the task watchdog by calling ``esp_task_wdt_feed()``. Calling this routine
+for the first time will register the task to the task watchdog; calling it subsequent times will feed
+the watchdog. If a task does not want to be watched anymore (e.g. because it is finished and will call 
+``vTaskDelete()`` on itself), it needs to call ``esp_task_wdt_delete()``.
+
+The task watchdog is built around the hardware watchdog in timer group 0. If this watchdog for some reason
+cannot execute the interrupt handler that prints the task data (e.g. because IRAM is overwritten by garbage
+or interrupts are disabled entirely) it will hard-reset the SOC.
+
+JTAG and watchdogs
+^^^^^^^^^^^^^^^^^^
+
+While debugging using OpenOCD, if the CPUs are halted the watchdogs will keep running, eventually resetting the
+CPU. This makes it very hard to debug code; that is why the OpenOCD config will disable both watchdogs on startup.
+This does mean that you will not get any warnings or panics from either the task or interrupt watchdog when the ESP32
+is connected to OpenOCD via JTAG.
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * `esp32/include/esp_int_wdt.h <https://github.com/espressif/esp-idf/blob/master/components/esp32/include/esp_int_wdt.h>`_
+  * `esp32/include/esp_task_wdt.h <https://github.com/espressif/esp-idf/blob/master/components/esp32/include/esp_task_wdt.h>`_
+
+
+Functions
+---------
+
+.. doxygenfunction:: esp_int_wdt_init
+.. doxygenfunction:: esp_task_wdt_init
+.. doxygenfunction:: esp_task_wdt_feed
+.. doxygenfunction:: esp_task_wdt_delete

diff --git a/docs/index.rst b/docs/index.rst
index 1ca6e28eec6dab62e242d9c68a451a785c657db9..c19fc52c9accf9135faeba2e49bee7e554bec7e2 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -42,9 +42,9 @@ Contents:
      1.2. Application startup flow - TBA
      1.3. Flash encryption and secure boot: how they work and APIs - TBA
      1.4. Lower Power Coprocessor - TBA
-     1.5. Watchdogs
+     1.5. Watchdogs <api/wdts>
      1.6. ...
-   2. Memeory - TBA
+   2. Memory - TBA
      2.1. Memory layout of the application (IRAM/IROM, limitations of each) - TBA
      2.2. Flash layout and partitions - TBA
      2.3. Flash access APIs - TBA
@@ -92,6 +92,7 @@ Contents:
 
    Wi-Fi <api/esp_wifi>
    Bluetooth <api/bt>
+   Watchdogs <api/wdts>
 
    api/gpio
    api/uart