espressif/esptool
1
0
Fork 0
mirror of https://github.com/espressif/esptool.git synced 2025-10-16 23:06: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
------------------------
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
-------------------------------------
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.
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.
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.
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

1
docs/en/index.rst
View File

@@ -51,5 +51,6 @@ More Information
Troubleshooting <troubleshooting>
Contribute <contributing>
Versions <versions>
Migration Guide <migration-guide>
Resources <resources>
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(
"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(
"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 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):
"""Get key from value in dictionary"""
for key, value in dict.items():
@@ -778,12 +815,12 @@ def image_info(args):
return None
print()
title = "{} image header".format(args.chip.upper())
title = f"{args.chip.upper()} image header".format()
print(title)
print("=" * len(title))
print("Image version: {}".format(image.version))
print(f"Image version: {image.version}")
print(
"Entry point: {:#8x}".format(image.entrypoint)
f"Entry point: {image.entrypoint:#8x}"
if image.entrypoint != 0
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 = get_key_from_value(image.ROM_LOADER.FLASH_SIZES, flash_s_bits)
print(
"Flash size: {}".format(flash_s)
f"Flash size: {flash_s}"
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_fr_bits = image.flash_size_freq & 0x0F # low four bits
flash_fr = get_key_from_value(image.ROM_LOADER.FLASH_FREQUENCY, flash_fr_bits)
print(
"Flash freq: {}".format(flash_fr)
f"Flash freq: {flash_fr}"
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 = get_key_from_value(FLASH_MODES, image.flash_mode)
print(
"Flash mode: {}".format(flash_mode.upper())
f"Flash mode: {flash_mode.upper()}"
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)
if args.chip != "esp8266":
print()
title = "{} extended image header".format(args.chip.upper())
title = f"{args.chip.upper()} extended image header"
print(title)
print("=" * len(title))
print(
@@ -868,9 +905,7 @@ def image_info(args):
"Segment", "Length", "Load addr", "File offs", "Memory types"
)
)
print(
"{} {} {} {} {}".format("-" * 7, "-" * 7, "-" * 10, "-" * 10, "-" * 12)
)
print("{} {} {} {} {}".format("-" * 7, "-" * 7, "-" * 10, "-" * 10, "-" * 12))
format_str = "{:7} {:#07x} {:#010x} {:#010x} {}"
app_desc = None
bootloader_desc = None
@@ -884,9 +919,7 @@ def image_info(args):
# The DRAM segment starts with the esp_bootloader_desc_t struct
if len(seg.data) >= 80:
bootloader_desc = seg.data[:80]
print(
format_str.format(idx, len(seg.data), seg.addr, seg.file_offs, seg_name)
)
print(format_str.format(idx, len(seg.data), seg.addr, seg.file_offs, seg_name))
print()
# Footer
@@ -895,12 +928,12 @@ def image_info(args):
print("=" * len(title))
calc_checksum = image.calculate_checksum()
print(
"Checksum: {:#02x} ({})".format(
"Checksum: 0x{:02x} ({})".format(
image.checksum,
(
"valid"
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),
"valid" if is_valid else "invalid",
)
print("Validation hash: {}".format(digest_msg))
print(f"Validation hash: {digest_msg}")
except AttributeError:
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'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):
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
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.
Returns the command output.
Filenames are relative to the 'test/images' directory.
@@ -39,8 +39,6 @@ class TestImageInfo:
chip,
"image_info",
]
if version is not None:
cmd += ["--version", str(version)]
# if path was passed use the whole path
# 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])]
@@ -58,28 +56,8 @@ class TestImageInfo:
print(e.output)
raise
def test_v1_esp32(self):
out = self.run_image_info("esp32", "bootloader_esp32.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")
def test_esp32c3(self):
out = self.run_image_info("esp32c3", "bootloader_esp32c3.bin")
# Header
assert "Entry point: 0x403c0000" in out, "Wrong entry point"
@@ -117,8 +95,8 @@ class TestImageInfo:
if ex_hdr[15] == 1: # Hash appended
assert "Validation hash: 4faeab1bd3fd" in out, "Invalid hash"
def test_v2_esp8266(self):
out = self.run_image_info("esp8266", ESP8266_BIN, "2")
def test_esp8266(self):
out = self.run_image_info("esp8266", ESP8266_BIN)
assert "Image version: 1" in out, "Wrong image version"
assert "Entry point: 0x40101844" in out, "Wrong entry point"
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"
def test_image_type_detection(self):
# ESP8266, version 1 and 2
out = self.run_image_info("auto", ESP8266_BIN, "1")
assert "Detected image type: ESP8266" in out
assert "Segment 1: len 0x00014" in out
out = self.run_image_info("auto", ESP8266_BIN, "2")
# ESP8266
out = self.run_image_info("auto", ESP8266_BIN)
assert "Detected image type: ESP8266" 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
# 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
out = self.run_image_info(
"auto", "ram_helloworld/helloworld-esp32_edit.bin", "2"
)
out = self.run_image_info("auto", "ram_helloworld/helloworld-esp32_edit.bin")
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
# 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
# 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
def test_invalid_image_type_detection(self, capsys):
with pytest.raises(subprocess.CalledProcessError):
# Invalid image
self.run_image_info("auto", "one_kb.bin", "2")
self.run_image_info("auto", "one_kb.bin")
assert (
"This is not a valid image (invalid magic number: 0xed)"
in capsys.readouterr().out
)
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 "Project name: blink" 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 "ESP-IDF: v5.0-beta1-427-g4532e6e0b2-dirt" in out
# 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
out = self.run_image_info("auto", ESP8266_BIN, "2")
out = self.run_image_info("auto", ESP8266_BIN)
assert "Application information" not in out
def test_bootloader_info(self):
# This bootloader binary is built from "hello_world" project
# 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 "Bootloader information" in out
assert "Bootloader version: 1" in out
@@ -219,7 +192,7 @@ class TestImageInfo:
fd, file = tempfile.mkstemp(suffix=".hex")
try:
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 "Bootloader information" in out
assert "Bootloader version: 1" in out

4
test/test_imagegen.py
View File

@@ -128,11 +128,11 @@ class BaseTestCase:
print(e.output)
raise
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"
if assert_sha:
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"
assert (
"warning" not in output.lower()