feat(spi_nand_flash): Add linux target support

.build-test-rules.yml

@@ -79,6 +79,11 @@ spi_nand_flash/test_app:
     - if: IDF_VERSION_MAJOR < 5
       reason: The spi_nand_flash component is compatible with IDF version v5.0 and above, due to a change in the f_mkfs API in versions above v5.0, which is not supported in older IDF versions.
 
+spi_nand_flash/host_test:
+  disable:
+    - if: IDF_VERSION_MAJOR < 5
+      reason: The spi_nand_flash component is compatible with IDF version v5.0 and above, due to a change in the f_mkfs API in versions above v5.0, which is not supported in older IDF versions.
+
 thorvg/examples/thorvg-example:
   enable:
     - if: (IDF_VERSION_MAJOR == 5 and IDF_VERSION_MINOR >= 3) and (IDF_TARGET in ["esp32p4"])

spi_nand_flash/CMakeLists.txt

@@ -1,28 +1,45 @@
+idf_build_get_property(target IDF_TARGET)
+
+set(inc diskio include)
+set(priv_inc priv_include)
 set(srcs "src/nand.c"
-         "src/nand_winbond.c"
-         "src/nand_gigadevice.c"
-         "src/nand_alliance.c"
-         "src/nand_micron.c"
-         "src/nand_impl.c"
-         "src/nand_impl_wrap.c"
-         "src/nand_diag_api.c"
-         "src/spi_nand_oper.c"
          "src/dhara_glue.c"
-         "vfs/vfs_fat_spinandflash.c"
+         "src/nand_impl_wrap.c"
          "diskio/diskio_nand.c")
 
-set(reqs fatfs)
+if(${target} STREQUAL "linux")
+
+list(APPEND srcs "src/nand_impl_linux.c"
+                 "src/nand_linux_mmap_emul.c")
+
+else()
+
+list(APPEND srcs "src/nand_winbond.c"
+                 "src/nand_gigadevice.c"
+                 "src/nand_alliance.c"
+                 "src/nand_micron.c"
+                 "src/nand_impl.c"
+                 "src/nand_impl_wrap.c"
+                 "src/nand_diag_api.c"
+                 "src/spi_nand_oper.c"
+                 "vfs/vfs_fat_spinandflash.c")
+
+set(priv_reqs vfs)
+list(APPEND inc vfs)
 
 if("${IDF_VERSION_MAJOR}.${IDF_VERSION_MINOR}" VERSION_GREATER "5.3")
     list(APPEND reqs esp_driver_spi)
 else()
     list(APPEND reqs driver)
 endif()
 
-set(priv_reqs vfs)
+endif()
+
 
 idf_component_register(SRCS ${srcs}
-        INCLUDE_DIRS include vfs diskio
-        PRIV_INCLUDE_DIRS "priv_include"
+        INCLUDE_DIRS ${inc}
+        PRIV_INCLUDE_DIRS ${priv_inc}
         REQUIRES ${reqs}
         PRIV_REQUIRES ${priv_reqs})
+
+target_link_libraries(${COMPONENT_LIB} PRIVATE idf::fatfs)

spi_nand_flash/Kconfig

@@ -7,4 +7,11 @@ menu "SPI NAND Flash configuration"
             If this option is enabled, any time SPI NAND flash is written then the data will be read
             back and verified. This can catch hardware problems with SPI NAND flash, or flash which
             was not erased before verification.
+
+    config NAND_ENABLE_STATS
+        bool "Host test statistics enabled"
+        depends on IDF_TARGET_LINUX
+        default n
+        help
+            This option enables gathering host test statistics and SPI NAND flash wear levelling simulation.
 endmenu

spi_nand_flash/README.md

@@ -18,6 +18,28 @@ SPI NAND Flash combines the benefits of NAND Flash technology with the simplicit
 
 * Fast Read/Write Operations: The SPI interface enables reasonably fast read and write operations, making it suitable for applications where data access speed is crucial.
 
+### Implementation Architecture
+
+```mermaid
+graph TD
+    A[Application] --> B[FATFS]
+    B --> C[Dhara Library]
+    C --> Hardware_Path[Hardware Path]
+    C --> Linux_Path[Linux Path]
+
+    subgraph Hardware_Path [Hardware Path]
+        HP1[NAND Flash Layer]
+        HP1 --> HP2[SPI NAND Flash Driver]
+        HP2 --> HP3["SPI Driver (ESP-IDF)"]
+        HP3 --> HP4[Hardware via SPI]
+    end
+
+    subgraph Linux_Path [Linux Path]
+        LP1[NAND Flash Layer]
+        LP1 --> LP2[NAND Emulation Layer]
+        LP2 --> LP3[Memory Mapped File]
+    end
+```
 ## Supported SPI NAND Flash chips
 
 At present, `spi_nand_flash` component is compatible with the chips produced by the following manufacturers and and their respective model numbers:

spi_nand_flash/diskio/diskio_nand.c

@@ -6,7 +6,6 @@
  * SPDX-FileContributor: 2015-2023 Espressif Systems (Shanghai) CO LTD
  */
 
-#include "ff.h"
 #include "diskio.h"
 #include "esp_log.h"
 #include "esp_check.h"
@@ -133,11 +132,12 @@ DRESULT ff_nand_ioctl(BYTE pdrv, BYTE cmd, void *buff)
         break;
     }
 #if FF_USE_TRIM
-    case CTRL_TRIM:
+    case CTRL_TRIM: {
         DWORD start_sector = *((DWORD *)buff);
         DWORD end_sector = *((DWORD *)buff + 1) + 1;
         DWORD sector_count = end_sector - start_sector;
         return ff_nand_trim(pdrv, start_sector, sector_count);
+    }
 #endif //FF_USE_TRIM
     default:
         return RES_ERROR;

spi_nand_flash/diskio/diskio_nand.h

@@ -9,7 +9,6 @@
 #pragma once
 
 #include "spi_nand_flash.h"
-#include "ff.h"
 
 #ifdef __cplusplus
 extern "C" {

spi_nand_flash/examples/nand_flash/main/CMakeLists.txt

@@ -1,4 +1,4 @@
 idf_component_register(SRCS "spi_nand_flash_example_main.c"
                        INCLUDE_DIRS "."
-                       PRIV_REQUIRES spi_nand_flash
+                       PRIV_REQUIRES spi_nand_flash fatfs
                        )

spi_nand_flash/examples/nand_flash_debug_app/main/CMakeLists.txt

@@ -1,4 +1,4 @@
 idf_component_register(SRCS "spi_nand_flash_debug_app_main.c"
                        INCLUDE_DIRS "."
-                       PRIV_REQUIRES spi_nand_flash esp_timer
+                       PRIV_REQUIRES spi_nand_flash esp_timer fatfs
                        )

spi_nand_flash/host_test/README.md

@@ -0,0 +1,54 @@
+| Supported Targets | Linux |
+| ----------------- | ----- |
+
+# Host Test for SPI NAND Flash Emulation
+
+## NAND Flash Emulation Configuration
+
+The NAND flash emulation can be configured using the `nand_mmap_emul_config_t` structure:
+
+```c
+// Configuration structure for NAND emulation
+nand_mmap_emul_config_t cfg = {
+    .flash_file_name = "",                  // Empty string for temporary file, or specify path
+    .flash_file_size = EMULATED_NAND_SIZE,  // Default is 128MB
+    .keep_dump = true                       // true to keep file after tests
+};
+```
+
+### Configuration Options:
+
+1. **flash_file_name**:
+   - Empty string ("") - Creates temporary file with pattern "/tmp/idf-nand-XXXXXX"
+   - Custom path - Creates file at specified location
+   - Maximum length: 256 characters
+
+2. **flash_file_size**:
+   - Default: EMULATED_NAND_SIZE (128MB)
+   - Can be customized based on test requirements
+   - Must be aligned to block size
+
+3. **keep_dump**:
+   - true: Removes the memory-mapped file after testing
+   - false: Keeps the file for debugging or data persistence
+
+### Usage Example:
+
+```c
+// Initialize with custom settings
+nand_mmap_emul_config_t cfg = {
+    .flash_file_name = "/tmp/my_nand.bin",
+    .flash_file_size = 1024 * 1024,  // 1MB
+    .keep_dump = false
+};
+spi_nand_flash_config_t nand_flash_config = {.emul_conf = &cfg};
+
+// Initialize nand_flash with NAND emulation parameter
+spi_nand_flash_device_t *handle;
+spi_nand_flash_init_device(&nand_flash_config, &handle)
+
+// Use NAND operations...
+
+// Cleanup
+ESP_ERROR_CHECK(spi_nand_flash_deinit_device(handle));
+```

spi_nand_flash/host_test/nand_flash_host_example/CMakeLists.txt

@@ -0,0 +1,6 @@
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+set(COMPONENTS main)
+
+project(nand_flash_host_example)

spi_nand_flash/host_test/nand_flash_host_example/main/CMakeLists.txt

@@ -0,0 +1,6 @@
+idf_component_register(SRCS "nand_flash_host_example.cpp"
+                       REQUIRES fatfs
+                       WHOLE_ARCHIVE
+                       )
+
+target_link_libraries(${COMPONENT_LIB} PRIVATE Catch2WithMain)

spi_nand_flash/host_test/nand_flash_host_example/main/idf_component.yml

@@ -0,0 +1,5 @@
+dependencies:
+  espressif/catch2: "^3.4.0"
+  espressif/spi_nand_flash:
+    version: '*'
+    override_path: '../../../'

spi_nand_flash/host_test/nand_flash_host_example/main/nand_flash_host_example.cpp

@@ -0,0 +1,104 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdio.h>
+#include <catch2/catch_session.hpp>
+#include <catch2/catch_test_macros.hpp>
+
+#include "ff.h"
+#include "esp_log.h"
+#include "diskio_impl.h"
+#include "diskio_nand.h"
+#include "spi_nand_flash.h"
+#include "nand_linux_mmap_emul.h"
+
+const char *TAG = "nand_host_example";
+
+extern "C" void app_main(void)
+{
+    ESP_LOGI(TAG, "Starting application");
+    FRESULT fr_result;
+    BYTE pdrv;
+    FATFS fs;
+    FIL file;
+    UINT bw;
+
+    esp_err_t esp_result;
+    nand_file_mmap_emul_config_t conf = {};
+    spi_nand_flash_config_t nand_flash_config = {.emul_conf = &conf};
+    spi_nand_flash_device_t *device_handle;
+    assert(spi_nand_flash_init_device(&nand_flash_config, &device_handle) == ESP_OK);
+
+    // Get a physical drive
+    esp_result = ff_diskio_get_drive(&pdrv);
+    assert(esp_result == ESP_OK);
+
+    // Register physical drive as wear-levelled partition
+    esp_result = ff_diskio_register_nand(pdrv, device_handle);
+
+    // Create FAT volume on the entire disk
+    LBA_t part_list[] = {100, 0, 0, 0};
+    BYTE work_area[FF_MAX_SS];
+
+    fr_result = f_fdisk(pdrv, part_list, work_area);
+    assert(fr_result == FR_OK);
+
+    char drv[3] = {(char)('0' + pdrv), ':', 0};
+    const MKFS_PARM opt = {(BYTE)(FM_ANY), 0, 0, 0, 0};
+    fr_result = f_mkfs(drv, &opt, work_area, sizeof(work_area)); // Use default volume
+    assert(fr_result == FR_OK);
+
+    // Mount the volume
+    fr_result = f_mount(&fs, drv, 0);
+    assert(fr_result == FR_OK);
+
+    // Open, write and read data
+    fr_result = f_open(&file, "0:/test.txt", FA_OPEN_ALWAYS | FA_READ | FA_WRITE);
+    assert(fr_result == FR_OK);
+
+    // Generate data
+    uint32_t data_size = 1000;
+
+    char *data = (char *) malloc(data_size);
+    char *read = (char *) malloc(data_size);
+
+    for (uint32_t i = 0; i < data_size; i += sizeof(i)) {
+        *((uint32_t *)(data + i)) = i;
+    }
+
+    // Write generated data
+    fr_result = f_write(&file, data, data_size, &bw);
+    assert(fr_result == FR_OK);
+    assert(bw == data_size);
+
+    // Move to beginning of file
+    fr_result = f_lseek(&file, 0);
+    assert(fr_result == FR_OK);
+
+    // Read written data
+    fr_result = f_read(&file, read, data_size, &bw);
+    assert(fr_result == FR_OK);
+    assert(bw == data_size);
+
+    assert(memcmp(data, read, data_size) == 0);
+
+    // Close file
+    fr_result = f_close(&file);
+    assert(fr_result == FR_OK);
+
+    // Unmount default volume
+    fr_result = f_mount(0, drv, 0);
+    assert(fr_result == FR_OK);
+
+    // Clear
+    free(read);
+    free(data);
+    ff_diskio_unregister(pdrv);
+    ff_diskio_clear_pdrv_nand(device_handle);
+    spi_nand_flash_deinit_device(device_handle);
+
+    ESP_LOGI(TAG, "Returned from app_main");
+}

spi_nand_flash/host_test/nand_flash_host_example/pytest_nand_flash_linux.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD                                                                                   
+# SPDX-License-Identifier: Unlicense OR CC0-1.0
+import pytest
+from pytest_embedded import Dut 
+
+
+@pytest.mark.linux
+@pytest.mark.host_test
+def test_nand_flash_linux(dut: Dut) -> None:
+    dut.expect_exact("Starting application")
+    dut.expect_exact("Returned from app_main")

spi_nand_flash/host_test/nand_flash_host_example/sdkconfig.defaults

@@ -0,0 +1,5 @@
+CONFIG_IDF_TARGET="linux"
+CONFIG_COMPILER_CXX_EXCEPTIONS=y
+CONFIG_UNITY_ENABLE_IDF_TEST_RUNNER=n
+CONFIG_MMU_PAGE_SIZE=0X10000
+CONFIG_NAND_ENABLE_STATS=y

spi_nand_flash/host_test/nand_flash_host_test/CMakeLists.txt

@@ -0,0 +1,6 @@
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+set(COMPONENTS main)
+
+project(nand_flash_host_test)

spi_nand_flash/host_test/nand_flash_host_test/main/CMakeLists.txt

@@ -0,0 +1,6 @@
+idf_component_register(SRCS "test_nand_flash.cpp" "test_app_main.cpp"
+                       REQUIRES fatfs
+                       WHOLE_ARCHIVE
+                       )
+
+target_link_libraries(${COMPONENT_LIB} PRIVATE Catch2WithMain)

spi_nand_flash/host_test/nand_flash_host_test/main/idf_component.yml

@@ -0,0 +1,5 @@
+dependencies:
+  espressif/catch2: "^3.4.0"
+  espressif/spi_nand_flash:
+    version: '*'
+    override_path: '../../../'