@@ -13,6 +13,7 @@
<h2>Table of contents</h2>
<li><a href="general.html#L_overview">MTD overview</a></li>
+ <li><a href="general.html#L_mtd_api">MTD API</a></li>
<li><a href="general.html#L_mtd_tests">MTD tests</a></li>
<li><a href="general.html#L_mtdblock">The <code>mtdblock</code> driver</a></li>
<li><a href="general.html#L_old_docs">Old MTD documentation</a></li>
@@ -50,7 +51,10 @@ discusses this in more details.</p>
full information about each MTD device in the system. This interface is
easily extensible and developers are encouraged to use the
<code>sysfs</code> interface instead of older <code>ioctl</code> or
- <code>/proc/mtd</code> interfaces, when possible.</li>
+ <code>/proc/mtd</code> interfaces, when possible. The <code>sysfs</code>
+ interface for the mtd subsystem is documentated in the kernel, and
+ currently can be found at
<li>The <code>/proc/mtd</code> proc file system file provides general
MTD information. This is a legacy interface and the sysfs interface
@@ -69,6 +73,37 @@ not maintained very much.</p>
+<h2><a name="L_mtd_api">MTD API</a></h2>
+<p>The MTD subsystem API is defined in <code>include/linux/mtd/mtd.h</code>.
+The methods and data structures in this file are used by higher layer kernel
+code such as flash file systems to access and control the mtd devices, and also
+by device driver authors to interface their device to the mtd subsystem. The
+various methods by which a driver provides access to the device are defined
+within <code>struct mtd_info</code>. Prior to kernel version 3.4, higher layers
+called the driver methods directly by way of a pointer to <code>struct
+mtd_info</code>. As of kernel 3.4, these methods are implemented within the mtd
+subsystem core code, which then calls the corresponding driver methods. Users
+of kernel 3.4 and later should not call the driver methods directly, but instead
+use those prototyped in <code>mtd.h</code> outside of <code>struct
+mtd_info</code>. These methods include <code>mtd_read()</code>,
+Absent an error, the API methods will return zero, with one notable exception.
+<code>mtd_read()</code> may return <code>-EUCLEAN</code> in some circumstances.
+This return code is applicable mainly to NAND flash devices, and is used to
+indicate that some bit errors were corrected by the device's ECC facility.
+Prior to kernel version 3.4, <code>-EUCLEAN</code> was returned if one or more
+bit errors were corrected during the read operation. As of kernel 3.4, the
+meaning is more nuanced, and can be broadly interpreted to mean "a dangerously
+high number of bit errors were corrected". The <code>-EUCLEAN</code> return
+code is intended to help higher layers detect degradation of erase blocks. The
+conditions by which <code>mtd_read()</code> returns <code>-EUCLEAN</code> can be
+tuned using the <code>bitflip_threshold</code> element of the sysfs interface.
+Please see the kernel documentation for the MTD sysfs interface (referenced
+above) before adjusting this value.
<h2><a name="L_mtd_tests">MTD tests</a></h2>
<p>The MTD subsystem includes a set of tests which you may run to verify your