mirror of
https://github.com/sle118/squeezelite-esp32.git
synced 2026-03-25 15:18:00 +03:00
281 lines
11 KiB
Markdown
281 lines
11 KiB
Markdown
# 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`
|