Changelog

# Changelog

All notable changes to this component will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). See [VERSIONING.md](VERSIONING.md) for this component's versioning policy.

## [Unreleased]

## [1.5.0] - 2026-11-20

### Added

- Support for Zbit ZB35Q01CYIG
- New `nand_ecc_status_t` values: `NAND_ECC_1_TO_4_BITS_CORRECTED`, `NAND_ECC_1_TO_7_BITS_CORRECTED`, `NAND_ECC_5_TO_8_BITS_CORRECTED`, exact counts `NAND_ECC_1_BIT_CORRECTED` ... `NAND_ECC_8_BITS_CORRECTED`, and `NAND_ECC_INVALID` for an ECC status that cannot be determined
- **Generic chip detection (opt-in, BDL only):** When `CONFIG_NAND_FLASH_GENERIC_CHIP_DETECTION=y` (requires BDL), init bypasses the vendor database, uses ONFI parameter page then `GENERIC_GEOMETRY_*` Kconfig fallback, runs non-destructive probes, and exposes a **read-only Flash BDL** by default. Optional `CONFIG_NAND_FLASH_GENERIC_WRITE_ERASE_ENABLE` allows program/erase only after on-die ECC (CFG bit 4) is confirmed. Wear-leveling / FatFS are not supported on this path.
- Flash BDL ioctls `ESP_BLOCKDEV_CMD_GET_CHIP_SOURCE` (`DATABASE` | `ONFI` | `KCONFIG`) and `ESP_BLOCKDEV_CMD_GET_GENERIC_PROBE_REPORT`. The probe-report ioctl returns `ESP_ERR_NOT_SUPPORTED` when generic detection is off.

### Changed

- ECC status is decoded per chip family, so some chips now report different `nand_ecc_status_t` values than before. Code that compares against a single exact value (e.g. `== NAND_ECC_4_TO_6_BITS_CORRECTED`) should be reviewed; checking `NAND_ECC_NOT_CORRECTED` / `NAND_ECC_INVALID` for failures is unaffected:
  - Winbond KV (W25N02KV, W25N04KV) and Macronix (MX35LF2GE4AD, MX35LF4GE4AD): exact corrected bit count, read from the chip's extra ECC register
  - Winbond 1-bit ECC parts (W25N512G, W25N01G, W25N01JW): `NAND_ECC_1_BIT_CORRECTED`
  - Alliance and Zetta: values matching each chip's ECC strength (`1_TO_3` / `4_BITS` or `1_TO_7` / `8_BITS`)
  - XTX XT26G08D: a correction is reported as `NAND_ECC_8_BITS_CORRECTED`
- Winbond: the driver now switches the chip to Buffer Read mode (BUF=1) at init if it powered up with BUF=0. On KV parts BUF=0 also disables internal ECC.
- Winbond 1-bit ECC parts: data refresh threshold set to 1, so any corrected bit triggers a refresh

### Fixed

- feat: map ECC status correctly on GigaDevice chips using the ECCSE bits (status register F0h)
- fix: `nand_prog()` with `CONFIG_NAND_FLASH_VERIFY_WRITE` ignored a data mismatch when the page markers were intact, and did not check the ECC status of the verify read
- fix: `nand_copy()` with `CONFIG_NAND_FLASH_VERIFY_WRITE` read the reference data from the cache after Program Execute, where it is no longer valid, causing false verify failures
- fix: `nand_copy()` via RAM issued Program Execute twice (the second one without Write Enable) and leaked the copy buffer on error paths
- fix: `nand_prog()` and `nand_copy()` return `ESP_ERR_NOT_FINISHED` for every failure after Program Execute (including verify failures), so the page is never programmed again
- fix: allocate the verify and copy buffers before Program Execute, and from non-DMA memory on IDF >= 5.2
- fix: `nand_copy()` no longer uses Internal Data Move across LUNs (each LUN has its own cache, so the destination received stale data from the other LUN's cache); GD5F8GM8UExxG is described as one target with two LUNs of 2048 blocks (new `nand_flash_geometry_t::num_luns_per_target`)
- fix: Dhara glue always sets the error code, as required by the Dhara NAND contract: `DHARA_E_BAD_BLOCK` only when the chip may have been programmed or erased (`ESP_ERR_NOT_FINISHED`), `DHARA_E_ECC` for an uncorrectable ECC failure (`ESP_FAIL` with ECC status `NAND_ECC_NOT_CORRECTED` on read or copy source), `DHARA_E_NONE` for host-side or transient failures, which no longer retire the block; previously Dhara could program the same page twice after a failure
- Winbond 1-bit ECC parts: ECC field value `11b` is now reported as `NAND_ECC_NOT_CORRECTED` instead of `NAND_ECC_4_TO_6_BITS_CORRECTED`

### Deprecated

- `nand_ecc_data_t.ecc_status_reg_len_in_bits`: no longer used by the driver

### Notes
- Generic path uses SIO only; plane count from `CONFIG_NAND_FLASH_GENERIC_NUM_PLANES` (default 1). ECC STATUS is not decoded (`NAND_ECC_UNKNOWN`). OOB remains the baseline 4-byte markers at `page_size`.
- Default builds (generic detection **off**) remain database-only.

## [1.4.4] - 2026-09-10

### Fixed

- Extraction of ECC status bits

### Changed

- Demote per-page/per-block traces (`is_bad`, `erase_block`, `is_free`) from debug to verbose log level, since they flooded the log during any full-chip scan or erase

## [1.4.3]
- fix: add STAT_BUSY hang timeout in wait_for_ready

## [1.4.2]
- fix: use Internal Data Move same-parity handling for GigaDevice chips that require it (GD5F2GQ5, GD5F2GM7, GD5F4GQ6, GD5F4GM8, GD5F4GM7, GD5F8GM8), without treating them as hardware dual-plane

## [1.4.1]
- fix: free SPI bus in Unity tearDown so a failed test case does not leave the bus initialized for later cases

## [1.4.0]
- feat: added support for Gigadevice GD5F8GM8UExxG NAND flash

## [1.3.0]
- feat: added support for Macronix MX35LF2GE4AD, MX35LF4GE4AD NAND flash

## [1.2.0]
- feat: added support for Gigadevice GD5F4GM7UExxG NAND flash

## [1.1.0]
- feat: added support for Fudan Microelectronics (FM25S005BI3) NAND flash

## [1.0.3]
### Dependencies
- **Dhara** is now consumed as the in-repo `espressif/dhara` component at **1.0.0** (vendored upstream snapshot; the git submodule under `dhara/` is removed). The manifest dependency range is **`1.*`** (was `0.1.*`), matching the new component version with the same `override_path: "../dhara"` layout.

### Documentation
- README: clarify that Dhara is provided by the vendored `espressif/dhara` component and that no separate submodule checkout is required.

## [1.0.2]
### Fixes
- BDL error logging: correct format specifiers for size fields on 64-bit Linux (avoids undefined behavior and wrong log output).
- Linux NAND emulation: OOB markers and free-page detection aligned with the real hardware path.
- Linux mmap: correct backing file path selection for the emulated image.
- Linux mmap layout: on-disk stride accounts for interleaved OOB vs user-visible erase block size (bad-block handling, erase, and OOB clearing).

### Documentation
- Linux mmap emulator config: note how backing file size maps to interleaved OOB and reported user capacity.

### Testing
- Linux host tests: broader FTL and BDL coverage.
- Shared buffer pattern helpers (including seeded patterns) for host tests and the in-tree test application.

## [1.0.1]
- fix: fix incorrect flash geometry parameter for flash GD5F4GM8xExxG

## [1.0.0]
### Breaking Changes
- FATFS integration has been moved to a separate `spi_nand_flash_fatfs` component. Projects using FATFS with NAND flash must add `spi_nand_flash_fatfs` as a dependency. FatFs on SPI NAND still requires the **legacy** init path: keep **`CONFIG_NAND_FLASH_ENABLE_BDL` disabled** for that use case (no FatFs-on-BDL support in this release).
- When `CONFIG_NAND_FLASH_ENABLE_BDL` is enabled, the legacy `spi_nand_flash_init_device()` returns `ESP_ERR_NOT_SUPPORTED`. Use `spi_nand_flash_init_with_layers()` instead for block-device consumers.
- `spi_nand_erase_chip()` performs a physical full-media erase. Previously, the driver incorrectly attempted to erase every block without checking bad-block markers, which could erase factory-marked bad blocks. It now skips bad blocks and physically erases only blocks that are not marked bad.

### New Features
- Added Block Device Layer (BDL) support, available from ESP-IDF v6.0. Provides standard `esp_blockdev_t` interfaces for both raw flash access and wear-leveling.
- Added `spi_nand_flash_init_with_layers()` API for layered block device initialization.
- Added page-based API terminology (`read_page`, `write_page`, `get_page_count`, `get_page_size`) with backward-compatible sector aliases.

### Improvements
- Refactor the component for improved structure, maintainability and readability
- Sector API functions are now deprecated aliases for the page API equivalents.

**Migration:** See **Migration Guide (0.x → 1.0.0)** in [layered_architecture.md](layered_architecture.md).

## [0.21.0]
- fix: spi_nand_read fails in case buffer is not DMA aligned (https://github.com/espressif/idf-extra-components/issues/708)

## [0.20.0]
- feat: added support for Gigadevice (GD5F1GM7xExxG) NAND flash

## [0.19.0]
- fix: spi_nand_program_load fails in case buffer is not DMA aligned (https://github.com/espressif/idf-extra-components/issues/684)

## [0.18.0]
- fix: Update esp_vfs_fat_register prototype to esp_vfs_fat_register_cfg to align with ESP-IDF v6.0. The cfg version is now the primary API and remains aliased for compatibility.

## [0.17.0] 
- fix: fix a compilation error caused by the missing freertos/FreeRTOS.h header when building with ESP-IDF v6.0 and later.
- update: improvements to the lower-level APIs following updates in esp_driver_spi.

## [0.16.0]
- fix: fix nand flash issue caused by data length unalignment on esp32p4

## [0.15.0]
- feat: added support for Gigadevice (GD5F2GM7xExxG) NAND flash

## [0.14.0]
- feat: added support for XTX (XT26G08D) and Gigadevice (GD5F4GM8) NAND flash

## [0.13.0]
- feat: added support for Zetta (ZD35Q1GC) NAND flash
        and Winbond (W25N02KVxxIR/U, W25N04KVxxIR/U) NAND flash chips.

## [0.12.0]
- feat: added micron dual-plane nand flash chip (MT29F2G) support
- fix: fixed build failure in host tests

## [0.11.0]
- feat: added QIO mode support

## [0.10.0]
- feat: added support for standard SPI mode (full-duplex) and DIO mode

## [0.9.0]
- feat: added linux target support
- fix: fixed memory alignment issue occurring on esp32c3

## [0.8.0]
- feat: added diagnostics application

## [0.7.0]
- feat: exposed lower-level API and make it usable without dhara library

## [0.6.0]
- feat: implemented CTRL_TRIM in fatfs diskio layer
- feat: added data refresh threshold for ECC correction

## [0.5.0]
- feat: added Kconfig option to verify write operations
- feat: added support for Micron MT29F1G01ABAFDSF-AAT:F

## [0.4.1]
- update: handled alignment and DMA requirements for work buffers

## [0.4.0]
- fix: fixed memory leaks in test, add performance log

## [0.3.1]
- fix: correct calloc call arguments for GCC14 compat

## [0.3.0]
- fix: use 32 bit sector size and id

## [0.2.0]
- feat: added support for Micron MT29F nand flash

## [0.1.0]
- Initial release with basic NAND flash support based on dhara nand library
- Support for Winbond, Alliance and Gigadevice devices
- Added test application for the same