Skip to content

Commit 4e0c5d3

Browse files
shenmengjingespressif-bot
shenmengjing
authored and
espressif-bot
committed
docs: Provide translation for ecdsa.rst and qemu.rst
1 parent 10c22e8 commit 4e0c5d3

File tree

10 files changed

+228
-7
lines changed

10 files changed

+228
-7
lines changed

‎docs/en/api-guides/tools/qemu.rst

+6-4
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
QEMU Emulator
22
=============
33

4-
Espressif maintains a `fork <https://github.com/espressif/qemu>`_ of the QEMU emulator with support for {IDF_TARGET_NAME}. This fork implements emulation of the CPU, memory, and several peripherals of {IDF_TARGET_NAME}. For more information about QEMU for {IDF_TARGET_NAME}, see the `documentation <https://github.com/espressif/esp-toolchain-docs/blob/main/qemu/README.md>`_.
4+
:link_to_translation:`zh_CN:[中文]`
55

6-
:doc:`idf.py<idf-py>` allows for running and debugging applications in QEMU. This is a convenient way to test applications without having to flash them to real hardware.
6+
Espressif maintains a `fork <https://github.com/espressif/qemu>`_ of the QEMU emulator with support for {IDF_TARGET_NAME}. This fork implements emulation of the CPU, memory, and several peripherals of {IDF_TARGET_NAME}. For more information about QEMU for {IDF_TARGET_NAME}, see the `QEMU README documentation <https://github.com/espressif/esp-toolchain-docs/blob/main/qemu/README.md>`_.
7+
8+
:doc:`idf.py <idf-py>` allows for running and debugging applications in QEMU. This is a convenient way to test applications without having to flash them to real hardware.
79

810
Prerequisites
911
-------------
1012

11-
To use QEMU with ``idf.py`` you first need to install the above-mentioned fork of QEMU. ESP-IDF provides pre-built binaries for x86_64 and arm64 Linux and macOS, as well as x86_64 Windows. Before you use the pre-built binaries on Linux and macOS platroms please install system dependencies:
13+
To use QEMU with ``idf.py``, you first need to install the above-mentioned fork of QEMU. ESP-IDF provides pre-built binaries for x86_64 and arm64 Linux and macOS, as well as x86_64 Windows. Before you use the pre-built binaries on Linux and macOS platroms please install system dependencies:
1214

1315
- Ubuntu and Debian:
1416

@@ -56,7 +58,7 @@ To run an IDF application in QEMU, use the following command:
5658
5759
idf.py qemu monitor
5860
59-
This command builds the application, starts QEMU and opens :doc:`IDF monitor <idf-monitor>`, connecting it to the emulated UART port. You can see the console output of the application and interact with it. IDF Monitor also provides automatic decoding of panic backtraces and UART core dumps.
61+
This command builds the application, starts QEMU and opens :doc:`IDF monitor <idf-monitor>`, and connects IDF Monitor to the emulated UART port. You can see the console output of the application and interact with it. IDF Monitor also provides automatic decoding of panic backtraces and UART core dumps.
6062

6163
Debugging
6264
~~~~~~~~~

‎docs/en/api-reference/peripherals/ecdsa.rst

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
Elliptic Curve Digital Signature Algorithm (ECDSA)
22
==================================================
33

4+
:link_to_translation:`zh_CN:[中文]`
5+
46
The Elliptic Curve Digital Signature Algorithm (ECDSA) offers a variant of the Digital Signature Algorithm (DSA) which uses elliptic-curve cryptography.
57

68
{IDF_TARGET_NAME}'s ECDSA peripheral provides a secure and efficient environment for computing ECDSA signatures. It offers fast computations while ensuring the confidentiality of the signing process to prevent information leakage. ECDSA private key used in the signing process is accessible only to the hardware peripheral, and it is not readable by software.
@@ -82,7 +84,7 @@ Application Outline
8284

8385
Please refer to the :ref:`ecdsa-peri-with-esp-tls` guide for details on how-to use ECDSA peripheral for establishing a mutually authenticated TLS connection.
8486

85-
The ECDSA peripheral in mbedTLS stack is integrated by overriding the ECDSA sign and verify APIs. Please note that, the ECDSA peripheral does not support all curves or hash algorithms and hence for cases where the requirements do not meet the hardware, implementation falls back to the software.
87+
The ECDSA peripheral in Mbed TLS stack is integrated by overriding the ECDSA signing and verifying APIs. Please note that, the ECDSA peripheral does not support all curves or hash algorithms, and hence for cases where the hardware requirements are not met, the implementation falls back to the software.
8688

8789
For a particular TLS context, additional APIs have been supplied to populate certain fields (e.g., private key ctx) to differentiate routing to hardware. ESP-TLS layer integrates these APIs internally and hence no additional work is required at the application layer. However, for custom use-cases please refer to API details below.
8890

‎docs/en/api-reference/peripherals/parlio.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
Parallel IO
22
===========
33

4+
:link_to_translation:`zh_CN:[中文]`
5+
46
Introduction
57
------------
68

‎docs/en/third-party-tools/clion.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
.. _clion:
22

3+
:link_to_translation:`zh_CN:[中文]`
4+
35
CLion
46
#####
57

‎docs/en/third-party-tools/visualgdb.rst

+2
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
VisualGDB
44
#########
55

6+
:link_to_translation:`zh_CN:[中文]`
7+
68
What Is VisualGDB?
79
~~~~~~~~~~~~~~~~~~
810

‎docs/zh_CN/api-guides/tools/qemu.rst

+113-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,113 @@
1-
.. include:: ../../../en/api-guides/tools/qemu.rst
1+
QEMU 模拟器
2+
===========
3+
4+
:link_to_translation:`en:[English]`
5+
6+
乐鑫维护了一个 QEMU 模拟器的 `分支 <https://github.com/espressif/qemu>`_，支持 {IDF_TARGET_NAME}。这个分支实现了对 {IDF_TARGET_NAME} 的 CPU、内存和多个外设的模拟。更多有关 {IDF_TARGET_NAME} 的 QEMU 的信息，请参阅 `QEMU README 文档 <https://github.com/espressif/esp-toolchain-docs/blob/main/qemu/README.md>`_。
7+
8+
:doc:`idf.py <idf-py>` 支持在 QEMU 中运行和调试应用程序，因此不必将应用程序烧录到真实硬件中，也可以便捷地进行测试。
9+
10+
先决条件
11+
--------
12+
13+
要使用 ``idf.py`` 和 QEMU，首先需要安装上述 QEMU 分支。ESP-IDF 为 x86_64、 arm64 版本的 Linux 和 macOS，以及 x86_64 Windows 提供了预构建的二进制文件。在 Linux 和 macOS 中使用预构建的二进制文件之前，请先安装系统依赖项：
14+
15+
- Ubuntu 和 Debian:
16+
17+
.. code-block:: console
18+
19+
sudo apt-get install -y libgcrypt20 libglib2.0-0 libpixman-1-0 libsdl2-2.0-0 libslirp0
20+
21+
- CentOS:
22+
23+
.. code-block:: console
24+
25+
sudo yum install -y --enablerepo=powertools libgcrypt glib2 pixman SDL2 libslirp
26+
27+
- Arch:
28+
29+
.. code-block:: console
30+
31+
sudo pacman -S --needed libgcrypt glib2 pixman sdl2 libslirp
32+
33+
- macOS:
34+
35+
.. code-block:: console
36+
37+
brew install libgcrypt glib pixman sdl2 libslirp
38+
39+
然后使用以下命令来安装预构建的二进制文件：
40+
41+
.. code-block:: console
42+
43+
python $IDF_PATH/tools/idf_tools.py install qemu-xtensa qemu-riscv32
44+
45+
安装完 QEMU，请在 ESP-IDF 目录中运行 ``. ./export.sh``，从而确保 QEMU 已被添加到 PATH 中。
46+
47+
如果使用的平台不同，则需要从源代码构建 QEMU。请参考官方 QEMU 文档。
48+
49+
用法
50+
----
51+
52+
运行应用程序
53+
~~~~~~~~~~~~
54+
55+
请使用以下命令，在 QEMU 中运行 IDF 应用程序：
56+
57+
.. code-block:: console
58+
59+
idf.py qemu monitor
60+
61+
此命令可用于构建应用程序、启动 QEMU 、打开 :doc:`IDF 监视器 <idf-monitor>`，并将 IDF 监视器连接到模拟的 UART 端口。你可以看到应用程序的控制台输出并与之交互。IDF 监视器还能对 panic 回溯以及对 UART 主存转储进行自动解码。
62+
63+
调试
64+
~~~~
65+
66+
请使用以下命令，在 QEMU 中调试应用程序：
67+
68+
.. code-block:: console
69+
70+
idf.py qemu gdb
71+
72+
此命令能构建应用程序，启用 GDB 服务器，并启动 QEMU，开启交互式 GDB 会话。这样就能像在真实的硬件上一样，通过 GDB 调试应用程序。
73+
74+
如需在 QEMU 中调试的同时查看控制台输出，可使用两个终端。
75+
76+
* 在第一个终端中运行：
77+
78+
.. code-block:: console
79+
80+
idf.py qemu --gdb monitor
81+
82+
此命令可启动 QEMU 和 IDF 监视器，并告知 QEMU 等待 GDB 连接。
83+
84+
* 在第二个终端中运行：
85+
86+
.. code-block:: console
87+
88+
idf.py gdb
89+
90+
此命令可开启交互式 GDB 会话，并将其连接到 QEMU。现在可以调试应用程序，并在第一个终端中看见控制台输出。
91+
92+
也可以在不使用 IDF 监视器的情况下运行 QEMU：
93+
94+
.. code-block:: console
95+
96+
idf.py qemu
97+
98+
使用该命令不会启动 IDF 监视器，可直接与 QEMU 进程进行交互。按下 Ctrl-A 快捷键，可以在模拟的 UART 控制台和 QEMU 控制台（“QEMU 监视器”）之间切换。例如，想要退出 QEMU，可以使用 Ctrl-A 快捷键，然后键入 ``q`` 并按 Enter 键。还可以使用 QEMU 控制台输入命令，例如可用于检查寄存器和内存。
99+
100+
图形支持
101+
~~~~~~~~
102+
103+
QEMU 支持虚拟帧缓冲设备。帧缓冲设备在真实的 {IDF_TARGET_NAME} 硬件中并不存在，但可以用于在 QEMU 中测试图形应用程序。
104+
105+
请使用以下命令，启动带有虚拟帧缓冲设备的 QEMU：
106+
107+
.. code-block:: console
108+
109+
idf.py qemu --graphics monitor
110+
111+
当启用 ``--graphics`` 选项时，QEMU 会打开一个额外的窗口，显示帧缓冲内容。
112+
113+
要在应用程序中使用虚拟帧缓冲设备，可以将 `espressif/esp_lcd_qemu_rgb <https://components.espressif.com/components/espressif/esp_lcd_qemu_rgb>`_ 组件添加到项目中。此组件为虚拟帧缓冲设备提供了一个与 esp_lcd 兼容的驱动程序。

‎docs/zh_CN/api-reference/peripherals/ecdsa.rst

+94-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,94 @@
1-
.. include:: ../../../en/api-reference/peripherals/ecdsa.rst
1+
椭圆曲线数字签名算法 (ECDSA)
2+
============================
3+
4+
:link_to_translation:`en:[English]`
5+
6+
椭圆曲线数字签名算法 (ECDSA) 是数字签名算法 (DSA) 基于椭圆曲线密码学的变体。
7+
8+
{IDF_TARGET_NAME} 的 ECDSA 外设为计算 ECDSA 签名提供了一个安全高效的环境，不仅能确保签名过程的机密性，防止信息泄露，也提供了快速的计算。在签名过程中使用的 ECDSA 私钥只能由硬件外设访问，软件无法读取。
9+
10+
ECDSA 外设可以为 TLS 双向身份验证等用例建立 **安全设备身份认证**。
11+
12+
支持的特性
13+
----------
14+
15+
- ECDSA 数字签名生成和验证
16+
- 两种不同的椭圆曲线，P-192 和 P-256（FIPS 186-3 规范）
17+
- ECDSA 操作中哈希消息的两种哈希算法，SHA-224 和 SHA-256（FIPS PUB 180-4 规范）
18+
19+
20+
{IDF_TARGET_NAME} 上的 ECDSA
21+
----------------------------
22+
23+
在 {IDF_TARGET_NAME} 上，ECDSA 模块使用烧录到 eFuse 块中的密钥。密码模块外的任何资源都不可访问此密钥（默认模式），从而避免密钥泄露。
24+
25+
ECDSA 密钥可以通过 ``espefuse.py`` 脚本在外部编程：
26+
27+
.. code:: bash
28+
29+
espefuse.py burn_key <BLOCK_NUM> </path/to/ecdsa_private_key.pem> ECDSA_KEY
30+
31+
.. only:: SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK
32+
33+
.. note::
34+
35+
五个物理 eFuse 块可作为 ECDSA 模块的密钥：块 4 ~ 块 8。例如，对于块 4（第一个密钥块），参数为 ``BLOCK_KEY0``。
36+
37+
.. only:: not SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK
38+
39+
.. note::
40+
41+
六个物理 eFuse 块可作为 ECDSA 模块的密钥：块 4 ~ 块 9。例如，对于块 4（第一个密钥块），参数为 ``BLOCK_KEY0``。
42+
43+
44+
另外，ECDSA 密钥也可以通过在目标上运行的应用程序进行编程。
45+
46+
以下代码片段使用 :cpp:func:`esp_efuse_write_key` 将 eFuse 中的物理密钥块 0 的密钥目的设置为 :cpp:enumerator:`esp_efuse_purpose_t::ESP_EFUSE_KEY_PURPOSE_ECDSA_KEY`:
47+
48+
.. code-block:: c
49+
50+
#include "esp_efuse.h"
51+
52+
const uint8_t key_data[32] = { ... };
53+
54+
esp_err_t status = esp_efuse_write_key(EFUSE_BLK_KEY0,
55+
ESP_EFUSE_KEY_PURPOSE_ECDSA_KEY,
56+
key_data, sizeof(key_data));
57+
58+
if (status == ESP_OK) {
59+
// written key
60+
} else {
61+
// writing key failed, maybe written already
62+
}
63+
64+
.. only:: SOC_ECDSA_SUPPORT_DETERMINISTIC_MODE
65+
66+
生成确定性签名
67+
--------------
68+
69+
{IDF_TARGET_NAME} 的 ECDSA 外设还支持使用确定性推导参数 K 来生成确定性签名，详见 `RFC 6979 <https://tools.ietf.org/html/rfc6979>`_ 第 3.2 节。
70+
71+
72+
生成非确定性签名
73+
----------------
74+
75+
对 TRNG 的依赖
76+
^^^^^^^^^^^^^^
77+
78+
ECDSA 外设依靠硬件真随机数生成器 (TRNG) 来满足其内部熵要求，从而生成非确定性签名。在创建 ECDSA 签名时，算法需要生成一个随机整数，在 `RFC 6090 <https://tools.ietf.org/html/rfc6090>`_ 第 5.3.2 节有说明。
79+
80+
在应用程序中启动 ECDSA 计算（主要是签名）之前，请确保硬件 :doc:`RNG <../system/random>` 已经启用。
81+
82+
应用程序概述
83+
------------
84+
85+
有关如何使用 ECDSA 外设建立 TLS 双向身份验证连接的详细信息，请参阅 :ref:`ecdsa-peri-with-esp-tls` 指南。
86+
87+
通过覆盖 ECDSA 签名以及验证 API，可以集成 Mbed TLS 堆栈中的 ECDSA 外设。请注意，ECDSA 外设并不支持所有曲线或哈希算法。因此，在不满足硬件要求时，实现会退回到软件。
88+
89+
对于特定的 TLS 上下文，可用额外的 API 来填充某些字段（例如私钥 ctx），以区分路由到硬件的路径。ESP-TLS 层在内部集成了这些 API，因此在应用程序层不需要额外的操作。对于自定义用例，请参阅以下 API 详细信息。
90+
91+
API 参考
92+
--------
93+
94+
.. include-build-file:: inc/ecdsa_alt.inc

‎docs/zh_CN/api-reference/peripherals/parlio.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
并行 IO
22
=======
33

4+
:link_to_translation:`en:[English]`
5+
46
简介
57
----
68

‎docs/zh_CN/third-party-tools/clion.rst

+2
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
CLion
44
#####
55

6+
:link_to_translation:`en:[English]`
7+
68
CLion是什么？
79
~~~~~~~~~~~~~
810

‎docs/zh_CN/third-party-tools/visualgdb.rst

+2
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
VisualGDB
44
#########
55

6+
:link_to_translation:`en:[English]`
7+
68
VisualGDB 是什么?
79
~~~~~~~~~~~~~~~~~~
810

0 commit comments

Comments
 (0)