Merge branch 'espressif:master' into pioarduino

Author: Jason2866

CHANGELOG.md

@@ -20,6 +20,22 @@
 </div>
 <hr>
 
+## v5.0.2 (2025-07-30)
+
+### 🐛 Bug Fixes
+
+- **esp32-c3**: Disable flasher stub when Secure Boot is active *(Radim Karniš - 1f1ea9a)*
+- **esp32-s3**: Allow stub flasher execution with active Secure Boot *(Radim Karniš - 7ba285b)*
+- **espefuse**: Handle error in burn-efuse command when no arguments are provided *(Peter Dragun - 0f32306)*
+- Fix buffering issues with CP2102 converter causing connection failures *(Jaroslav Burian - 5338ea0)*
+- Fix compatibility with Click 8.2.0+ *(Peter Dragun - 524825e)*
+- Fix --port-filter argument parsing *(Peter Dragun - b53a16c)*
+
+### 🔧 Code Refactoring
+
+- **elf2image**: Use common MMU page size configuration function for ESP32-H4 *(Jaroslav Burian - 977ff44)*
+
+
 ## v5.0.1 (2025-07-15)
 
 ### 🐛 Bug Fixes

espefuse/efuse/base_operations.py

@@ -23,12 +23,22 @@
 from .emulate_efuse_controller_base import EmulateEfuseControllerBase
 
 
-class EfuseValuePairArg(click.Argument):
+class EfuseArgument(click.Argument):
+    def make_metavar(self, ctx: click.Context | None = None) -> str:
+        """Compatibility layer for Click 8.2.0+; which now requires a ctx parameter."""
+        try:
+            return super().make_metavar(ctx)  # type: ignore
+        except TypeError:
+            # Fall back to the old signature (pre-Click 8.2.0)
+            return super().make_metavar()  # type: ignore
+
+
+class EfuseValuePairArg(EfuseArgument):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
-    def make_metavar(self) -> str:
-        return f"[{super().make_metavar()}] ..."
+    def make_metavar(self, ctx=None) -> str:
+        return f"[{super().make_metavar(ctx)}] ..."
 
     def type_cast_value(self, ctx: click.Context, value: list[str]):
         return self.type.convert(value, None, ctx)
@@ -52,7 +62,9 @@ def check_efuse_name(efuse_name: str):
 
         # Handle single value case (eFuse name only)
         efuse_value_pairs = {}
-        if len(value) > 1:
+        if len(value) == 0:
+            raise click.BadParameter("Missing eFuse name and value pair.")
+        elif len(value) > 1:
             if len(value) % 2:
                 raise click.BadParameter(
                     f"The list does not have a valid pair (name value) {value}"
@@ -82,17 +94,17 @@ def convert(self, value: str, param: click.Parameter | None, ctx: click.Context)
         return base_fields.CheckArgValue(ctx.obj["efuses"], "CUSTOM_MAC")(value)
 
 
-class TupleParameter(click.Argument):
+class TupleParameter(EfuseArgument):
     def __init__(self, *args, **kwargs):
         self.max_arity = kwargs.pop("max_arity", None)
         super().__init__(*args, **kwargs)
 
-    def make_metavar(self) -> str:
+    def make_metavar(self, ctx=None) -> str:
         if self.nargs == 1:
-            return super().make_metavar()  # type: ignore
+            return super().make_metavar(ctx)  # type: ignore
         if self.max_arity is None:
-            return f"[{super().make_metavar()}] ..."
-        return f"[{super().make_metavar()}] ... (max {self.max_arity} groups)"
+            return f"[{super().make_metavar(ctx)}] ..."
+        return f"[{super().make_metavar(ctx)}] ... (max {self.max_arity} groups)"
 
     def type_cast_value(self, ctx: click.Context, value: list[str]) -> tuple[Any, ...]:
         # This is by default eating all options, so we need to check for help option

esptool/__init__.py

@@ -31,7 +31,7 @@
     "write_mem",
 ]
 
-__version__ = "5.0.1"
+__version__ = "5.0.2"
 
 import os
 import shlex
@@ -930,11 +930,6 @@ def erase_flash_cli(ctx, force, **kwargs):
 )
 @click.argument("address", type=AnyIntType())
 @click.argument("size", type=AutoSizeType())
-@click.option(
-    "--force",
-    is_flag=True,
-    help="Erase region even if security features are enabled. Use with caution!",
-)
 @add_spi_connection_arg
 @click.pass_context
 def erase_region_cli(ctx, address, size, force, **kwargs):

esptool/bin_image.py

@@ -710,7 +710,7 @@ class ESP32FirmwareImage(BaseFirmwareImage):
     can be placed in the normal image (just @ MMU page size padded offsets).
     """
 
-    ROM_LOADER = ESP32ROM
+    ROM_LOADER: type[ESPLoader] = ESP32ROM
 
     # ROM bootloader will read the wp_pin field if SPI flash
     # pins are remapped via flash. IDF actually enables QIO only
@@ -1211,7 +1211,7 @@ class ESP32C2FirmwareImage(ESP32FirmwareImage):
 class ESP32C6FirmwareImage(ESP32FirmwareImage):
     """ESP32C6 Firmware Image almost exactly the same as ESP32FirmwareImage"""
 
-    ROM_LOADER = ESP32C6ROM
+    ROM_LOADER: type[ESPLoader] = ESP32C6ROM
     MMU_PAGE_SIZE_CONF = (8192, 16384, 32768, 65536)
 
 
@@ -1236,19 +1236,11 @@ class ESP32C5FirmwareImage(ESP32FirmwareImage):
 ESP32C5ROM.BOOTLOADER_IMAGE = ESP32C5FirmwareImage
 
 
-class ESP32H4FirmwareImage(ESP32FirmwareImage):
-    """ESP32H4 Firmware Image almost exactly the same as ESP32FirmwareImage"""
+class ESP32H4FirmwareImage(ESP32C6FirmwareImage):
+    """ESP32H4 Firmware Image almost exactly the same as ESP32C6FirmwareImage"""
 
     ROM_LOADER = ESP32H4ROM
 
-    def set_mmu_page_size(self, size):
-        if size not in [8192, 16384, 32768, 65536]:
-            raise FatalError(
-                "{} bytes is not a valid ESP32-H4 page size, "
-                "select from 64KB, 32KB, 16KB, 8KB.".format(size)
-            )
-        self.IROM_ALIGN = size
-
 
 ESP32H4ROM.BOOTLOADER_IMAGE = ESP32H4FirmwareImage
 

esptool/cli_util.py

@@ -155,7 +155,9 @@ class AddrFilenamePairType(click.Path):
 
     name = "addr-filename-pair"
 
-    def get_metavar(self, param):
+    def get_metavar(
+        self, param: click.Parameter | None, ctx: click.Context | None = None
+    ):
         return "<address> <filename>"
 
     def convert(
@@ -294,13 +296,23 @@ def __init__(self, *args, **kwargs):
         self._eat_all_parser = None
         # Set the metavar dynamically based on the type's metavar
         if self.type and hasattr(self.type, "name"):
-            self.metavar = f"[{self.type.get_metavar(None) or self.type.name.upper()}]"
+            self.metavar = f"[{self._get_metavar() or self.type.name.upper()}]"
+
+    def _get_metavar(self):
+        """Get the metavar for the option. Wrapper for compatibility reasons.
+        In Click 8.2.0+, the `get_metavar` requires new parameter `ctx`.
+        """
+        try:
+            ctx = click.get_current_context(silent=True)
+            return self.type.get_metavar(None, ctx)
+        except TypeError:
+            return self.type.get_metavar(None)
 
     def add_to_parser(self, parser, ctx):
         def parser_process(value, state):
             # Method to hook into the parser.process
             done = False
-            value = [value]
+            values = [value]
             # Grab everything up to the next option/command
             while state.rargs and not done:
                 for prefix in self._eat_all_parser.prefixes:
@@ -310,10 +322,16 @@ def parser_process(value, state):
                 if state.rargs[0] in self._commands_list:
                     done = True
                 if not done:
-                    value.append(state.rargs.pop(0))
+                    values.append(state.rargs.pop(0))
 
             # Call the original parser process method on the rest of the arguments
-            self._previous_parser_process(value, state)
+            if self.multiple:
+                # If multiple options can be used, Click does not support extending the
+                # value; as the 'value' is list, we need to process each item separately
+                for v in values:
+                    self._previous_parser_process(v, state)
+            else:
+                self._previous_parser_process(values, state)
 
         retval = super(OptionEatAll, self).add_to_parser(parser, ctx)
         for name in self.opts:
@@ -379,7 +397,7 @@ def arg_auto_int(x: str) -> int:
 
 
 def parse_port_filters(
-    value: list[str],
+    value: tuple[str],
 ) -> tuple[list[int], list[int], list[str], list[str]]:
     """Parse port filter arguments into separate lists for each filter type"""
     filterVids = []
@@ -389,7 +407,7 @@ def parse_port_filters(
     for f in value:
         kvp = f.split("=")
         if len(kvp) != 2:
-            FatalError("Option --port-filter argument must consist of key=value.")
+            raise FatalError("Option --port-filter argument must consist of key=value.")
         if kvp[0] == "vid":
             filterVids.append(arg_auto_int(kvp[1]))
         elif kvp[0] == "pid":

esptool/cmds.py

@@ -1626,6 +1626,11 @@ def run_stub(esp: ESPLoader) -> ESPLoader:
             "Stub flasher is not supported in Secure Download Mode, "
             "it has been disabled. Set --no-stub to suppress this warning."
         )
+    elif esp.CHIP_NAME == "ESP32-C3" and esp.get_secure_boot_enabled():
+        log.warning(
+            "Stub flasher is not supported on ESP32-C3 with Secure Boot, "
+            "it has been disabled. Set --no-stub to suppress this warning."
+        )
     elif not esp.IS_STUB and esp.stub_is_disabled:
         log.warning(
             "Stub flasher has been disabled for compatibility, "

esptool/loader.py

@@ -502,10 +502,35 @@ def command(
                 if op is None or op_ret == op:
                     return val, data
                 if byte(data, 0) != 0 and byte(data, 1) == self.ROM_INVALID_RECV_MSG:
-                    # Unsupported read_reg can result in
+
+                    def drain_input_buffer(buffering_time=0.2):
+                        """
+                        Actively drain the input buffer by reading data
+                        for a specified time. Simple approach for some
+                        drivers that have issues with the buffer flushing.
+
+                        Args:
+                            buffering_time: Time in seconds to wait for
+                            the buffer to fill.
+                        """
+                        time.sleep(buffering_time)
+                        original_timeout = self._port.timeout
+                        # Set a very short timeout for draining
+                        self._port.timeout = 0.001
+
+                        # Unsupported command response is sent 8 times and has
+                        # 14 bytes length including delimiter 0xC0 bytes.
+                        # At least part of it is read as a command response,
+                        # but to be safe, read it all.
+                        self._port.read(14 * 8)
+
+                        # Restore original timeout
+                        self._port.timeout = original_timeout
+                        self.flush_input()
+
+                    # Unsupported command can result in
                     # more than one error response for some reason
-                    time.sleep(0.2)  # Wait for input buffer to fill
-                    self.flush_input()  # Flush input buffer of hanging response
+                    drain_input_buffer(0.2)
                     raise UnsupportedCommandError(self, op)
 
         finally:
@@ -1259,6 +1284,10 @@ def run_stub(self, stub: StubFlasher | None = None) -> "ESPLoader":
             log.print("Stub flasher is already running. No upload is necessary.")
             return self.STUB_CLASS(self) if self.STUB_CLASS is not None else self
 
+        secure_boot_workflow = (
+            self.CHIP_NAME == "ESP32-S3" and self.get_secure_boot_enabled()
+        )
+
         # Upload
         log.print("Uploading stub flasher...")
         for field in [stub.text, stub.data]:
@@ -1271,8 +1300,24 @@ def run_stub(self, stub: StubFlasher | None = None) -> "ESPLoader":
                     from_offs = seq * self.ESP_RAM_BLOCK
                     to_offs = from_offs + self.ESP_RAM_BLOCK
                     self.mem_block(field[from_offs:to_offs], seq)
+
         log.print("Running stub flasher...")
-        self.mem_finish(stub.entry)
+        if not secure_boot_workflow:
+            self.mem_finish(stub.entry)
+        else:
+            # Bug in ESP32-S3 ROM prevents stub execution if secure boot is enabled
+            # Hijack the `read` function in ROM to point to the stub entrypoint
+            # got with GDB - p &rom_spiflash_legacy_funcs.read
+            rom_spiflash_legacy_funcs_read_ptr = 0x3FCEF688
+            self.mem_finish(0)  # Finish uploading to RAM but don't run the stub yet
+            stored_read_pointer = self.read_reg(rom_spiflash_legacy_funcs_read_ptr)
+            self.write_reg(rom_spiflash_legacy_funcs_read_ptr, stub.entry)
+            self.command(  # Trigger the `read` in ROM to jump to the stub entrypoint
+                self.ESP_CMDS["READ_FLASH_SLOW"],
+                struct.pack("<II", 0, 0),
+                wait_response=False,
+            )
+
         try:
             p = self.read()
         except StopIteration:
@@ -1284,6 +1329,9 @@ def run_stub(self, stub: StubFlasher | None = None) -> "ESPLoader":
 
         if p != b"OHAI":
             raise FatalError(f"Failed to start stub flasher. Unexpected response: {p}")
+        if secure_boot_workflow:
+            # Restore the original `read` function pointer
+            self.write_reg(rom_spiflash_legacy_funcs_read_ptr, stored_read_pointer)
         log.stage(finish=True)
         log.print("Stub flasher running.")
         return self.STUB_CLASS(self) if self.STUB_CLASS is not None else self

pyproject.toml

@@ -38,7 +38,7 @@
         "PyYAML>=5.1",
         "intelhex",
         "rich_click",
-        "click<8.2.0",
+        "click<9",
     ]
 
 [project.urls]
@@ -78,7 +78,7 @@
 
 [tool.commitizen]
     name = "czespressif"
-    version = "5.0.1"
+    version = "5.0.2"
     update_changelog_on_bump = true
     tag_format = "v$version"
     changelog_start_rev = "v4.2.1"