doc: Add performance guides for execuion speed, binary size, RAM usage

Closes #7007 Closes #6715 Closes #3781 Closes #2566
espressif · Jun 3, 2021 · dc6b950 · dc6b950
1 parent 2a27e46
commit dc6b950
Show file tree

Hide file tree

Showing 23 changed files with 860 additions and 13 deletions.
diff --git a/Kconfig b/Kconfig
@@ -361,6 +361,7 @@ mainmenu "Espressif IoT Development Framework Configuration"
 
                 - coverage: NORMAL < STRONG < OVERALL
 
+                The performance impact includes increasing the amount of stack memory required for each task.
 
             config COMPILER_STACK_CHECK_MODE_NONE
                 bool "None"

diff --git a/components/bt/controller/esp32/Kconfig.in b/components/bt/controller/esp32/Kconfig.in
@@ -31,7 +31,7 @@ config BTDM_CTRL_BR_EDR_MAX_ACL_CONN
     range 1 7
     help
         BR/EDR ACL maximum connections of bluetooth controller.
-        Each connection uses 1.2KB static DRAM whenever the BT controller is enabled.
+        Each connection uses 1.2 KB DRAM whenever the BT controller is enabled.
 
 config BTDM_CTRL_BR_EDR_MAX_SYNC_CONN
     int "BR/EDR Sync(SCO/eSCO) Max Connections"
@@ -40,7 +40,7 @@ config BTDM_CTRL_BR_EDR_MAX_SYNC_CONN
     range 0 3
     help
         BR/EDR Synchronize maximum connections of bluetooth controller.
-        Each connection uses 2KB static DRAM whenever the BT controller is enabled.
+        Each connection uses 2 KB DRAM whenever the BT controller is enabled.
 
 
 

diff --git a/components/esp_system/include/esp_task.h b/components/esp_system/include/esp_task.h
@@ -21,6 +21,8 @@
  * 4. If the configMAX_PRIORITIES is modified, please make all priority are
  *    greater than 0
  * 5. Make sure esp_task.h is consistent between wifi lib and idf
+ * 6. If changing system task priorities, please check the values documented in /api-guides/performance/speed.rst
+ * are up to date
  */
 
 #ifndef _ESP_TASK_H_

diff --git a/components/freertos/include/freertos/FreeRTOSConfig.h b/components/freertos/include/freertos/FreeRTOSConfig.h
@@ -136,11 +136,7 @@
 #define configTICK_RATE_HZ                              ( CONFIG_FREERTOS_HZ )
 
 /* This has impact on speed of search for highest priority */
-#ifdef SMALL_TEST
-#define configMAX_PRIORITIES                            ( 7 )
-#else
 #define configMAX_PRIORITIES                            ( 25 )
-#endif
 
 /* Various things that impact minimum stack sizes */
 

diff --git a/components/soc/esp32/include/soc/soc_caps.h b/components/soc/esp32/include/soc/soc_caps.h
@@ -102,6 +102,8 @@
 
 #define SOC_CPU_WATCHPOINT_SIZE         64 // bytes
 
+#define SOC_CPU_HAS_FPU             1
+
 /*-------------------------- DAC CAPS ----------------------------------------*/
 #define SOC_DAC_PERIPH_NUM      2
 #define SOC_DAC_RESOLUTION      8 // DAC resolution ratio 8 bit

diff --git a/components/soc/esp32s3/include/soc/cpu_caps.h b/components/soc/esp32s3/include/soc/cpu_caps.h
@@ -18,3 +18,5 @@
 #define SOC_CPU_WATCHPOINTS_NUM         2
 
 #define SOC_CPU_WATCHPOINT_SIZE         64 // bytes
+
+#define SOC_CPU_HAS_FPU             1
diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst
@@ -93,15 +93,13 @@ The autocomplete support for PowerShell is planned in the future.
 
 .. note:: The environment variables ``ESPPORT`` and ``ESPBAUD`` can be used to set default values for the ``-p`` and ``-b`` options, respectively. Providing these options on the command line overrides the default.
 
-.. _idf.py-size:
-
 Advanced Commands
 ^^^^^^^^^^^^^^^^^
 
 - ``idf.py app``, ``idf.py bootloader``, ``idf.py partition_table`` can be used to build only the app, bootloader, or partition table from the project as applicable.
 - There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the target.
 - ``idf.py -p PORT erase_flash`` will use esptool.py to erase the target's entire flash chip.
-- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively. If you define variable ``-DOUTPUT_JSON=1`` when running CMake (or ``idf.py``), the output will be formatted as JSON not as human readable text.
+- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively. If you define variable ``-DOUTPUT_JSON=1`` when running CMake (or ``idf.py``), the output will be formatted as JSON not as human readable text. See ``idf.py-size`` for more information.
 - ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree, or when modifying CMake cache variables. For example, ``idf.py -DNAME='VALUE' reconfigure`` can be used to set variable ``NAME`` in CMake cache to value ``VALUE``.
 - ``idf.py python-clean`` deletes generated Python byte code from the IDF directory which may cause issues when switching between IDF and Python versions. It is advised to run this target after switching versions of Python.
 

diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst
@@ -29,6 +29,7 @@ API Guides
     Memory Types <memory-types>
     lwIP TCP/IP Stack <lwip>
     Partition Tables <partition-tables>
+    Performance <performance/index>
     RF Calibration <RF_calibration>
     :esp32: Secure Boot <../security/secure-boot-v1>
     Secure Boot V2 <../security/secure-boot-v2>

diff --git a/docs/en/api-guides/lwip.rst b/docs/en/api-guides/lwip.rst
@@ -337,6 +337,8 @@ Calling ``send()`` or ``sendto()`` repeatedly on a UDP socket may eventually fai
 
     Increasing the number of TX buffers in the :ref:`Wi-Fi <CONFIG_ESP32_WIFI_TX_BUFFER>` project configuration may also help.
 
+.. _lwip-performance:
+
 Performance Optimization
 ------------------------
 
@@ -351,10 +353,12 @@ The :example_file:`wifi/iperf/sdkconfig.defaults` file for the iperf example con
 
 .. important:: Suggest applying changes a few at a time and checking the performance each time with a particular application workload.
 
-- If a lot of tasks are competing for CPU time on the system, consider that the lwIP task has configurable CPU affinity (:ref:`CONFIG_LWIP_TCPIP_TASK_AFFINITY`) and runs at fixed priority ``ESP_TASK_TCPIP_PRIO`` (18). Configure competing tasks to be pinned to a different core, or to run at a lower priority.
+- If a lot of tasks are competing for CPU time on the system, consider that the lwIP task has configurable CPU affinity (:ref:`CONFIG_LWIP_TCPIP_TASK_AFFINITY`) and runs at fixed priority ``ESP_TASK_TCPIP_PRIO`` (18). Configure competing tasks to be pinned to a different core, or to run at a lower priority. See also :ref:`built-in-task-priorities`.
 
 - If using ``select()`` function with socket arguments only, setting :ref:`CONFIG_LWIP_USE_ONLY_LWIP_SELECT` will make ``select()`` calls faster.
 
+- If there is enough free IRAM, select :ref:`CONFIG_LWIP_IRAM_OPTIMIZATION` to improve TX/RX throughput
+
 If using a Wi-Fi network interface, please also refer to :ref:`wifi-buffer-usage`.
 
 Minimum latency

diff --git a/docs/en/api-guides/performance/index.rst b/docs/en/api-guides/performance/index.rst
@@ -0,0 +1,24 @@
+Performance
+===========
+
+ESP-IDF ships with default settings that are designed for a trade-off between performance, resource usage, and available functionality.
+
+These guides describe how to optimize a firmware application for a particular aspect of performance. Usually this involves some trade-off in terms of limiting available functions, or swapping one aspect of performance (such as execution speed) for another (such as RAM usage).
+
+How to Optimize Performance
+---------------------------
+
+1. Decide what the performance-critical aspects of your application are (for example: a particular response time to a certain network operation, a particular startup time limit, particular peripheral data throughput, etc.).
+2. Find a way to measure this performance (some methods are outlined in the guides below).
+3. Modify the code and project configuration and compare the new measurement to the old measurement.
+4. Repeat step 3 until the performance meets the requirements set out in step 1.
+
+Guides
+------
+
+.. toctree::
+   :maxdepth: 2
+
+    Execution Speed <speed>
+    Binary Size <size>
+    RAM Usage <ram-usage>