mirror of
https://github.com/espressif/esp-idf.git
synced 2025-09-25 01:37:22 +00: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
@@ -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
|
||||
-----------------------------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user