Merge branch 'feature/parttable_improve_doc_and_error' into 'master'

partition_table: Improve an error msg and doc Closes IDFGH-8377 See merge request espressif/esp-idf!20687
espressif · Oct 24, 2022 · daf3da5 · daf3da5
2 parents e8e9fae + b5315ae
commit daf3da5
Show file tree

Hide file tree

Showing 3 changed files with 19 additions and 4 deletions.
diff --git a/components/partition_table/gen_esp32part.py b/components/partition_table/gen_esp32part.py
@@ -175,10 +175,12 @@ def expand_vars(f):
         for e in res:
             if e.offset is not None and e.offset < last_end:
                 if e == res[0]:
-                    raise InputError('CSV Error: First partition offset 0x%x overlaps end of partition table 0x%x'
-                                     % (e.offset, last_end))
+                    raise InputError('CSV Error at line %d: Partitions overlap. Partition sets offset 0x%x. '
+                                     'But partition table occupies the whole sector 0x%x. '
+                                     'Use a free offset 0x%x or higher.'
+                                     % (e.line_no, e.offset, offset_part_table, last_end))
                 else:
-                    raise InputError('CSV Error: Partitions overlap. Partition at line %d sets offset 0x%x. Previous partition ends 0x%x'
+                    raise InputError('CSV Error at line %d: Partitions overlap. Partition sets offset 0x%x. Previous partition ends 0x%x'
                                      % (e.line_no, e.offset, last_end))
             if e.offset is None:
                 pad_to = get_alignment_for_type(e.type)

diff --git a/components/partition_table/test_gen_esp32part_host/gen_esp32part_tests.py b/components/partition_table/test_gen_esp32part_host/gen_esp32part_tests.py
@@ -409,6 +409,16 @@ def test_bad_alignment(self):
             t = gen_esp32part.PartitionTable.from_csv(csv)
             t.verify()
 
+    def test_overlap_part_table(self):
+        csv = """
+# Name,Type, SubType,Offset,Size
+nvs,      data, nvs,     0x0000,  0x6000,
+phy_init, data, phy,     ,        0x1000,
+factory,  app,  factory, ,        1M,
+"""
+        with self.assertRaisesRegex(gen_esp32part.InputError, r'CSV Error at line 3: Partitions overlap. Partition sets offset 0x0'):
+            gen_esp32part.PartitionTable.from_csv(csv)
+
     def test_only_one_otadata(self):
         csv_txt = """
 # Name,Type, SubType,Offset,Size

diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst
@@ -7,7 +7,8 @@ Overview
 
 A single {IDF_TARGET_NAME}'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 (:ref:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) 0x8000 in the flash.
 
-Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum, which is used for checking the integrity of the partition table, is appended after the table data.
+The partition table length is 0xC00 bytes, as we allow a maximum of 95 entries. An MD5 checksum, used for checking the integrity of the partition table at runtime, is appended after the table data. Thus, the partition table occupies an entire flash sector, which size is 0x1000 (4KB). As a result, any partition following it must be at least located at (:ref:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) + 0x1000.
+
 
 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.
 
@@ -139,6 +140,8 @@ A component can define a new partition subtype by setting the ``EXTRA_PARTITION_
 Offset & Size
 ~~~~~~~~~~~~~
 
+The offset represents the partition address in the SPI flash, which sector size is 0x1000 (4KB). Thus, the offset must be a multiple of 4KB.
+
 Partitions with blank offsets in the CSV file will start after the previous partition, or after the partition table in the case of the first partition.
 
 Partitions of type ``app`` have to be placed at offsets aligned to 0x10000 (64K). If you leave the offset field blank,  ``gen_esp32part.py`` will automatically align the partition. If you specify an unaligned offset for an app partition, the tool will return an error.