From d83dd3be6e961ce97ba49f1b1e17a98a68ff2ef5 Mon Sep 17 00:00:00 2001
From: Peter Dragun <peter.dragun@espressif.com>
Date: Tue, 9 Jul 2024 13:57:50 +0200
Subject: [PATCH] docs: add note about Intel Hex merging limitations

https://github.com/espressif/esptool/pull/960
https://github.com/espressif/esptool/pull/959
---
 docs/en/esptool/basic-commands.rst |  5 +++++
 esptool/cmds.py                    |  7 +++++++
 test/test_merge_bin.py             | 11 +++++++----
 3 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/docs/en/esptool/basic-commands.rst b/docs/en/esptool/basic-commands.rst
index d313bca9d..c92804583 100644
--- a/docs/en/esptool/basic-commands.rst
+++ b/docs/en/esptool/basic-commands.rst
@@ -285,6 +285,11 @@ Intel Hex format offers distinct advantages when compared to the binary format,
 
     esptool.py --chip {IDF_TARGET_NAME} merge_bin --format hex -o merged-flash.hex --flash_mode dio --flash_size 4MB 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin
 
+.. note::
+
+    Please note that during the conversion to the `Intel Hex` format, the binary input file is treated as a black box. The conversion process does not consider the actual contents of the binary file. This means that the `Intel Hex` file will contain the same data as the binary file (including the padding), but the data will be represented in a different format.
+    When merging multiple files, the `Intel Hex` format, unlike the binary format, does not include any padding between the input files.
+    It is recommended to merge multiple files instead of converting one already merged to get smaller merged outputs.
 
 RAW Output Format
 ^^^^^^^^^^^^^^^^^
diff --git a/esptool/cmds.py b/esptool/cmds.py
index a76fdebb3..63d9a20c7 100644
--- a/esptool/cmds.py
+++ b/esptool/cmds.py
@@ -1413,6 +1413,13 @@ def pad_to(flash_offs):
             )
     elif args.format == "hex":
         out = IntelHex()
+        if len(input_files) == 1:
+            print(
+                "WARNING: Only one input file specified, output may include "
+                "additional padding if input file was previously merged. "
+                "Please refer to the documentation for more information: "
+                "https://docs.espressif.com/projects/esptool/en/latest/esptool/basic-commands.html#hex-output-format"  # noqa E501
+            )
         for addr, argfile in input_files:
             ihex = IntelHex()
             image = argfile.read()
diff --git a/test/test_merge_bin.py b/test/test_merge_bin.py
index c4f97673b..75df9bc8b 100755
--- a/test/test_merge_bin.py
+++ b/test/test_merge_bin.py
@@ -31,7 +31,7 @@ def read_image(filename):
 
 @pytest.mark.host_test
 class TestMergeBin:
-    def run_merge_bin(self, chip, offsets_names, options=[]):
+    def run_merge_bin(self, chip, offsets_names, options=[], allow_warnings=False):
         """Run merge_bin on a list of (offset, filename) tuples
         with output to a named temporary file.
 
@@ -62,9 +62,10 @@ def run_merge_bin(self, chip, offsets_names, options=[]):
             )
             output = output.decode("utf-8")
             print(output)
-            assert (
-                "warning" not in output.lower()
-            ), "merge_bin should not output warnings"
+            if not allow_warnings:
+                assert (
+                    "warning" not in output.lower()
+                ), "merge_bin should not output warnings"
 
             with open(output_file.name, "rb") as f:
                 return f.read()
@@ -203,6 +204,7 @@ def test_merge_mixed(self):
             "esp32",
             [(0x1000, "bootloader_esp32.bin")],
             options=["--format", "hex"],
+            allow_warnings=True,
         )
         # create a temp file with hex content
         with tempfile.NamedTemporaryFile(suffix=".hex", delete=False) as f:
@@ -233,6 +235,7 @@ def test_merge_bin2hex(self):
                 (0x1000, "bootloader_esp32.bin"),
             ],
             options=["--format", "hex"],
+            allow_warnings=True,
         )
         lines = merged.splitlines()
         # hex format - :0300300002337A1E