mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
update CN translation for ulp-risc-v partition-table tips-and-quirks and idf-monitor for api-guides
This commit is contained in:
daiziyan
parent
4ab76197e9
commit
3d2d0e2247
@ -4,7 +4,6 @@ Tips and Quirks
|
||||
|
||||
This section provides collection of all tips and quirks referred to from various parts of this guide.
|
||||
|
||||
|
||||
.. _jtag-debugging-tip-breakpoints:
|
||||
|
||||
Breakpoints and watchpoints available
|
||||
@ -72,8 +71,6 @@ FreeRTOS support
|
||||
|
||||
OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS tasks as threads. Viewing them all can be done using the GDB ``i threads`` command, changing to a certain task is done with ``thread n``, with ``n`` being the number of the thread. FreeRTOS detection can be disabled in target's configuration. For more details see :ref:`jtag-debugging-tip-openocd-configure-target`.
|
||||
|
||||
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. _jtag-debugging-tip-code-flash-voltage:
|
||||
@ -87,7 +84,6 @@ OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS task
|
||||
|
||||
Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3 V flash. WROVER earlier than ESP32-WROVER-B use 1.8 V flash, while ESP32-WROVER-B and -E modules use 3.3 V flash.
|
||||
|
||||
|
||||
.. _jtag-debugging-tip-optimize-jtag-speed:
|
||||
|
||||
.. only:: not esp32
|
||||
@ -197,7 +193,7 @@ The board can be reset by entering ``mon reset`` or ``mon reset halt`` into GDB.
|
||||
Do not use JTAG pins for something else
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides {IDF_TARGET_NAME} module and JTAG adapter. {IDF_TARGET_NAME} JTAG us using the following pins:
|
||||
Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides {IDF_TARGET_NAME} module and JTAG adapter. {IDF_TARGET_NAME} JTAG is using the following pins:
|
||||
|
||||
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
|
||||
:start-after: jtag-pins
|
||||
|
||||
@ -39,15 +39,15 @@ Here is the summary printed for the "Factory app, two OTA definitions" configura
|
||||
nvs, data, nvs, 0x9000, 0x4000,
|
||||
otadata, data, ota, 0xd000, 0x2000,
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
factory, 0, 0, 0x10000, 1M,
|
||||
ota_0, 0, ota_0, 0x110000, 1M,
|
||||
ota_1, 0, ota_1, 0x210000, 1M,
|
||||
factory, app, factory, 0x10000, 1M,
|
||||
ota_0, app, ota_0, 0x110000, 1M,
|
||||
ota_1, app, ota_1, 0x210000, 1M,
|
||||
|
||||
* There are now three app partition definitions. The type of the factory app (at 0x10000) and the next two "OTA" apps are all set to "app", but their subtypes are different.
|
||||
* There is also a new "otadata" slot, which holds the data for OTA updates. The bootloader consults this data in order to know which app to execute. If "ota data" is empty, it will execute the factory app.
|
||||
|
||||
Creating Custom Tables
|
||||
----------------------
|
||||
-------------------------
|
||||
|
||||
If you choose "Custom partition table CSV" in menuconfig then you can also enter the name of a CSV file (in the project directory) to use for your partition table. The CSV file can describe any number of definitions for the table you need.
|
||||
|
||||
@ -80,7 +80,7 @@ If your app needs to store data in a format not already supported by ESP-IDF, th
|
||||
|
||||
See :cpp:type:`esp_partition_type_t` for the enum definitions for ``app`` and ``data`` partitions.
|
||||
|
||||
If writing in C++ then specifying a application-defined partition type requires casting an integer to :cpp:type:`esp_partition_type_t` in order to use it with the :ref:`partition API <api-reference-partition-table>`. For example::
|
||||
If writing in C++ then specifying a application-defined partition type requires casting an integer to :cpp:type:`esp_partition_type_t` in order to use it with the :ref:`partition API<api-reference-partition-table>`. For example::
|
||||
|
||||
static const esp_partition_type_t APP_PARTITION_TYPE_A = (esp_partition_type_t)0x40;
|
||||
|
||||
@ -99,6 +99,7 @@ See enum :cpp:type:`esp_partition_subtype_t` for the full list of subtypes defin
|
||||
|
||||
- OTA never updates the factory partition.
|
||||
- If you want to conserve flash usage in an OTA project, you can remove the factory partition and use ``ota_0`` instead.
|
||||
|
||||
- ``ota_0`` (0x10) ... ``ota_15`` (0x1F) are the OTA app slots. When :doc:`OTA <../api-reference/system/ota>` is in use, the OTA data partition configures which app slot the bootloader should boot. When using OTA, an application should have at least two OTA application slots (``ota_0`` & ``ota_1``). Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details.
|
||||
- ``test`` (0x20) is a reserved subtype for factory test procedures. It will be used as the fallback boot partition if no other valid app partition is found. It is also possible to configure the bootloader to read a GPIO input during each boot, and boot this partition if the GPIO is held low, see :ref:`bootloader_boot_from_test_firmware`.
|
||||
|
||||
@ -127,7 +128,7 @@ See enum :cpp:type:`esp_partition_subtype_t` for the full list of subtypes defin
|
||||
|
||||
* If the partition type is any application-defined value (range 0x40-0xFE), then ``subtype`` field can be any value chosen by the application (range 0x00-0xFE).
|
||||
|
||||
Note that when writing in C++, an application-defined subtype value requires casting to type :cpp:type:`esp_partition_subtype_t` in order to use it with the :ref:`partition API <api-reference-partition-table>`.
|
||||
Note that when writing in C++, an application-defined subtype value requires casting to type :cpp:type:`esp_partition_subtype_t` in order to use it with the :ref:`partition API<api-reference-partition-table>`.
|
||||
|
||||
Offset & Size
|
||||
~~~~~~~~~~~~~
|
||||
@ -145,7 +146,9 @@ Flags
|
||||
|
||||
Only one flag is currently supported, ``encrypted``. If this field is set to ``encrypted``, this partition will be encrypted if :doc:`/security/flash-encryption` is enabled.
|
||||
|
||||
(Note that ``app`` type partitions will always be encrypted, regardless of whether this flag is set or not.)
|
||||
.. note::
|
||||
|
||||
``app`` type partitions will always be encrypted, regardless of whether this flag is set or not.
|
||||
|
||||
Generating Binary Partition Table
|
||||
---------------------------------
|
||||
@ -181,7 +184,10 @@ Flashing the partition table
|
||||
|
||||
A manual flashing command is also printed as part of ``idf.py partition_table`` output.
|
||||
|
||||
Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``idf.py erase_flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents.
|
||||
.. note::
|
||||
|
||||
Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``idf.py erase_flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents.
|
||||
|
||||
|
||||
Partition Tool (parttool.py)
|
||||
----------------------------
|
||||
@ -193,8 +199,7 @@ The component `partition_table` provides a tool :component_file:`parttool.py<par
|
||||
- erasing a partition (erase_partition)
|
||||
- retrieving info such as name, offset, size and flag ("encrypted") of a given partition (get_partition_info)
|
||||
|
||||
The tool can either be imported and used from another Python script or invoked from shell script for users wanting to perform operation programmatically. This is facilitated by the tool's Python API
|
||||
and command-line interface, respectively.
|
||||
The tool can either be imported and used from another Python script or invoked from shell script for users wanting to perform operation programmatically. This is facilitated by the tool's Python API and command-line interface, respectively.
|
||||
|
||||
Python API
|
||||
~~~~~~~~~~~
|
||||
@ -236,8 +241,7 @@ The created object can now be used to perform operations on the target device:
|
||||
storage = target.get_partition_info(PARTITION_BOOT_DEFAULT)
|
||||
print(storage.size)
|
||||
|
||||
The partition to operate on is specified using `PartitionName` or `PartitionType` or PARTITION_BOOT_DEFAULT. As the name implies, these can be used to refer
|
||||
to partitions of a particular name, type-subtype combination, or the default boot partition.
|
||||
The partition to operate on is specified using `PartitionName` or `PartitionType` or PARTITION_BOOT_DEFAULT. As the name implies, these can be used to refer to partitions of a particular name, type-subtype combination, or the default boot partition.
|
||||
|
||||
More information on the Python API is available in the docstrings for the tool.
|
||||
|
||||
@ -278,5 +282,4 @@ More information can be obtained by specifying `--help` as argument:
|
||||
# Show descriptions for specific subcommand arguments
|
||||
parttool.py [subcommand] --help
|
||||
|
||||
|
||||
.. _secure boot: security/secure-boot-v1.rst
|
||||
|
||||
@ -6,50 +6,66 @@ IDF Monitor
|
||||
|
||||
The IDF monitor tool is mainly a serial terminal program which relays serial data to and from the target device's serial port. It also provides some IDF-specific features.
|
||||
|
||||
This tool can be launched from an IDF project by running ``idf.py monitor``.
|
||||
This tool can be launched from an IDF project by running ``idf.py monitor``.
|
||||
|
||||
For the legacy GNU Make system, run ``make monitor``.
|
||||
|
||||
(For the legacy GNU Make system, run ``make monitor``.)
|
||||
|
||||
Keyboard Shortcuts
|
||||
==================
|
||||
|
||||
For easy interaction with IDF Monitor, use the keyboard shortcuts given in the table.
|
||||
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Keyboard Shortcut | Action | Description |
|
||||
+===================+========================================================+======================================================================================================================================================================================================================================================+
|
||||
| Ctrl+] | Exit the program | |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Ctrl+T | Menu escape key | Press and follow it by one of the keys given below. |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| - Ctrl+T | Send the menu character itself to remote | |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| - Ctrl+] | Send the exit character itself to remote | |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| - Ctrl+P | Reset target into bootloader to pause app via RTS line | Resets the target, into bootloader via the RTS line (if connected), so that the board runs nothing. Useful when you need to wait for another device to startup. |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| - Ctrl+R | Reset target board via RTS | Resets the target board and re-starts the application via the RTS line (if connected). |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| - Ctrl+F | Build and flash the project | Pauses idf_monitor to run the project ``flash`` target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. Target ``encrypted-flash`` is run if idf_monitor was started with argument ``-E``. |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| - Ctrl+A (or A) | Build and flash the app only | Pauses idf_monitor to run the ``app-flash`` target, then resumes idf_monitor. Similar to the ``flash`` target, but only the main app is built and re-flashed. Target ``encrypted-app-flash`` is run if idf_monitor was started with argument ``-E``. |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| - Ctrl+Y | Stop/resume log output printing on screen | Discards all incoming serial data while activated. Allows to quickly pause and examine log output without quitting the monitor. |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| - Ctrl+L | Stop/resume log output saved to file | Creates a file in the project directory and the output is written to that file until this is disabled with the same keyboard shortcut (or IDF Monitor exits). |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| - Ctrl+H (or H) | Display all keyboard shortcuts | |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| - Ctrl+X (or X) | Exit the program | |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 15 25 55
|
||||
|
||||
* - Keyboard Shortcut
|
||||
- Action
|
||||
- Description
|
||||
* - Ctrl+]
|
||||
- Exit the program
|
||||
-
|
||||
* - Ctrl+T
|
||||
- Menu escape key
|
||||
- Press and follow it by one of the keys given below.
|
||||
* - * Ctrl+T
|
||||
- Send the menu character itself to remote
|
||||
-
|
||||
* - * Ctrl+]
|
||||
- Send the exit character itself to remote
|
||||
-
|
||||
* - * Ctrl+P
|
||||
- Reset target into bootloader to pause app via RTS line
|
||||
- Resets the target, into bootloader via the RTS line (if connected), so that the board runs nothing. Useful when you need to wait for another device to startup.
|
||||
* - * Ctrl+R
|
||||
- Reset target board via RTS
|
||||
- Resets the target board and re-starts the application via the RTS line (if connected).
|
||||
* - * Ctrl+F
|
||||
- Build and flash the project
|
||||
- Pauses idf_monitor to run the project ``flash`` target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. Target ``encrypted-flash`` is run if idf_monitor was started with argument ``-E``.
|
||||
* - * Ctrl+A (or A)
|
||||
- Build and flash the app only
|
||||
- Pauses idf_monitor to run the ``app-flash`` target, then resumes idf_monitor. Similar to the ``flash`` target, but only the main app is built and re-flashed. Target ``encrypted-app-flash`` is run if idf_monitor was started with argument ``-E``.
|
||||
* - * Ctrl+Y
|
||||
- Stop/resume log output printing on screen
|
||||
- Discards all incoming serial data while activated. Allows to quickly pause and examine log output without quitting the monitor.
|
||||
* - * Ctrl+L
|
||||
- Stop/resume log output saved to file
|
||||
- Creates a file in the project directory and the output is written to that file until this is disabled with the same keyboard shortcut (or IDF Monitor exits).
|
||||
* - * Ctrl+H (or H)
|
||||
- Display all keyboard shortcuts
|
||||
-
|
||||
* - * Ctrl+X (or X)
|
||||
- Exit the program
|
||||
-
|
||||
|
||||
Any keys pressed, other than ``Ctrl-]`` and ``Ctrl-T``, will be sent through the serial port.
|
||||
|
||||
|
||||
IDF-specific features
|
||||
=====================
|
||||
|
||||
|
||||
Automatic Address Decoding
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -97,9 +113,7 @@ To decode each address, IDF Monitor runs the following command in the background
|
||||
|
||||
.. note::
|
||||
|
||||
Set environment variable ``ESP_MONITOR_DECODE`` to ``0``
|
||||
or call idf_monitor.py with specific command line option: ``idf_monitor.py --disable-address-decoding``
|
||||
to disable address decoding.
|
||||
Set environment variable ``ESP_MONITOR_DECODE`` to ``0`` or call idf_monitor.py with specific command line option: ``idf_monitor.py --disable-address-decoding`` to disable address decoding.
|
||||
|
||||
Launching GDB with GDBStub
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -127,40 +141,23 @@ Restrictions on what to print can be specified as a series of ``<tag>:<log_level
|
||||
For example, ``PRINT_FILTER="tag1:W"`` matches and prints only the outputs written with ``ESP_LOGW("tag1", ...)`` or at lower verbosity level, i.e. ``ESP_LOGE("tag1", ...)``. Not specifying a ``<log_level>`` or using ``*`` defaults to Verbose level.
|
||||
|
||||
.. note::
|
||||
Use primary logging to disable at compilation the outputs you do not
|
||||
need through the :doc:`logging library<../../api-reference/system/log>`.
|
||||
Output filtering with IDF monitor is a secondary solution
|
||||
which can be useful for adjusting the filtering options without
|
||||
recompiling the application.
|
||||
Use primary logging to disable at compilation the outputs you do not need through the :doc:`logging library<../../api-reference/system/log>`. Output filtering with IDF monitor is a secondary solution which can be useful for adjusting the filtering options without recompiling the application.
|
||||
|
||||
Your app tags must not contain spaces, asterisks ``*``,
|
||||
or colons ``:`` to be compatible with the output filtering feature.
|
||||
Your app tags must not contain spaces, asterisks ``*``, or colons ``:`` to be compatible with the output filtering feature.
|
||||
|
||||
If the last line of the output in your app is not followed by a carriage return, the output filtering might get confused, i.e., the monitor starts to print the line and later finds out that the line should not have been written. This is a known issue and can be avoided by always adding a carriage return (especially when no output follows immediately afterwards).
|
||||
|
||||
Examples Of Filtering Rules:
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- ``*`` can be used to match any tags. However, the string
|
||||
``PRINT_FILTER="*:I tag1:E"`` with regards to ``tag1`` prints errors
|
||||
only, because the rule for ``tag1`` has a higher priority over the rule for ``*``.
|
||||
- The default (empty) rule is equivalent to ``*:V`` because matching every tag
|
||||
at the Verbose level or lower means matching everything.
|
||||
- ``"*:N"`` suppresses not only the outputs from logging functions, but also
|
||||
the prints made by ``printf``, etc. To avoid this, use ``*:E`` or a higher verbosity level.
|
||||
- Rules ``"tag1:V"``, ``"tag1:v"``, ``"tag1:"``, ``"tag1:*"``, and ``"tag1"``
|
||||
are equivalent.
|
||||
- Rule ``"tag1:W tag1:E"`` is equivalent to ``"tag1:E"`` because any
|
||||
consequent occurrence of the same tag name overwrites the previous one.
|
||||
- Rule ``"tag1:I tag2:W"`` only prints ``tag1`` at the Info verbosity level or
|
||||
lower and ``tag2`` at the Warning verbosity level or lower.
|
||||
- Rule ``"tag1:I tag2:W tag3:N"`` is essentially equivalent to the previous
|
||||
one because ``tag3:N`` specifies that ``tag3`` should not be printed.
|
||||
- ``tag3:N`` in the rule ``"tag1:I tag2:W tag3:N *:V"`` is more meaningful because
|
||||
without ``tag3:N`` the ``tag3`` messages could have been printed;
|
||||
the errors for ``tag1`` and ``tag2`` will be printed at the specified (or lower)
|
||||
verbosity level and everything else will be printed by default.
|
||||
|
||||
- ``*`` can be used to match any tags. However, the string ``PRINT_FILTER="*:I tag1:E"`` with regards to ``tag1`` prints errors only, because the rule for ``tag1`` has a higher priority over the rule for ``*``.
|
||||
- The default (empty) rule is equivalent to ``*:V`` because matching every tag at the Verbose level or lower means matching everything.
|
||||
- ``"*:N"`` suppresses not only the outputs from logging functions, but also the prints made by ``printf``, etc. To avoid this, use ``*:E`` or a higher verbosity level.
|
||||
- Rules ``"tag1:V"``, ``"tag1:v"``, ``"tag1:"``, ``"tag1:*"``, and ``"tag1"`` are equivalent.
|
||||
- Rule ``"tag1:W tag1:E"`` is equivalent to ``"tag1:E"`` because any consequent occurrence of the same tag name overwrites the previous one.
|
||||
- Rule ``"tag1:I tag2:W"`` only prints ``tag1`` at the Info verbosity level or lower and ``tag2`` at the Warning verbosity level or lower.
|
||||
- Rule ``"tag1:I tag2:W tag3:N"`` is essentially equivalent to the previous one because ``tag3:N`` specifies that ``tag3`` should not be printed.
|
||||
- ``tag3:N`` in the rule ``"tag1:I tag2:W tag3:N *:V"`` is more meaningful because without ``tag3:N`` the ``tag3`` messages could have been printed; the errors for ``tag1`` and ``tag2`` will be printed at the specified (or lower) verbosity level and everything else will be printed by default.
|
||||
|
||||
|
||||
A More Complex Filtering Example
|
||||
@ -197,7 +194,7 @@ Known Issues with IDF Monitor
|
||||
=============================
|
||||
|
||||
Issues Observed on Windows
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- If in the Windows environment you receive the error "winpty: command not found", fix it by running ``pacman -S winpty``.
|
||||
- Arrow keys, as well as some other keys, do not work in GDB due to Windows Console limitations.
|
||||
|
||||
@ -17,7 +17,6 @@ If you have already set up ESP-IDF with CMake build system according to the :doc
|
||||
|
||||
.. note: In earlier versions of ESP-IDF, RISC-V toolchain had a different prefix: `riscv-none-embed-gcc`.
|
||||
|
||||
|
||||
Compiling the ULP-RISC-V Code
|
||||
-----------------------------
|
||||
|
||||
|
||||
@ -35,6 +35,8 @@
|
||||
|
||||
由于 GDB 在连接 OpenOCD 时仅仅请求一次内存映射，所以可以在 TCL 配置文件中指定该命令，或者通过命令行传递给 OpenOCD。对于后者，命令行示例如下：
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
|
||||
:start-after: run-openocd-appimage-offset
|
||||
:end-before: ---
|
||||
@ -64,8 +66,8 @@ ESP-IDF 有一些针对 OpenOCD 调试功能的选项可以在编译时进行设
|
||||
|
||||
.. _jtag-debugging-tip-freertos-support:
|
||||
|
||||
支持FreeRTOS
|
||||
^^^^^^^^^^^^
|
||||
支持 FreeRTOS
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRTOS 中的任务当做线程。使用 GDB 命令 ``i threads`` 可以查看所有的线程，使用命令 ``thread n`` 可以切换到某个具体任务的堆栈，其中 ``n`` 是线程的编号。检测 FreeRTOS 的功能可以在配置目标时被禁用。更多详细信息，请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`.
|
||||
|
||||
@ -138,7 +140,7 @@ OpenOCD 有很多种配置文件（``*.cfg``），它们位于 OpenOCD 安装目
|
||||
自定义配置文件
|
||||
""""""""""""""
|
||||
|
||||
OpenOCD 的配置文件是用 TCL 语言编写的, 包含了定制和编写脚本的各种选项。这在非标准调试的场景中非常有用，更多关于 TCL 脚本的内容请参考 `OpenOCD 参考手册`_ 。
|
||||
OpenOCD 的配置文件是用 TCL 语言编写的, 包含了定制和编写脚本的各种选项。这在非标准调试的场景中非常有用，更多关于 TCL 脚本的内容请参考 `OpenOCD 参考手册`_。
|
||||
|
||||
.. _jtag-debugging-tip-openocd-config-vars:
|
||||
|
||||
@ -178,7 +180,6 @@ TCL 语言中为变量赋值的语法是:
|
||||
:start-after: openocd-target-specific-config-vars
|
||||
:end-before: ---
|
||||
|
||||
|
||||
.. _jtag-debugging-tip-reset-by-debugger:
|
||||
|
||||
复位 {IDF_TARGET_NAME}
|
||||
@ -194,14 +195,12 @@ TCL 语言中为变量赋值的语法是:
|
||||
|
||||
如果除了 {IDF_TARGET_NAME} 模组和 JTAG 适配器之外的其他硬件也连接到了 JTAG 引脚，那么 JTAG 的操作可能会受到干扰。{IDF_TARGET_NAME} JTAG 使用以下引脚：
|
||||
|
||||
|
||||
|
||||
如果用户应用程序更改了 JTAG 引脚的配置，JTAG 通信可能会失败。如果 OpenOCD 正确初始化（检测到两个 Tensilica 内核），但在程序运行期间失去了同步并报出大量 DTR/DIR 错误，则应用程序可能将 JTAG 引脚重新配置为其他功能或者用户忘记将 Vtar 连接到 JTAG 适配器。
|
||||
|
||||
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
|
||||
:start-after: jtag-pins
|
||||
:end-before: ---
|
||||
|
||||
如果用户应用程序更改了 JTAG 引脚的配置，JTAG 通信可能会失败。如果 OpenOCD 正确初始化（检测到两个 Tensilica 内核），但在程序运行期间失去了同步并报出大量 DTR/DIR 错误，则应用程序可能将 JTAG 引脚重新配置为其他功能或者用户忘记将 Vtar 连接到 JTAG 适配器。
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
下面是 GDB 在应用程序进入重新配置 MTDO/GPIO15 作为输入代码后报告的一系列错误摘录::
|
||||
@ -227,14 +226,21 @@ Kconfig 配置项 :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` 可以改变这个默认
|
||||
- 软件断点和闪存加密是不兼容的，目前 OpenOCD 尚不支持对 Flash 中的内容进行加密和解密。
|
||||
- 如果开启了安全引导功能，设置软件断点会改变被签名的程序的摘要，从而使得签名失效。这也意味着，如果设置了软件断点，系统会在下次重启时的签名验证阶段失败，导致无法启动。
|
||||
|
||||
关闭 JTAG 的软件断点功能，可以在启动 OpenOCD 时在命令行额外加一项配置参数 ``-c 'set ESP_FLASH_SIZE 0'`` 例如 ::
|
||||
|
||||
openocd -c 'set ESP_FLASH_SIZE 0' -f board/esp32-wrover-kit-3.3v.cfg
|
||||
关闭 JTAG 的软件断点功能，可以在启动 OpenOCD 时在命令行额外加一项配置参数 ``-c 'set ESP_FLASH_SIZE 0'``，请参考 :ref:`jtag-debugging-tip-openocd-config-vars`。
|
||||
|
||||
.. note::
|
||||
|
||||
同样地，当启用该选项，并且调试过程中打了软件断点，之后引导程序将无法校验通过应用程序的签名。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
JTAG 和 ESP32-WROOM-32 AT 固件兼容性问题
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
ESP32-WROOM 系列模块预装了 AT 固件。该固件将 GPIO12 至 GPIO15 管脚配置为 SPI 从属接口，使得无法使用 JTAG。
|
||||
|
||||
要想使用 JTAG，需要编译新的固件，新的固件不能使用专门用于 JTAG 通信的管脚（GPIO12 至 GPIO15），然后将固件烧录到模组中。请参考 :ref:`jtag-debugging-tip-jtag-pins-reconfigured`。
|
||||
|
||||
.. _jtag-debugging-tip-reporting-issues:
|
||||
|
||||
报告 OpenOCD / GDB 的问题
|
||||
@ -279,4 +285,4 @@ Kconfig 配置项 :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` 可以改变这个默认
|
||||
4. 请将 ``openocd_log.txt`` 和 ``gdb_log.txt`` 文件附在你的问题报告中。
|
||||
|
||||
|
||||
.. _OpenOCD 参考手册: http://openocd.org/doc/html/index.html
|
||||
.. _OpenOCD 参考手册: http://openocd.org/doc/html/index.html
|
||||
@ -5,11 +5,9 @@
|
||||
概述
|
||||
----
|
||||
|
||||
每片 {IDF_TARGET_NAME} 的 flash 可以包含多个应用程序，以及多种不同类型的数据（例如校准数据、文件系统数据、参数存储器数据等）。因此，我们需要引入分区表的概念。
|
||||
每片 {IDF_TARGET_NAME} 的 flash 可以包含多个应用程序，以及多种不同类型的数据（例如校准数据、文件系统数据、参数存储数据等）。因此，我们在 flash 的 :ref:`默认偏移地址 <CONFIG_PARTITION_TABLE_OFFSET>` 0x8000 处烧写一张分区表。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
具体来说，{IDF_TARGET_NAME} 在 flash 的 :ref:`默认偏移地址 <CONFIG_PARTITION_TABLE_OFFSET>` 0x8000 处烧写一张分区表。该分区表的长度为 0xC00 字节（最多可以保存 95 条分区表条目）。分区表数据后还保存着该表的 MD5 校验和，用于验证分区表的完整性。此外，如果芯片使能了 :doc:`安全启动 </security/secure-boot-v2>` 功能，则该分区表后还会保存签名信息。
|
||||
分区表的长度为 0xC00 字节（最多可以保存 95 条分区表条目）。分区表数据后还保存着该表的 MD5 校验和，用于验证分区表的完整性。此外，如果芯片使能了 :doc:`安全启动 </security/secure-boot-v2>` 功能，则该分区表后还会保存签名信息。
|
||||
|
||||
分区表中的每个条目都包括以下几个部分：Name（标签）、Type（app、data 等）、SubType 以及在 flash 中的偏移量（分区的加载地址）。
|
||||
|
||||
@ -23,8 +21,7 @@
|
||||
内置分区表
|
||||
------------
|
||||
|
||||
以下是 "Single factory app, no OTA" 选项的分区表信息摘要：
|
||||
|
||||
以下是 "Single factory app, no OTA" 选项的分区表信息摘要::
|
||||
|
||||
# ESP-IDF Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
@ -32,19 +29,19 @@
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
factory, app, factory, 0x10000, 1M,
|
||||
|
||||
- flash 的 0x10000 (64KB) 偏移地址处存放一个标记为 "factory" 的二进制应用程序，且启动加载器将默认加载这个应用程序。
|
||||
- flash 的 0x10000 (64 KB) 偏移地址处存放一个标记为 "factory" 的二进制应用程序，且启动加载器将默认加载这个应用程序。
|
||||
- 分区表中还定义了两个数据区域，分别用于存储 NVS 库专用分区和 PHY 初始化数据。
|
||||
|
||||
以下是 "Factory app, two OTA definitions" 选项的分区表信息摘要：
|
||||
以下是 "Factory app, two OTA definitions" 选项的分区表信息摘要::
|
||||
|
||||
# ESP-IDF Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x4000,
|
||||
otadata, data, ota, 0xd000, 0x2000,
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
factory, app, factory, 0x10000, 1M,
|
||||
ota_0, app, ota_0, 0x110000, 1M,
|
||||
ota_1, app, ota_1, 0x210000, 1M,
|
||||
# ESP-IDF Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x4000,
|
||||
otadata, data, ota, 0xd000, 0x2000,
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
factory, app, factory, 0x10000, 1M,
|
||||
ota_0, app, ota_0, 0x110000, 1M,
|
||||
ota_1, app, ota_1, 0x210000, 1M,
|
||||
|
||||
- 分区表中定义了三个应用程序分区，这三个分区的类型都被设置为 “app”，但具体 app 类型不同。其中，位于 0x10000 偏移地址处的为出厂应用程序（factory），其余两个为 OTA 应用程序（ota_0，ota_1）。
|
||||
- 新增了一个名为 “otadata” 的数据分区，用于保存 OTA 升级时需要的数据。启动加载器会查询该分区的数据，以判断该从哪个 OTA 应用程序分区加载程序。如果 “otadata” 分区为空，则会执行出厂程序。
|
||||
@ -54,7 +51,7 @@
|
||||
|
||||
如果在 ``menuconfig`` 中选择了 “Custom partition table CSV”，则还需要输入该分区表的 CSV 文件在项目中的路径。CSV 文件可以根据需要，描述任意数量的分区信息。
|
||||
|
||||
CSV 文件的格式与上面摘要中打印的格式相同，但是在 CSV 文件中并非所有字段都是必需的。例如下面是一个自定义的 OTA 分区表的 CSV 文件：
|
||||
CSV 文件的格式与上面摘要中打印的格式相同，但是在 CSV 文件中并非所有字段都是必需的。例如下面是一个自定义的 OTA 分区表的 CSV 文件::
|
||||
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x4000
|
||||
@ -77,47 +74,61 @@ Name 字段可以是任何有意义的名称，但不能超过 16 个字符（
|
||||
Type 字段
|
||||
~~~~~~~~~
|
||||
|
||||
Type 字段可以指定为 app (0) 或者 data (1)，也可以直接使用数字 0-254（或者十六进制 0x00-0xFE）。注意，0x00-0x3F 不得使用（预留给 esp-idf 的核心功能）。
|
||||
Type 字段可以指定为 app (0x00) 或者 data (0x01)，也可以直接使用数字 0-254（或者十六进制 0x00-0xFE）。注意，0x00-0x3F 不得使用（预留给 esp-idf 的核心功能）。
|
||||
|
||||
如果您的应用程序需要保存数据，请在 0x40-0xFE 内添加一个自定义分区类型。
|
||||
如果您的应用程序需要以 ESP-IDF 尚未支持的格式存储数据，请在 0x40-0xFE 内添加一个自定义分区类型。
|
||||
|
||||
注意，启动加载器将忽略 app (0) 和 data (1) 以外的其他分区类型。
|
||||
参考 :cpp:type:`esp_partition_type_t` 关于 ``app``和 ``data`` 分区的枚举定义。
|
||||
|
||||
如果用 C++ 编写，那么指定一个应用程序定义的分区类型，需要在 :cpp:type:`esp_partition_type_t` 中使用整数，从而与 :ref:`分区 API<api-reference-partition-table>` 一起使用。例如::
|
||||
|
||||
static const esp_partition_type_t APP_PARTITION_TYPE_A = (esp_partition_type_t)0x40;
|
||||
|
||||
注意，启动加载器将忽略 ``app`` (0x00) 和 ``data`` (0x01) 以外的其他分区类型。
|
||||
|
||||
SubType 字段
|
||||
~~~~~~~~~~~~
|
||||
|
||||
SubType 字段长度为 8 bit，内容与具体 Type 有关。目前，esp-idf 仅仅规定了 “app” 和 “data” 两种子类型。
|
||||
SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，esp-idf 仅仅规定了 “app” 和 “data” 两种分区类型的子类型含义。
|
||||
|
||||
* 当 Type 定义为 ``app`` 时，SubType 字段可以指定为 factory (0)，ota_0 (0x10) ... ota_15 (0x1F) 或者 test (0x20)。
|
||||
参考 :cpp:type:`esp_partition_subtype_t`，以了解 ESP-IDF 定义的全部子类型列表，包括：
|
||||
|
||||
- factory (0) 是默认的 app 分区。启动加载器将默认加载该应用程序。但如果存在类型为 data/ota 分区，则启动加载器将加载 data/ota 分区中的数据，进而判断启动哪个 OTA 镜像文件。
|
||||
* 当 Type 定义为 ``app`` 时，SubType 字段可以指定为 ``factory`` (0x00)、 ``ota_0`` (0x10) … ``ota_15`` (0x1F) 或者 ``test`` (0x20)。
|
||||
|
||||
- ``factory`` (0x00) 是默认的 app 分区。启动加载器将默认加载该应用程序。但如果存在类型为 data/ota 分区，则启动加载器将加载 data/ota 分区中的数据，进而判断启动哪个 OTA 镜像文件。
|
||||
|
||||
- OTA 升级永远都不会更新 factory 分区中的内容。
|
||||
- 如果您希望在 OTA 项目中预留更多 flash，可以删除 factory 分区，转而使用 ota_0 分区。
|
||||
|
||||
- ota_0 (0x10) ... ota_15 (0x1F) 为 OTA 应用程序分区，启动加载器将根据 OTA 数据分区中的数据来决定加载哪个 OTA 应用程序分区中的程序。在使用 OTA 功能时，应用程序应至少拥有 2 个 OTA 应用程序分区（ota_0 和 ota_1）。更多详细信息，请参考 :doc:`OTA 文档 </api-reference/system/ota>` 。
|
||||
- test (0x2) 为预留 app 子类型，用于工厂测试流程。如果没有其他有效 app 分区，test 将作为备选启动分区使用。也可以在每次启动时配置启动加载器读取 GPIO，如果 GPIO 被拉低则启动该分区。详细信息请查阅 :ref:`bootloader_boot_from_test_firmware`。
|
||||
- ota_0 (0x10) … ota_15 (0x1F) 为 OTA 应用程序分区，启动加载器将根据 OTA 数据分区中的数据来决定加载哪个 OTA 应用程序分区中的程序。在使用 OTA 功能时，应用程序应至少拥有 2 个 OTA 应用程序分区（``ota_0`` 和 ``ota_1``）。更多详细信息，请参考 :doc:`OTA 文档 </api-reference/system/ota>` 。
|
||||
- ``test`` (0x20) 为预留的子类型，用于工厂测试流程。如果没有其他有效 app 分区，test 将作为备选启动分区使用。也可以配置启动加载器在每次启动时读取 GPIO，如果 GPIO 被拉低则启动该分区。详细信息请查阅 :ref:`bootloader_boot_from_test_firmware`。
|
||||
|
||||
* 当 Type 定义为 ``data`` 时，SubType 字段可以指定为 ota (0)，phy (1)，nvs (2) 或者 nvs_keys (4)。
|
||||
* 当 Type 定义为 ``data`` 时，SubType 字段可以指定为 ``ota`` (0x00)、``phy`` (0x01)、``nvs`` (0x02)、``nvs_keys`` (0x04) 或者其他组件特定的子类型（请参考 :cpp:type:`子类型枚举 <esp_partition_subtype_t>`).
|
||||
|
||||
- ota (0) 即 :ref:`OTA 数据分区 <ota_data_partition>` ，用于存储当前所选的 OTA 应用程序的信息。这个分区的大小需要设定为 0x2000。更多详细信息，请参考 :doc:`OTA 文档 <../api-reference/system/ota>` 。
|
||||
- phy (1) 分区用于存放 PHY 初始化数据，从而保证可以为每个设备单独配置 PHY，而非必须采用固件中的统一 PHY 初始化数据。
|
||||
- ``ota`` (0) 即 :ref:`OTA 数据分区 <ota_data_partition>` ，用于存储当前所选的 OTA 应用程序的信息。这个分区的大小需要设定为 0x2000。更多详细信息，请参考 :doc:`OTA 文档 <../api-reference/system/ota>` 。
|
||||
- ``phy`` (1) 分区用于存放 PHY 初始化数据，从而保证可以为每个设备单独配置 PHY，而非必须采用固件中的统一 PHY 初始化数据。
|
||||
|
||||
- 默认配置下，phy 分区并不启用，而是直接将 phy 初始化数据编译至应用程序中，从而节省分区表空间（直接将此分区删掉）。
|
||||
- 如果需要从此分区加载 phy 初始化数据，请打开项目配置菜单（``idf.py menuconfig``），并且使能 :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` 选项。此时，您还需要手动将 phy 初始化数据烧至设备 flash（esp-idf 编译系统并不会自动完成该操作）。
|
||||
- nvs (2) 是专门给 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 使用的分区。
|
||||
- ``nvs`` (2) 是专门给 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 使用的分区。
|
||||
|
||||
- 用于存储每台设备的 PHY 校准数据（注意，并不是 PHY 初始化数据）。
|
||||
- 用于存储 Wi-Fi 数据（如果使用了 :cpp:func:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <esp_wifi_set_storage>` 初始化函数）。
|
||||
- 用于存储 Wi-Fi 数据（如果使用了 :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <../api-reference/network/esp_wifi>` 初始化函数）。
|
||||
- NVS API 还可以用于其他应用程序数据。
|
||||
- 强烈建议您应为 NVS 分区分配至少 0x3000 字节空间。
|
||||
- 如果使用 NVS API 存储大量数据，请增加 NVS 分区的大小（默认是 0x6000 字节）。
|
||||
- nvs_keys (4) 是 NVS 秘钥分区。详细信息，请参考 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 文档。
|
||||
- ``nvs_keys`` (4) 是 NVS 秘钥分区。详细信息，请参考 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 文档。
|
||||
|
||||
- 用于存储加密密钥（如果启用了 `NVS 加密` 功能）。
|
||||
- 此分区应至少设定为 4096 字节。
|
||||
|
||||
其它数据子类型已预留给 esp-idf 未来使用。
|
||||
- ESP-IDF 还支持其它预定义的子类型用于数据存储，包括 :doc:`FAT 文件系统 </api-reference/storage/fatfs>` (:cpp:enumerator:`ESP_PARTITION_SUBTYPE_DATA_FAT`), :doc:`SPIFFS </api-reference/storage/spiffs>` (:cpp:enumerator:`ESP_PARTITION_SUBTYPE_DATA_SPIFFS`) 等。
|
||||
|
||||
其它数据子类型已预留给 esp-idf 未来使用。
|
||||
|
||||
* 如果分区类型是由应用程序定义的任意值（0x40-0xFE），那么 ``subtype`` 字段可以是由应用程序选择的任何值（0x00-0xFE）。
|
||||
|
||||
请注意如果用 C++ 编写，应用程序定义的子类型值需要转换为 :cpp:type:`esp_partition_type_t`，从而与 :ref:`分区 API<api-reference-partition-table>` 一起使用。
|
||||
|
||||
Offset 和 Size 字段
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
@ -133,7 +144,7 @@ app 分区的大小和偏移地址可以采用十进制数、以 0x 为前缀的
|
||||
Flags 字段
|
||||
~~~~~~~~~~
|
||||
|
||||
当前仅支持 ``encrypted`` 标记。如果 Flags 字段设置为 ``encrypted``，且已启用 :doc:`Flash Encryption </security/flash-encryption>` 功能，则该分区将会被加密。
|
||||
当前仅支持 ``encrypted`` 标记。如果 Flags 字段设置为 ``encrypted``，且已启用 :doc:`Flash 加密 </security/flash-encryption>` 功能，则该分区将会被加密。
|
||||
|
||||
.. note::
|
||||
|
||||
@ -142,19 +153,19 @@ Flags 字段
|
||||
生成二进制分区表
|
||||
----------------
|
||||
|
||||
烧写到 ESP32 中的分区表采用二进制格式，而不是 CSV 文件本身。此时，:component_file:`partition_table/gen_esp32part.py` 工具可以实现 CSV 和二进制文件之间的转换。
|
||||
烧写到 {IDF_TARGET_NAME} 中的分区表采用二进制格式，而不是 CSV 文件本身。此时，:component_file:`partition_table/gen_esp32part.py` 工具可以实现 CSV 和二进制文件之间的转换。
|
||||
|
||||
如果您在项目配置菜单（``idf.py menuconfig``）中设置了分区表 CSV 文件的名称，然后构建项目或执行 ``idf.py partition_table``。这时，转换将在编译过程中自动完成。
|
||||
|
||||
手动将 CSV 文件转换为二进制文件:
|
||||
手动将 CSV 文件转换为二进制文件::
|
||||
|
||||
python gen_esp32part.py input_partitions.csv binary_partitions.bin
|
||||
|
||||
手动将二进制文件转换为 CSV 文件:
|
||||
手动将二进制文件转换为 CSV 文件::
|
||||
|
||||
python gen_esp32part.py binary_partitions.bin input_partitions.csv
|
||||
|
||||
在标准输出（stdout）上，打印二进制分区表的内容（在运行 ``idf.py partition_table`` 时，我们正是这样打印上文展示的信息摘要的）:
|
||||
在标准输出（stdout）上，打印二进制分区表的内容（运行 ``idf.py partition_table`` 时展示的信息摘要也是这样生成的）::
|
||||
|
||||
python gen_esp32part.py binary_partitions.bin
|
||||
|
||||
@ -163,7 +174,7 @@ MD5 校验和
|
||||
|
||||
二进制格式的分区表中含有一个 MD5 校验和。这个 MD5 校验和是根据分区表内容计算的，可在设备启动阶段，用于验证分区表的完整性。
|
||||
|
||||
注意，一些版本较老的启动加载器无法支持 MD5 校验，如果发现 MD5 校验和则将报错 ``invalid magic number 0xebeb``。此时，用户可通过 ``gen_esp32part.py`` 的 ``--disable-md5sum`` 选项或者 ``menuconfig`` 的 :ref:`CONFIG_PARTITION_TABLE_MD5` 选项关闭 MD5 校验。
|
||||
注意，一些版本较老的启动加载器无法支持 MD5 校验，如果发现 MD5 校验和则将报错 ``invalid magic number 0xebeb``。此时，用户可通过 ``gen_esp32part.py`` 的 ``--disable-md5sum`` 选项或者 :ref:`CONFIG_PARTITION_TABLE_MD5` 选项关闭 MD5 校验。
|
||||
|
||||
烧写分区表
|
||||
----------
|
||||
@ -175,7 +186,7 @@ MD5 校验和
|
||||
|
||||
.. note::
|
||||
|
||||
分区表的更新并不会擦除根据之前分区表存储的数据。此时，您可以使用 ``idf.py erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。
|
||||
分区表的更新并不会擦除根据旧分区表存储的数据。此时，您可以使用 ``idf.py erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。
|
||||
|
||||
|
||||
分区工具 (parttool.py)
|
||||
@ -186,7 +197,7 @@ MD5 校验和
|
||||
- 读取分区，将内容存储到文件中 (read_partition)
|
||||
- 将文件中的内容写至分区 (write_partition)
|
||||
- 擦除分区 (erase_partition)
|
||||
- 检索特定分区的偏移和大小等信息 (get_partition_info)
|
||||
- 检索特定分区的名称、偏移、大小和 flag（“加密”） 标志等信息 (get_partition_info)
|
||||
|
||||
用户若想通过编程方式完成相关操作，可从另一个 Python 脚本导入并使用分区工具，或者从 Shell 脚本调用分区工具。前者可使用工具的 Python API，后者可使用命令行界面。
|
||||
|
||||
@ -271,6 +282,4 @@ Python API
|
||||
# 显示子命令的描述
|
||||
parttool.py [subcommand] --help
|
||||
|
||||
|
||||
.. _secure boot: security/secure-boot-v1.rst
|
||||
|
||||
|
||||
@ -11,36 +11,63 @@ IDF 监视器是一个串行终端程序，用于收发目标设备串口的串
|
||||
- **若使用 CMake 编译系统，则请调用**：``idf.py monitor``
|
||||
- **若使用传统 GNU Make 编译系统，请调用**：``make monitor``
|
||||
|
||||
|
||||
|
||||
操作快捷键
|
||||
==================
|
||||
|
||||
为了方便与 IDF 监视器进行交互，请使用表中给出的快捷键。
|
||||
|
||||
=================== ======================================================================== =======================================================================================================================================================================================
|
||||
快捷键 操作 描述
|
||||
=================== ======================================================================== =======================================================================================================================================================================================
|
||||
Ctrl+] 退出监视器程序
|
||||
Ctrl+T 菜单退出键 按下如下给出的任意键，并按指示操作。
|
||||
- Ctrl+T 将菜单字符发送至远程
|
||||
- Ctrl+] 将 exit 字符发送至远程
|
||||
- Ctrl+P 重置目标设备，进入 Bootloader，通过 RTS 线暂停应用程序 重置目标设备，通过 RTS 线（如已连接）进入 Bootloader，此时开发板不运行任何程序。等待其他设备启动时可以使用此操作。
|
||||
- Ctrl+R 通过 RTS 线重置目标设备 重置设备，并通过 RTS 线（如已连接）重新启动应用程序。
|
||||
- Ctrl+F 编译并烧录此项目 暂停 idf_monitor，运行 ``idf.py flash`` 目标，然后恢复 idf_monitor。任何改动的源文件都会被重新编译，然后重新烧录。
|
||||
- Ctrl+A (A) 仅编译及烧录应用程序 暂停 idf_monitor，运行 ``app-flash`` 目标，然后恢复 idf_monitor。 这与 ``flash`` 类似，但只有主应用程序被编译并被重新烧录。
|
||||
- Ctrl+Y 停止/恢复日志输出在屏幕上打印 激活时，会丢弃所有传入的串行数据。允许在不退出监视器的情况下快速暂停和检查日志输出。
|
||||
- Ctrl+L 停止/恢复向文件写入日志输出 在工程目录下创建一个文件，用于写入日志输出。可使用快捷键停止/恢复该功能（退出 IDF 监视器也会终止该功能）
|
||||
- Ctrl+H (H) 显示所有快捷键
|
||||
=================== ======================================================================== =======================================================================================================================================================================================
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 15 25 55
|
||||
|
||||
* - 快捷键
|
||||
- 操作
|
||||
- 描述
|
||||
* - Ctrl+]
|
||||
- 退出监视器程序
|
||||
-
|
||||
* - Ctrl+T
|
||||
- 菜单退出键
|
||||
- 按下如下给出的任意键之一，并按指示操作。
|
||||
* - * Ctrl+T
|
||||
- 将菜单字符发送至远程
|
||||
-
|
||||
* - * Ctrl+]
|
||||
- 将 exit 字符发送至远程
|
||||
-
|
||||
* - * Ctrl+P
|
||||
- 重置目标设备，进入 Bootloader，通过 RTS 线暂停应用程序
|
||||
- 重置目标设备，通过 RTS 线（如已连接）进入 Bootloader，此时开发板不运行任何程序。等待其他设备启动时可以使用此操作。
|
||||
* - * Ctrl+R
|
||||
- 通过 RTS 线重置目标设备
|
||||
- 重置设备，并通过 RTS 线（如已连接）重新启动应用程序。
|
||||
* - * Ctrl+F
|
||||
- 编译并烧录此项目
|
||||
- 暂停 idf_monitor，运行 ``flash`` 目标，然后恢复 idf_monitor。任何改动的源文件都会被重新编译，然后重新烧录。如果 idf_monitor 是以参数 ``-E`` 启动的，则会运行目标 ``encrypted-flash``。
|
||||
* - * Ctrl+A (或者 A)
|
||||
- 仅编译及烧录应用程序
|
||||
- 暂停 idf_monitor，运行 ``app-flash`` 目标，然后恢复 idf_monitor。 这与 ``flash`` 类似，但只有主应用程序被编译并被重新烧录。如果 idf_monitor 是以参数 ``-E`` 启动的，则会运行目标 ``encrypted-flash``。
|
||||
* - * Ctrl+Y
|
||||
- 停止/恢复在屏幕上打印日志输出
|
||||
- 激活时，会丢弃所有传入的串行数据。允许在不退出监视器的情况下快速暂停和检查日志输出。
|
||||
* - * Ctrl+L
|
||||
- 停止/恢复向文件写入日志输出
|
||||
- 在工程目录下创建一个文件，用于写入日志输出。可使用快捷键停止/恢复该功能（退出 IDF 监视器也会终止该功能）
|
||||
* - * Ctrl+H (或者 H)
|
||||
- 显示所有快捷键
|
||||
-
|
||||
* - * Ctrl+X (或者 X)
|
||||
- 退出监视器程序
|
||||
-
|
||||
|
||||
除了 ``Ctrl-]`` 和 ``Ctrl-T``，其他快捷键信号会通过串口发送到目标设备。
|
||||
|
||||
|
||||
兼具 IDF 特性
|
||||
=====================
|
||||
|
||||
自动解码地址
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
ESP-IDF 输出形式为 ``0x4_______`` 的十六进制代码地址后，IDF 监视器将使用 addr2line_ 查找该地址在源代码中的位置和对应的函数名。
|
||||
|
||||
@ -84,6 +111,9 @@ IDF 监视器在后台运行以下命令，解码各地址::
|
||||
|
||||
xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
|
||||
|
||||
.. note::
|
||||
|
||||
将环境变量 ``ESP_MONITOR_DECODE`` 设置为 ``0`` 或者调用 idf_monitor.py 的特定命令行选项：``idf_monitor.py --disable-address-decoding`` 来禁止地址解码。
|
||||
|
||||
配置 GDBStub 以启用 GDB
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -104,11 +134,11 @@ IDF 监控器在后台运行如下命令::
|
||||
输出筛选
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
IDF 监视器有两种启用方式：运行 ``idf.py monitor PRINT_FILTER=""`` （适用于 CMake） 或者 ``make monitor PRINT_FILTER=""`` （适用于传统 GNU Make），其中，``--print-filter`` 是输出筛选的参数。参数默认值为空字符串，可打印任何内容。
|
||||
可以调用 ``idf.py monitor --print-filter="xyz"`` 启动 IDF 监视器，其中，``--print-filter`` 是输出筛选的参数。参数默认值为空字符串，可打印任何内容。
|
||||
|
||||
若需对打印内容设置限制，可指定 ``<tag>:<log_level>`` 等选项，其中 ``<tag>`` 是标签字符串，``<log_level>`` 是 ``{N, E, W, I, D, V, *}`` 集合中的一个字母，指的是 :doc:`日志 <../../api-reference/system/log>` 级别。
|
||||
|
||||
例如，``PRINT_FILTER="tag1:W"`` 只匹配并打印 ``ESP_LOGW("tag1", ...)`` 所写的输出，或者写在较低冗余级别的输出，即 ``ESP_LOGE("tag1", ...)``。请勿指定 ``<log_level>`` 或使用冗余级别默认值 ``*``。
|
||||
例如，``PRINT_FILTER="tag1:W"`` 只匹配并打印 ``ESP_LOGW("tag1", ...)`` 所写的输出，或者写在较低日志详细度级别的输出，即 ``ESP_LOGE("tag1", ...)``。请勿指定 ``<log_level>`` 或使用详细级别默认值 ``*``。
|
||||
|
||||
.. note::
|
||||
编译时，可以使用主日志在 :doc:`日志库 <../../api-reference/system/log>` 中禁用不需要的输出。也可以使用 IDF 监视器筛选输出来调整筛选设置，且无需重新编译应用程序。
|
||||
@ -118,16 +148,16 @@ IDF 监视器有两种启用方式：运行 ``idf.py monitor PRINT_FILTER=""``
|
||||
如果应用程序输出的最后一行后面没有回车，可能会影响输出筛选功能，即，监视器开始打印该行，但后来发现该行不应该被写入。这是一个已知问题，可以通过添加回车来避免此问题（特别是在没有输出紧跟其后的情况下）。
|
||||
|
||||
筛选规则示例
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
- ``*`` 可用于匹配任何类型标签。但 ``PRINT_FILTER="*:I tag1:E"`` 打印关于 ``tag1`` 的输出时会报错，这是因为 ``tag1`` 规则比 ``*`` 规则的优先级高。
|
||||
- 默认规则（空）等价于 ``*:V``，因为在冗余级别或更低级别匹配任意标签即意味匹配所有内容。
|
||||
- 默认规则（空）等价于 ``*:V``，因为在详细级别或更低级别匹配任意标签即意味匹配所有内容。
|
||||
- ``"*:N"`` 不仅抑制了日志功能的输出，也抑制了 ``printf`` 的打印输出。为了避免这一问题，请使用 ``*:E`` 或更高的冗余级别。
|
||||
- 规则 ``"tag1:V"``、``"tag1:v"``、``"tag1:"``、``"tag1:*"`` 和 ``"tag1"`` 等同。
|
||||
- 规则 ``"tag1:W tag1:E"`` 等同于 ``"tag1:E"``，这是因为后续出现的具有相同名称的标签会覆盖掉前一个标签。
|
||||
- 规则 ``"tag1:I tag2:W"`` 仅在 Info 冗余级别或更低级别打印 ``tag1``，在 Warning 冗余级别或更低级别打印 ``tag2``。
|
||||
- 规则 ``"tag1:I tag2:W"`` 仅在 Info 详细度级别或更低级别打印 ``tag1``，在 Warning 详细度级别或更低级别打印 ``tag2``。
|
||||
- 规则 ``"tag1:I tag2:W tag3:N"`` 在本质上等同于上一规则，这是因为 ``tag3:N`` 指定 ``tag3`` 不打印。
|
||||
- ``tag3:N`` 在规则 ``"tag1:I tag2:W tag3:N *:V"`` 中更有意义，这是因为如果没有 ``tag3:N``，``tag3`` 信息就可能打印出来了；``tag1`` 和 ``tag2`` 错误信息会打印在指定的冗余级别（或更低级别），并默认打印所有内容。
|
||||
- ``tag3:N`` 在规则 ``"tag1:I tag2:W tag3:N *:V"`` 中更有意义，这是因为如果没有 ``tag3:N``，``tag3`` 信息就可能打印出来了；``tag1`` 和 ``tag2`` 错误信息会打印在指定的详细度级别（或更低级别），并默认打印所有内容。
|
||||
|
||||
|
||||
高级筛选规则示例
|
||||
|
||||
@ -6,12 +6,12 @@ ULP-RISC-V 协处理器编程
|
||||
:maxdepth: 1
|
||||
|
||||
|
||||
ULP-RISC-V 协处理器是 ULP 的一种变体，用于 ESP32-S2。与 ULP 类似，ULP-RISC-V 协处理器可以在主处理器处于低功耗模式时执行传感器读数等任务。ULP-RISC-V 与 ULP-FSM 的主要区别在于可以使用标准 GNU 工具、以 C 语言进行编程。ULP-RISC-V 可以访问 RTC_SLOW_MEM 内存区域及 RTC_CNTL、RTC_IO、SARADC 等外设寄存器。RISC-V 处理器是一种 32 位定点处理器，指令集基于 RV32IMC，包括硬件乘除法和压缩指令。
|
||||
ULP-RISC-V 协处理器是 ULP 的一种变体，用于 ESP32-S2。与 ULP 类似，ULP-RISC-V 协处理器可以在主处理器处于低功耗模式时执行传感器读数等任务。与 ULP-FSM 的主要区别在于，ULP-RISC-V 可以使用标准 GNU 工具、以 C 语言进行编程。ULP-RISC-V 可以访问 RTC_SLOW_MEM 内存区域及 RTC_CNTL、RTC_IO、SARADC 等外设的寄存器。RISC-V 处理器是一种 32 位定点处理器，指令集基于 RV32IMC，包括硬件乘除法和压缩指令。
|
||||
|
||||
安装 ULP-RISC-V 工具链
|
||||
-----------------------------------
|
||||
|
||||
ULP-RISC-V 协处理器代码以 C 语言编写（也可能是汇编语言），使用基于GCC的 RISC-V 工具链进行编译。
|
||||
ULP-RISC-V 协处理器代码以 C 语言编写（也可能是汇编语言），使用基于 GCC 的 RISC-V 工具链进行编译。
|
||||
|
||||
如果你已依照 :doc:`快速入门指南 <../../get-started/index>` 中的介绍安装好了 ESP-IDF 及其 CMake 构建系统，那么 ULP-RISC-V 工具链已经被默认安装到了你的开发环境中。
|
||||
|
||||
@ -55,14 +55,14 @@ ULP-RISC-V 协处理器代码以 C 语言编写（也可能是汇编语言），
|
||||
|
||||
5. **将 ELF 文件中的内容转储为二进制文件** (``ulp_app_name.bin``)，以便嵌入到应用程序中。
|
||||
|
||||
6. 使用 ``riscv-none-embed-nm`` 在 ELF 文件中 **生成全局符号列表** (``ulp_app_name.sym``)。
|
||||
6. 使用 ``riscv32-esp-elf-nm`` 在 ELF 文件中 **生成全局符号列表** (``ulp_app_name.sym``)。
|
||||
|
||||
7. **创建 LD 导出脚本和头文件** （``ulp_app_name.ld`` 和 ``ulp_app_name.h``），包含来自 ``ulp_app_name.sym`` 的符号。此步骤可借助 ``esp32ulp_mapgen.py`` 工具来完成。
|
||||
|
||||
8. **将生成的二进制文件添加到要嵌入应用程序的二进制文件列表中。**
|
||||
|
||||
访问 ULP-RISC-V 程序变量
|
||||
------------------------------------------
|
||||
----------------------------
|
||||
|
||||
在 ULP-RISC-V 程序中定义的全局符号也可以在主程序中使用。
|
||||
|
||||
@ -140,7 +140,7 @@ ULP-RISC-V 协处理器由定时器启动，调用 :cpp:func:`ulp_riscv_run` 即
|
||||
|
||||
此应用程序可以调用 :cpp:func:`ulp_set_wakeup_period` 函数来设置 ULP 定时器周期值 (RTC_CNTL_ULP_CP_TIMER_1_REG)。
|
||||
|
||||
一旦定时器为所选的 ``RTC_CNTL_ULP_CP_TIMER_1_REG`` 寄存器的 Tick 事件计数，ULP 协处理器就会启动，并调用 :cpp:func:`ulp_riscv_run` 的入口点开始运行程序。
|
||||
一旦定时器数到 ``RTC_CNTL_ULP_CP_TIMER_1_REG`` 寄存器中设置的 Tick 数，ULP 协处理器就会启动，并调用 :cpp:func:`ulp_riscv_run` 的入口点开始运行程序。
|
||||
|
||||
程序保持运行，直至 ``RTC_CNTL_COCPU_CTRL_REG`` 寄存器中的 ``RTC_CNTL_COCPU_DONE`` 字段被置位或因非法处理器状态出现陷阱。一旦程序停止，ULP 协处理器会关闭电源，定时器再次启动。
|
||||
|
||||
|
||||
@ -34,6 +34,9 @@ SPI Flash API 参考
|
||||
.. include-build-file:: inc/esp_flash.inc
|
||||
.. include-build-file:: inc/spi_flash_types.inc
|
||||
|
||||
|
||||
.. _api-reference-partition-table:
|
||||
|
||||
分区表 API 参考
|
||||
-------------------------------
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user