Skip to content

Commit d41da27

Browse files
Icarus113Icarus113
committed
doc: add flash and psram configuration doc in programming guide
1 parent 1c44c3b commit d41da27

File tree

7 files changed

+182
-5
lines changed

7 files changed

+182
-5
lines changed

‎docs/conf_common.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,8 @@
8686
'api-reference/peripherals/touch_element.rst'] + FTDI_JTAG_DOCS
8787

8888
ESP32S3_DOCS = ['hw-reference/esp32s3/**',
89-
'api-reference/system/ipc.rst']
89+
'api-reference/system/ipc.rst',
90+
'api-guides/flash_psram_config.rst']
9091

9192
# No JTAG docs for this one as it gets gated on SOC_USB_SERIAL_JTAG_SUPPORTED down below.
9293
ESP32C3_DOCS = ['hw-reference/esp32c3/**']

‎docs/en/api-guides/flash_psram_config.rst‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
SPI Flash and External SPI RAM Configuration
2+
============================================
3+
4+
This page is a guide for configuring SPI Flash and external SPI RAM. Supported frequency and mode combination, error handling are also elaborated.
5+
6+
Terminology
7+
-----------
8+
9+
============= ===========================
10+
Term Definition
11+
============= ===========================
12+
**SPI** Serial Peripheral Interface
13+
**MSPI** Memory SPI Peripheral, SPI Peripheral dedicated for memory
14+
**SDR** Single Data Rate
15+
**DDR** Double Data Rate
16+
**line mode** Number of signals used to transfer data in the data phase of SPI transactions. e.g., for 4-bit-mode, the speed of the data phase would be 4 bit per clock cycle.
17+
**FxRx** F stands for Flash, R stands for PSRAM, x stands for line mode. e.g. F4R4 stands for an {IDF_TARGET_NAME} with Quad Flash and Quad PSRAM
18+
============= ===========================
19+
20+
.. note::
21+
22+
On {IDF_TARGET_NAME}, MSPI stands for the SPI0/1. SPI0 and SPI1 share a common SPI bus. The main Flash and PSRAM are connected to the MSPI peripheral. CPU accesses them via Cache.
23+
24+
25+
.. _flash-psram-configuration:
26+
27+
How to configure Flash and PSRAM
28+
--------------------------------
29+
30+
``idf.py menuconfig`` is used to open the configuration menu.
31+
32+
Configure the Flash
33+
^^^^^^^^^^^^^^^^^^^
34+
35+
The Flash related configurations are under ``Serial flasher config`` menu.
36+
37+
1. Flash type used on the board. For Octal Flash, select :ref:`CONFIG_ESPTOOLPY_OCT_FLASH`. For Quad Flash, uncheck this configuration.
38+
2. Flash line mode. Select a line mode in :ref:`CONFIG_ESPTOOLPY_FLASHMODE`. The higher the line mode is, the faster the SPI speed is. See terminology above about the line mode.
39+
3. Flash sample mode. Select a sample mode in :ref:`CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE`. DDR mode is faster than SDR mode. See terminology above about SDR and DDR mode.
40+
4. Flash speed. Select a Flash frequency in :ref:`CONFIG_ESPTOOLPY_FLASHFREQ`.
41+
5. Flash size. Flash size, in megabytes. Select a Flash size in :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`.
42+
43+
Configure the PSRAM
44+
^^^^^^^^^^^^^^^^^^^
45+
46+
To enable PSRAM, please enable the :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_SPIRAM_SUPPORT` under ``Component config / {IDF_TARGET_NAME}-Specific`` menu. Then all the PSRAM related configurations will be visible under ``SPI RAM config`` menu.
47+
48+
1. PSRAM type used on the board. Select a type in :ref:`CONFIG_SPIRAM_MODE` for Quad or Octal PSRAM.
49+
2. PSRAM speed. Select a PSRAM frequency in :ref:`CONFIG_SPIRAM_SPEED`.
50+
51+
.. note::
52+
53+
Configuration 1 of Flash and PSRAM should be selected according to your actual hardware.
54+
55+
For the reset of the above configurations:
56+
57+
- Flash and PSRAM share the same internal clock.
58+
- Quad Flash only supports STR mode. Octal Flash may support either/both STR/DTR modes under OPI mode, depending on the flash model and the vendor.
59+
- Quad PSRAM only supports STR mode, while Octal PSRAM only supports DTR mode.
60+
61+
Therefore, some limitations should be noticed when configuring configuration 2, 3 and 4 of Flash, and configuration 2 of PSRAM. Please refer to :ref:`All Supported Modes and Speeds <flash-psram-combination>`
62+
63+
.. note::
64+
65+
If a board with Octal Flash resets before the second-stage bootloader, please refer to :ref:`Error Handling Chapter <flash-psram-error>`
66+
67+
68+
.. _flash-psram-combination:
69+
70+
All Supported Modes and Speeds
71+
------------------------------
72+
73+
.. note::
74+
75+
For MSPI DDR mode, the data are sampled on both the positive edge and the negative edge. e.g.: if a Flash is set to 80 MHz and DDR mode, then the final speed of the Flash is 160 MHz. This is faster than the Flash setting to 120 Mhz and STR mode.
76+
77+
78+
F8R8 Hardware
79+
^^^^^^^^^^^^^
80+
81+
======= =============== ======= ============
82+
Group Flash mode Group PSRAM mode
83+
======= =============== ======= ============
84+
A 120 MHz SDR A N.A.
85+
B 80 MHz DDR B 80 MHz DDR
86+
C 80 MHz SDR C 40 MHz DDR
87+
C 40 MHz DDR C
88+
C < 40 MHz C
89+
D D disable
90+
======= =============== ======= ============
91+
92+
1. Flash mode in group A works with PSRAM mode in group A/D
93+
2. Flash mode in group B/C works with PSRAM mode in group B/C/D
94+
95+
96+
F4R8 Hardware
97+
^^^^^^^^^^^^^
98+
99+
======= =============== ======= ============
100+
Group Flash mode Group PSRAM mode
101+
======= =============== ======= ============
102+
A 120 MHz SDR A N.A.
103+
B 80 MHz SDR B 80MHz DDR
104+
C 40 MHz SDR C 40MHz DDR
105+
C 20 MHz SDR C
106+
D D disable
107+
======= =============== ======= ============
108+
109+
1. Flash mode in group A works with PSRAM mode in group A/D
110+
2. Flash mode in group B/C works with PSRAM mode in group B/C/D
111+
112+
113+
F4R4 Hardware
114+
^^^^^^^^^^^^^
115+
116+
====== =============== ====== ============
117+
Type Flash Type PSRAM
118+
====== =============== ====== ============
119+
A 120 MHz A 120MHz
120+
B 80 MHz B 80MHz
121+
C 40 MHz C 40MHz
122+
C 20 MHz C
123+
D D disable
124+
====== =============== ====== ============
125+
126+
1. Flash in A works with PSRAM in A/C/D
127+
2. Flash in B works with PSRAM in B/C/D
128+
3. Flash in C works with PSRAM in A/B/C/D
129+
130+
131+
.. _flash-psram-error:
132+
133+
Error handling
134+
--------------
135+
136+
1. If a board with Octal Flash resets before the second-stage bootloader:
137+
138+
.. code-block:: c
139+
140+
ESP-ROM:esp32s3-20210327
141+
Build:Mar 27 2021
142+
rst:0x7 (TG0WDT_SYS_RST),boot:0x18 (SPI_FAST_FLASH_BOOT)
143+
Saved PC:0x400454d5
144+
SPIWP:0xee
145+
mode:DOUT, clock div:1
146+
load:0x3fcd0108,len:0x171c
147+
ets_loader.c 78
148+
149+
it may mean that the necessary efuses are not correctly burnt. please check the eFuse bits of the chip using command ``espefuse.py summary``.
150+
151+
The 1st bootloader relies on an eFuse bit ``FLASH_TYPE`` to reset the Flash into the default mode (SPI mode). If this bit is not burnt and the flash is working in OPI mode, 1st bootloader may not be able to read from the flash and load the following images.
152+
153+
Run this command to burn the eFuse bit:
154+
155+
.. code-block:: python
156+
157+
python3 ./espefuse.py -p /dev/<serial_device> --do-not-confirm burn_efuse FLASH_TYPE 1
158+
159+
.. note::
160+
161+
This step is irreversible. Please do check if your hardware is actually using an Octal Flash.

‎docs/en/api-guides/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ API Guides
2121
:SOC_SPIRAM_SUPPORTED: External SPI-connected RAM <external-ram>
2222
Fatal Errors <fatal-errors>
2323
Flash Encryption <../security/flash-encryption>
24+
:esp32s3: Flash and External SPI RAM Configuration <flash_psram_config>
2425
FreeRTOS SMP Changes <freertos-smp>
2526
Hardware Abstraction <hardware-abstraction>
2627
:CONFIG_IDF_TARGET_ARCH_XTENSA: High Level Interrupts <hlinterrupts>

‎docs/en/api-reference/storage/spi_flash.rst‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Support for features of flash chips
2929

3030
Flash features of different vendors are operated in different ways and need special support. The fast/slow read and Dual mode (DOUT/DIO) of almost all 24-bits address flash chips are supported, because they don't need any vendor-specific commands.
3131

32-
The Quad mode (QIO/QOUT) the following chip types are supported:
32+
Quad mode (QIO/QOUT) is supported on following chip types:
3333

3434
1. ISSI
3535
2. GD
@@ -39,6 +39,14 @@ The Quad mode (QIO/QOUT) the following chip types are supported:
3939
6. XMC
4040
7. BOYA
4141

42+
.. only:: esp32s3
43+
44+
Octal mode (OPI) are supported on following chip types:
45+
46+
1. MXIC
47+
48+
To know how to configure menuconfig for a board with different Flash and PSRAM, please refer to the :ref:`SPI Flash and External SPI RAM Configuration <flash-psram-configuration>`
49+
4250
The 32-bit address range of following chip type is supported:
4351

4452
1. W25Q256
@@ -151,7 +159,7 @@ Differences between :cpp:func:`spi_flash_mmap` and :cpp:func:`esp_partition_mmap
151159

152160
Note that since memory mapping happens in pages, it may be possible to read data outside of the partition provided to ``esp_partition_mmap``, regardless of the partition boundary.
153161

154-
.. note::
162+
.. note::
155163
mmap is supported by cache, so it can only be used on main flash.
156164

157165
SPI Flash Implementation
@@ -248,5 +256,3 @@ API Reference - Flash Encrypt
248256
-----------------------------
249257

250258
.. include-build-file:: inc/esp_flash_encrypt.inc
251-
252-

‎docs/en/get-started/index.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -774,6 +774,12 @@ To exit IDF monitor use the shortcut ``Ctrl+]``.
774774

775775
idf.py -p PORT flash monitor
776776

777+
.. only:: esp32s3
778+
779+
.. note::
780+
781+
If a board with Octal Flash resets before the second-stage bootloader, please refer to :ref:`Octal Flash Error Handling <flash-psram-error>`
782+
777783
See also:
778784

779785
- :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor.

‎docs/zh_CN/api-guides/flash_psram_config.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. include:: ../../en/api-guides/flash_psram_config.rst

‎docs/zh_CN/api-guides/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ API 指南
2121
:SOC_SPIRAM_SUPPORTED: 片外 SPI RAM <external-ram>
2222
严重错误 <fatal-errors>
2323
Flash 加密 <../security/flash-encryption>
24+
:esp32s3: Flash and External SPI RAM Configuration <flash_psram_config>
2425
FreeRTOS SMP 变化 <freertos-smp>
2526
硬件抽象层 <hardware-abstraction>
2627
:CONFIG_IDF_TARGET_ARCH_XTENSA: 高层中断 <hlinterrupts>

0 commit comments

Comments
 (0)