mirror of
https://github.com/espressif/esp-idf.git
synced 2026-05-19 23:45:28 +02:00
Docs: provide CN translation for three short docs of api-guides
This commit is contained in:
Cai Xin Ying
@@ -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>`_.
|
||||
Reference in New Issue
Block a user