chore: import upstream snapshot with attribution

components/bootloader_support/bootloader_flash/include/bootloader_flash.h

@@ -0,0 +1,73 @@
+/*
+ * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include <stdint.h>
+#include <esp_err.h>
+#include "spi_flash_mmap.h" /* including in bootloader for error values */
+#include "esp_private/spi_flash_os.h"
+#include "sdkconfig.h"
+#include "soc/soc_caps.h"
+#include "bootloader_flash_override.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Read flash ID by sending RDID command (0x9F)
+ * @return flash raw ID
+ *     mfg_id = (ID >> 16) & 0xFF;
+       flash_id = ID & 0xffff;
+ */
+uint32_t bootloader_read_flash_id(void);
+
+/**
+ * @brief Startup flow recommended by XMC. Call at startup before any erase/write operation.
+ *
+ * @return ESP_OK When startup successfully, otherwise ESP_FAIL (indicating you should reboot before erase/write).
+ */
+esp_err_t bootloader_flash_xmc_startup(void);
+
+/**
+  * @brief Unlock Flash write protect.
+  *        Please do not call this function in SDK.
+  *
+  * @note This can be overridden because it's attribute weak, when there is a same name symbol.
+  */
+esp_err_t bootloader_flash_unlock(void);
+
+/**
+  * @brief Unlock Flash write protect.
+  *        This is alias to `bootloader_flash_unlock`.
+  *        Please do not call this function in SDK.
+  */
+esp_err_t bootloader_flash_unlock_default(void);
+
+/**
+ * @brief Reset the flash chip (66H + 99H).
+ *
+ * @return ESP_OK if success, otherwise ESP_FAIL.
+ */
+esp_err_t bootloader_flash_reset_chip(void);
+
+/**
+ * @brief Check if octal flash mode is enabled in eFuse
+ *
+ * @return True if flash is in octal mode, false else
+ */
+bool bootloader_flash_is_octal_mode_enabled(void);
+
+/**
+ * @brief Get the spi flash working mode.
+ *
+ * @return The mode of flash working mode, see `esp_rom_spiflash_read_mode_t`
+ */
+esp_rom_spiflash_read_mode_t bootloader_flash_get_spi_mode(void);
+
+#ifdef __cplusplus
+}
+#endif

components/bootloader_support/bootloader_flash/include/bootloader_flash_config.h

@@ -0,0 +1,93 @@
+/*
+ * SPDX-FileCopyrightText: 2018-2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "sdkconfig.h"
+#include "esp_image_format.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Update the flash id in g_rom_flashchip(global esp_rom_spiflash_chip_t structure).
+ *
+ * @return None
+ */
+void bootloader_flash_update_id(void);
+
+/**
+ * @brief Update the flash size in g_rom_flashchip (global esp_rom_spiflash_chip_t structure).
+ *
+ * @param size The size to store, in bytes.
+ * @return None
+ */
+void bootloader_flash_update_size(uint32_t size);
+
+/**
+ * @brief Set the flash CS setup and hold time.
+ *
+ * @note CS setup time is recomemded to be 1.5T, and CS hold time is recommended to be 2.5T.
+ *       cs_setup = 1, cs_setup_time = 0; cs_hold = 1, cs_hold_time = 1.
+ *
+ * @return None
+ */
+void bootloader_flash_cs_timing_config(void);
+
+/**
+ * @brief Configure SPI flash clock.
+ *
+ * @note This function only set clock frequency for SPI0.
+ *
+ * @param pfhdr Pointer to App image header, from where to fetch flash settings.
+ *
+ * @return None
+ */
+void bootloader_flash_clock_config(const esp_image_header_t* pfhdr);
+
+/**
+ * @brief Configure SPI flash gpio, include the IO matrix and drive strength configuration.
+ *
+ * @param pfhdr Pointer to App image header, from where to fetch flash settings.
+ *
+ * @return None
+ */
+void bootloader_flash_gpio_config(const esp_image_header_t* pfhdr);
+
+#ifdef CONFIG_IDF_TARGET_ESP32
+/**
+ * @brief Configure SPI flash read dummy based on different mode and frequency.
+ *
+ * @param pfhdr Pointer to App image header, from where to fetch flash settings.
+ *
+ * @return None
+ */
+void bootloader_flash_dummy_config(const esp_image_header_t* pfhdr);
+#else
+// The meaning has changed on this chip. Deprecated, Call `bootloader_configure_spi_pins()` and `bootloader_flash_set_dummy_out()` directly.
+void bootloader_flash_dummy_config(const esp_image_header_t* pfhdr) __attribute__((deprecated));
+#endif
+
+#ifdef CONFIG_IDF_TARGET_ESP32
+/**
+ * @brief Return the pin number used for custom SPI flash and/or SPIRAM WP pin
+ *
+ * Can be determined by eFuse values in most cases, or overriden in configuration
+ *
+ * This value is only meaningful if the other SPI flash pins are overriden via eFuse.
+ *
+ * This value is only meaningful if flash is set to QIO or QOUT mode, or if
+ * SPIRAM is enabled.
+ *
+ * @return Pin number to use, or -1 if the default should be kept
+ */
+int bootloader_flash_get_wp_pin(void);
+#endif
+
+#ifdef __cplusplus
+}
+#endif

components/bootloader_support/bootloader_flash/include/bootloader_flash_override.h

@@ -0,0 +1,130 @@
+/*
+ * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include <stdint.h>
+#include "esp_err.h"
+#include "esp_attr.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef unsigned (*bootloader_flash_read_status_fn_t)(void);
+typedef void (*bootloader_flash_write_status_fn_t)(unsigned);
+
+typedef struct __attribute__((packed))
+{
+    const char *manufacturer;
+    uint8_t mfg_id; /* 8-bit JEDEC manufacturer ID */
+    uint16_t flash_id; /* 16-bit JEDEC flash chip ID */
+    uint16_t id_mask; /* Bits to match on in flash chip ID */
+    bootloader_flash_read_status_fn_t read_status_fn;
+    bootloader_flash_write_status_fn_t write_status_fn;
+    uint8_t status_qio_bit;
+} bootloader_qio_info_t;
+
+/**
+ * @brief Read 8 bit status using RDSR command
+ *
+ * @return Value of SR1.
+ */
+unsigned bootloader_read_status_8b_rdsr(void);
+
+/**
+ * @brief Read 8 bit status (second byte) using RDSR2 command
+ *
+ * @return Value of SR2
+ */
+unsigned bootloader_read_status_8b_rdsr2(void);
+
+/**
+ * @brief Read 8 bit status (third byte) using RDSR3 command
+ *
+ * @return Value of SR3
+ */
+unsigned bootloader_read_status_8b_rdsr3(void);
+
+/**
+ * @brief Read 16 bit status using RDSR & RDSR2 (low and high bytes)
+ *
+ * @return Value of SR2#SR1.
+ */
+unsigned bootloader_read_status_16b_rdsr_rdsr2(void);
+
+/**
+ * @brief Write 8 bit status using WRSR
+ */
+void bootloader_write_status_8b_wrsr(unsigned new_status);
+
+/**
+ * @brief Write 8 bit status (second byte) using WRSR2.
+ */
+void bootloader_write_status_8b_wrsr2(unsigned new_status);
+
+/**
+ * @brief Write 8 bit status (third byte) using WRSR3.
+ */
+void bootloader_write_status_8b_wrsr3(unsigned new_status);
+
+/**
+ * @brief Write 16 bit status using WRSR, (both write SR1 and SR2)
+ */
+void bootloader_write_status_16b_wrsr(unsigned new_status);
+
+/**
+ * @brief Read 8 bit status of XM25QU64A.
+ *
+ * @return Value of 8 bit SR.
+ */
+unsigned bootloader_read_status_8b_xmc25qu64a(void);
+
+/**
+ * @brief Write 8 bit status for XM25QU64A
+ */
+void bootloader_write_status_8b_xmc25qu64a(unsigned new_status);
+
+/* Array of known flash chips and data to enable Quad I/O mode
+
+   Manufacturer & flash ID can be tested by running "esptool
+   flash-id"
+
+   If manufacturer ID matches, and flash ID ORed with flash ID mask
+   matches, enable_qio_mode() will execute "Read Cmd", test if bit
+   number "QIE Bit" is set, and if not set it will call "Write Cmd"
+   with this bit set.
+
+   Searching of this table stops when the first match is found.
+ */
+extern const bootloader_qio_info_t* bootloader_flash_qe_support_list;
+
+/**
+ * @brief The bootloader flash qe list count number.
+*/
+extern uint8_t bootloader_flash_qe_list_count;
+
+/**
+  * @brief Unlock Flash write protect.
+  *        Please do not call this function in SDK.
+  *
+  * @note This can be overridden because it's attribute weak, when there is a same name symbol.
+  */
+esp_err_t bootloader_flash_unlock(void);
+
+#if CONFIG_BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH || CONFIG_BOOTLOADER_CACHE_32BIT_ADDR_OCTAL_FLASH
+/**
+ * @brief Enable 32bits address flash(larger than 16MB) can map to cache.
+ *
+ * @param flash_mode SPI flash working mode.
+ *
+ * @note This can be overridden because it's attribute weak, when there is a same name symbol.
+ */
+void __attribute__((weak)) bootloader_flash_32bits_address_map_enable(esp_rom_spiflash_read_mode_t flash_mode);
+#endif
+
+#ifdef __cplusplus
+}
+#endif

components/bootloader_support/bootloader_flash/include/bootloader_flash_priv.h

@@ -0,0 +1,207 @@
+/*
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#ifndef __BOOTLOADER_FLASH_H
+#define __BOOTLOADER_FLASH_H
+
+#include <stddef.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <esp_err.h>
+#include <spi_flash_mmap.h> /* including in bootloader for error values */
+#include "sdkconfig.h"
+#include "bootloader_flash.h"
+#include "soc/ext_mem_defs.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define FLASH_SECTOR_SIZE 0x1000
+#define FLASH_BLOCK_SIZE 	0x10000
+
+#define MMAP_ALIGNED_MASK 	(SPI_FLASH_MMU_PAGE_SIZE - 1)
+#define MMU_FLASH_MASK    (~(SPI_FLASH_MMU_PAGE_SIZE - 1))
+#define MMU_FLASH_MASK_FROM_VAL(PAGE_SZ) (~((PAGE_SZ) - 1))
+#define MMU_DROM_END_ENTRY_VADDR_FROM_VAL(PAGE_SZ) (SOC_DRAM_FLASH_ADDRESS_HIGH - (PAGE_SZ))
+
+/**
+ * MMU mapping must always be in the unit of a SPI_FLASH_MMU_PAGE_SIZE
+ * This macro is a helper for you to get needed page nums to be mapped. e.g.:
+ * Let's say SPI_FLASH_MMU_PAGE_SIZE is 64KB.
+ * - v_start = 0x4200_0004
+ * - size = 4 * 64KB
+ *
+ * You should map from 0x4200_0000, then map 5 pages.
+ */
+#define GET_REQUIRED_MMU_PAGES(size, v_start)    ((size + (v_start - (v_start & MMU_FLASH_MASK)) + SPI_FLASH_MMU_PAGE_SIZE - 1) / SPI_FLASH_MMU_PAGE_SIZE)
+
+/* SPI commands (actual on-wire commands not SPI controller bitmasks)
+   Suitable for use with the bootloader_execute_flash_command static function.
+*/
+#define CMD_RDID       0x9F
+#define CMD_WRSR       0x01
+#define CMD_WRSR2      0x31 /* Not all SPI flash uses this command */
+#define CMD_WRSR3      0x11 /* Not all SPI flash uses this command */
+#define CMD_WREN       0x06
+#define CMD_WRENVSR    0x50 /* Flash write enable for volatile SR bits */
+#define CMD_WRDI       0x04
+#define CMD_RDSR       0x05
+#define CMD_RDSR2      0x35 /* Not all SPI flash uses this command */
+#define CMD_RDSR3      0x15 /* Not all SPI flash uses this command */
+#define CMD_OTPEN      0x3A /* Enable OTP mode, not all SPI flash uses this command */
+#define CMD_RDSFDP     0x5A /* Read the SFDP of the flash */
+#define CMD_RESUME     0x7A /* Resume command to clear flash suspend bit */
+#define CMD_RESETEN    0x66
+#define CMD_RESET      0x99
+#define CMD_FASTRD_QIO_4B   0xEC
+#define CMD_FASTRD_QUAD_4B  0x6C
+#define CMD_FASTRD_DIO_4B   0xBC
+#define CMD_FASTRD_DUAL_4B  0x3C
+#define CMD_FASTRD_4B       0x0C
+#define CMD_SLOWRD_4B       0x13
+
+
+/* Provide a Flash API for bootloader_support code,
+   that can be used from bootloader or app code.
+
+   This header is available to source code in the bootloader &
+   bootloader_support components only.
+*/
+
+/**
+ * @brief Get number of free pages
+ *
+ * @return Number of free pages
+ */
+uint32_t bootloader_mmap_get_free_pages(void);
+
+/**
+ * @brief Map a region of flash to data memory
+ *
+ * @important In bootloader code, only one region can be bootloader_mmaped at once. The previous region must be bootloader_munmapped before another region is mapped.
+ *
+ * @important In app code, these functions are not thread safe.
+ *
+ * Call bootloader_munmap once for each successful call to bootloader_mmap.
+ *
+ * In esp-idf app, this function maps directly to spi_flash_mmap with the @ref
+ * spi_flash_mmap_flag_t::SPI_FLASH_MMAP_FLAG_BLOCKS_WRITE flag set. When XIP on PSRAM (`CONFIG_SPIRAM_XIP_FROM_PSRAM`)  enabled, flash erasing/writing
+ * will be blocked until unmap.
+ *
+ * @param offset - Starting flash offset to map to memory.
+ * @param length - Length of data to map.
+ *
+ * @return Pointer to mapped data memory (at src_addr), or NULL
+ * if an allocation error occurred.
+ */
+const void *bootloader_mmap(uint32_t src_addr, uint32_t size);
+
+
+/**
+ * @brief Unmap a previously mapped region of flash
+ *
+ * Call bootloader_munmap once for each successful call to bootloader_mmap.
+ */
+void bootloader_munmap(const void *mapping);
+
+/**
+ * @brief  Read data from Flash.
+ *
+ *
+ * @note All of src, dest and size have to be 4-byte aligned.
+ *
+ * @param  src   source address of the data in Flash.
+ * @param  dest  pointer to the destination buffer
+ * @param  size  length of data
+ * @param  allow_decrypt If true and flash encryption is enabled, data on flash
+ *         will be decrypted transparently as part of the read.
+ *
+ * @return ESP_OK on success, ESP_ERR_FLASH_OP_FAIL on SPI failure,
+ * ESP_ERR_FLASH_OP_TIMEOUT on SPI timeout.
+ */
+esp_err_t bootloader_flash_read(size_t src_addr, void *dest, size_t size, bool allow_decrypt);
+
+
+/**
+ * @brief  Write data to Flash.
+ *
+ * @note All of dest_addr, src and size have to be 4-byte aligned. If write_encrypted is set, dest_addr and size must be 32-byte aligned.
+ *
+ * @note In bootloader, when write_encrypted == true, the src buffer is encrypted in place.
+ *
+ * @note [ESP-TEE] Using this API from the TEE will return an error if the dest_addr lies
+ *       within the active TEE partition range.
+ *
+ * @param  dest_addr Destination address to write in Flash.
+ * @param  src Pointer to the data to write to flash
+ * @param  size Length of data in bytes.
+ * @param  write_encrypted If true, data will be written encrypted on flash.
+ *
+ * @return ESP_OK on success, ESP_ERR_FLASH_OP_FAIL on SPI failure,
+ * ESP_ERR_FLASH_OP_TIMEOUT on SPI timeout.
+ */
+esp_err_t bootloader_flash_write(size_t dest_addr, void *src, size_t size, bool write_encrypted);
+
+/**
+ * @brief  Erase the Flash sector.
+ *
+ * @param  sector  Sector number, the count starts at sector 0, 4KB per sector.
+ *
+ * @return esp_err_t
+ */
+esp_err_t bootloader_flash_erase_sector(size_t sector);
+
+/**
+ * @brief  Erase the Flash range.
+ *
+ * @note   [ESP-TEE] Using this API from the TEE will return an error if the start_addr lies
+ *         within the active TEE partition range.
+ *
+ * @param  start_addr start address of flash offset
+ * @param  size       sector aligned size to be erased
+ *
+ * @return esp_err_t
+ */
+esp_err_t bootloader_flash_erase_range(uint32_t start_addr, uint32_t size);
+
+/**
+ * @brief Execute a user command on the flash
+ *
+ * @param command The command value to execute.
+ * @param mosi_data MOSI data to send
+ * @param mosi_len Length of MOSI data, in bits
+ * @param miso_len Length of MISO data to receive, in bits
+ * @return Received MISO data
+ */
+uint32_t bootloader_execute_flash_command(uint8_t command, uint32_t mosi_data, uint8_t mosi_len, uint8_t miso_len);
+
+/**
+ * @brief Read the SFDP of the flash
+ *
+ * @param sfdp_addr Address of the parameter to read
+ * @param miso_byte_num Bytes to read
+ * @return The read SFDP, little endian, 4 bytes at most
+ */
+uint32_t bootloader_flash_read_sfdp(uint32_t sfdp_addr, unsigned int miso_byte_num);
+
+/**
+ * @brief Enable the flash write protect (WEL bit).
+ */
+void bootloader_enable_wp(void);
+
+/**
+ * @brief Once this function is called,
+ * any on-going internal operations will be terminated and the device will return to its default power-on
+ * state and lose all the current volatile settings, such as Volatile Status Register bits, Write Enable Latch
+ * (WEL) status, Program/Erase Suspend status, etc.
+ */
+void bootloader_spi_flash_reset(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

components/bootloader_support/bootloader_flash/include/esp_private/bootloader_flash_internal.h

@@ -0,0 +1,38 @@
+/*
+ * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+#include <stdint.h>
+#include <esp_err.h>
+#include "soc/soc_caps.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Initialize spi_flash in bootloader and print flash info
+ *
+ * @return ESP_OK on success, otherwise see esp_err_t
+ */
+esp_err_t bootloader_init_spi_flash(void);
+
+#if CONFIG_APP_BUILD_TYPE_RAM && !CONFIG_APP_BUILD_TYPE_PURE_RAM_APP
+/**
+ * @brief Config all flash related stuff according to the header. The consistency of all flash configs is ensured.
+ *
+ * @return None
+ */
+void bootloader_flash_hardware_init(void);
+#endif
+
+/**
+ * @brief Initialise mspi core clock
+ */
+void bootloader_init_mspi_clock(void);
+
+#ifdef __cplusplus
+}
+#endif

components/bootloader_support/bootloader_flash/include/flash_qio_mode.h

@@ -0,0 +1,31 @@
+/*
+ * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @brief Enable Quad I/O mode in bootloader (if configured)
+ *
+ * Queries attached SPI flash ID and sends correct SPI flash
+ * commands to enable QIO or QOUT mode, then enables this mode.
+ */
+void bootloader_enable_qio_mode(void);
+
+/**
+ * @brief Read flash ID by sending 0x9F command
+ * @return flash raw ID
+ *     mfg_id = (ID >> 16) & 0xFF;
+       flash_id = ID & 0xffff;
+ */
+uint32_t bootloader_read_flash_id(void);
+
+#ifdef __cplusplus
+}
+#endif