Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 14 additions & 11 deletions docs/en/additionalfeatures/application-size-analysis.rst
Original file line number Diff line number Diff line change
@@ -1,24 +1,27 @@
ESP-IDF Application Size Analysis
===================================
=================================

The Application Size Analysis editor provides a way to analyze the static memory footprint of your application. It has two sections:
:link_to_translation:`zh_CN:[中文]`

- The **Overview** section provides a summary of the application's memory usage;
- The **Details** section includes in-depth details about components and per-symbol level memory information.
The Application Size Analysis editor helps you examine your application's static memory usage. It has two sections:

The **Details** table viewer also provides searching and sorting capabilities on various columns.
- ``Overview``: Summarizes the application's memory usage.
- ``Details``: Shows detailed component and per-symbol memory information, with search and sort features.

To launch the Application Size Analysis editor:

#. Right-click on the project.
#. Select **ESP-IDF > Application Size Analysis** menu option to launch the editor.
#. Select ``ESP-IDF: Application Size Analysis`` menu option to launch the editor.

**Application Size Analysis - Overview**

.. image:: ../../../media/sizeanalysis_overview.png
.. figure:: ../../../media/sizeanalysis_overview.png
:align: center
:alt: Application Size Analysis - Overview

**Application Size Analysis - Details**
Application Size Analysis – Overview


.. image:: ../../../media/sizeanalysis_details.png
.. figure:: ../../../media/sizeanalysis_details.png
:align: center
:alt: Application Size Analysis - Details

Application Size Analysis – Details
42 changes: 22 additions & 20 deletions docs/en/additionalfeatures/gdbstubdebugging.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,47 +2,49 @@

GDBStub Debugging
=================
You can now use the GDBStub debugging inside our Eclipse plugin to help you diagnose and debug issues on chips via Eclipse when it is in panic mode.

:link_to_translation:`zh_CN:[中文]`

You can now use the GDBStub debugging in the Eclipse plugin to diagnose and debug chip issues when the chip enters panic mode.

To enable GDBStub debugging for a project:

1. Launch the `sdkconfig` in project root by double-clicking on it which will open the configuration editor.
1. Launch the ``sdkconfig`` file in the project root by double-clicking it. This will open the configuration editor.

.. image:: ../../../media/GDBStubDebugging/sdkconfig_editor.png
.. image:: ../../../media/GDBStubDebugging/sdkconfig_editor.png

2. Expand the `Component Config` section and select `ESP System Settings`. From the settings on the right for `Panic Handler behaviour` select the `GDBStub on Panic option` from the list.
2. Expand the ``Component Config`` section and select ``ESP System Settings``. From the settings on the right for ``Panic handler behaviour`` select the ``GDBStub on panic`` option from the list.

.. image:: ../../../media/GDBStubDebugging/sdkconfig_editor_panic_behavior.png
.. image:: ../../../media/GDBStubDebugging/sdkconfig_editor_panic_behavior.png

Now you will be taken to the GDBStub debugger automatically when you connect the serial monitor and there is a panic for this example.
When you connect the serial monitor and a panic occurs in this example, the GDBStub debugger will be launched automatically.

To use the GDBStub debugging for a project:

1. Create a template `hello_world` project and add the following lines in the main C file:
1. Create a template ``hello_world`` project and add the following lines in the ``main.c`` file:

.. code-block:: c
.. code-block:: c

This is a global variable<br/>
COREDUMP_DRAM_ATTR uint8_t global_var;
// This is a global variable
COREDUMP_DRAM_ATTR uint8_t global_var;

2. Now add these two lines just above the `esp_restart()` function:
2. Now add these two lines just above the ``esp_restart()`` function:

.. code-block:: c
.. code-block:: c

global_var = 25;
assert(0);
global_var = 25;
assert(0);

The final file should be something like this:
The final file should look like the following:

.. image:: ../../../media/GDBStubDebugging/code_example.png

Build and flash the project and launch the serial monitor. On line number 45, we are signaling for a failing assert which will put the chip in panic mode and when that line reaches, you will be prompted to switch the perspective to debug mode and the chip will be halted.
Build and flash the project, then launch the serial monitor. At line 45, a failing assert is triggered, which puts the chip into panic mode. When execution reaches this line, you will be prompted to switch to the Debug perspective, and the chip will be halted.

Remember that this is a panic mode and you cannot continue the execution from here, you will have to stop and restart the chip through IDF commands or simply restart the serial monitor.
The chip is in panic mode, and execution cannot continue from this point. You must stop and restart the chip using IDF commands or by restarting the serial monitor.

.. image:: ../../../media/GDBStubDebugging/debug_panic_mode.png

You can view the registers stack trace and even view the value of variables in the stack frame.

To exit the debug session simply press the `stop` button.
You can view the registers, stack trace, and even the value of variables in the stack frame.

To exit the debug session, simply press the ``stop`` button.
42 changes: 24 additions & 18 deletions docs/en/additionalfeatures/nvspartitioneditor.rst
Original file line number Diff line number Diff line change
@@ -1,35 +1,41 @@
NVS Table Editor
================

The NVS Table Editor helps create a binary file based on key-value pairs provided in a CSV file. The resulting binary file is compatible with the NVS architecture as defined in `ESP-IDF Non Volatile Storage <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_flash.html>`_. The expected CSV format is:
:link_to_translation:`zh_CN:[中文]`

The NVS Table Editor helps create a binary file based on key-value pairs provided in a CSV file. The resulting binary file is compatible with the NVS architecture as defined in ESP-IDF `Non-Volatile Storage <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_flash.html>`_. The expected CSV format is:

.. code-block:: text

key,type,encoding,value <-- column header (must be the first line)
namespace_name,namespace,, <-- First entry must be of type "namespace"
key1,data,u8,1
key2,file,string,/path/to/file
key,type,encoding,value <-- column header (must be the first line)
namespace_name,namespace,, <-- First entry must be of type "namespace"
key1,data,u8,1
key2,file,string,/path/to/file

.. note::

.. note:: This is based on ESP-IDF `NVS Partition Generator Utility <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_partition_gen.html>`_.
This is based on ESP-IDF `NVS Partition Generator Utility <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_partition_gen.html>`_.

Steps
-----

1. Right-click on a project in the *Project Explorer*.
2. Click on the *ESP-IDF > NVS Table Editor* menu option:
1. Right-click on a project in the Project Explorer.
2. Click on the ``ESP-IDF: NVS Table Editor`` menu option.

.. image:: https://user-images.githubusercontent.com/24419842/216114697-9f231211-f5dd-431b-9432-93ecc656cfec.png
:alt: NVS Table Editor menu option

.. image:: https://user-images.githubusercontent.com/24419842/216114697-9f231211-f5dd-431b-9432-93ecc656cfec.png
:alt: NVS Table Editor menu option
3. Make desired changes to the CSV data.
4. Save changes by clicking the ``Save`` button. If everything is correct, you will see an information message at the top of the dialog:

3. Make desired changes to the CSV data.
4. Save changes by clicking the *Save* button. If everything is correct, you will see an information message at the top of the dialog:
.. image:: https://user-images.githubusercontent.com/24419842/216115906-9bb4fe55-293b-4c6b-8d22-0aa3520581ab.png
:alt: Save confirmation in NVS Table Editor

.. image:: https://user-images.githubusercontent.com/24419842/216115906-9bb4fe55-293b-4c6b-8d22-0aa3520581ab.png
:alt: Save confirmation in NVS Table Editor
5. Generate the partition binary. Choose ``Encrypt`` to encrypt the binary, and disable the ``Generate Key`` option if you want to use your own key. An information message will appear at the top of the dialog showing the result of the generated binaries. Hover over the message to view the full content if it is truncated:

5. Generate the partition binary (choose *Encrypt* to encrypt the binary, and disable the *Generate Key* option to use your own key if desired). You will see an information message at the top of the dialog about the result of the generated binaries. Hover over the message if it's too long to read fully:
.. image:: https://user-images.githubusercontent.com/24419842/216117261-9bee798a-3a9e-4be5-9466-fc9d3847834b.png
:alt: Binary generation result in NVS Table Editor

.. image:: https://user-images.githubusercontent.com/24419842/216117261-9bee798a-3a9e-4be5-9466-fc9d3847834b.png
:alt: Binary generation result in NVS Table Editor
.. note::

.. note:: If there are any errors, they will be highlighted. Hover over the error icon to read more about the error. You will also see an error message at the top of
If there are any errors, they will be highlighted. Hover over the error icon to read more about the error. An error message will also appear at the top of the dialog.
28 changes: 27 additions & 1 deletion docs/zh_CN/additionalfeatures/application-size-analysis.rst
Original file line number Diff line number Diff line change
@@ -1 +1,27 @@
.. include:: ../../en/additionalfeatures/application-size-analysis.rst
ESP-IDF 应用程序大小分析
========================

:link_to_translation:`en:[English]`

应用程序大小分析编辑器可用于分析应用的静态内存占用情况。该编辑器包含两个部分:

- ``Overview``:总结应用程序的内存使用情况。
- ``Details``:显示组件级和符号级的详细内存信息,并提供搜索和排序功能。

可参照下列步骤启动应用程序大小分析编辑器:

#. 右键单击你的项目。
#. 选择 ``ESP-IDF: Application Size Analysis`` 菜单选项以启动编辑器。

.. figure:: ../../../media/sizeanalysis_overview.png
:align: center
:alt: 应用大小分析 — 概览

应用程序大小分析 – 概览


.. figure:: ../../../media/sizeanalysis_details.png
:align: center
:alt: 应用大小分析 — 详细信息

应用程序大小分析 – 详细信息
51 changes: 50 additions & 1 deletion docs/zh_CN/additionalfeatures/gdbstubdebugging.rst
Original file line number Diff line number Diff line change
@@ -1 +1,50 @@
.. include:: ../../en/additionalfeatures/gdbstubdebugging.rst
.. _gdbstubdebugging:

GDBStub 调试
============

:link_to_translation:`en:[English]`

你可以在 Eclipse 插件中使用 GDBStub 调试功能,在芯片进入 panic 模式时诊断和调试相关问题。

可参照下列步骤为项目启用 GDBStub 调试:

1. 在项目根目录中双击 ``sdkconfig``,打开配置编辑器。

.. image:: ../../../media/GDBStubDebugging/sdkconfig_editor.png

2. 展开 ``Component Config`` 部分并选择 ``ESP System Settings``。在右侧设置中,将 ``Panic handler behaviour`` 设为列表中的 ``GDBStub on Panic`` 选项。

.. image:: ../../../media/GDBStubDebugging/sdkconfig_editor_panic_behavior.png

当连接串口监视器且此示例发生 panic 时,将自动进入 GDBStub 调试器。

参照下列步骤在项目中使用 GDBStub 调试:

1. 创建 ``hello_world`` 模板项目,并在 ``main.c`` 文件中加入以下内容:

.. code-block:: c

// 这是一个全局变量
COREDUMP_DRAM_ATTR uint8_t global_var;

2. 现在在 ``esp_restart()`` 函数的上方加入下面两行代码:

.. code-block:: c

global_var = 25;
assert(0);

最终生成的文件应如下所示:

.. image:: ../../../media/GDBStubDebugging/code_example.png

构建并烧录项目,然后启动串口监视器。在第 45 行,会触发一个失败的断言,导致芯片进入 panic 模式。当程序执行到该行时,IDE 会提示你切换到调试模式,并暂停芯片执行。

此时芯片处于 panic 模式,无法继续执行程序。必须通过 IDF 命令停止并重启芯片,或者直接重启串口监视器。

.. image:: ../../../media/GDBStubDebugging/debug_panic_mode.png

你可以查看寄存器、栈回溯以及栈帧中的变量值。

若要退出调试会话,只需点击 ``stop`` 按钮。
42 changes: 41 additions & 1 deletion docs/zh_CN/additionalfeatures/nvspartitioneditor.rst
Original file line number Diff line number Diff line change
@@ -1 +1,41 @@
.. include:: ../../en/additionalfeatures/nvspartitioneditor.rst
NVS 表格编辑器
==============

:link_to_translation:`en:[English]`

NVS 表格编辑器可根据 CSV 文件中的键值对创建二进制文件。生成的二进制文件与 ESP-IDF `非易失性存储库 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-reference/storage/nvs_flash.html>`_ 中定义的 NVS 架构兼容。CSV 格式应如下所示:

.. code-block:: text

key,type,encoding,value <-- 列标题,必须是第一行
namespace_name,namespace,, <-- 第一条目类型必须为 "namespace"
key1,data,u8,1
key2,file,string,/path/to/file

.. note::

此功能基于 ESP-IDF `NVS 分区生成程序 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-reference/storage/nvs_partition_gen.html>`_。

操作步骤
--------

1. 在资源管理器中右键单击某个项目。
2. 点击 ``ESP-IDF: NVS Table Editor`` 菜单选项。

.. image:: https://user-images.githubusercontent.com/24419842/216114697-9f231211-f5dd-431b-9432-93ecc656cfec.png
:alt: NVS 表格编辑器菜单选项

3. 按需修改 CSV 数据。
4. 点击 ``Save`` 按钮保存更改。若配置正确,则将在对话框顶部看到一条信息提示:

.. image:: https://user-images.githubusercontent.com/24419842/216115906-9bb4fe55-293b-4c6b-8d22-0aa3520581ab.png
:alt: 在 NVS 表格编辑器中的保存确认

5. 生成分区二进制文件。可选择 ``Encrypt`` 以加密该二进制文件。如需使用自定义密钥,可禁用 ``Generate Key`` 选项。文件生成后,对话框顶部会显示生成结果的信息提示。如果提示内容过长无法完全显示,可将鼠标悬停其上以查看全文:

.. image:: https://user-images.githubusercontent.com/24419842/216117261-9bee798a-3a9e-4be5-9466-fc9d3847834b.png
:alt: 在 NVS 表格编辑器中的二进制文件生成结果

.. note::

如果出现错误,将会高亮显示。将鼠标悬停在错误图标上可以查看错误详情,同时在对话框顶部也会显示错误信息。
Loading