Merge branch 'doc/improve_part_table_doc' into 'master'

feat(partition_table): Improves documentation for partition table

See merge request espressif/esp-idf!39368

Author: Konstantin Kondrashov

components/partition_table/Kconfig.projbuild

@@ -154,15 +154,20 @@ menu "Partition Table"
         hex "Offset of partition table"
         default 0x8000
         help
-            The address of partition table (by default 0x8000).
-            Allows you to move the partition table, it gives more space for the bootloader.
-            Note that the bootloader and app will both need to be compiled with the same PARTITION_TABLE_OFFSET value.
+            The offset address of the partition table is, by default, 0x8000, and it starts right after
+            the bootloader. This offset can be changed if more space is required for the bootloader.
+            If you change this offset, both the bootloader and the app must be compiled with the same
+            PARTITION_TABLE_OFFSET value.
 
-            This number should be a multiple of 0x1000.
+            This value must be a multiple of 0x1000.
 
-            Note that partition offsets in the partition table CSV file may need to be changed if this value is set to
-            a higher value. To have each partition offset adapt to the configured partition table offset, leave all
-            partition offsets blank in the CSV file.
+            If you change the partition table offset, make sure to update the partition offsets in
+            the partition table CSV file. To let the build system automatically adjust partition offsets based on
+            the configured partition table offset, leave the offset fields blank in the CSV file.
+
+            Note: If you specify fixed offsets in the partition table CSV (i.e., the offset column is not blank),
+            the first partition must start at PARTITION_TABLE_OFFSET + 0x1000, since the partition table occupies
+            0x1000 bytes of flash space.
 
     config PARTITION_TABLE_MD5
         bool "Generate an MD5 checksum for the partition table"

docs/en/api-guides/partition-tables.rst

@@ -69,9 +69,9 @@ The CSV format is the same format as printed in the summaries shown above. Howev
     ota_1,    app,  ota_1,    ,         1M
     nvs_key,  data, nvs_keys, ,        0x1000
 
-* Whitespace between fields is ignored, and so is any line starting with # (comments).
+* 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.
-* The ``Offset`` field for each partition is empty. The ``gen_esp32part.py`` tool fills in each blank offset, starting after the partition table and making sure each partition is aligned correctly.
+* If you change the value of :ref:`CONFIG_PARTITION_TABLE_OFFSET`, you should update any fixed ``Offset`` in your CSV file to avoid overlaps with the new partition table location. Alternatively, leaving the ``Offset`` field blank allows the ``gen_esp32part.py`` tool to automatically calculate the correct offset based on the current partition table offset and alignment requirements.
 
 Here is an example of a CSV partition table that includes bootloader and partition table partitions:
 
@@ -224,7 +224,9 @@ Offset & Size
     - Sizes and offsets can be specified as decimal numbers, hex numbers with the prefix 0x, or size multipliers K or M (1024 and 1024*1024 bytes).
     - For ``bootloader`` and ``partition_table`` types, specifying ``N/A`` for size and offset in the CSV file means that these values are automatically determined by the tool and cannot be manually defined. This requires setting the ``--offset`` and ``--primary-partition-offset`` arguments of ``gen_esp32part.py``.
 
-If you want the partitions in the partition table to work relative to any placement (:ref:`CONFIG_PARTITION_TABLE_OFFSET`) of the table itself, leave the offset field (in CSV file) for all partitions blank. Similarly, if changing the partition table offset then be aware that all blank partition offsets may change to match, and that any fixed offsets may now collide with the partition table (causing an error).
+.. note::
+
+    If you want the partitions in the partition table to work relative to any placement (:ref:`CONFIG_PARTITION_TABLE_OFFSET`) of the table itself, leave the offset field (in CSV file) for all partitions blank. Similarly, if changing the partition table offset, then be aware that all blank partition offsets may change to match, and that any fixed offsets may now collide with the partition table (causing an error).
 
 Flags
 ~~~~~

docs/zh_CN/api-guides/partition-tables.rst

@@ -69,9 +69,9 @@ CSV 文件的格式与上面摘要中打印的格式相同，但是在 CSV 文
     ota_1,    app,  ota_1,    ,         1M
     nvs_key,  data, nvs_keys, ,        0x1000
 
-*  字段之间的空格会被忽略，任何以 ``#`` 开头的行（注释）也会被忽略。
-*  CSV 文件中的每个非注释行均为一个分区定义。
-*  每个分区的 ``Offset`` 字段可以为空，``gen_esp32part.py`` 工具会从分区表位置的后面开始自动计算并填充该分区的偏移地址，同时确保每个分区的偏移地址正确对齐。
+* 字段之间的空格会被忽略，任何以 ``#`` 开头的行（注释）也会被忽略。
+* CSV 文件中的每个非注释行均为一个分区定义。
+* 如需调整 :ref:`CONFIG_PARTITION_TABLE_OFFSET` 参数值，请同步更新 CSV 文件中所有固定 ``Offset`` 值，防止与新分区表位置产生冲突。也可将 ``Offset`` 字段留空，此时 ``gen_esp32part.py`` 工具将基于当前分区表偏移量和对齐要求，自动计算出正确的偏移地址。
 
 下面是一个包含引导加载程序和分区表分区的 CSV 分区表示例：
 
@@ -224,7 +224,9 @@ SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，ESP
     - ``app`` 分区的大小和偏移地址可以采用十进制数或是以 0x 为前缀的十六进制数，且支持 K 或 M 的倍数单位（K 和 M 分别代表 1024 和 1024*1024 字节）。
     - 对于 ``bootloader`` 和 ``partition_table``，在 CSV 文件中将大小和偏移量指定为 ``N/A`` 意味着这些值将由工具自动确定，无法手动定义。这需要设置 ``gen_esp32part.py`` 工具的 ``--offset`` 和 ``--primary-partition-offset`` 参数。
 
-如果你希望允许分区表中的分区采用任意起始偏移量 (:ref:`CONFIG_PARTITION_TABLE_OFFSET`)，请将分区表（CSV 文件）中所有分区的偏移字段都留空。注意，此时，如果你更改了分区表中任意分区的偏移地址，则其他分区的偏移地址也会跟着改变。这种情况下，如果你之前还曾设定某个分区采用固定偏移地址，则可能造成分区表冲突，从而导致报错。
+.. note::
+
+    如果你希望分区表中各个分区的偏移地址是相对于分区表本身的位置 (由 :ref:`CONFIG_PARTITION_TABLE_OFFSET` 指定)，请将分区表（CSV 文件）中所有分区的偏移字段都留空。这样，在更改分区表的偏移地址时，留空的分区偏移地址会自动做出相应的改变。而如果你在某个分区采用了固定的偏移值，就可能与分区表发生冲突，导致报错。
 
 Flags 字段
 ~~~~~~~~~~