espressif/esptool
1
0
Fork 0
mirror of https://github.com/espressif/esptool.git synced 2025-10-20 04:54:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(image_info): Deprecate the --version 1 output format

Browse Source 
BREAKING CHANGE
This commit is contained in:
Radim Karniš
2025-01-15 16:25:24 +01:00
parent 83613c8518
commit 3f625c39ad
8 changed files with 229 additions and 287 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/en/advanced-topics/firmware-image-format.rst
View File

@@ -189,4 +189,4 @@ The file is padded with zeros until its size is one byte less than a multiple of
Analyzing a Binary Image Analyzing a Binary Image
------------------------ ------------------------
To analyze a binary image and get a complete summary of its headers and segments, use the :ref:`image_info <image-info>` command with the ``--version 2`` option. To analyze a binary image and get a complete summary of its headers and segments, use the :ref:`image_info <image-info>` command.

6
docs/en/esptool/basic-commands.rst
View File

@@ -225,15 +225,13 @@ By default, ``elf2image`` uses the sections in the ELF file to generate each seg
Output .bin Image Details: image_info Output .bin Image Details: image_info
------------------------------------- -------------------------------------
The ``image_info`` command outputs some information (load addresses, sizes, etc) about a ``.bin`` file created by ``elf2image``. Command also supports ``.hex`` file created by ``merge_bin`` command from supported ``.bin`` files. The ``image_info`` command outputs some information (load addresses, segment sizes, set flash size, frequency, and mode, extended header information, etc) about a ``.bin`` file created by ``elf2image``. Command also supports ``.hex`` file created by ``merge_bin`` command from supported ``.bin`` files.
To view more information about the image, such as set flash size, frequency and mode, or extended header information, use the ``--version 2`` option. This extended output will become the default in a future major release.
This information corresponds to the headers described in :ref:`image-format`. This information corresponds to the headers described in :ref:`image-format`.
:: ::
esptool.py image_info --version 2 my_esp_app.bin esptool.py image_info my_esp_app.bin
.. only:: not esp8266 .. only:: not esp8266

1
docs/en/index.rst
View File

@@ -51,5 +51,6 @@ More Information
Troubleshooting <troubleshooting> Troubleshooting <troubleshooting>
Contribute <contributing> Contribute <contributing>
Versions <versions> Versions <versions>
Migration Guide <migration-guide>
Resources <resources> Resources <resources>
About <about> About <about>

23
docs/en/migration-guide.rst Normal file
View File

@@ -0,0 +1,23 @@
.. _migration:
esptool.py ``v5`` Migration Guide
=================================
This document describes the breaking changes made to esptool.py in the major release ``v5``. It provides guidance on adapting existing workflows and scripts to ensure compatibility when updating from ``v4.*``.
``image_info`` Output Format Change
***********************************
The output format of the :ref:`image_info <image-info>` command has been **updated in v5**. The original format (``--version 1``) is **deprecated** and replaced by the updated format (``--version 2``). The ``--version`` argument has been **removed entirely**, and the new format is now the default and only option.
**Changes in the New Format:**
- Improved readability and structure
- Additional metadata fields for better debugging and analysis
- Consistent formatting for all ESP chip variants
**Migration Steps:**
1. Update any scripts or tools that parse the ``image_info`` output to use the new format
2. Remove any ``--version`` arguments from ``image_info`` commands

7
esptool/__init__.py
View File

@@ -402,13 +402,6 @@ def main(argv=None, esp=None):
parser_image_info.add_argument( parser_image_info.add_argument(
"filename", help="Image file to parse", action=AutoHex2BinAction "filename", help="Image file to parse", action=AutoHex2BinAction
) )
parser_image_info.add_argument(
"--version",
"-v",
help="Output format version (1 - legacy, 2 - extended)",
choices=["1", "2"],
default="1",
)
parser_make_image = subparsers.add_parser( parser_make_image = subparsers.add_parser(
"make_image", help="Create an application image from binary files" "make_image", help="Create an application image from binary files"

152
esptool/cmds.py
View File

@@ -769,7 +769,44 @@ def write_flash(esp, args):
def image_info(args): def image_info(args):
def v2(): print(f"File size: {get_file_size(args.filename)} (bytes)")
with open(args.filename, "rb") as f:
# magic number
try:
common_header = f.read(8)
magic = common_header[0]
except IndexError:
raise FatalError("File is empty")
if magic not in [
ESPLoader.ESP_IMAGE_MAGIC,
ESP8266V2FirmwareImage.IMAGE_V2_MAGIC,
]:
raise FatalError(
f"This is not a valid image (invalid magic number: {magic:#x})"
)
if args.chip == "auto":
try:
extended_header = f.read(16)
# append_digest, either 0 or 1
if extended_header[-1] not in [0, 1]:
raise FatalError("Append digest field not 0 or 1")
chip_id = int.from_bytes(extended_header[4:5], "little")
for rom in [n for n in ROM_LIST if n.CHIP_NAME != "ESP8266"]:
if chip_id == rom.IMAGE_CHIP_ID:
args.chip = rom.CHIP_NAME
break
else:
raise FatalError(f"Unknown image chip ID ({chip_id})")
except FatalError:
args.chip = "esp8266"
print(f"Detected image type: {args.chip.upper()}")
image = LoadFirmwareImage(args.chip, args.filename)
def get_key_from_value(dict, val): def get_key_from_value(dict, val):
"""Get key from value in dictionary""" """Get key from value in dictionary"""
for key, value in dict.items(): for key, value in dict.items():
@@ -778,12 +815,12 @@ def image_info(args):
return None return None
print() print()
title = "{} image header".format(args.chip.upper()) title = f"{args.chip.upper()} image header".format()
print(title) print(title)
print("=" * len(title)) print("=" * len(title))
print("Image version: {}".format(image.version)) print(f"Image version: {image.version}")
print( print(
"Entry point: {:#8x}".format(image.entrypoint) f"Entry point: {image.entrypoint:#8x}"
if image.entrypoint != 0 if image.entrypoint != 0
else "Entry point not set" else "Entry point not set"
) )
@@ -794,32 +831,32 @@ def image_info(args):
flash_s_bits = image.flash_size_freq & 0xF0 # high four bits flash_s_bits = image.flash_size_freq & 0xF0 # high four bits
flash_s = get_key_from_value(image.ROM_LOADER.FLASH_SIZES, flash_s_bits) flash_s = get_key_from_value(image.ROM_LOADER.FLASH_SIZES, flash_s_bits)
print( print(
"Flash size: {}".format(flash_s) f"Flash size: {flash_s}"
if flash_s is not None if flash_s is not None
else "WARNING: Invalid flash size ({:#02x})".format(flash_s_bits) else f"WARNING: Invalid flash size ({flash_s_bits:#02x})"
) )
# Flash frequency # Flash frequency
flash_fr_bits = image.flash_size_freq & 0x0F # low four bits flash_fr_bits = image.flash_size_freq & 0x0F # low four bits
flash_fr = get_key_from_value(image.ROM_LOADER.FLASH_FREQUENCY, flash_fr_bits) flash_fr = get_key_from_value(image.ROM_LOADER.FLASH_FREQUENCY, flash_fr_bits)
print( print(
"Flash freq: {}".format(flash_fr) f"Flash freq: {flash_fr}"
if flash_fr is not None if flash_fr is not None
else "WARNING: Invalid flash frequency ({:#02x})".format(flash_fr_bits) else f"WARNING: Invalid flash frequency ({flash_fr_bits:#02x})"
) )
# Flash mode # Flash mode
flash_mode = get_key_from_value(FLASH_MODES, image.flash_mode) flash_mode = get_key_from_value(FLASH_MODES, image.flash_mode)
print( print(
"Flash mode: {}".format(flash_mode.upper()) f"Flash mode: {flash_mode.upper()}"
if flash_mode is not None if flash_mode is not None
else "WARNING: Invalid flash mode ({})".format(image.flash_mode) else f"WARNING: Invalid flash mode ({image.flash_mode})"
) )
# Extended header (ESP32 and later only) # Extended header (ESP32 and later only)
if args.chip != "esp8266": if args.chip != "esp8266":
print() print()
title = "{} extended image header".format(args.chip.upper()) title = f"{args.chip.upper()} extended image header"
print(title) print(title)
print("=" * len(title)) print("=" * len(title))
print( print(
@@ -868,9 +905,7 @@ def image_info(args):
"Segment", "Length", "Load addr", "File offs", "Memory types" "Segment", "Length", "Load addr", "File offs", "Memory types"
) )
) )
print( print("{} {} {} {} {}".format("-" * 7, "-" * 7, "-" * 10, "-" * 10, "-" * 12))
"{} {} {} {} {}".format("-" * 7, "-" * 7, "-" * 10, "-" * 10, "-" * 12)
)
format_str = "{:7} {:#07x} {:#010x} {:#010x} {}" format_str = "{:7} {:#07x} {:#010x} {:#010x} {}"
app_desc = None app_desc = None
bootloader_desc = None bootloader_desc = None
@@ -884,9 +919,7 @@ def image_info(args):
# The DRAM segment starts with the esp_bootloader_desc_t struct # The DRAM segment starts with the esp_bootloader_desc_t struct
if len(seg.data) >= 80: if len(seg.data) >= 80:
bootloader_desc = seg.data[:80] bootloader_desc = seg.data[:80]
print( print(format_str.format(idx, len(seg.data), seg.addr, seg.file_offs, seg_name))
format_str.format(idx, len(seg.data), seg.addr, seg.file_offs, seg_name)
)
print() print()
# Footer # Footer
@@ -895,12 +928,12 @@ def image_info(args):
print("=" * len(title)) print("=" * len(title))
calc_checksum = image.calculate_checksum() calc_checksum = image.calculate_checksum()
print( print(
"Checksum: {:#02x} ({})".format( "Checksum: 0x{:02x} ({})".format(
image.checksum, image.checksum,
( (
"valid" "valid"
if image.checksum == calc_checksum if image.checksum == calc_checksum
else "invalid - calculated {:02x}".format(calc_checksum) else f"invalid - calculated 0x{calc_checksum:02x}"
), ),
) )
) )
@@ -912,7 +945,7 @@ def image_info(args):
hexify(image.calc_digest, uppercase=False), hexify(image.calc_digest, uppercase=False),
"valid" if is_valid else "invalid", "valid" if is_valid else "invalid",
) )
print("Validation hash: {}".format(digest_msg)) print(f"Validation hash: {digest_msg}")
except AttributeError: except AttributeError:
pass # ESP8266 image has no append_digest field pass # ESP8266 image has no append_digest field
@@ -982,85 +1015,6 @@ def image_info(args):
print(f'ESP-IDF: {idf_ver.decode("utf-8")}') print(f'ESP-IDF: {idf_ver.decode("utf-8")}')
print(f'Compile time: {date_time.decode("utf-8")}') print(f'Compile time: {date_time.decode("utf-8")}')
print(f"File size: {get_file_size(args.filename)} (bytes)")
with open(args.filename, "rb") as f:
# magic number
try:
common_header = f.read(8)
magic = common_header[0]
except IndexError:
raise FatalError("File is empty")
if magic not in [
ESPLoader.ESP_IMAGE_MAGIC,
ESP8266V2FirmwareImage.IMAGE_V2_MAGIC,
]:
raise FatalError(
f"This is not a valid image (invalid magic number: {magic:#x})"
)
if args.chip == "auto":
try:
extended_header = f.read(16)
# append_digest, either 0 or 1
if extended_header[-1] not in [0, 1]:
raise FatalError("Append digest field not 0 or 1")
chip_id = int.from_bytes(extended_header[4:5], "little")
for rom in [n for n in ROM_LIST if n.CHIP_NAME != "ESP8266"]:
if chip_id == rom.IMAGE_CHIP_ID:
args.chip = rom.CHIP_NAME
break
else:
raise FatalError(f"Unknown image chip ID ({chip_id})")
except FatalError:
args.chip = "esp8266"
print(f"Detected image type: {args.chip.upper()}")
image = LoadFirmwareImage(args.chip, args.filename)
if args.version == "2":
v2()
return
print("Image version: {}".format(image.version))
print(
"Entry point: {:8x}".format(image.entrypoint)
if image.entrypoint != 0
else "Entry point not set"
)
print("{} segments".format(len(image.segments)))
print()
idx = 0
for seg in image.segments:
idx += 1
segs = seg.get_memory_type(image)
seg_name = ",".join(segs)
print("Segment {}: {} [{}]".format(idx, seg, seg_name))
calc_checksum = image.calculate_checksum()
print(
"Checksum: {:02x} ({})".format(
image.checksum,
(
"valid"
if image.checksum == calc_checksum
else "invalid - calculated {:02x}".format(calc_checksum)
),
)
)
try:
digest_msg = "Not appended"
if image.append_digest:
is_valid = image.stored_digest == image.calc_digest
digest_msg = "{} ({})".format(
hexify(image.calc_digest, uppercase=False),
"valid" if is_valid else "invalid",
)
print("Validation Hash: {}".format(digest_msg))
except AttributeError:
pass # ESP8266 image has no append_digest field
def make_image(args): def make_image(args):
print("Creating {} image...".format(args.chip)) print("Creating {} image...".format(args.chip))

65
test/test_image_info.py
View File

@@ -25,7 +25,7 @@ def read_image(filename):
@pytest.mark.host_test @pytest.mark.host_test
class TestImageInfo: class TestImageInfo:
def run_image_info(self, chip, file, version=None): def run_image_info(self, chip, file):
"""Runs image_info on a binary file. """Runs image_info on a binary file.
Returns the command output. Returns the command output.
Filenames are relative to the 'test/images' directory. Filenames are relative to the 'test/images' directory.
@@ -39,8 +39,6 @@ class TestImageInfo:
chip, chip,
"image_info", "image_info",
] ]
if version is not None:
cmd += ["--version", str(version)]
# if path was passed use the whole path # if path was passed use the whole path
# if file does not exists try to use file from IMAGES_DIR directory # if file does not exists try to use file from IMAGES_DIR directory
cmd += [file] if os.path.isfile(file) else ["".join([IMAGES_DIR, os.sep, file])] cmd += [file] if os.path.isfile(file) else ["".join([IMAGES_DIR, os.sep, file])]
@@ -58,28 +56,8 @@ class TestImageInfo:
print(e.output) print(e.output)
raise raise
def test_v1_esp32(self): def test_esp32c3(self):
out = self.run_image_info("esp32", "bootloader_esp32.bin") out = self.run_image_info("esp32c3", "bootloader_esp32c3.bin")
assert "Entry point: 4009816c" in out, "Wrong entry point"
assert "Checksum: 83 (valid)" in out, "Invalid checksum"
assert "4 segments" in out, "Wrong number of segments"
assert (
"Segment 3: len 0x01068 load 0x40078000 file_offs 0x00000b64 [CACHE_APP]"
in out
), "Wrong segment info"
def test_v1_esp8266(self):
out = self.run_image_info("esp8266", ESP8266_BIN)
assert "Image version: 1" in out, "Wrong image version"
assert "Entry point: 40101844" in out, "Wrong entry point"
assert "Checksum: 6b (valid)" in out, "Invalid checksum"
assert "1 segments" in out, "Wrong number of segments"
assert (
"Segment 1: len 0x00014 load 0x40100000 file_offs 0x00000008 [IRAM]" in out
), "Wrong segment info"
def test_v2_esp32c3(self):
out = self.run_image_info("esp32c3", "bootloader_esp32c3.bin", "2")
# Header # Header
assert "Entry point: 0x403c0000" in out, "Wrong entry point" assert "Entry point: 0x403c0000" in out, "Wrong entry point"
@@ -117,8 +95,8 @@ class TestImageInfo:
if ex_hdr[15] == 1: # Hash appended if ex_hdr[15] == 1: # Hash appended
assert "Validation hash: 4faeab1bd3fd" in out, "Invalid hash" assert "Validation hash: 4faeab1bd3fd" in out, "Invalid hash"
def test_v2_esp8266(self): def test_esp8266(self):
out = self.run_image_info("esp8266", ESP8266_BIN, "2") out = self.run_image_info("esp8266", ESP8266_BIN)
assert "Image version: 1" in out, "Wrong image version" assert "Image version: 1" in out, "Wrong image version"
assert "Entry point: 0x40101844" in out, "Wrong entry point" assert "Entry point: 0x40101844" in out, "Wrong entry point"
assert "Flash size: 512KB" in out, "Wrong flash size" assert "Flash size: 512KB" in out, "Wrong flash size"
@@ -129,45 +107,40 @@ class TestImageInfo:
assert "0 0x00014 0x40100000 0x00000008 IRAM" in out, "Wrong segment info" assert "0 0x00014 0x40100000 0x00000008 IRAM" in out, "Wrong segment info"
def test_image_type_detection(self): def test_image_type_detection(self):
# ESP8266, version 1 and 2 # ESP8266
out = self.run_image_info("auto", ESP8266_BIN, "1") out = self.run_image_info("auto", ESP8266_BIN)
assert "Detected image type: ESP8266" in out
assert "Segment 1: len 0x00014" in out
out = self.run_image_info("auto", ESP8266_BIN, "2")
assert "Detected image type: ESP8266" in out assert "Detected image type: ESP8266" in out
assert "Flash freq: 40m" in out assert "Flash freq: 40m" in out
out = self.run_image_info("auto", "esp8266_deepsleep.bin", "2") out = self.run_image_info("auto", "esp8266_deepsleep.bin")
assert "Detected image type: ESP8266" in out assert "Detected image type: ESP8266" in out
# ESP32, with and without detection # ESP32, with and without detection
out = self.run_image_info("auto", "bootloader_esp32.bin", "2") out = self.run_image_info("auto", "bootloader_esp32.bin")
assert "Detected image type: ESP32" in out assert "Detected image type: ESP32" in out
out = self.run_image_info( out = self.run_image_info("auto", "ram_helloworld/helloworld-esp32_edit.bin")
"auto", "ram_helloworld/helloworld-esp32_edit.bin", "2"
)
assert "Detected image type: ESP32" in out assert "Detected image type: ESP32" in out
out = self.run_image_info("esp32", "bootloader_esp32.bin", "2") out = self.run_image_info("esp32", "bootloader_esp32.bin")
assert "Detected image type: ESP32" not in out assert "Detected image type: ESP32" not in out
# ESP32-C3 # ESP32-C3
out = self.run_image_info("auto", "bootloader_esp32c3.bin", "2") out = self.run_image_info("auto", "bootloader_esp32c3.bin")
assert "Detected image type: ESP32-C3" in out assert "Detected image type: ESP32-C3" in out
# ESP32-S3 # ESP32-S3
out = self.run_image_info("auto", "esp32s3_header.bin", "2") out = self.run_image_info("auto", "esp32s3_header.bin")
assert "Detected image type: ESP32-S3" in out assert "Detected image type: ESP32-S3" in out
def test_invalid_image_type_detection(self, capsys): def test_invalid_image_type_detection(self, capsys):
with pytest.raises(subprocess.CalledProcessError): with pytest.raises(subprocess.CalledProcessError):
# Invalid image # Invalid image
self.run_image_info("auto", "one_kb.bin", "2") self.run_image_info("auto", "one_kb.bin")
assert ( assert (
"This is not a valid image (invalid magic number: 0xed)" "This is not a valid image (invalid magic number: 0xed)"
in capsys.readouterr().out in capsys.readouterr().out
) )
def test_application_info(self): def test_application_info(self):
out = self.run_image_info("auto", "esp_idf_blink_esp32s2.bin", "2") out = self.run_image_info("auto", "esp_idf_blink_esp32s2.bin")
assert "Application information" in out assert "Application information" in out
assert "Project name: blink" in out assert "Project name: blink" in out
assert "App version: qa-test-v5.0-20220830-4-g4532e6" in out assert "App version: qa-test-v5.0-20220830-4-g4532e6" in out
@@ -178,15 +151,15 @@ class TestImageInfo:
assert "cd0dab311febb0a3ea79eaa223ac2b0" in out assert "cd0dab311febb0a3ea79eaa223ac2b0" in out
assert "ESP-IDF: v5.0-beta1-427-g4532e6e0b2-dirt" in out assert "ESP-IDF: v5.0-beta1-427-g4532e6e0b2-dirt" in out
# No application info in image # No application info in image
out = self.run_image_info("auto", "bootloader_esp32.bin", "2") out = self.run_image_info("auto", "bootloader_esp32.bin")
assert "Application information" not in out assert "Application information" not in out
out = self.run_image_info("auto", ESP8266_BIN, "2") out = self.run_image_info("auto", ESP8266_BIN)
assert "Application information" not in out assert "Application information" not in out
def test_bootloader_info(self): def test_bootloader_info(self):
# This bootloader binary is built from "hello_world" project # This bootloader binary is built from "hello_world" project
# with default settings, IDF version is v5.2. # with default settings, IDF version is v5.2.
out = self.run_image_info("esp32", "bootloader_esp32_v5_2.bin", "2") out = self.run_image_info("esp32", "bootloader_esp32_v5_2.bin")
assert "File size: 26768 (bytes)" in out assert "File size: 26768 (bytes)" in out
assert "Bootloader information" in out assert "Bootloader information" in out
assert "Bootloader version: 1" in out assert "Bootloader version: 1" in out
@@ -219,7 +192,7 @@ class TestImageInfo:
fd, file = tempfile.mkstemp(suffix=".hex") fd, file = tempfile.mkstemp(suffix=".hex")
try: try:
convert_bin2hex(file) convert_bin2hex(file)
out = self.run_image_info("esp32", file, "2") out = self.run_image_info("esp32", file)
assert "File size: 26768 (bytes)" in out assert "File size: 26768 (bytes)" in out
assert "Bootloader information" in out assert "Bootloader information" in out
assert "Bootloader version: 1" in out assert "Bootloader version: 1" in out

4
test/test_imagegen.py
View File

@@ -128,11 +128,11 @@ class BaseTestCase:
print(e.output) print(e.output)
raise raise
assert re.search( assert re.search(
r"Checksum: [a-fA-F0-9]{2} \(valid\)", output r"Checksum: 0x[a-fA-F0-9]{2} \(valid\)", output
), "Checksum calculation should be valid" ), "Checksum calculation should be valid"
if assert_sha: if assert_sha:
assert re.search( assert re.search(
r"Validation Hash: [a-fA-F0-9]{64} \(valid\)", output r"Validation hash: [a-fA-F0-9]{64} \(valid\)", output
), "SHA256 should be valid" ), "SHA256 should be valid"
assert ( assert (
"warning" not in output.lower() "warning" not in output.lower()