universalisos/bootloader_support_audit.md

ESP-IDF bootloader_support Component — Deep Audit

Component path: components/bootloader_support/ Total ~21,760 lines of C/header code across 130+ files. Scope: ESP-IDF 5.x 2nd-stage bootloader support — shared code between bootloader and application.

---

1. Top-Level /include/ — Public API Headers

include/esp_app_format.h (127 lines)

Purpose: Defines the binary image header structures shared between bootloader and app. Key symbols:

• esp_image_spi_mode_t, esp_image_spi_freq_t, esp_image_flash_size_t — SPI flash config enums
• esp_chip_id_t — Enum of all supported chip IDs (ESP32 through ESP32-S31)
• esp_image_header_t (24 bytes) — Main binary image header: magic, segment_count, spi_mode, spi_speed, spi_size, entry_addr, chip_id, min/max chip revision, hash_appended
• esp_image_segment_header_t — Per-segment header: load_addr, data_len
• ESP_IMAGE_HEADER_MAGIC (0xE9), ESP_IMAGE_MAX_SEGMENTS (16)

include/esp_image_format.h (236 lines)

Purpose: Image loading, verification, and metadata API. Key types/functions:

• esp_image_metadata_t — Full on-flash image metadata: start_addr, header, segments, data offsets, image_len, SHA-256 digest, secure_version, mmu_page_size
• esp_image_load_mode_t — ESP_IMAGE_VERIFY, ESP_IMAGE_VERIFY_SILENT, ESP_IMAGE_LOAD, ESP_IMAGE_LOAD_NO_VALIDATE
• rtc_retain_mem_t — Deep-sleep RTC memory layout (partition, reboot_counter, factory_reset flags, CRC)
• esp_image_verify() / esp_image_load() / esp_image_basic_verify() — Image validation and loading
• ESP_ERR_IMAGE_BASE, ESP_ERR_IMAGE_FLASH_FAIL, ESP_ERR_IMAGE_INVALID

include/esp_flash_partitions.h (135 lines)

Purpose: Partition table definitions and flash layout constants. Key symbols:

• Partition type/subtype constants: PART_TYPE_APP, PART_TYPE_DATA, PART_TYPE_BOOTLOADER, PART_TYPE_PARTITION_TABLE, factory/OTA/test subtypes
• esp_partition_info_t, esp_partition_pos_t, esp_ota_select_entry_t — Partition structures
• ESP_PARTITION_MAGIC (0x50AA), ESP_PARTITION_MAGIC_MD5 (0xEBEB)
• ESP_PARTITION_TABLE_OFFSET, ESP_BOOTLOADER_OFFSET — Fixed flash offsets
• PART_FLAG_ENCRYPTED, PART_FLAG_READONLY
• esp_partition_table_verify() — Validates partition table with MD5 checksum

include/bootloader_common.h (295 lines)

Purpose: Common utilities for both bootloader and application (GPIO, OTA data, chip revision checks). Key functions:

• bootloader_common_check_chip_revision_validity() — Validates chip revision against image requirements
• bootloader_common_read_otadata() — Reads OTA data partition
• bootloader_common_ota_select_crc() / _valid() / _invalid() — OTA selection helpers
• bootloader_common_check_long_hold_gpio() / _level() — GPIO long/short hold detection
• bootloader_common_label_search() — Searches comma-separated label lists
• bootloader_common_check_chip_validity() — Comprehensive chip compatibility check
• bootloader_common_erase_otadata() — Erases OTA data partition
• Types: esp_comm_gpio_hold_t (LONG_HOLD, SHORT_HOLD, NOT_HOLD)

include/esp_secure_boot.h (382 lines)

Purpose: Secure Boot V1/V2 API — public interface for signature verification, key digest management. Key definitions:

• esp_secure_boot_sig_scheme_t — V1_ECDSA, V2_RSA, V2_ECDSA
• ESP_SECURE_BOOT_DIGEST_LEN (32 or 48 for ECDSA-384)
• ESP_SECURE_BOOT_KEY_DIGEST_LEN
• esp_secure_boot_enabled() — Checks if hardware secure boot is active
• esp_secure_boot_verify_sbv2_signature_block() — Verifies SBV2 signature block
• esp_secure_boot_verify_signature() — Main signature verification entry point
• esp_secure_boot_permanently_enable() — Burns efuses to permanently enable

include/esp_flash_encrypt.h (226 lines)

Purpose: Flash encryption public API. Key definitions:

• esp_flash_enc_mode_t — DISABLED, DEVELOPMENT, RELEASE
• esp_flash_encryption_enabled() — Check if encryption is active
• esp_flash_encrypt_check_and_update() — On-device flash encryption during boot
• esp_flash_encrypt_state() — Returns and prints encryption state
• esp_flash_encrypt_contents() — Encrypts flash partitions in place
• esp_flash_encrypt_init() / esp_flash_encryption_init_checks()

include/bootloader_memory_utils.h (244 lines)

Purpose: Memory region checking utilities (IRAM/DRAM/RTC bounds, cache address mapping). Key inline functions:

• esp_dram_match_iram() — Check if DRAM/IRAM share memory space
• esp_ptr_in_iram() / esp_ptr_in_dram() / esp_ptr_in_diram_dram() — Pointer region checks
• esp_ptr_in_rtc_dram() / esp_ptr_in_rtc_iram() / esp_ptr_byte_accessible() — RTC memory checks
• esp_ptr_in_rom() / esp_ptr_executable() — Execution checks
• esp_ptr_dma_capable() / esp_ptr_internal() / esp_ptr_external_ram()
• esp_ptr_32bit_addressable() — Address range validation

include/bootloader_random.h (60 lines)

Purpose: RNG entropy for bootloader (HWRNG via SAR ADC or WDEV_RND_REG). Key functions:

• bootloader_random_enable() — Enable entropy source (ADC-based)
• bootloader_random_disable() — Disable entropy source
• bootloader_fill_random() — Fill buffer with random bytes

include/bootloader_clock.h (25 lines)

Purpose: Bootloader clock configuration API. Key functions:

• bootloader_clock_configure() — Configures CPU/APB clocks for early boot
• bootloader_clock_get_rated_freq_mhz() — Returns chip's rated max frequency

include/bootloader_mem.h (16 lines)

Purpose: Memory initialization for bootloader. Key functions:

• bootloader_init_mem() — Configure memory protection (APM, region protection)

include/bootloader_util.h (37 lines)

Purpose: Simple utility function. Key functions:

• bootloader_util_regions_overlap() — Check if [start1, end1) overlaps [start2, end2)

include/bootloader_utility_tee.h (53 lines)

Purpose: TEE (Trusted Execution Environment) OTA boot partition management. Key functions:

• bootloader_utility_tee_get_boot_partition() — Fetch running TEE partition
• bootloader_utility_tee_set_boot_partition() — Set new TEE boot partition
• bootloader_utility_tee_get_next_update_partition() — Fetch next TEE update partition
• bootloader_utility_tee_mark_app_valid_and_cancel_rollback() — Commit TEE OTA update

include/esp_tee_ota_utils.h (45 lines)

Purpose: TEE OTA data structures. Key symbols:

• esp_tee_ota_select_entry_t — TEE OTA selection structure (magic, version, boot_partition, ota_state, crc)
• esp_tee_ota_img_states_t — NEW, PENDING_VERIFY, INVALID, VALID, UNDEFINED
• TEE_OTADATA_MAGIC (0x4337e1e1)

include/esp_flash_data_types.h (7 lines)

Purpose: Deprecated stub — forwards to esp_flash_partitions.h.

---

2. private_include/ — Internal Headers (Bootloader-Only)

private_include/bootloader_config.h (51 lines)

Purpose: Bootloader state structure and configuration constants. Key symbols:

• bootloader_state_t — Core bootloader state: ota_info, factory, test, tee_ota_info, tee[N], ota[N], app_count, selected_subtype
• MAX_OTA_SLOTS (16), MAX_TEE_OTA_SLOTS (2)
• FACTORY_INDEX (-1), TEST_APP_INDEX (-2), INVALID_INDEX (-99)
• SPI_SEC_SIZE (0x1000), SPI_ERROR_LOG
• flash_encrypt() — Forward declaration

private_include/bootloader_init.h (65 lines)

Purpose: Bootloader initialization steps. Key symbols:

• _bss_start, _bss_end, _data_start, _data_end — Linker script symbols
• bootloader_image_hdr — Bootloader's own image header
• bootloader_read_bootloader_header() — Read bootloader header from flash
• bootloader_check_bootloader_validity() — Validate bootloader against chip/efuses
• bootloader_clear_bss_section() — Zero BSS
• bootloader_config_wdt() — Configure watchdog timers
• bootloader_enable_random() — Enable RNG entropy source
• bootloader_print_banner() — Print bootloader version banner
• bootloader_init() — Main hardware preparation (cache, MMU, pins, clocks)
• bootloader_init_ext_mem() — Initialize cache and MMU

private_include/bootloader_utility.h (157 lines)

Purpose: Core bootloader application loading logic. Key functions:

• bootloader_utility_load_partition_table() — Load and parse partition table
• bootloader_utility_get_selected_boot_partition() — Determine preferred boot partition
• bootloader_utility_load_boot_image() — Load and start application (noreturn)
• bootloader_utility_load_boot_image_from_deep_sleep() — Deep-sleep wake boot path
• bootloader_utility_load_tee_image() — Load TEE image
• bootloader_utility_reset_sha(), bootloader_utility_sha256_finish() — SHA helpers
• bootloader_utility_debug_after_reset() — Post-reset debug info

private_include/bootloader_sha.h (44 lines)

Purpose: SHA-256/512 hardware acceleration API for bootloader. Key functions:

• bootloader_sha256_start() / _data() / _finish() — SHA-256 streaming API
• bootloader_sha512_start() / _data() / _finish() — SHA-512 streaming API (SoC-dependent)

private_include/bootloader_signature.h (38 lines)

Purpose: Secure Boot V2 RSA signature verification (backward compatibility wrapper). Key functions:

• esp_secure_boot_verify_rsa_signature_block() — Legacy RSA SBV2 signature verification

private_include/bootloader_console.h (31 lines)

Purpose: Console initialization for bootloader (UART/USB CDC). Key functions:

• bootloader_console_init() — Initialize console output
• bootloader_console_deinit() — De-initialize console
• bootloader_console_write_char_usb() — USB CDC character output

private_include/bootloader_soc.h (36 lines)

Purpose: SoC-level security features (glitch detection, super WDT). Key functions:

• bootloader_ana_super_wdt_reset_config() — Configure analog super WDT
• bootloader_ana_clock_glitch_reset_config() — Configure clock glitch reset
• bootloader_power_glitch_reset_config() — Configure power glitch reset

---

3. bootloader_flash/ — SPI Flash Subsystem

bootloader_flash/include/bootloader_flash.h (73 lines)

Purpose: Public SPI flash operations. Key functions:

• bootloader_read_flash_id() — Read flash JEDEC ID (0x9F)
• bootloader_flash_xmc_startup() — XMC flash startup sequence
• bootloader_flash_unlock() / _default() — Unlock flash write protect
• bootloader_flash_reset_chip() — Reset flash chip (66H+99H)
• bootloader_flash_is_octal_mode_enabled() — Check octal mode efuse
• bootloader_flash_get_spi_mode() — Get current SPI working mode

bootloader_flash/include/bootloader_flash_config.h (93 lines)

Purpose: Flash configuration from image header. Key functions:

• bootloader_flash_update_id() — Update flash ID in global ROM structure
• bootloader_flash_update_size() — Update flash size in global structure
• bootloader_flash_cs_timing_config() — Set CS setup/hold time
• bootloader_flash_clock_config() — Configure SPI flash clock from image header
• bootloader_flash_gpio_config() — Configure SPI flash GPIO pins
• bootloader_flash_dummy_config() — Configure read dummy cycles (ESP32 only)
• bootloader_flash_get_wp_pin() — Get WP pin override (ESP32)

bootloader_flash/include/bootloader_flash_override.h (130 lines)

Purpose: Flash QE (Quad Enable) bit support — per-manufacturer status register read/write. Key symbols:

• bootloader_qio_info_t — Flash chip QE metadata (mfg, IDs, status read/write fns, QIE bit position)
• bootloader_read_status_8b_rdsr() / _rdsr2() / _rdsr3() — Status register reads
• bootloader_read_status_16b_rdsr_rdsr2() — Combined 16-bit read
• bootloader_write_status_8b_wrsr() / _wrsr2() / _wrsr3() — Status register writes
• bootloader_write_status_16b_wrsr() — Combined 16-bit write
• bootloader_read_status_8b_xmc25qu64a() / _write_... — XMC-specific
• bootloader_flash_qe_support_list / bootloader_flash_qe_list_count — QE support table
• bootloader_flash_32bits_address_map_enable() — Enable 32-bit flash addressing

bootloader_flash/include/bootloader_flash_priv.h (205 lines)

Purpose: Private flash API for bootloader and bootloader_support internals. Key symbols:

• SPI command constants: CMD_RDID, CMD_WRSR, CMD_WREN, CMD_RDSR, etc.
• FLASH_SECTOR_SIZE (0x1000), FLASH_BLOCK_SIZE (0x10000)
• MMU mapping macros: MMAP_ALIGNED_MASK, MMU_FLASH_MASK, GET_REQUIRED_MMU_PAGES()
• bootloader_mmap_get_free_pages() — Get free MMU pages
• bootloader_flash_read() — Read from flash (with encryption support)
• bootloader_flash_write() — Write to flash (with encryption support)
• bootloader_flash_erase_sector() / _range() — Erase operations
• bootloader_flash_execute_command() — Execute raw SPI command
• bootloader_cache_utils_init() / bootloader_flash_xip_unlock_for_write()

bootloader_flash/include/flash_qio_mode.h (31 lines)

Purpose: Quad I/O mode enable public API. Key functions:

• bootloader_enable_qio_mode() — Enable QIO/QOUT mode on attached flash
• bootloader_read_flash_id() — Read flash ID

bootloader_flash/include/esp_private/bootloader_flash_internal.h (38 lines)

Purpose: Internal flash init for bootloader. Key functions:

• bootloader_init_spi_flash() — Full SPI flash initialization
• bootloader_flash_hardware_init() — Hardware init for RAM-based apps
• bootloader_init_mspi_clock() — Initialize MSPI core clock

---

4. src/ — Main Source Files

src/bootloader_init.c (159 lines)

Purpose: Bootloader entry point initialization. Key functions:

• bootloader_clear_bss_section() — memset BSS to zero
• bootloader_read_bootloader_header() — Reads bootloader image header from flash
• bootloader_check_bootloader_validity() — Validates chip revision + efuse block version
• bootloader_config_wdt() — Disables flashboot WDT protection, enables RTCWDT for boot phase
• bootloader_enable_random() — Enables early RNG entropy source
• bootloader_print_banner() — Prints ESP-IDF version / compile time banner
• bootloader_init_ext_mem() — Initializes cache HAL + MMU

src/bootloader_utility.c (1313 lines) — Largest file

Purpose: Core bootloader logic: partition table parsing, image loading, app boot. Key functions:

• bootloader_utility_load_partition_table() — Read, verify, parse partition table; populate bootloader_state_t
• bootloader_utility_get_selected_boot_partition() — OTA-based boot partition selection
• bootloader_utility_load_boot_image() — Main image loading, validation, MMU mapping, jump-to-app (noreturn)
• bootloader_utility_load_tee_image() — Load TEE image
• bootloader_utility_load_boot_image_from_deep_sleep() — Deep-sleep resume image load
• set_cache_and_start_app() — Configure MMU cache mapping and jump to application entry point
• bootloader_utility_debug_after_reset() — Print post-reset debug info

src/esp_image_format.c (1202 lines) — 2nd largest file

Purpose: Binary image parsing, verification, and loading. Key functions:

• esp_image_verify() — Verify image header + segments + appended SHA-256 hash
• esp_image_load() — Verify + load image segments into memory
• esp_image_basic_verify() — Lightweight header-only verification
• esp_image_get_metadata() — Extract metadata without loading
• Internal helpers for segment validation, hash computation, secure boot signature checking

src/bootloader_common.c (188 lines)

Purpose: Common GPIO and OTA utilities (app or bootloader context). Key functions:

• bootloader_common_check_long_hold_gpio() / _level() — GPIO hold detection
• bootloader_common_label_search() — Label list search

src/bootloader_common_loader.c (292 lines)

Purpose: Additional common utilities for bootloader-only context. Key functions:

• bootloader_common_check_chip_revision_validity() — Chip revision checks
• bootloader_common_check_chip_validity() — Full chip compatibility (revision + secure version + efuse)
• bootloader_common_read_otadata() — Read OTA data from partition
• bootloader_common_ota_select_crc() / _valid() / _invalid() — OTA helpers
• bootloader_common_erase_otadata() — Erase OTA data

src/bootloader_console.c (150 lines)

Purpose: UART/USB CDC console initialization for bootloader. Key functions:

• bootloader_console_init() — Multiple implementations: CONFIG_ESP_CONSOLE_NONE, _UART, _USB_CDC
• UART pin configuration, baud rate setup, USB CDC initialization

src/bootloader_console_loader.c (83 lines)

Purpose: Console functions placed in iram_loader_seg (survives iram overwrite during loading). Key functions:

• USB CDC buffered TX with bootloader_console_flush_usb(), bootloader_console_write_one_char_usb()

src/bootloader_sha.c (300 lines)

Purpose: SHA-256/512 hardware acceleration (bootloader and non-OS builds). Key functions:

• bootloader_sha256_start() / _data() / _finish() — Streaming SHA-256 via ets_sha_* ROM functions
• bootloader_sha512_start() / _data() / _finish() — SHA-512/384 (SoC-dependent)
• Alternative mbedTLS-based implementation for application builds

src/bootloader_random.c (99 lines)

Purpose: HWRNG entropy generation for bootloader. Key functions:

• bootloader_fill_random() — Fill buffer with random bytes (WDEV_RND_REG based, XORed with RTC timer)
• bootloader_random_enable() / _disable() — Placeholder stubs for bringup targets

src/bootloader_random_esp32*.c (10 SoC-specific files, ~70-125 lines each)

Purpose: Per-chip entropy source initialization using SAR ADC sampling. Pattern: Each provides chip-specific bootloader_random_enable() and bootloader_random_disable() implementations. Chips covered: ESP32, ESP32-S2, ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-P4

src/bootloader_clock_init.c (171 lines)

Purpose: Clock tree configuration for bootloader. Key functions:

• bootloader_clock_configure() — Set CPU frequency, configure RTC clocks, enable 32k XTAL early, clear power-management interrupts

src/bootloader_clock_loader.c (16 lines)

Purpose: APB frequency query in iram_loader_seg. Key functions:

• esp_clk_apb_freq() — Returns APB frequency from RTC

src/bootloader_mem.c (44 lines)

Purpose: Memory protection and APM initialization. Key functions:

• bootloader_init_mem() — Disable APM control filters, set master security modes, configure region protection

src/bootloader_efuse.c (64 lines)

Purpose: Efuse reading utilities. Key functions:

• bootloader_common_get_chip_ver_pkg() — Read chip version + package from efuse
• bootloader_clock_get_rated_freq_mhz() — Per-chip rated maximum frequency

src/bootloader_panic.c (36 lines)

Purpose: Minimal assert/abort handlers for bootloader. Key functions:

• __assert_func() — Assert failure handler (prints + infinite loop)
• abort() — Abort handler (prints PC + optional OCD break + infinite loop)

src/flash_partitions.c (77 lines)

Purpose: Partition table verification. Key functions:

• esp_partition_table_verify() — Validate partition table magic, bounds, MD5 checksum, count entries

src/bootloader_utility_tee.c (260 lines)

Purpose: TEE OTA boot partition management (read/write TEE OTA data, set boot partition). Key internal functions:

• write_tee_otadata_sector() — Write TEE OTA data to flash
• read_tee_otadata() — Read both TEE OTA data copies
• bootloader_utility_tee_get_boot_partition() — Determine current TEE boot partition
• bootloader_utility_tee_set_boot_partition() — Set new TEE boot partition
• bootloader_utility_tee_get_next_update_partition() — Find next TEE slot for update
• bootloader_utility_tee_mark_app_valid_and_cancel_rollback() — Commit TEE update

src/flash_encrypt.c (519 lines)

Purpose: Flash encryption efuse checks and initialization (application context). Key functions:

• esp_flash_encryption_init_checks() — Validate encryption efuse state consistency
• esp_flash_encrypt_state() — Print encryption state
• esp_flash_write_protect_crypt_cnt() — Write-protect FLASH_CRYPT_CNT efuse
• esp_flash_encryption_enabled() — Check if encryption is enabled via efuses

src/secure_boot.c (465 lines)

Purpose: Secure boot efuse management and state checks (application context). Key functions:

• esp_secure_boot_enabled() — Check secure boot efuse state
• esp_secure_boot_permanently_enable() — Burn secure boot efuses
• esp_secure_boot_verify_signature() — Signature verification dispatch
• V1-specific: secure_boot_v1_check(), esp_secure_boot_verify_signature_block()
• ECDSA key management: esp_secure_boot_verify_ecdsa_signature_block()

---

5. src/flash_encryption/ — On-Device Flash Encryption

src/flash_encryption/flash_encrypt.c (705 lines)

Purpose: On-device flash encryption operations during bootloader phase. Key functions:

• esp_flash_encrypt_check_and_update() — Main entry: checks FLASH_CRYPT_CNT parity, encrypts plaintext flash regions in place
• esp_flash_encrypt_contents() — Encrypts all marked partitions in place
• Internal helpers for bootloader encryption, partition table encryption, app partition encryption
• Key manager integration for XTS_AES key deployment (P4 etc.)

---

6. src/secure_boot_v1/ — Secure Boot V1 (ESP32)

src/secure_boot_v1/secure_boot.c (193 lines)

Purpose: Secure Boot V1 bootloader implementation (AES-based digest generation, efuse burning). Key functions:

• secure_boot_generate() — Generate boot digest ("abstract") + IV for SBV1
• esp_secure_boot_permanently_enable() — Burn SBV1 efuses (ABS_DONE + key)
• esp_secure_boot_verify_signature_block() — V1 signature verification

src/secure_boot_v1/secure_boot_signatures_app.c (121 lines)

Purpose: V1 signature block parsing and verification (app-side).

src/secure_boot_v1/secure_boot_signatures_bootloader.c (86 lines)

Purpose: V1 bootloader self-verification.

---

7. src/secure_boot_v2/ — Secure Boot V2 (RSA/ECDSA)

src/secure_boot_v2/secure_boot.c (407 lines)

Purpose: Secure Boot V2 bootloader implementation. Key functions:

• esp_secure_boot_verify_sbv2_signature_block() — Main SBV2 signature verification
• esp_secure_boot_permanently_enable() — Burn SBV2 efuses
• validate_signature_block() — Validate individual signature block (magic, CRC, digest)

src/secure_boot_v2/secure_boot_rsa_signature.c (194 lines)

Purpose: RSA-3072 signature verification for SBV2 (uses PSA/mbedTLS). Key functions:

• verify_rsa_signature_block() — RSA PKCS#1 v1.5 signature verification
• encode_rsa_pubkey_der() — Manual DER encoding of RSA public key

src/secure_boot_v2/secure_boot_ecdsa_signature.c (118 lines)

Purpose: ECDSA signature verification for SBV2 (uses hardware ECDSA peripheral where available). Key functions:

• verify_ecdsa_signature_block() — ECDSA P-256/P-384 signature verification

src/secure_boot_v2/secure_boot_signatures_app.c (330 lines)

Purpose: SBV2 signature verification logic for application images.

src/secure_boot_v2/secure_boot_signatures_bootloader.c (212 lines)

Purpose: SBV2 bootloader self-verification logic.

src/secure_boot_v2/secure_boot_signature_priv.h (11 lines)

Purpose: Private signature verification dispatch. Key functions:

• verify_ecdsa_signature_block() — Internal ECDSA verifier
• verify_rsa_signature_block() — Internal RSA verifier

---

8. bootloader_flash/src/ — Flash Implementation

bootloader_flash/src/bootloader_flash.c (1074 lines)

Purpose: Core SPI flash operations for bootloader (read, write, erase, XIP unlock, cache). Key functions:

• bootloader_read_flash_id() — JEDEC ID read
• bootloader_flash_read() / _write() / _erase_sector() / _erase_range() — Flash I/O
• bootloader_flash_execute_command() — Raw SPI command execution
• bootloader_flash_xmc_startup() — XMC flash startup sequence
• bootloader_flash_unlock() — Write-protect unlock
• bootloader_flash_reset_chip() — Flash reset sequence
• bootloader_cache_utils_init() — Cache utility initialization
• bootloader_flash_xip_unlock_for_write() — XIP unlock for write operations
• bootloader_flash_is_octal_mode_enabled() / bootloader_flash_get_spi_mode()

bootloader_flash/src/flash_qio_mode.c (230 lines)

Purpose: Quad I/O mode enable for supported flash chips. Key symbols:

• bootloader_flash_qe_support_list_default[] — Known flash chips table (MXIC, ISSI, GD, XMC, etc.) with QE bit positions
• bootloader_enable_qio_mode() — Main entry: match flash ID, check QE bit, set if needed

bootloader_flash/src/bootloader_flash_config_esp32*.c (19 SoC-specific files, ~300-500 lines each)

Purpose: Per-chip SPI flash configuration (pins, clock, dummy cycles, cache MMU, octal mode). Chips covered: ESP32, ESP32-S2, ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-H21, ESP32-H4, ESP32-P4, ESP32-S31 Key per-file functions:

• bootloader_flash_gpio_config() / bootloader_flash_clock_config() / bootloader_flash_dummy_config()
• bootloader_flash_cs_timing_config(), bootloader_configure_spi_pins()
• MMU page size configuration, octal flash DDR mode setup

---

9. src/esp32*/ — SoC-Specific Bootloader Implementations (14 target dirs)

Each directory contains:

• bootloader_esp32xxx.c — SoC-specific bootloader init (bootloader_init() implementation: cache config, CPU freq, SPI pins, flash config)
• bootloader_soc.c — SoC-specific security features (super WDT, clock/power glitch reset config)
• secure_boot_secure_features.c — SoC-specific secure boot efuse checks
• flash_encryption_secure_features.c — SoC-specific flash encryption efuse/bus configuration

Key target directories: esp32/, esp32c2/, esp32c3/, esp32c5/, esp32c6/, esp32c61/, esp32h2/, esp32h21/, esp32h4/, esp32p4/, esp32s2/, esp32s3/, esp32s31/

Special: src/esp32c6/bootloader_ecdsa.c (35 lines)

Purpose: ESP32-C6 hardware ECDSA peripheral integration for secure boot.

---

10. Test Apps

test_apps/bootloader_support/

• main/test_app_main.c — Test entry point
• main/test_verify_image.c (120 lines) — Image verification tests
• pytest_bootloader_support.py — Pytest automation

test_apps/rtc_custom_section/

• main/test_main.c (31 lines) — RTC memory custom section test
• pytest_rtc_mem.py — Pytest for RTC memory

test_apps/.build-test-rules.yml

Purpose: CI build test matrix configuration.

---

11. Build Files

CMakeLists.txt

Purpose: CMake build definition — compiles sources conditionally per target/chip, sets iram_loader_seg placement.

README.rst

Purpose: Component documentation.

---

Summary Statistics

Metric	Count
Total files (C + H)	~130
Total lines of code	~21,760
Public API headers	13
Private headers	7
Flash subsystem headers	6
Core source files	~20
SoC-specific source files	~52 (14 targets × ~3-4 files)
Flash config source files	19
Secure boot source files	10
Flash encryption source files	2
Test files	8

Key Architectural Patterns

1. Dual-context compilation: Many files compile for both bootloader (BOOTLOADER_BUILD) and application, using #ifdef guards.
2. SoC abstraction via per-target directories: Each chip target has its own src/esp32xxx/ subdirectory with flash config, security features, and bootloader init.
3. iram_loader_seg: Critical "loader" phase code (console, clock, flash operations during image loading) is placed in .iram_loader_seg which survives the iram overwrite.
4. ROM function reliance: Heavy use of ROM SPI flash, SHA, and secure boot functions — the component is essentially a HAL wrapper around ROM bootloader primitives.
5. Appended SHA-256: Every ESP image carries a simple hash for corruption detection; secure boot signatures are appended after it.