From b5315aec16b54fba34ceb5da795d1333b8b9ad34 Mon Sep 17 00:00:00 2001
From: KonstantinKondrashov <konstantin@espressif.com>
Date: Thu, 20 Oct 2022 01:16:17 +0800
Subject: [PATCH] partition_table: Improve an error msg and doc

Closes https://github.com/espressif/esp-idf/issues/9846
---
 components/partition_table/gen_esp32part.py            |  8 +++++---
 .../test_gen_esp32part_host/gen_esp32part_tests.py     | 10 ++++++++++
 docs/en/api-guides/partition-tables.rst                |  5 ++++-
 3 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/components/partition_table/gen_esp32part.py b/components/partition_table/gen_esp32part.py
index 3c1f6022b2..273f4e312f 100755
--- a/components/partition_table/gen_esp32part.py
+++ b/components/partition_table/gen_esp32part.py
@@ -175,10 +175,12 @@ class PartitionTable(list):
         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
index c82b26df66..a4bb917288 100755
--- 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 @@ factory,  app,  factory, ,        1M,
             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
index 0847768b0c..24c884e081 100644
--- 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.