feat: update structure for initial SPI Flash support

Author: antmak

example/build.sh

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+set -eo pipefail
+
 TARGETS="esp8266 esp32 esp32s2 esp32s3 esp32c2 esp32c3 esp32c5 esp32c6 esp32c61 esp32h2 esp32p4"
 
 ESP8266_LINUX_TOOLCHAIN_URL="https://dl.espressif.com/dl/xtensa-lx106-elf-gcc8_4_0-esp-2020r3-linux-amd64.tar.gz"

include/esp-stub-lib/bit_utils.h

@@ -46,6 +46,14 @@ extern "C" {
 #define MAX(a, b)               ((a) > (b) ? (a) : (b))
 #endif
 
+#ifndef KB
+#define KB(bytes)               ((bytes) / 1024)
+#endif
+
+#ifndef MB
+#define MB(bytes)               ((bytes) / (1024 * 1024))
+#endif
+
 #ifdef __cplusplus
 }
 #endif

include/esp-stub-lib/err.h

@@ -8,5 +8,7 @@
 
 typedef int stub_lib_err_t;
 
-#define STUB_LIB_OK         0       // stub_lib_err_t value indicating success (no error)
-#define STUB_LIB_FAIL       -1      // Generic stub_lib_err_t code indicating failure
+#define STUB_LIB_OK                             0       // stub_lib_err_t value indicating success (no error)
+#define STUB_LIB_FAIL                           -1      // Generic stub_lib_err_t code indicating failure
+
+#define STUB_LIB_ERR_UNKNOWN_FLASH_ID           0x1

include/esp-stub-lib/flash.h

@@ -9,7 +9,7 @@
 #include <stdint.h>
 #include "err.h"
 
-typedef struct stub_flash_info {
+typedef struct stub_lib_flash_info {
     uint32_t id;
     uint32_t size;
     uint32_t block_size;
@@ -23,9 +23,34 @@ typedef struct stub_flash_info {
 extern "C" {
 #endif // __cplusplus
 
+/**
+ * @brief Initialize SPI Flash before any use.
+ *
+ * Configure SPI, Flash ID, flash size, and the internal ROM's config
+ *
+ * @param state Unused
+ *
+ * @return Error code:
+ * - STUB_LIB_OK    - success
+ * - STUB_LIB_ERR_UNKNOWN_FLASH_ID   - can't get size from flash id
+ */
 stub_lib_err_t stub_lib_flash_init(void **state);
+
+/**
+ * @brief Restore flash state at the end of the stub.
+ *
+ * @param state Unused.
+ */
 void stub_lib_flash_deinit(const void *state);
-stub_lib_err_t stub_lib_flash_get_info(stub_lib_flash_info_t *info);
+
+/**
+ * @brief Retrieve SPI Flash information.
+ *
+ * @param[out] info Pointer to receive the result.
+ */
+void stub_lib_flash_get_info(stub_lib_flash_info_t *info);
+
+void stub_lib_flash_info_print(const stub_lib_flash_info_t *info);
 stub_lib_err_t stub_lib_flash_read_buff(uint32_t addr, void *buffer, uint32_t size);
 stub_lib_err_t stub_lib_flash_write_buff(uint32_t addr, const void *buffer, uint32_t size, int encrypt);
 stub_lib_err_t stub_lib_flash_erase_area(uint32_t addr, uint32_t size);

src/flash.c

@@ -6,11 +6,24 @@
 
 #include <flash.h>
 #include <err.h>
+#include <log.h>
+#include <bit_utils.h>
 #include <target/flash.h>
+#include <private/rom_flash_config.h>
 
 stub_lib_err_t stub_lib_flash_init(void **state)
 {
     stub_target_flash_init(state);
+    uint32_t flash_id = stub_target_flash_get_flash_id();
+    uint32_t flash_size = stub_target_flash_id_to_flash_size(flash_id);
+    if (flash_size == 0) {
+        STUB_LOGE("Invalid flash size: 0\n");
+        return STUB_LIB_ERR_UNKNOWN_FLASH_ID;
+    }
+    STUB_LOG_TRACEF("Flash size: %d MB\n", MB(flash_size));
+
+    stub_target_flash_update_config(flash_id, flash_size);
+
     return STUB_LIB_OK;
 }
 
@@ -19,9 +32,32 @@ void stub_lib_flash_deinit(const void *state)
     stub_target_flash_deinit(state);
 }
 
-stub_lib_err_t stub_lib_flash_get_info(stub_lib_flash_info_t *info)
+void stub_lib_flash_get_info(stub_lib_flash_info_t *info)
 {
-    (void)info;
-    // TODO: implement
-    return STUB_LIB_OK;
+    const esp_rom_spiflash_chip_t * chip = stub_target_flash_get_config();
+
+    info->id = chip->flash_id;
+    info->size = chip->chip_size;
+    info->block_size = chip->block_size;
+    info->sector_size = chip->sector_size;
+    info->page_size = chip->page_size;
+    info->mode = 0; // TODO: Implement
+    info->encrypted = 0; // TODO: Implement
+}
+
+void stub_lib_flash_info_print(const stub_lib_flash_info_t *info)
+{
+    (void)info; // to avoid the 'unused-parameter' warning when LOG is disabled
+    STUB_LOGI("Flash info:\n"
+              "\tid: 0x%x, size: %d KB,\n"
+              "\tblock: %d KB (0x%x), sector: %d B (0x%x), page: %d B (0x%x),\n"
+              "\tmode: %d, enc: %d\n",
+              info->id,
+              KB(info->size),
+              KB(info->block_size), info->block_size,
+              info->sector_size, info->sector_size,
+              info->page_size, info->page_size,
+              info->mode,
+              info->encrypted
+             );
 }

src/target/common/CMakeLists.txt

@@ -1,4 +1,5 @@
 set(common_srcs
+    src/flash.c
 )
 
 add_library(${ESP_COMMON_LIB} STATIC ${common_srcs})

src/target/common/include/private/rom_flash.h

@@ -0,0 +1,56 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stdint.h>
+
+typedef struct esp_rom_spiflash_chip {
+    uint32_t flash_id;
+    uint32_t chip_size;    // chip size in bytes
+    uint32_t block_size;
+    uint32_t sector_size;
+    uint32_t page_size;
+    uint32_t status_mask;
+} esp_rom_spiflash_chip_t;
+
+/**
+  * @brief SPI Flash init
+  *
+  * @param spiconfig
+  * (for ESP32 chip)
+  * - 0 for default SPI pins
+  * - 1 for default HSPI pins
+  * - other for custom pin configuration
+  *
+  * (for S2, C3, S3 chips)
+  * - 0 for auto SPI configuration from eFuse is supported
+  * - value for custom pin configuration
+  *
+  * (others chips)
+  * - 0 is only a compatibility value, auto SPI configuration is not supported
+  *
+  * @param legacy
+  * - false is only a deprecated compatibility API value, for all chips
+  *
+  */
+extern void esp_rom_spiflash_attach(uint32_t spiconfig, bool legacy);
+
+/**
+  * @brief Initialize internal ROM config's flash_id from hw registers
+  *
+  */
+extern void esp_rom_spi_flash_update_id(void);
+
+/**
+  * @brief Initialize internal ROM config from arguments
+  *
+  * @return Always returns 0.
+  */
+extern int esp_rom_spiflash_config_param(uint32_t flash_id, uint32_t chip_size,
+                                         uint32_t block_size, uint32_t sector_size,
+                                         uint32_t page_size, uint32_t status_mask);

src/target/common/include/private/rom_flash_config.h

@@ -0,0 +1,20 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#include "rom_flash.h"
+
+typedef struct {
+    esp_rom_spiflash_chip_t chip;
+    uint8_t dummy_len_plus[3];
+    uint8_t sig_matrix;
+} esp_rom_spiflash_legacy_data_t;
+
+extern esp_rom_spiflash_legacy_data_t *rom_spiflash_legacy_data;
+
+#define g_rom_flashchip (rom_spiflash_legacy_data->chip)
+#define g_rom_spiflash_dummy_len_plus (rom_spiflash_legacy_data->dummy_len_plus)

src/target/common/include/target/flash.h

@@ -6,5 +6,52 @@
 
 #pragma once
 
+#include <stdint.h>
+
+struct esp_rom_spiflash_chip;
+
+/**
+ * @brief Initialize SPI Flash hardware.
+ *
+ * Configure SPI pins, registers, mode, etc.
+ *
+ * @param state Unused.
+ */
 void stub_target_flash_init(void *state);
+
+/**
+ * @brief Not implemented. Intended for restoring the state
+ *
+ * @param state Unused.
+ */
 void stub_target_flash_deinit(const void *state);
+
+/**
+ * @brief Retrieve Flash ID (aka flash device id, aka flash chip id) from internal hw.
+ *
+ * @return Flash ID, that includes manufacture and size information.
+ */
+uint32_t stub_target_flash_get_flash_id(void);
+
+/**
+ * @brief Get a pointer to the internal SPI flash config in ROM.
+ *
+ * @return Always a non-NULL, but the structure may be uninitialized or incorrect.
+ */
+const struct esp_rom_spiflash_chip *stub_target_flash_get_config(void);
+
+/**
+ * @brief Set correct values to the internal SPI flash config in ROM
+ *
+ */
+void stub_target_flash_update_config(uint32_t flash_id, uint32_t flash_size);
+
+/**
+ * @brief Infer flash size (in bytes) from Flash ID
+ *
+ * @param flash_id Raw Flash ID value
+ *
+ * @return Flash size in bytes, or:
+ * - 0 if flash_id is unknown
+ */
+uint32_t stub_target_flash_id_to_flash_size(uint32_t flash_id);

src/target/common/src/flash.c

@@ -0,0 +1,50 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#include <stdint.h>
+#include <log.h>
+#include <target/flash.h>
+#include <private/rom_flash.h>
+
+/* Flash geometry constants */
+#define STUB_FLASH_SECTOR_SIZE          0x1000
+#define STUB_FLASH_BLOCK_SIZE           0x10000
+#define STUB_FLASH_PAGE_SIZE            0x100
+#define STUB_FLASH_STATUS_MASK          0xFFFF
+
+void stub_target_flash_update_config(uint32_t flash_id, uint32_t flash_size)
+{
+    (void)esp_rom_spiflash_config_param(flash_id,
+                                        flash_size,
+                                        STUB_FLASH_BLOCK_SIZE,
+                                        STUB_FLASH_SECTOR_SIZE,
+                                        STUB_FLASH_PAGE_SIZE,
+                                        STUB_FLASH_STATUS_MASK);
+}
+
+uint32_t stub_target_flash_id_to_flash_size(uint32_t flash_id)
+{
+    const uint32_t id = flash_id & 0xff;
+    switch (id) {
+    case 0x12:  // 256 KB
+    case 0x13:
+    case 0x14:  // 1 MB
+    case 0x15:
+    case 0x16:
+    case 0x17:
+    case 0x18:
+    case 0x19:  // 32 MB
+    case 0x1A:  // 64 MB
+    case 0x1B:  // 128 MB
+    case 0x1C:  // 256 MB
+        return 1u << id;
+    case 0x39:
+        return 32 * 1024 * 1024;
+    }
+
+    STUB_LOGE("Unknown flash_id: 0x%x", flash_id);
+    return 0;
+}