docs: add note about Intel Hex merging limitations

espressif#960
espressif#959

Author: peterdragun

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
 ^^^^^^^^^^^^^^^^^

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()

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