diff --git a/docs/docs_not_updated/esp32c2.txt b/docs/docs_not_updated/esp32c2.txt index 0189c837cf..c9aded5d59 100644 --- a/docs/docs_not_updated/esp32c2.txt +++ b/docs/docs_not_updated/esp32c2.txt @@ -5,12 +5,6 @@ api-guides/esp-ble-mesh/ble-mesh-feature-list api-guides/esp-ble-mesh/ble-mesh-terminology api-guides/esp-ble-mesh/ble-mesh-architecture api-guides/esp-ble-mesh/ble-mesh-faq -api-reference/api-conventions -api-reference/template -api-reference/provisioning/protocomm -api-reference/provisioning/provisioning -api-reference/provisioning/index -api-reference/provisioning/wifi_provisioning api-reference/storage/vfs api-reference/storage/spiffs api-reference/storage/wear-levelling @@ -23,49 +17,10 @@ api-reference/storage/nvs_flash api-reference/storage/sdmmc api-reference/storage/mass_mfg api-reference/storage/index -api-reference/peripherals/adc -api-reference/peripherals/sdspi_host -api-reference/peripherals/lcd -api-reference/kconfig -api-reference/network/esp_openthread -api-reference/network/esp_eth -api-reference/network/esp_netif_driver -api-reference/network/tcpip_adapter_migration -api-reference/network/esp_dpp -api-reference/network/esp_now -api-reference/network/esp_smartconfig -api-reference/network/index -api-reference/network/esp_netif api-reference/system/sleep_modes -api-reference/system/ota -api-reference/system/app_trace -api-reference/system/perfmon -api-reference/system/esp_function_with_shared_stack -api-reference/system/async_memcpy -api-reference/system/random -api-reference/system/esp_timer -api-reference/system/esp_event -api-reference/system/freertos -api-reference/system/system_time -api-reference/system/log -api-reference/system/internal-unstable -api-reference/system/app_image_format -api-reference/system/freertos_additions -api-reference/system/himem api-reference/system/power_management -api-reference/system/mem_alloc -api-reference/system/esp_event_legacy api-reference/system/wdts api-reference/system/inc/power_management_esp32s2_and_later -api-reference/system/heap_debug -api-reference/system/ipc -api-reference/system/esp_https_ota -api-reference/system/esp_err -api-reference/system/console -api-reference/system/intr_alloc -api-reference/system/index -api-reference/system/system -api-reference/system/pthread api-reference/bluetooth/esp_spp api-reference/bluetooth/esp_avrc api-reference/bluetooth/controller_vhci @@ -89,7 +44,6 @@ api-reference/bluetooth/esp-ble-mesh api-reference/bluetooth/index api-reference/bluetooth/esp_gap_ble api-reference/bluetooth/classic_bt -api-reference/error-codes api-reference/protocols/icmp_echo api-reference/protocols/esp_serial_slave_link api-reference/protocols/mqtt diff --git a/docs/en/api-reference/kconfig.rst b/docs/en/api-reference/kconfig.rst index f9c9357931..44f4b73a22 100644 --- a/docs/en/api-reference/kconfig.rst +++ b/docs/en/api-reference/kconfig.rst @@ -4,10 +4,7 @@ Project Configuration Introduction ============ -ESP-IDF uses kconfiglib_ which is a Python-based extension to the Kconfig_ system which provides a compile-time -project configuration mechanism. Kconfig is based around options of several types: integer, string, boolean. Kconfig -files specify dependencies between options, default values of the options, the way the options are grouped together, -etc. +ESP-IDF uses kconfiglib_ which is a Python-based extension to the Kconfig_ system which provides a compile-time project configuration mechanism. Kconfig is based around options of several types: integer, string, boolean. Kconfig files specify dependencies between options, default values of the options, the way the options are grouped together, etc. For the complete list of available features please see Kconfig_ and `kconfiglib extentions`_. @@ -44,25 +41,14 @@ The following attributes of ``Kconfig`` files are standardized: Format checker -------------- -``tools/check_kconfigs.py`` is provided for checking the ``Kconfig`` formatting -rules. The checker checks all ``Kconfig`` and ``Kconfig.projbuild`` files in -the ESP-IDF directory and generates a new file with suffix ``.new`` with some -recommendations how to fix issues (if there are any). Please note that the -checker cannot correct all rules and the responsibility of the developer is to -check and make final corrections in order to pass the tests. For example, -indentations will be corrected if there isn't some misleading previous -formatting but it cannot come up with a common prefix for options inside a -menu. +``tools/check_kconfigs.py`` is provided for checking the ``Kconfig`` formatting rules. The checker checks all ``Kconfig`` and ``Kconfig.projbuild`` files in the ESP-IDF directory and generates a new file with suffix ``.new`` with some recommendations how to fix issues (if there are any). Please note that the checker cannot correct all rules and the responsibility of the developer is to check and make final corrections in order to pass the tests. For example, indentations will be corrected if there isn't some misleading previous formatting but it cannot come up with a common prefix for options inside a menu. .. _configuration-options-compatibility: Backward Compatibility of Kconfig Options ========================================= -The standard Kconfig_ tools ignore unknown options in ``sdkconfig``. So if a -developer has custom settings for options which are renamed in newer ESP-IDF -releases then the given setting for the option would be silently ignored. -Therefore, several features have been adopted to avoid this: +The standard Kconfig_ tools ignore unknown options in ``sdkconfig``. So if a developer has custom settings for options which are renamed in newer ESP-IDF releases then the given setting for the option would be silently ignored. Therefore, several features have been adopted to avoid this: 1. ``confgen.py`` is used by the tool chain to pre-process ``sdkconfig`` files before anything else, for example ``menuconfig``, would read them. As the consequence, the settings for old options will be kept and not ignored. diff --git a/docs/en/api-reference/system/app_image_format.rst b/docs/en/api-reference/system/app_image_format.rst index 04af9bea48..bda9375036 100644 --- a/docs/en/api-reference/system/app_image_format.rst +++ b/docs/en/api-reference/system/app_image_format.rst @@ -41,7 +41,7 @@ To get the list of your image segments, please run the following command: Checksum: e8 (valid)Validation Hash: 407089ca0eae2bbf83b4120979d3354b1c938a49cb7a0c997f240474ef2ec76b (valid) You can also see the information on segments in the ESP-IDF logs while your application is booting: - + .. code-block:: I (443) esp_image: segment 0: paddr=0x00020020 vaddr=0x3f400020 size=0x13ce0 ( 81120) map @@ -62,7 +62,7 @@ You can also see the information on segments in the ESP-IDF logs while your appl For more details on the type of memory segments and their address ranges, see *{IDF_TARGET_NAME} Technical Reference Manual* > *System and Memory* > *Embedded Memory* [`PDF <{IDF_TARGET_TRM_EN_URL}#sysmem>`__]. -.. only:: esp32s2 or esp32s3 or esp32c3 +.. only:: not esp32 For more details on the type of memory segments and their address ranges, see *{IDF_TARGET_NAME} Technical Reference Manual* > *System and Memory* > *Internal Memory* [`PDF <{IDF_TARGET_TRM_EN_URL}#sysmem>`__]. diff --git a/docs/en/api-reference/system/async_memcpy.rst b/docs/en/api-reference/system/async_memcpy.rst index 37b2db3e0d..c04592db6e 100644 --- a/docs/en/api-reference/system/async_memcpy.rst +++ b/docs/en/api-reference/system/async_memcpy.rst @@ -21,10 +21,11 @@ Configure and Install driver :cpp:func:`esp_async_memcpy_install` is used to install the driver with user's configuration. Please note that async memcpy has to be called with the handle returned from :cpp:func:`esp_async_memcpy_install`. Driver configuration is described in :cpp:type:`async_memcpy_config_t`: -:cpp:member:`backlog`: This is used to configured the maximum number of DMA operation that can be working at the background at the same time. -:cpp:member:`sram_trans_align`: Declare SRAM alignment for both data address and copy size, set to zero if the data has no restriction in alignment. If set to a quadruple value (i.e. 4X), the driver will enable the burst mode internally, which is helpful for some performance related application. -:cpp:member:`psram_trans_align`: Declare PSRAM alignment for both data address and copy size. User has to give it a valid value (only 16, 32, 64 are supported) if the destination of memcpy is located in PSRAM. The default alignment (i.e. 16) will be applied if it's set to zero. Internally, the driver configures the size of block used by DMA to access PSRAM, according to the alignment. -:cpp:member:`flags`: This is used to enable some special driver features. + +* :cpp:member:`backlog`: This is used to configure the maximum number of DMA operations being processed at the same time. +* :cpp:member:`sram_trans_align`: Declare SRAM alignment for both data address and copy size, set to zero if the data has no restriction in alignment. If set to a quadruple value (i.e. 4X), the driver will enable the burst mode internally, which is helpful for some performance related application. +* :cpp:member:`psram_trans_align`: Declare PSRAM alignment for both data address and copy size. User has to give it a valid value (only 16, 32, 64 are supported) if the destination of memcpy is located in PSRAM. The default alignment (i.e. 16) will be applied if it's set to zero. Internally, the driver configures the size of block used by DMA to access PSRAM, according to the alignment. +* :cpp:member:`flags`: This is used to enable some special driver features. :c:macro:`ASYNC_MEMCPY_DEFAULT_CONFIG` provides a default configuration, which specifies the backlog to 8. diff --git a/docs/en/api-reference/system/esp_function_with_shared_stack.rst b/docs/en/api-reference/system/esp_function_with_shared_stack.rst index dfce1867c2..7ef63f92be 100644 --- a/docs/en/api-reference/system/esp_function_with_shared_stack.rst +++ b/docs/en/api-reference/system/esp_function_with_shared_stack.rst @@ -4,13 +4,7 @@ Call function with external stack Overview -------- -A given function can be executed with a user allocated stack space -which is independent of current task stack, this mechanism can be -used to save stack space wasted by tasks which call a common function -with intensive stack usage such as `printf`. The given function can -be called inside the shared stack space which is a callback function -deferred by calling :cpp:func:`esp_execute_shared_stack_function`, -passing that function as parameter +A given function can be executed with a user allocated stack space which is independent of current task stack, this mechanism can be used to save stack space wasted by tasks which call a common function with intensive stack usage such as `printf`. The given function can be called inside the shared stack space which is a callback function deferred by calling :cpp:func:`esp_execute_shared_stack_function`, passing that function as parameter. Usage ----- @@ -22,9 +16,7 @@ Usage - the size of stack in bytes - a pointer to the shared stack function -The user defined function will be deferred as a callback -and can be called using the user allocated space without -taking space from current task stack. +The user defined function will be deferred as a callback and can be called using the user allocated space without taking space from current task stack. The usage may look like the code below: @@ -46,15 +38,15 @@ The usage may look like the code below: //Allocate a mutex to protect its usage: SemaphoreHandle_t printf_lock = xSemaphoreCreateMutex(); assert(printf_lock != NULL); - + //Call the desired function using the macro helper: - esp_execute_shared_stack_function(printf_lock, + esp_execute_shared_stack_function(printf_lock, shared_stack, 8192, external_stack_function); - - vSemaphoreDelete(printf_lock); - free(shared_stack); + + vSemaphoreDelete(printf_lock); + free(shared_stack); } .. _esp-call-with-stack-basic_usage: diff --git a/docs/en/api-reference/system/esp_https_ota.rst b/docs/en/api-reference/system/esp_https_ota.rst index 4c2fb72573..55a346aa63 100644 --- a/docs/en/api-reference/system/esp_https_ota.rst +++ b/docs/en/api-reference/system/esp_https_ota.rst @@ -4,8 +4,7 @@ ESP HTTPS OTA Overview -------- -``esp_https_ota`` provides simplified APIs to perform firmware upgrades over HTTPS. -It's an abstraction layer over existing OTA APIs. +``esp_https_ota`` provides simplified APIs to perform firmware upgrades over HTTPS. It's an abstraction layer over existing OTA APIs. Application Example ------------------- @@ -43,15 +42,11 @@ Please refer to :ref:`ESP-TLS: TLS Server Verification ` f Multiple Handlers Sharing A Source ---------------------------------- -Several handlers can be assigned to a same source, given that all handlers are allocated using the ``ESP_INTR_FLAG_SHARED`` flag. -They will all be allocated to the interrupt, which the source is attached to, and called sequentially when the source is active. -The handlers can be disabled and freed individually. The source is attached to the interrupt (enabled), if one or more handlers are enabled, otherwise detached. -A handler will never be called when disabled, while **its source may still be triggered** if any one of its handler enabled. +Several handlers can be assigned to a same source, given that all handlers are allocated using the ``ESP_INTR_FLAG_SHARED`` flag. They will all be allocated to the interrupt, which the source is attached to, and called sequentially when the source is active. The handlers can be disabled and freed individually. The source is attached to the interrupt (enabled), if one or more handlers are enabled, otherwise detached. A handler will never be called when disabled, while **its source may still be triggered** if any one of its handler enabled. Sources attached to non-shared interrupt do not support this feature. -Though the framework support this feature, you have to use it *very carefully*. There usually exist two ways to stop an interrupt from being triggered: *disable the source* or *mask peripheral interrupt status*. -IDF only handles enabling and disabling of the source itself, leaving status and mask bits to be handled by users. +Though the framework support this feature, you have to use it *very carefully*. There usually exist two ways to stop an interrupt from being triggered: *disable the source* or *mask peripheral interrupt status*. IDF only handles enabling and disabling of the source itself, leaving status and mask bits to be handled by users. **Status bits shall either be masked before the handler responsible for it is disabled, either be masked and then properly handled in another enabled interrupt**. Please note that leaving some status bits unhandled without masking them, while disabling the handlers for them, will cause the interrupt(s) to be triggered indefinitely, resulting therefore in a system crash.