mirror of
https://github.com/espressif/esp-idf.git
synced 2025-11-02 16:11:41 +01:00
docs: provide CN translation for three short docs of api-guides (backport v5.1)
This commit is contained in:
Cai Xin Ying
morris
@@ -1,6 +1,8 @@
|
||||
RF calibration
|
||||
RF Calibration
|
||||
==============
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
{IDF_TARGET_NAME} supports three RF calibration methods during RF initialization:
|
||||
|
||||
1. Partial calibration
|
||||
@@ -9,55 +11,45 @@ RF calibration
|
||||
|
||||
3. No calibration
|
||||
|
||||
Partial calibration
|
||||
Partial Calibration
|
||||
-------------------
|
||||
During RF initialization, the partial calibration method is used by default for RF calibration.
|
||||
It is done based on the full calibration data which is stored in the NVS.
|
||||
To use this method, please go to ``menuconfig`` and enable :ref:`CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE`.
|
||||
|
||||
Full calibration
|
||||
During RF initialization, the partial calibration method is used by default for RF calibration. It is done based on the full calibration data which is stored in the NVS. To use this method, please go to ``menuconfig`` and enable :ref:`CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE`.
|
||||
|
||||
Full Calibration
|
||||
----------------
|
||||
Full calibration is triggered in the follwing conditions:
|
||||
|
||||
Full calibration is triggered in the following conditions:
|
||||
|
||||
1. NVS does not exist.
|
||||
|
||||
2. The NVS partition to store calibration data is erased.
|
||||
2. The NVS partition to store calibration data has been erased.
|
||||
|
||||
3. Hardware MAC address is changed.
|
||||
3. Hardware MAC address has changed.
|
||||
|
||||
4. PHY library version is changed.
|
||||
4. PHY library version has changed.
|
||||
|
||||
5. The RF calibration data loaded from the NVS partition is broken.
|
||||
|
||||
It takes about 100ms more than partial calibration.
|
||||
If boot duration is not critical, it is suggested to use the full calibration method.
|
||||
To switch to the full calibration method, go to ``menuconfig`` and disable :ref:`CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE`.
|
||||
If you use the default method of RF calibration, there are two ways to add the function of triggering full calibration as a last-resort remedy.
|
||||
Full calibration takes 100 ms longer than the partial calibration method. If boot duration is not of critical importance to the application, the full calibration method is recommended. To switch to the full calibration method, go to ``menuconfig`` and disable :ref:`CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE`. If you use the default method of RF calibration, there are two ways to add the function of triggering full calibration as a last-resort remedy.
|
||||
|
||||
1. Erase the NVS partition if you don't mind all of the data stored in the NVS partition is erased. That is indeed the easiest way.
|
||||
1. Erase the NVS partition if you do not mind all of the data stored in the NVS partition is erased. That is indeed the easiest way.
|
||||
|
||||
2. Call API :cpp:func:`esp_phy_erase_cal_data_in_nvs` before initializing WiFi and BT/BLE based on some conditions (e.g. an option provided in some diagnostic mode).
|
||||
In this case, only phy namespace of the NVS partition is erased.
|
||||
2. Call API :cpp:func:`esp_phy_erase_cal_data_in_nvs` before initializing Wi-Fi and Bluetooth®/Bluetooth Low Energy based on some conditions (e.g., an option provided in some diagnostic mode). In this case, only the PHY namespace of the NVS partition is erased.
|
||||
|
||||
No calibration
|
||||
No Calibration
|
||||
---------------
|
||||
No calibration method is only used when the device wakes up from deep sleep.
|
||||
|
||||
PHY initialization data
|
||||
The no calibration method is only used when the device wakes up from Deep-sleep mode.
|
||||
|
||||
PHY Initialization Data
|
||||
-----------------------
|
||||
The PHY initialization data is used for RF calibration.
|
||||
There are two ways to get the PHY initialization data.
|
||||
|
||||
One is the default initialization data which is located in the header file :idf_file:`components/esp_phy/{IDF_TARGET_PATH_NAME}/include/phy_init_data.h`.
|
||||
The PHY initialization data is used for RF calibration. There are two ways to get the PHY initialization data.
|
||||
|
||||
It is embedded into the application binary after compiling and then stored into read-only memory (DROM).
|
||||
To use the default initialization data, please go to ``menuconfig`` and disable :ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`.
|
||||
One is to use the default initialization data which is located in the header file :idf_file:`components/esp_phy/{IDF_TARGET_PATH_NAME}/include/phy_init_data.h`. It is embedded into the application binary after compiling and then stored into read-only memory (DROM). To use the default initialization data, please go to ``menuconfig`` and disable :ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`.
|
||||
|
||||
Another is the initialization data which is stored in a partition.
|
||||
When using a custom partition table, make sure that PHY data partition is included (type: `data`, subtype: `phy`).
|
||||
With default partition table, this is done automatically.
|
||||
If initialization data is stored in a partition, it has to be flashed there, otherwise runtime error will occur.
|
||||
To switch to the initialization data stored in a partition, go to ``menuconfig`` and enable :ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`.
|
||||
An alternative is to store the initialization data in a PHY data partition. A PHY data partition is included in the default partition table. However, when using a custom partition table, please ensure that a PHY data partition (type: ``data``, subtype: ``phy``) is included in the custom partition table. Whether you are using a custom partition table or the default partition table, if initialization data is stored in a partition, it has to be flashed there, otherwise a runtime error occurs. If you want to use initialization data stored in a partition, go to ``menuconfig`` and enable the option :ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
@@ -1,49 +1,80 @@
|
||||
High-Level Interrupts
|
||||
=====================
|
||||
High Priority Interrupts
|
||||
========================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
The Xtensa architecture has support for 32 interrupts, divided over 7 levels (levels 1 to 7, with 7 being an NMI), plus an assortment of exceptions. On the {IDF_TARGET_NAME}, the interrupt mux allows most interrupt sources to be routed to these interrupts using the :doc:`interrupt allocator <../api-reference/system/intr_alloc>`. Normally, interrupts will be written in C, but ESP-IDF allows high-level interrupts to be written in assembly as well, resulting in very low interrupt latencies.
|
||||
The Xtensa architecture supports 32 interrupts, divided over 7 priority levels from level 1 to 7, with level 7 being an non-maskable interrupt (NMI), plus an assortment of exceptions. On the {IDF_TARGET_NAME}, the :doc:`../api-reference/system/intr_alloc` can route most interrupt sources to these interrupts via the interrupt mux. Normally, interrupts are written in C, but ESP-IDF allows high-priority interrupts to be written in assembly as well, resulting in very low interrupt latencies.
|
||||
|
||||
Interrupt Levels
|
||||
----------------
|
||||
Interrupt Priorities
|
||||
--------------------
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
===== ================= ====================================================
|
||||
Level Symbol Remark
|
||||
===== ================= ====================================================
|
||||
1 N/A Exception and level 0 interrupts. Handled by ESP-IDF
|
||||
2-3 N/A Medium level interrupts. Handled by ESP-IDF
|
||||
4 xt_highint4 Free to use :ref:`(See 1) <hlinterrupts-pin-notes>`
|
||||
5 xt_highint5 Normally used by ESP-IDF debug logic :ref:`(See 1) <hlinterrupts-pin-notes>`
|
||||
NMI xt_nmi Free to use
|
||||
dbg xt_debugexception Debug exception. Called on e.g. a BREAK instruction. :ref:`(See 2) <hlinterrupts-pin-notes>`
|
||||
===== ================= ====================================================
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 20 30 50
|
||||
:align: center
|
||||
|
||||
* - Priority Level
|
||||
- Symbol
|
||||
- Remark
|
||||
* - 1
|
||||
- N/A
|
||||
- Exception and low priority interrupts, handled by ESP-IDF.
|
||||
* - 2-3
|
||||
- N/A
|
||||
- Medium priority interrupts, handled by ESP-IDF.
|
||||
* - 4
|
||||
- xt_highint4
|
||||
- High priority interrupt, free to use. [1]_
|
||||
* - 5
|
||||
- xt_highint5
|
||||
- Normally used by ESP-IDF debug logic. [1]_
|
||||
* - NMI
|
||||
- xt_nmi
|
||||
- Non-maskable interrupt, free to use.
|
||||
* - dbg
|
||||
- xt_debugexception
|
||||
- Debug exception. Called on e.g., a BREAK instruction. [2]_
|
||||
|
||||
.. _hlinterrupts-pin-notes:
|
||||
|
||||
The following notes give more information about the items in the tables above.
|
||||
|
||||
1. ESP-IDF debug logic can be configured to run on `xt_highint4` or `xt_highint5` in :ref:`CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL`. Bluetooth's interrupt can be configured to run on level 4 by enabling :ref:`CONFIG_BTDM_CTRL_HLI`. If :ref:`CONFIG_BTDM_CTRL_HLI` is enabled, ESP-IDF debug logic must be running on level 5 interrupt.
|
||||
2. If :ref:`CONFIG_BTDM_CTRL_HLI` is enabled, `xt_debugexception` is used to fix `live lock issue <https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>`_ in ESP32 ECO3.
|
||||
.. [1] ESP-IDF debug logic can be configured to run on ``xt_highint4`` or ``xt_highint5`` in :ref:`CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL`. Bluetooth's interrupt can be configured to run on priority level 4 by enabling :ref:`CONFIG_BTDM_CTRL_HLI`. If :ref:`CONFIG_BTDM_CTRL_HLI` is enabled, ESP-IDF debug logic must be running on priority level 5 interrupt.
|
||||
.. [2] If :ref:`CONFIG_BTDM_CTRL_HLI` is enabled, ``xt_debugexception`` is used to fix the `live lock issue <https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>`_ in ESP32 ECO3.
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
===== ================= ====================================================
|
||||
Level Symbol Remark
|
||||
===== ================= ====================================================
|
||||
1 N/A Exception and level 0 interrupts. Handled by ESP-IDF
|
||||
2-3 N/A Medium level interrupts. Handled by ESP-IDF
|
||||
4 xt_highint4 Normally used by ESP-IDF debug logic
|
||||
5 xt_highint5 Free to use
|
||||
NMI xt_nmi Free to use
|
||||
dbg xt_debugexception Debug exception. Called on e.g. a BREAK instruction.
|
||||
===== ================= ====================================================
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 20 30 50
|
||||
:align: center
|
||||
|
||||
Using these symbols is done by creating an assembly file (suffix .S) and defining the named symbols, like this::
|
||||
* - Priority Level
|
||||
- Symbol
|
||||
- Remark
|
||||
* - 1
|
||||
- N/A
|
||||
- Exception and low priority interrupts, handled by ESP-IDF.
|
||||
* - 2-3
|
||||
- N/A
|
||||
- Medium priority interrupts, handled by ESP-IDF.
|
||||
* - 4
|
||||
- xt_highint4
|
||||
- Normally used by ESP-IDF debug logic.
|
||||
* - 5
|
||||
- xt_highint5
|
||||
- High priority interrupts, free to use.
|
||||
* - NMI
|
||||
- xt_nmi
|
||||
- Non-maskable interrupt, free to use.
|
||||
* - dbg
|
||||
- xt_debugexception
|
||||
- Debug exception. Called on e.g., a BREAK instruction.
|
||||
|
||||
Using these symbols is done by creating an assembly file with suffix ``.S`` and defining the named symbols, like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
.section .iram1,"ax"
|
||||
.global xt_highint5
|
||||
@@ -60,32 +91,31 @@ For a real-life example, see the :component_file:`esp_system/port/soc/{IDF_TARGE
|
||||
Notes
|
||||
-----
|
||||
|
||||
- Do not call C code from a high-level interrupt; as these interrupts are run from a critical section, this can cause the target to crash.
|
||||
Note that although the panic handler interrupt does call normal C code, this exception is allowed due to the fact that this handler never returns (i.e., the application will not continue to run after the panic handler).
|
||||
so breaking C code execution flow is not a problem.
|
||||
- Do not call C code from a high-priority interrupt; as these interrupts are run from a critical section, this can cause the target to crash. Note that although the panic handler interrupt does call normal C code, this exception is allowed due to the fact that this handler never returns (i.e., the application does not continue to run after the panic handler), so breaking C code execution flow is not a problem.
|
||||
|
||||
.. only:: esp32
|
||||
.. only:: esp32
|
||||
|
||||
When :ref:`CONFIG_BTDM_CTRL_HLI` is enabled, C code is also called from a high-level interrupt, this is possible thanks to some additional protection added to it.
|
||||
When :ref:`CONFIG_BTDM_CTRL_HLI` is enabled, C code is also called from a high-priority interrupt, this is possible thanks to some additional protection added to it.
|
||||
|
||||
- Make sure your assembly code gets linked in. Indeed, as the free-to-use symbols are declared as weak, the linker may discard the file containing the symbol. This will
|
||||
happen if the only symbol defined, or used, from the user file is the ``xt_*`` free-to-use symbol. To avoid this, in the assembly file containing the ``xt_*`` symbol,
|
||||
define another symbol, like::
|
||||
- Make sure your assembly code gets linked in. Indeed, as the free-to-use symbols are declared as weak, the linker may discard the file containing the symbol. This happens if the only symbol defined, or used from the user file is the ``xt_*`` free-to-use symbol. To avoid this, in the assembly file containing the ``xt_*`` symbol, define another symbol, like:
|
||||
|
||||
.global ld_include_my_isr_file
|
||||
ld_include_my_isr_file:
|
||||
.. code-block:: none
|
||||
|
||||
Here it is called ``ld_include_my_isr_file`` but can have any name, as long as it is not defined anywhere else in the project.
|
||||
.global ld_include_my_isr_file
|
||||
ld_include_my_isr_file:
|
||||
|
||||
Then, in the component ``CMakeLists.txt``, add this name as an unresolved symbol to the ld command line arguments::
|
||||
Here it is called ``ld_include_my_isr_file`` but can have any name, as long as it is not defined anywhere else in the project.
|
||||
|
||||
target_link_libraries(${COMPONENT_TARGET} "-u ld_include_my_isr_file")
|
||||
Then, in the component ``CMakeLists.txt``, add this name as an unresolved symbol to the ld command line arguments:
|
||||
|
||||
This should cause the linker to always include the file defining ``ld_include_my_isr_file``, causing the ISR to always be linked in.
|
||||
.. code-block:: none
|
||||
|
||||
- High-level interrupts can be routed and handled using :cpp:func:`esp_intr_alloc` and associated functions. The handler and handler arguments
|
||||
to :cpp:func:`esp_intr_alloc` must be NULL, however.
|
||||
target_link_libraries(${COMPONENT_TARGET} "-u ld_include_my_isr_file")
|
||||
|
||||
- In theory, medium priority interrupts could also be handled in this way. ESP-IDF does not support this yet.
|
||||
This will ensure the linker to always includes the file defining ``ld_include_my_isr_file``, so that the ISR is always linked.
|
||||
|
||||
- To check Xtensa instruction set architecture (ISA), please refer to `Xtensa ISA Summary <https://www.cadence.com/content/dam/cadence-www/global/en_US/documents/tools/ip/tensilica-ip/isa-summary.pdf>`_.
|
||||
- High-priority interrupts can be routed and handled using :cpp:func:`esp_intr_alloc` and associated functions. The handler and handler arguments to :cpp:func:`esp_intr_alloc` must be NULL, however.
|
||||
|
||||
- In theory, medium priority interrupts could also be handled in this way. ESP-IDF does not support this yet.
|
||||
|
||||
- To check Xtensa instruction set architecture (ISA), please refer to `Xtensa ISA Summary <https://www.cadence.com/content/dam/cadence-www/global/en_US/documents/tools/ip/tensilica-ip/isa-summary.pdf>`_.
|
||||
@@ -1,67 +1,55 @@
|
||||
Thread Local Storage
|
||||
====================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Thread-local storage (TLS) is a mechanism by which variables are allocated such that there
|
||||
is one instance of the variable per extant thread. ESP-IDF provides three ways to make use
|
||||
of such variables:
|
||||
Thread-local storage (TLS) is a mechanism by which variables are allocated such that there is one instance of the variable per extant thread. ESP-IDF provides three ways to make use of such variables:
|
||||
|
||||
- :ref:`freertos-native`: ESP-IDF FreeRTOS native API.
|
||||
- :ref:`pthread-api`: ESP-IDF's pthread API.
|
||||
- :ref:`c11-std`: C11 standard introduces special keyword to declare variables as thread local.
|
||||
- :ref:`freertos-native`: ESP-IDF FreeRTOS native APIs.
|
||||
- :ref:`pthread-api`: ESP-IDF pthread APIs.
|
||||
- :ref:`c11-std`: C11 standard introduces special keywords to declare variables as thread local.
|
||||
|
||||
.. _freertos-native:
|
||||
|
||||
FreeRTOS Native API
|
||||
FreeRTOS Native APIs
|
||||
--------------------
|
||||
|
||||
The ESP-IDF FreeRTOS provides the following API to manage thread local variables:
|
||||
The ESP-IDF FreeRTOS provides the following APIs to manage thread local variables:
|
||||
|
||||
- :cpp:func:`vTaskSetThreadLocalStoragePointer`
|
||||
- :cpp:func:`pvTaskGetThreadLocalStoragePointer`
|
||||
- :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback`
|
||||
- :cpp:func:`vTaskSetThreadLocalStoragePointer`
|
||||
- :cpp:func:`pvTaskGetThreadLocalStoragePointer`
|
||||
- :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback`
|
||||
|
||||
In this case maximum number of variables that can be allocated is limited by
|
||||
:ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` configuration value. Variables are kept in the task control block (TCB)
|
||||
and accessed by their index. Note that index 0 is reserved for ESP-IDF internal uses.
|
||||
In this case, the maximum number of variables that can be allocated is limited by :ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS`. Variables are kept in the task control block (TCB) and accessed by their index. Note that index 0 is reserved for ESP-IDF internal uses.
|
||||
|
||||
Using that API user can allocate thread local variables of an arbitrary size and assign them to any number of tasks.
|
||||
Different tasks can have different sets of TLS variables.
|
||||
Using the APIs above, you can allocate thread local variables of an arbitrary size, and assign them to any number of tasks. Different tasks can have different sets of TLS variables.
|
||||
|
||||
If size of the variable is more then 4 bytes then user is responsible for allocating/deallocating memory for it.
|
||||
Variable's deallocation is initiated by FreeRTOS when task is deleted, but user must provide function (callback)
|
||||
to do proper cleanup.
|
||||
If size of the variable is more then 4 bytes, then you need to allocate/deallocate memory for it. Variable's deallocation is initiated by FreeRTOS when task is deleted, but user must provide callback function to do proper cleanup.
|
||||
|
||||
.. _pthread-api:
|
||||
|
||||
Pthread API
|
||||
Pthread APIs
|
||||
----------------
|
||||
|
||||
The ESP-IDF provides the following :doc:`pthread API </api-reference/system/pthread>` to manage thread local variables:
|
||||
The ESP-IDF provides the following :doc:`/api-reference/system/pthread` to manage thread local variables:
|
||||
|
||||
- :cpp:func:`pthread_key_create`
|
||||
- :cpp:func:`pthread_key_delete`
|
||||
- :cpp:func:`pthread_getspecific`
|
||||
- :cpp:func:`pthread_setspecific`
|
||||
- :cpp:func:`pthread_key_create`
|
||||
- :cpp:func:`pthread_key_delete`
|
||||
- :cpp:func:`pthread_getspecific`
|
||||
- :cpp:func:`pthread_setspecific`
|
||||
|
||||
This API has all benefits of the one above, but eliminates some its limits. The number of variables is
|
||||
limited only by size of available memory on the heap.
|
||||
Due to the dynamic nature this API introduces additional performance overhead compared to the native one.
|
||||
These APIs have all benefits of the ones above, but eliminates some their limits. The number of variables is limited only by size of available memory on the heap. Due to the dynamic nature, this APIs introduce additional performance overhead compared to the native one.
|
||||
|
||||
.. _c11-std:
|
||||
|
||||
C11 Standard
|
||||
------------
|
||||
|
||||
The ESP-IDF FreeRTOS supports thread local variables according to C11 standard (ones specified with ``__thread`` keyword).
|
||||
For details on this GCC feature please see https://gcc.gnu.org/onlinedocs/gcc-5.5.0/gcc/Thread-Local.html#Thread-Local.
|
||||
Storage for that kind of variables is allocated on the task's stack.
|
||||
Note that area for all such variables in the program will be allocated on the stack of
|
||||
every task in the system even if that task does not use such variables at all. For example
|
||||
ESP-IDF system tasks (like ``ipc``, ``timer`` tasks etc.) will also have that extra stack space allocated.
|
||||
So this feature should be used with care. There is a tradeoff: C11 thread local variables are quite handy
|
||||
to use in programming and can be accessed using minimal CPU instructions, but this benefit goes
|
||||
with the cost of additional stack usage for all tasks in the system.
|
||||
Due to static nature of variables allocation all tasks in the system have the same sets of C11 thread local variables.
|
||||
The ESP-IDF FreeRTOS supports thread local variables according to C11 standard, ones specified with ``__thread`` keyword. For details on this feature, please refer to the `GCC documentation <https://gcc.gnu.org/onlinedocs/gcc-5.5.0/gcc/Thread-Local.html#Thread-Local>`_.
|
||||
|
||||
Storage for that kind of variables is allocated on the task stack. Note that area for all such variables in the program is allocated on the stack of every task in the system even if that task does not use such variables at all. For example, ESP-IDF system tasks (e.g., ``ipc``, ``timer`` tasks etc.) will also have that extra stack space allocated. Thus feature should be used with care.
|
||||
|
||||
Using C11 thread local variables comes at a trade-off. One one hand, they are quite handy to use in programming and can be accessed using minimal CPU instructions. However, this benefit comes at the cost of additional stack usage for all tasks in the system. Due to static nature of variables allocation, all tasks in the system have the same sets of C11 thread local variables.
|
||||
|
||||
Reference in New Issue
Block a user