mirror of
https://github.com/espressif/ESP8266_RTOS_SDK.git
synced 2025-05-22 01:27:11 +08:00
docs(partition_table): Modify document for ESP8266
This commit is contained in:
Dong Heng
@ -4,25 +4,25 @@ Partition Tables
|
||||
Overview
|
||||
--------
|
||||
|
||||
A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x8000 in the flash.
|
||||
A single ESP8266's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x8000 in the flash.
|
||||
|
||||
Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum is appended after the table data. If the partition table is signed due to `secure boot`, the signature is appended after the partition table.
|
||||
Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum is appended after the table data.
|
||||
|
||||
Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
|
||||
|
||||
The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables:
|
||||
|
||||
* "Single factory app, no OTA"
|
||||
* "Factory app, two OTA definitions"
|
||||
* "Two OTA app"
|
||||
|
||||
In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table.
|
||||
If you `make partition_table` then it will print a summary of the partition table.
|
||||
|
||||
Built-in Partition Tables
|
||||
-------------------------
|
||||
|
||||
Here is the summary printed for the "Single factory app, no OTA" configuration::
|
||||
|
||||
# Espressif ESP32 Partition Table
|
||||
# Espressif ESP8266 Partition Table
|
||||
# Name, Type, SubType, Offset, Size
|
||||
nvs, data, nvs, 0x9000, 0x6000
|
||||
phy_init, data, phy, 0xf000, 0x1000
|
||||
@ -31,20 +31,18 @@ Here is the summary printed for the "Single factory app, no OTA" configuration::
|
||||
* At a 0x10000 (64KB) offset in the flash is the app labelled "factory". The bootloader will run this app by default.
|
||||
* There are also two data regions defined in the partition table for storing NVS library partition and PHY init data.
|
||||
|
||||
Here is the summary printed for the "Factory app, two OTA definitions" configuration::
|
||||
Here is the summary printed for the "Two OTA definitions" configuration::
|
||||
|
||||
# Espressif ESP32 Partition Table
|
||||
# Name, Type, SubType, Offset, Size
|
||||
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, , 1M
|
||||
ota_1, 0, ota_1, , 1M
|
||||
# Espressif ESP8266 Partition Table
|
||||
# Name, Type, SubType, Offset, Size
|
||||
nvs, data, nvs, 0x9000, 0x4000
|
||||
otadata, data, ota, 0xd000, 0x2000
|
||||
phy_init, data, phy, 0xf000, 0x1000
|
||||
ota_0, 0, ota_0, 0x10000, 1M
|
||||
ota_1, 0, ota_1, 0x110000, 1M
|
||||
|
||||
* There are now three app partition definitions.
|
||||
* The type of all three are set as "app", but the subtype varies between the factory app at 0x10000 and the next two "OTA" apps.
|
||||
* There is also a new "ota data" 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.
|
||||
* There are now two app partition definitions, ota_0 at 0x10000 and ota_1 at 0x110000
|
||||
* There is also a new "ota data" 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 ota_0 app.
|
||||
|
||||
Creating Custom Tables
|
||||
----------------------
|
||||
@ -54,12 +52,11 @@ If you choose "Custom partition table CSV" in menuconfig then you can also enter
|
||||
The CSV format is the same format as printed in the summaries shown above. However, not all fields are required in the CSV. For example, here is the "input" CSV for the OTA partition table::
|
||||
|
||||
# Name, Type, SubType, Offset, Size
|
||||
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, , 1M
|
||||
ota_1, app, ota_1, , 1M
|
||||
nvs, data, nvs, 0x9000, 0x4000
|
||||
otadata, data, ota, 0xd000, 0x2000
|
||||
phy_init, data, phy, 0xf000, 0x1000
|
||||
ota_0, app, ota_0, 0x10000, 1M
|
||||
ota_1, app, ota_1, 0x110000, 1M
|
||||
|
||||
* Whitespace between fields is ignored, and so is any line starting with # (comments).
|
||||
* Each non-comment line in the CSV file is a partition definition.
|
||||
@ -68,7 +65,7 @@ The CSV format is the same format as printed in the summaries shown above. Howev
|
||||
Name field
|
||||
~~~~~~~~~~
|
||||
|
||||
Name field can be any meaningful name. It is not significant to the ESP32. Names longer than 16 characters will be truncated.
|
||||
Name field can be any meaningful name. It is not significant to the ESP8266. Names longer than 16 characters will be truncated.
|
||||
|
||||
Type field
|
||||
~~~~~~~~~~
|
||||
@ -89,14 +86,11 @@ esp-idf currently only specifies the meaning of the subtype field for "app" and
|
||||
App Subtypes
|
||||
~~~~~~~~~~~~
|
||||
|
||||
When type is "app", the subtype field can be specified as factory (0), ota_0 (0x10) ... ota_15 (0x1F) or test (0x20).
|
||||
When type is "app", the subtype field can be specified as ota_0 (0x10), ota_1 (0x11) ... ota_15 (0x1F) or test (0x20).
|
||||
|
||||
- factory (0) is the default app partition. The bootloader will execute the factory app unless there it sees a partition of type data/ota, in which case it reads this partition to determine which OTA image to boot.
|
||||
- ota_0 (0x10) is the default app partition. The bootloader will execute the ota_0 app unless there it sees another partition of type data/ota, in which case it reads this partition to determine which OTA image to boot.
|
||||
|
||||
- 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. Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details, which then use the OTA data partition to configure which app slot the bootloader should boot. If 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 (0x2) is a reserved subtype for factory test procedures. It is not currently supported by the esp-idf bootloader.
|
||||
|
||||
Data Subtypes
|
||||
~~~~~~~~~~~~~
|
||||
@ -107,7 +101,7 @@ When type is "data", the subtype field can be specified as ota (0), phy (1), nvs
|
||||
- phy (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware.
|
||||
|
||||
- In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space.
|
||||
- To load PHY data from this partition, run ``make menuconfig`` and enable :envvar:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically.
|
||||
- To load PHY data from this partition, run ``make menuconfig`` and enable :envvar:`ESP_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically.
|
||||
- nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`.
|
||||
|
||||
- NVS is used to store per-device PHY calibration data (different to initialisation data).
|
||||
@ -130,7 +124,7 @@ Sizes and offsets can be specified as decimal numbers, hex numbers with the pref
|
||||
Generating Binary Partition Table
|
||||
---------------------------------
|
||||
|
||||
The partition table which is flashed to the ESP32 is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats.
|
||||
The partition table which is flashed to the ESP8266 is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats.
|
||||
|
||||
If you configure the partition table CSV name in ``make menuconfig`` and then ``make partition_table``, this conversion is done as part of the build process.
|
||||
|
||||
@ -148,13 +142,6 @@ To display the contents of a binary partition table on stdout (this is how the s
|
||||
|
||||
``gen_esp32part.py`` takes one optional argument, ``--verify``, which will also verify the partition table during conversion (checking for overlapping partitions, unaligned partitions, etc.)
|
||||
|
||||
MD5 checksum
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The binary format of the partition table contains an MD5 checksum computed based on the partition table. This checksum is used for checking the integrity of the partition table during the boot.
|
||||
|
||||
The MD5 checksum generation can be disabled by the ``--disable-md5sum`` option of ``gen_esp32part.py`` or by the :envvar:`CONFIG_PARTITION_TABLE_MD5` option. This is useful for example when one uses a legacy bootloader which cannot process MD5 checksums and the boot fails with the error message ``invalid magic number 0xebeb``.
|
||||
|
||||
Flashing the partition table
|
||||
----------------------------
|
||||
|
||||
@ -163,6 +150,4 @@ Flashing the partition table
|
||||
|
||||
A manual flashing command is also printed as part of ``make partition_table``.
|
||||
|
||||
Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``make erase_flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents.
|
||||
|
||||
.. _secure boot: security/secure-boot.rst
|
||||
Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``make erase_flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents.
|
||||
Reference in New Issue
Block a user