feat(spi_nand_flash): Add block device support

[RathiSonika]

Change description

• Add block device support (nand_flash_bdl and nand_wl_bdl)

• Please refer spi_nand_flash/layered_architecture.md for the details and migration guide

• Refactor the component for improved structure, maintainability and readability
  - Added page-based API terminology (read_page, write_page, get_page_count, get_page_size) with backward-compatible sector aliases.

• Removed the fatfs/vfs component dependency; it will be relocated (along with examples) to another component in a different PR.

• Add Kconfig option NAND_FLASH_ENABLE_BDL to enable/disable BDL support

• Updated test_apps and host_tests to verify the same

• OTP and OOB area handling are still missing. I’ll address them in a separate PR, as the scope of this one is already growing.

[pacucha42]

Outcome of the final review:

1. Flash BDL erase: missing out-of-bounds check

Severity: High

nand_flash_blockdev_erase() validates alignment and non-zero length but never checks whether the erase range exceeds device bounds. An erase request past the end of flash passes all validation and proceeds to erase non-existent blocks.

Both nand_flash_blockdev_read() and nand_flash_blockdev_write() in the same file have this check. The WL BDL erase (spi_nand_flash_wl_blockdev_erase()) also has it.

Location: spi_nand_flash/src/nand_flash_blockdev.c, nand_flash_blockdev_erase()

Fix — add after the erase_len alignment check:

if (start_addr + erase_len > handle->geometry.disk_size) {
    ESP_LOGE(TAG, "Erase range exceeds device bounds");
    return ESP_ERR_INVALID_SIZE;
}

---

2. dhara_nand_read BDL path: dst_buf_size doesn't match actual buffer

Severity: Medium

In the BDL path of dhara_nand_read():

ret = bdl_handle->ops->read(bdl_handle, data, bdl_handle->geometry.read_size,
                            (p * bdl_handle->geometry.read_size) + offset, length);

bdl_handle->geometry.read_size (full page size, e.g. 2048) is passed as dst_buf_size, but Dhara's data buffer is only length bytes. The current read implementation only writes data_read_len bytes so there is no buffer overflow today; however, the safety check (dst_buf_size < data_read_len) is semantically defeated — it can never trip even when the actual buffer is smaller than claimed.

Location: spi_nand_flash/src/dhara_glue.c, dhara_nand_read()

Fix:

ret = bdl_handle->ops->read(bdl_handle, data, length,
                            (p * bdl_handle->geometry.read_size) + offset, length);

---

3. spi_nand_flash_init_device() doxygen not updated for BDL incompatibility

Severity: Medium

When CONFIG_NAND_FLASH_ENABLE_BDL=y, spi_nand_flash_init_device() unconditionally returns ESP_ERR_NOT_SUPPORTED. The CHANGELOG and migration guide document this, but:

• The doxygen on spi_nand_flash_init_device() in spi_nand_flash.h is unchanged — a user reading only the header won't know until runtime.
• The Kconfig help text for NAND_FLASH_ENABLE_BDL says "When disabled, only the legacy API is available" but does not state the inverse: when enabled, spi_nand_flash_init_device() is not available.

Location: spi_nand_flash/include/spi_nand_flash.h (doxygen of spi_nand_flash_init_device), spi_nand_flash/Kconfig

Fix:

Add to spi_nand_flash_init_device() doxygen:

 * @note When CONFIG_NAND_FLASH_ENABLE_BDL is enabled, this function returns
 *       ESP_ERR_NOT_SUPPORTED. Use spi_nand_flash_init_with_layers() instead.

Add to Kconfig help:

When enabled, the legacy spi_nand_flash_init_device() is not available
(returns ESP_ERR_NOT_SUPPORTED). Use spi_nand_flash_init_with_layers().

---

4. Triplicated ECC threshold check logic

Severity: Low

The same ECC-threshold comparison exists in three places:

File	Function
src/nand_flash_blockdev.c	is_ecc_exceed_threshold()
src/nand_diag_api.c	is_ecc_exceed_threshold()
src/nand.c	s_need_data_refresh()

All three are identical: compare ecc_corrected_bits_status against ecc_data_refresh_threshold using the same 1/4/7 mapping.

Fix: Extract a single shared helper (e.g. static inline in a private header) and call it from all three sites.

---

5. chip_name stores only manufacturer name

Severity: Low

Device init files (nand_gigadevice.c, nand_micron.c, nand_winbond.c, etc.) set chip_name to just the manufacturer string:

char *name = "gigadevice";
strncpy(dev->device_info.chip_name, name, strlen(name) + 1);

The GET_NAND_FLASH_INFO ioctl exposes this to users. For diagnostics, a model-specific name (e.g. "GD5F1GQ5UExxG" or at least "gigadevice-0x51") would be more useful. The 32-byte chip_name field is underutilized.

---

6. size_t → uint32_t truncation in erase log

Severity: Low

In nand_flash_blockdev_erase():

ESP_LOGV(TAG, "erase - ... size=0x%08" PRIx32 " ...", ..., (uint32_t)erase_len, ret);

erase_len is size_t (64-bit on Linux host). The (uint32_t) cast silently truncates. The WL erase log has the same pattern. Use %zx or cast to uint64_t with PRIx64.

---

Summary

#	Severity	Issue
1	High	Flash BDL erase: missing out-of-bounds check
2	Medium	dhara_nand_read BDL path: dst_buf_size doesn't match actual buffer
3	Medium	spi_nand_flash_init_device() doxygen/Kconfig not updated for BDL incompatibility
4	Low	Triplicated ECC threshold check logic
5	Low	chip_name only stores manufacturer, not model
6	Low	size_t → uint32_t truncation in erase log

After fixing those points (1,2,3 and 6 at least), the PR can be merged.

Thank you

[hfudev]

CI changes LGTM.

[pacucha42]

Great! Thank you for addressing all the comments. Approving

[hfudev]

need to revert the deletion of the workaround: https://github.com/espressif/idf-extra-components/compare/554f4734e8927e1308bfca81d213f39e512efdba..14991e0849cb7d6e2a7c41067d460657a54135d9

the latest docker images still requires hours to be created.

[hfudev]

need to revert the deletion of the workaround: https://github.com/espressif/idf-extra-components/compare/554f4734e8927e1308bfca81d213f39e512efdba..14991e0849cb7d6e2a7c41067d460657a54135d9

the latest docker images still requires hours to be created.

the latest docker image has been updated!

[haberturdeur]

Besides a small nitpick LGTM!

[pacucha42]

All looks good, approviing. Thank you @RathiSonika