'logical_sector' Argument Nomenclature Issue #67

Activity

1. fdesbiens commented on Apr 28, 2026

   

   fdesbiens

   on Apr 28, 2026

   Contributor

   More actions

   Hi @nflandin

   My apologies for the delay. It seems this issue escaped my notice until now.

   @rahmanih and @ayedm1: What is your take on this?

   👍React with 👍1Reacted by nflandin
2. fdesbiens

   self-assigned this

   on Apr 28, 2026
3. fdesbiens

   added this to ThreadX Roadmapon Apr 28, 2026
4. fdesbiens

   moved this to Discussion in ThreadX Roadmapon Apr 28, 2026
5. fdesbiens commented on Jun 26, 2026

   

   fdesbiens

   on Jun 26, 2026

   Contributor

   More actions

   Thank you @nflandin for raising this — it's a valid and well-reasoned observation, from my perspective.

   After reviewing the codebase, I agree that the sector terminology in the NAND flash API is misleading. In NAND flash architecture, the smallest read/write unit is a page, and a block is a group of pages (the smallest erasable unit). The term "sector" is a filesystem-level concept that doesn't map to NAND hardware, and using it in the NAND API — especially in parameter names like logical_sector and sector_count — creates unnecessary confusion for driver authors.

   Note that this concern applies only to the NAND flash API. The NOR flash API uses logical_sector correctly, as NOR flash genuinely maps filesystem-level logical sectors to physical sectors. Those names should remain unchanged.

   Proposed Changes

   • Rename public API functions: lx_nand_flash_sector_read/write/release → lx_nand_flash_page_read/write/release, and similarly for the sectors_* variants.
   • Rename the logical_sector parameter to logical_page and sector_count to page_count throughout the NAND flash implementation.
   • Introduce a compatibility layer of deprecated macros aliasing the old names to the new ones, to give downstream driver authors a transition path and avoid a hard break.
   • Update documentation accordingly.

   Questions for the Team and Community

   1. Naming philosophy: Should logical_page be the term at the API surface, or is there value in keeping a hardware-agnostic abstraction term (e.g., logical_unit) that works across flash types?
   2. Migration strategy: Is a deprecated-macro compatibility layer sufficient, or would a versioned API break with a clear migration guide be preferable?
   3. Timing: Should this be bundled into a larger release to minimize disruption, or addressed as a standalone fix?

   Feedback from @eclipse-threadx/iot-threadx-committers, @eclipse-threadx/iot-threadx-contributors, and the broader ThreadX community is very welcome!

   👍React with 👍1Reacted by nflandin
6. fdesbiens commented on Sep 30, 2026

   

   fdesbiens

   on Sep 30, 2026

   Contributor

   More actions

   @rahmanih, draft PRs #99 and eclipse-threadx/rtos-docs-asciidoc#103 add page-named NAND read, write, and release APIs and document them. The existing sector names remain compatible aliases to the same symbols. GCC 14.3 NAND regression passed (1/1). Could you review the approach? I’m willing to do it differently if you disagree. I’ll leave this issue open until the PRs merge.
7. fdesbiens

   removed this from ThreadX Roadmapon Sep 30, 2026