General MTD documentation

http://www.linux-mtd.infradead.org/doc/general.html

Table of contents

1. MTD overview
2. MTD API
3. MTD tests
4. The mtdblock driver
5. Old MTD documentation

MTD overview

MTD subsystem (stands for Memory Technology Devices) provides an abstractionlayer for raw flash devices. It makes it possible to use the same API whenworking with different flash types and technologies, e.g. NAND, OneNAND, NOR,AG-AND, ECC'd NOR, etc.

MTD subsystem does not deal with block devices like MMC, eMMC, SD,CompactFlash, etc. These devices are not raw flashes but they have a FlashTranslation layer inside, which makes them look like block devices. Thesedevices are the subject of the Linux block subsystem, not MTD. Please, refer tothis FAQ section for a shortlist of the main differences between block and MTD devices. And theraw flash vs. FTL devices UBIFS sectiondiscusses this in more details.

MTD subsystem has the following interfaces.

• MTD character devices - usually referred to as/dev/mtd0, /dev/mtd1, and so on. Thesecharacter devices provide I/O access to the raw flash. They support anumber ofioctl calls for erasing eraseblocks, markingthem as bad or checking if an eraseblock is bad, getting informationabout MTD devices, etc.
• The sysfs interface is relatively newer and it providesfull information about each MTD device in the system. This interface iseasily extensible and developers are encouraged to use thesysfs interface instead of olderioctl or/proc/mtd interfaces, when possible. The sysfsinterface for the mtd subsystem is documentated in the kernel, andcurrently can be found atDocumentation/ABI/testing/sysfs-class-mtd.
• The /proc/mtd proc file system file provides generalMTD information. This is a legacy interface and the sysfs interfaceprovides more information.

MTD subsystem supports bare NAND flashes withsoftware and hardware ECC, OneNAND flashes, CFI(Common Flash Interface)NOR flashes, and other flash types.

Additionally, MTD supports legacy FTL/NFTL "translation layers",M-Systems' DiskOnChip 2000 and Millennium chips, and PCMCIA flashes(pcmciamtd driver). But the corresponding drivers are very old andnot maintained very much.

MTD API

The MTD subsystem API is defined in include/linux/mtd/mtd.h.The methods and data structures in this file are used by higher layer kernelcode such as flash file systems to access and control the mtd devices, and alsoby device driver authors to interface their device to the mtd subsystem. Thevarious methods by which a driver provides access to the device are definedwithinstruct mtd_info. Prior to kernel version 3.4, higher layerscalled the driver methods directly by way of a pointer tostructmtd_info. As of kernel 3.4, these methods are implemented within the mtdsubsystem core code, which then calls the corresponding driver methods. Usersof kernel 3.4 and later should not call the driver methods directly, but insteaduse those prototyped in mtd.h outside of structmtd_info. These methods includemtd_read(),mtd_write(), etc.

Absent an error, the API methods will return zero, with two notable exceptions.mtd_read() andmtd_read_oob() may return-EUCLEAN in some circumstances. This return code is applicablemainly to NAND flash devices, and is used to indicate that some bit errors werecorrected by the device's ECC facility. Prior to kernel version 3.4,-EUCLEAN was returned if one or more bit errors were correctedduring the read operation. As of kernel 3.4, the meaning is more nuanced, andcan be broadly interpreted to mean "a dangerously high number of bit errors werecorrected". The-EUCLEAN return code is intended to help higherlayers detect degradation of erase blocks. The conditions by whichmtd_read() andmtd_read_oob() return-EUCLEAN can be tuned using the bitflip_thresholdelement of the sysfs interface. Please see the kernel documentation for the MTDsysfs interface (referenced above) before adjusting this value.

MTD tests

The MTD subsystem includes a set of tests which you may run to verify yourflash hardware and drivers. The tests are available in the mainline kernelsstarting from kernel version2.6.29 and they live in thedrivers/mtd/tests directory of the linux kernel source codes. Youmay compile the tests as kernel modules by enabling them in the kernelconfiguration menu by marking: "Device Drivers" ->"Memory Technology Device (MTD) support" -> "MTD tests support" (ortheMTD_TESTS symbol in the .config file).

If you have a pre-2.6.29 kernel, you may find the testshere:

git://git.infradead.org/users/ahunter/nand-tests.git

The MTD test-suite contains the following tests:

• mtd_speedtest: measures and reports read/write/erase speedof the MTD device.
• mtd_stresstest: performs random read/write/erase operationsand validates the MTD device I/O capabilities.
• mtd_readtest: this tests reads whole MTD device, one NANDpage at a time including OOB (or 512 bytes at a time in case of flasheslike NOR) and checks that reading works properly.
• mtd_pagetest: relevant only for NAND flashes, tests NAND pagewriting and reading in different sizes and order; this test wasoriginally developed for testing the OneNAND driver, so it might be alittle OneNAND-oriented, but must work on any NAND flash.
• mtd_oobtest: relevant only for NAND flashes, tests that theOOB area I/O works properly by writing data to different offsets andverifying it.
• mtd_subpagetest: relevant only for NAND flashes, testssub-page I/O.
• mtd_torturetest: this test is designed to wear out flasheraseblocks. It repeatedly writes and erases the same group oferaseblocks until an I/O error happens, so be careful! The testsupports a number of options (seemodinfo mtd_torturetest)which allow you to set the amount of eraseblocks to torture and how thetorturing is done. You may limit the amount of torturing cycles usingthecycles_count module parameter. It may be very god ideato run this test for some time and validate your flash driver and HW,providing you have a spare device. For example, we caught rather rareand nasty DMA issues on an OMAP2 board with OneNAND flash, just byrunning this tests for few hours.
• mtd_nandecctest: a simple test that checks correctness of thebuilt-in software ECC for 256 and 512-byte buffers; this test is notdriver-specific but tests general NAND support code.

The mtdblock driver

The mtdblock driver available in the MTD is an archaic toolwhich emulates block devices on top of MTD devices. It does not even havebad eraseblock handling, so it is not really usable with NAND flashes. And itworks by caching a whole flash erase block in RAM, modifying it as requested,then erasing the whole block and writing back the modified. This means thatmtdblock does not try to do any optimizations, and that you willlose lots of data in case of power cuts. And last, but not least,mtdblock does not do any wear-leveling.

Often people consider mtdblock as general FTL layer and try touse block-based file systems on top of bare flashes usingmtdblock. This is wrong in most cases.In other words, please,do not use mtdblock unless youknow exactly what you are doing.

There is also a read-only version of this driver which doesn't have thecapacity to do the caching and erase/writeback, mainly for use with uCLinuxwhere the extra RAM requirement was considered too large.

Old MTD documentation

Old MTD web site and old MTD documentation is availablehere. Old NAND flash interface descriptionis availablehere.