This is an automated email from the ASF dual-hosted git repository. xiaoxiang pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 4a765b557ffc0f7b6471483b266869016161be2f Author: jingfei <[email protected]> AuthorDate: Mon Jul 14 23:42:39 2025 +0800 Docs/drviers/mtd:Add description for MTD Device Registration and FTL Control Documentation: 1. Updates the registration process description and flag usage guidelines 2. Includes the MTD open sequence diagram (mtd_open_flow.png) --- Documentation/components/drivers/special/mtd.rst | 79 ++++++++++++++++++++- .../components/drivers/special/mtd_open_flow.png | Bin 0 -> 48832 bytes 2 files changed, 76 insertions(+), 3 deletions(-) diff --git a/Documentation/components/drivers/special/mtd.rst b/Documentation/components/drivers/special/mtd.rst index d9eb3163129..28807be6962 100644 --- a/Documentation/components/drivers/special/mtd.rst +++ b/Documentation/components/drivers/special/mtd.rst @@ -46,10 +46,83 @@ See include/nuttx/mtd/mtd.h for additional information. #. Get an instance of ``struct mtd_dev_s`` from the hardware-specific MTD device driver, and - #. Provide that instance to the initialization method of the - higher level device driver. -- **Examples**: ``drivers/mtd/m25px.c`` and ``drivers/mtd/ftl.c`` + #. Use the ``register_mtddriver`` interface to register the MTD drivers. + +- **Examples**: ``drivers/mtd/m25px.c`` and ``boards/arm/sama5/sama5d4-ek/src/sam_at25.c`` + + +Registration Method +=================== + +The ``register_mtddriver`` function provides a unified interface for +registering MTD devices. Upon registration, the MTD device will automatically +incorporate FTL (Flash Translation Layer) and BCH (Block-to-Character conversion) +wrappers during the ``open()`` process. This automatic wrapping obviates the +need for legacy registration methods ``ftl_initialize()`` and +``bchdev_register()`` in user code. Users can directly access the MTD device +via standard file operations (e.g., ``open()``, ``read()``, ``write()``) +after registration. + +- **Character Device Mode** (via ``open()``): + Enables byte-oriented access with both FTL and BCH layers applied + (requires ``CONFIG_BCH``). + +- **Block Device Mode** (via ``open_blockdriver()``): + Presents a block interface with only the FTL layer enabled + + The functions register_partition_with_mtd() and register_mtdpartition() + are actually wrappers built on top of register_mtddriver(), + and they can be used to create sub-partition devices for MTD devices. + + In scenarios where the FTL layer is not suitable for converting MTD to a + block device, alternatives like Dhara can be used instead. + To register a Dhara-backed block device: Use the ``dhara_initialize()`` + function, passing the underlying ``struct mtd_dev_s *dev`` + as a parameter to create a Dhara block device instance. Once Dhara is + initialized, register the block device using ``register_blockdriver()`` + with the Dhara device's block operations: This approach bypasses the FTL + layer and directly integrates Dhara's block management capabilities with the + MTD device. Dhara provides features such as wear-leveling and bad block + management tailored for specific use cases. + + +Control FTL Behavior via Open Flags +=================================== + +The FTL layer translates MTD operations into block-device semantics +while managing NAND-specific challenges (e.g., bad blocks, wear leveling). +By default, FTL employs a read-modify-write cycle for writes: + +1. Read the entire erase block into a cache buffer. +2. Modify the target data in memory. +3. Erase the physical block. +4. Write the entire buffer back. + +This approach ensures data consistency but introduces latency and requires +sufficient RAM. +To accommodate performance-sensitive applications, +FTL supports the following flags during ``open()``: + +- **``O_DIRECT``**: + Bypasses the read-modify-write cycle, enabling direct writes to flash. + Use this flag when: Write speed is critical or Sufficient RAM for caching + is unavailable. + +- **``O_SYNC``**: + Assumes blocks are pre-erased, skipping the erase step during writes. + This flag only takes effect when used in conjunction with ``O_DIRECT``. + +The diagram below illustrates the workflow when opening an MTD device node +via the ``open()`` function, highlighting how ``oflags`` +(e.g., ``O_DIRECT``, ``O_SYNC``) are propagated through layers to control +FTL behavior: + +.. figure:: ./mtd_open_flow.png + :align: center + :alt: MTD Device Open Sequence with Oflags + + *Figure 1: Sequence of opening an MTD device node and oflag propagation* EEPROM ====== diff --git a/Documentation/components/drivers/special/mtd_open_flow.png b/Documentation/components/drivers/special/mtd_open_flow.png new file mode 100644 index 00000000000..bf6a650560f Binary files /dev/null and b/Documentation/components/drivers/special/mtd_open_flow.png differ
