From patchwork Sun May 13 16:53:27 2012
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Patchwork-Submitter: Mike Dunn
X-Patchwork-Id: 158845
Return-Path:
X-Original-To: incoming@patchwork.ozlabs.org
Delivered-To: patchwork-incoming@bilbo.ozlabs.org
Received: from merlin.infradead.org (merlin.infradead.org
[IPv6:2001:4978:20e::2])
(using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
(Client did not present a certificate)
by ozlabs.org (Postfix) with ESMTPS id DA944B700A
for ;
Mon, 14 May 2012 02:55:40 +1000 (EST)
Received: from localhost ([::1] helo=merlin.infradead.org)
by merlin.infradead.org with esmtp (Exim 4.76 #1 (Red Hat Linux))
id 1STc37-0001PX-28; Sun, 13 May 2012 16:53:37 +0000
Received: from smtp.newsguy.com ([74.209.136.69])
by merlin.infradead.org with esmtps (Exim 4.76 #1 (Red Hat Linux))
id 1STc33-0001PJ-JA
for linux-mtd@lists.infradead.org; Sun, 13 May 2012 16:53:34 +0000
Received: from localhost.localdomain (153.sub-166-250-9.myvzw.com
[166.250.9.153])
by smtp.newsguy.com (8.14.3/8.14.3) with ESMTP id q4DGrUsr004833
(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO);
Sun, 13 May 2012 09:53:31 -0700 (PDT)
(envelope-from mikedunn@newsguy.com)
From: Mike Dunn
To: linux-mtd@lists.infradead.org
Subject: [PATCH] mtd-www: add blurb about API changes and -EUCLEAN to
doc/general
Date: Sun, 13 May 2012 09:53:27 -0700
Message-Id: <1336928007-3603-1-git-send-email-mikedunn@newsguy.com>
X-Mailer: git-send-email 1.7.3.4
X-Spam-Note: CRM114 invocation failed
X-Spam-Score: -0.5 (/)
X-Spam-Report: SpamAssassin version 3.3.2 on merlin.infradead.org summary:
Content analysis details: (-0.5 points)
pts rule name description
---- ----------------------
--------------------------------------------------
1.4 RCVD_IN_BRBL_LASTEXT RBL: RCVD_IN_BRBL_LASTEXT
[74.209.136.69 listed in bb.barracudacentral.org]
-0.0 T_RP_MATCHES_RCVD Envelope sender domain matches handover relay
domain
-0.0 SPF_PASS SPF: sender matches SPF record
-1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1%
[score: 0.0000]
Cc: Mike Dunn
X-BeenThere: linux-mtd@lists.infradead.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Linux MTD discussion mailing list
List-Unsubscribe: ,
List-Archive:
List-Post:
List-Help:
List-Subscribe: ,
MIME-Version: 1.0
Sender: linux-mtd-bounces@lists.infradead.org
Errors-To: linux-mtd-bounces+incoming=patchwork.ozlabs.org@lists.infradead.org
Here's my attempt at the documentation requested by Artem. There was no
discussion of the API, so it seemed like some general info was needed before
discussing EUCLEAN. Also mentioned the switch to the API wrappers.
Signed-off-by: Mike Dunn
---
doc/general.xml | 37 ++++++++++++++++++++++++++++++++++++-
1 files changed, 36 insertions(+), 1 deletions(-)
diff --git a/doc/general.xml b/doc/general.xml
index ea09556..ba76c4f 100644
--- a/doc/general.xml
+++ b/doc/general.xml
@@ -13,6 +13,7 @@
Table of contents
- MTD overview
+ - MTD API
- MTD tests
- The
mtdblock
driver
- Old MTD documentation
@@ -50,7 +51,10 @@ discusses this in more details.
full information about each MTD device in the system. This interface is
easily extensible and developers are encouraged to use the
sysfs
interface instead of older ioctl
or
- /proc/mtd
interfaces, when possible.
+ /proc/mtd
interfaces, when possible. The sysfs
+ interface for the mtd subsystem is documentated in the kernel, and
+ currently can be found at
+ Documentation/ABI/testing/sysfs-class-mtd
.
The /proc/mtd
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.
+
+
+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 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 struct mtd_info
. Prior to kernel version 3.4, higher layers
+called the driver methods directly by way of a pointer to struct
+mtd_info
. 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 mtd.h
outside of struct
+mtd_info
. These methods include mtd_read()
,
+mtd_write()
, etc.
+
+Absent an error, the API methods will return zero, with one notable exception.
+mtd_read()
may return -EUCLEAN
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, -EUCLEAN
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 -EUCLEAN
return
+code is intended to help higher layers detect degradation of erase blocks. The
+conditions by which mtd_read()
returns -EUCLEAN
can be
+tuned using the bitflip_threshold
element of the sysfs interface.
+Please see the kernel documentation for the MTD sysfs interface (referenced
+above) before adjusting this value.
+
+
The MTD subsystem includes a set of tests which you may run to verify your