Mirror/squeezelite-esp32
1
0
Fork 0
mirror of https://github.com/sle118/squeezelite-esp32.git synced 2026-03-14 14:32:44 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
refactoring
squeezelite-esp32/documentation/IDF55_REMEDIATION_IMPACTS.md

11 KiB
Raw Permalink Blame History

ESP-IDF v5.5 Migration Remediation Impacts

Date: 2026-02-11
Branch: refactoring
Scope: Container-first migration and iterative build remediation on ESP-IDF v5.5 baseline.

Purpose

This document records the impacts that have already been remediated during the migration to the new container/IDF baseline.
It focuses on remediation outcomes (what broke, what was fixed, and where).

Remediated Impact Areas

1) Container/CI baseline alignment

  • Impact:
    • Firmware and UI workflows were not aligned on a single ESP-IDF/container baseline.
  • Mitigation:
    • Unified workflows and docker tooling toward the IDF v5.5 container baseline.
    • Updated contributor guidance to container-first while preserving native setup path.
  • Primary files:
    • .github/workflows/Platform_build.yml
    • .github/workflows/CrossBuild.yml
    • .github/workflows/esp-idf-v4.3-build.yml
    • .github/workflows/web_deploy.yml
    • Dockerfile
    • docker/build_tools.py
    • README.md

2) Component dependency and CMake modernization

  • Impact:
    • Legacy component dependency assumptions caused configure/build incompatibilities on IDF 5.5.
  • Mitigation:
    • Added/updated component requirements and removed obsolete dependencies.
    • Updated component-level REQUIRES/PRIV_REQUIRES for headers now split into dedicated components.
  • Primary files:
    • main/idf_component.yml
    • main/CMakeLists.txt
    • components/squeezelite/CMakeLists.txt
    • components/services/CMakeLists.txt
    • components/metrics/CMakeLists.txt
    • components/platform_console/CMakeLists.txt
    • components/platform_console/app_recovery/CMakeLists.txt
    • components/esp_http_server/CMakeLists.txt

3) Ethernet stack migration (SPI + RMII + netif integration)

  • Impact:
    • IDF 5.5 changed Ethernet init/config APIs and SPI-Ethernet setup flow.
  • Mitigation:
    • Updated SPI Ethernet config macros to new signatures.
    • Migrated RMII MAC/PHY constructor usage.
    • Updated esp_mac usage and timer callback signatures in Ethernet manager.
    • Removed obsolete SPI device attach path where IDF now handles internals in driver flow.
  • Primary files:
    • components/wifi-manager/network_driver_W5500.c
    • components/wifi-manager/network_driver_DM9051.c
    • components/wifi-manager/network_driver_LAN8720.c
    • components/wifi-manager/network_ethernet.c
    • components/wifi-manager/network_services.h
    • components/wifi-manager/network_manager.h
    • components/raop/util.c
    • components/squeezelite-ota/protocol_examples_common.h
    • components/tools/tcpip_adapter_compat.h

4) FreeRTOS legacy API/type removal

  • Impact:
    • Build failures due to removed/deprecated compatibility symbols (portTICK_RATE_MS, legacy queue/tick types, callback signatures).
  • Mitigation:
    • Replaced portTICK_RATE_MS with portTICK_PERIOD_MS.
    • Updated queue/tick types and timer callback prototypes to current FreeRTOS API.
  • Primary files:
    • components/services/led.c
    • components/services/buttons.c
    • components/services/battery.c
    • components/services/audio_controls.c
    • components/services/infrared.c
    • components/services/gpio_exp.c
    • components/platform_console/cmd_i2ctools.c
    • components/platform_console/cmd_wifi.c
    • components/services/services.c
    • components/driver_bt/bt_app_core.c
    • components/driver_bt/bt_app_source.c

5) GPIO/pad selection API updates

  • Impact:
    • Legacy GPIO pad selection symbols produced missing symbol/implicit declaration failures on IDF 5.5.
  • Mitigation:
    • Migrated to esp_rom_gpio_pad_select_gpio(...) path and aligned wrapper macro behavior.
    • Added explicit include coverage where needed.
  • Primary files:
    • components/services/gpio_exp.h
    • components/services/gpio_exp.c
    • components/services/services.c
    • components/squeezelite/output_i2s.c
    • components/display/SSD1675.c

6) Strict compiler checks and type-width corrections (-Werror)

  • Impact:
    • New toolchain and stricter flags surfaced format-string and pointer-width mismatches.
  • Mitigation:
    • Fixed printf/snprintf/sscanf format mismatches.
    • Switched to width-safe intermediates/casts and correct callback argument types.
    • Corrected size-type usage in SPIFFS info reporting and metadata parsing.
  • Primary files:
    • components/services/monitor.c
    • components/tools/tools_spiffs_utils.cpp
    • components/tools/tools.c
    • components/squeezelite/alac.c
    • components/squeezelite/helix-aac.c
    • components/squeezelite/mad.c
    • components/squeezelite/decode_external.c
    • components/raop/raop.c (partial type-format cleanup)

7) Header hygiene and removed transitive includes

  • Impact:
    • IDF 5.5 no longer transitively includes some headers (for example MAC APIs), and some internal/private headers are no longer valid.
  • Mitigation:
    • Added explicit includes where required (esp_mac.h, etc.).
    • Removed stale/internal header use in multiple components.
  • Primary files:
    • components/wifi-manager/network_ethernet.c
    • components/tools/tools.c
    • components/squeezelite/embedded.c
    • components/tools/bootstate.cpp
    • components/services/accessors.c
    • components/telnet/telnet.c
    • components/services/messaging.c
    • components/tools/trace.c

8) Protobuf/Nanopb tooling stability in container

  • Impact:
    • Generator and plugin execution flow had environment/shebang/version conflicts in the new container baseline.
  • Mitigation:
    • Fixed Python shebangs for container runtime.
    • Improved protobuf package checks and version constraints.
    • Corrected nanopb/protoc lookup behavior to prefer valid compiler binary.
  • Primary files:
    • tools/protoc_utils/check_python_packages.py
    • tools/protoc_utils/ProtocParser.py
    • tools/protoc_utils/parse_bin.py
    • tools/protoc_utils/generate_bin.py
    • tools/protoc_utils/protoc-gen-defaults.py
    • tools/protoc_utils/protoc-gen-dump.py
    • tools/protoc_utils/protoc-gen-json.py
    • tools/protoc_utils/protoc-gen-options.py
    • components/spotify/cspot/bell/external/nanopb/extra/FindNanopb.cmake

9) SPIFFS/path and partition constraints

  • Impact:
    • Asset/image generation and partition validation failed under new checks.
  • Mitigation:
    • Increased SPIFFS object-name length where required.
    • Updated partition flags to satisfy stricter partition-table checks.
  • Primary files:
    • sdkconfig
    • build-scripts/I2S-4MFlash-sdkconfig.defaults
    • build-scripts/Muse-sdkconfig.defaults
    • build-scripts/SqueezeAmp-sdkconfig.defaults
    • partitions.csv

10) Additional compile/runtime compatibility fixes

  • Impact:
    • Multiple compile breaks from deprecated/changed API surfaces and C/C++ correctness issues.
  • Mitigation:
    • Added missing includes.
    • Updated legacy flash size call path.
    • Fixed string and initialization issues and allocator mismatch in ESP-DSP sources.
    • Added HTTP redirect event handling for OTA flow.
  • Primary files:
    • components/platform_console/cmd_system.c
    • components/platform_console/app_recovery/recovery.c
    • components/squeezelite-ota/squeezelite-ota.c
    • components/squeezelite-ota/squeezelite-ota.h
    • components/spotify/cspot/bell/main/io/URLParser.cpp
    • components/metrics/Batch.h
    • components/esp-dsp/modules/support/snr/float/dsps_snr_f32.cpp
    • components/esp-dsp/modules/support/sfdr/float/dsps_sfdr_f32.cpp
    • components/esp-dsp/modules/support/view/dsps_view.cpp

11) Connectivity and service-layer compatibility

  • Impact:
    • Compatibility gaps around network utility functions and handler glue code.
  • Mitigation:
    • Added tcpip adapter compatibility shims and network helper updates.
    • Updated network/address conversion helper usage for current lwIP/IDF behavior.
  • Primary files:
    • components/tools/tcpip_adapter_compat.h
    • components/wifi-manager/http_server_handlers.c
    • components/wifi-manager/network_manager.c
    • components/wifi-manager/network_services.h

12) RAOP mbedTLS v3 migration + late-stage build hardening

  • Impact:
    • RAOP RSA flow used legacy mbedTLS APIs removed/changed in IDF 5.5.
    • Additional strict-format and -fno-common/linkage issues appeared after earlier compile blockers were removed.
  • Mitigation:
    • Migrated RAOP RSA key parse/sign/decrypt flow to mbedTLS v3-compatible APIs and added RNG callback/error handling.
    • Corrected display time formatting width mismatches.
    • Updated Wi-Fi auth-mode switch mapping for new IDF enums and fixed RSSI format typing.
    • Fixed multiple-definition issues by converting header-level globals to extern declarations and adding single C definitions.
    • Resolved duplicate loglevel definition in squeezelite decode path.
  • Primary files:
    • components/raop/raop.c
    • components/display/display.c
    • components/platform_config/WifiList.cpp
    • components/squeezelite/embedded.h
    • components/squeezelite/slimproto.c
    • components/display/display.h
    • components/display/core/gds_font.h
    • components/squeezelite/decode.c

Current Status

  • Build progress has moved significantly forward versus initial migration state.
  • RAOP mbedTLS migration blocker in components/raop/raop.c is remediated and RAOP now compiles/links.
  • Most broad migration impacts above are remediated.
  • Remaining blockers have moved to final link/image stages:
    • unresolved symbol groups in final squeezelite.elf link (network/PPP/mbedTLS TLS13/WPS/BT/RTC symbol families)
    • binary/footprint constraints (IRAM pressure hint and image-size pressure hint)
    • recovery.bin partition overflow warning (recovery partition too small for current binary)
  • Latest investigated logs:
    • build/log/idf_py_stderr_output_68994
    • build/log/idf_py_stdout_output_68994

Footprint Net-Gain Ledger (Recovery App)

Partition policy note: app partition sizes are fixed; this ledger tracks binary reduction only.

Baseline reference (handover):

  • recovery.bin: 0x149a60
  • recovery partition: 0x130000
  • overflow: 0x19a60

Measured changes (now moved to a recovery-only profile):

  1. Disable mbedTLS certificate bundle in recovery profile
    • # CONFIG_MBEDTLS_CERTIFICATE_BUNDLE is not set
    • observed recovery.bin: 0x149ae0 (intermediate run)
  2. Disable optional Wi-Fi auth feature families in recovery profile
    • # CONFIG_ESP_WIFI_ENABLE_WPA3_SAE is not set
    • # CONFIG_ESP_WIFI_ENABLE_WPA3_OWE_STA is not set
    • # CONFIG_ESP_WIFI_ENTERPRISE_SUPPORT is not set
    • observed recovery.bin: 0x142e20

Profile split applied:

  • shared sdkconfig restored for full app compatibility
  • recovery trims moved to sdkconfig.recovery.defaults
  • helper script added: build-scripts/build_recovery_size.sh

Net result vs baseline:

  • recovery.bin delta: -0x6c40 bytes (-27,712)
  • overflow delta: -0x6c40 bytes (-27,712)
  • current overflow: 0x12e20

Latest size snapshot (build/recovery.map):

  • Total image size: 1,322,415 bytes
  • Flash code: 961,016
  • Flash rodata (+appdesc): 237,152
  • IRAM: 98,647 (75.26%)
  • DRAM: 33,748 (27.09%)

Notes for Contributors

  • This file documents remediated impacts only.
  • For open blockers, refer to latest in-container build logs under:
    • build/log/idf_py_stderr_output_*
    • build/log/idf_py_stdout_output_*
  • For recovery-only footprint experiments (without changing shared sdkconfig), use:
    • build-scripts/build_recovery_size.sh <platform|defaults-file> [build-dir]
    • platform aliases: i2s, muse, squeezeamp