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