* [PATCH 0/5] Convert more books to ReST
@ 2017-05-13 11:10 Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 1/5] docs-rst: convert librs book " Mauro Carvalho Chehab
` (5 more replies)
0 siblings, 6 replies; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-13 11:10 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Richard Weinberger, linux-mtd,
Greg Kroah-Hartman, Brian Norris, Jani Nikula, Yoshinori Sato,
Markus Heiser, Cyrille Pitchen, Herton R. Krzesinski,
Boris Brezillon, Marek Vasut, Sebastian Andrzej Siewior,
linux-sh, Takashi Iwai, David Woodhouse, Rich Felker,
Silvio Fricke, sayli karnik, linux-security-module
This patch series convert the following books to ReST:
- librs
- mtdnand
- sh
And it is based on my previous series of conversion patches.
After this series, there will be just one DocBook pending conversion:
- lsm (Linux Security Modules)
This book is very outdated: no changes since the Kernel moved
to git, in 2005 (except for a minor editorial fix in 2008).
I took a look on the described API: it doesn't seem to be describing
the current security implementation.
The best here is if someone that works with LSM to convert it to
ReST with:
$ Documentation/sphinx/tmplcvt Documentation/DocBook/lsm.tmpl lsm.rst
And fix the document to produce something that reflects the current
implementation. If nobody is interested, then maybe we could just
drop it.
-
This patch series is based on my past 00/36 patch series, applied on
the top of docs tree (next branch).
The full patch series is on this tree is at:
https://git.linuxtv.org//mchehab/experimental.git/log/?h=docbook
And the HTML output at:
http://www.infradead.org/~mchehab/kernel_docs/
https://mchehab.fedorapeople.org/kernel_docs/
Mauro Carvalho Chehab (5):
docs-rst: convert librs book to ReST
docs-rst: convert mtdnand book to ReST
mtdnand.rst: Fix some typos and group the "::" with previous line
mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings
docs-rst: convert sh book to ReST
Documentation/DocBook/Makefile | 5 +-
Documentation/DocBook/librs.tmpl | 289 --------
Documentation/DocBook/mtdnand.tmpl | 1291 ----------------------------------
Documentation/DocBook/sh.tmpl | 105 ---
Documentation/conf.py | 2 +
Documentation/core-api/index.rst | 1 +
Documentation/core-api/librs.rst | 212 ++++++
Documentation/driver-api/index.rst | 1 +
Documentation/driver-api/mtdnand.rst | 1007 ++++++++++++++++++++++++++
Documentation/index.rst | 11 +
Documentation/sh/index.rst | 59 ++
drivers/mtd/nand/nand_base.c | 7 +-
include/linux/mtd/nand.h | 2 +-
13 files changed, 1300 insertions(+), 1692 deletions(-)
delete mode 100644 Documentation/DocBook/librs.tmpl
delete mode 100644 Documentation/DocBook/mtdnand.tmpl
delete mode 100644 Documentation/DocBook/sh.tmpl
create mode 100644 Documentation/core-api/librs.rst
create mode 100644 Documentation/driver-api/mtdnand.rst
create mode 100644 Documentation/sh/index.rst
--
2.9.3
^ permalink raw reply [flat|nested] 10+ messages in thread
* [PATCH 1/5] docs-rst: convert librs book to ReST
2017-05-13 11:10 [PATCH 0/5] Convert more books to ReST Mauro Carvalho Chehab
@ 2017-05-13 11:10 ` Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 2/5] docs-rst: convert mtdnand " Mauro Carvalho Chehab
` (4 subsequent siblings)
5 siblings, 0 replies; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-13 11:10 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jani Nikula, Greg Kroah-Hartman, Markus Heiser,
Takashi Iwai, Herton R. Krzesinski, Silvio Fricke,
Sebastian Andrzej Siewior, sayli karnik
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DocBook/Makefile | 2 +-
Documentation/DocBook/librs.tmpl | 289 ---------------------------------------
Documentation/core-api/index.rst | 1 +
Documentation/core-api/librs.rst | 212 ++++++++++++++++++++++++++++
4 files changed, 214 insertions(+), 290 deletions(-)
delete mode 100644 Documentation/DocBook/librs.tmpl
create mode 100644 Documentation/core-api/librs.rst
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index baedb14f3b40..0a82f6253682 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -8,7 +8,7 @@
DOCBOOKS := \
lsm.xml \
- mtdnand.xml librs.xml \
+ mtdnand.xml \
sh.xml
ifeq ($(DOCBOOKS),)
diff --git a/Documentation/DocBook/librs.tmpl b/Documentation/DocBook/librs.tmpl
deleted file mode 100644
index 94f21361e0ed..000000000000
--- a/Documentation/DocBook/librs.tmpl
+++ /dev/null
@@ -1,289 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="Reed-Solomon-Library-Guide">
- <bookinfo>
- <title>Reed-Solomon Library Programming Interface</title>
-
- <authorgroup>
- <author>
- <firstname>Thomas</firstname>
- <surname>Gleixner</surname>
- <affiliation>
- <address>
- <email>tglx@linutronix.de</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2004</year>
- <holder>Thomas Gleixner</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- The generic Reed-Solomon Library provides encoding, decoding
- and error correction functions.
- </para>
- <para>
- Reed-Solomon codes are used in communication and storage
- applications to ensure data integrity.
- </para>
- <para>
- This documentation is provided for developers who want to utilize
- the functions provided by the library.
- </para>
- </chapter>
-
- <chapter id="bugs">
- <title>Known Bugs And Assumptions</title>
- <para>
- None.
- </para>
- </chapter>
-
- <chapter id="usage">
- <title>Usage</title>
- <para>
- This chapter provides examples of how to use the library.
- </para>
- <sect1>
- <title>Initializing</title>
- <para>
- The init function init_rs returns a pointer to an
- rs decoder structure, which holds the necessary
- information for encoding, decoding and error correction
- with the given polynomial. It either uses an existing
- matching decoder or creates a new one. On creation all
- the lookup tables for fast en/decoding are created.
- The function may take a while, so make sure not to
- call it in critical code paths.
- </para>
- <programlisting>
-/* the Reed Solomon control structure */
-static struct rs_control *rs_decoder;
-
-/* Symbolsize is 10 (bits)
- * Primitive polynomial is x^10+x^3+1
- * first consecutive root is 0
- * primitive element to generate roots = 1
- * generator polynomial degree (number of roots) = 6
- */
-rs_decoder = init_rs (10, 0x409, 0, 1, 6);
- </programlisting>
- </sect1>
- <sect1>
- <title>Encoding</title>
- <para>
- The encoder calculates the Reed-Solomon code over
- the given data length and stores the result in
- the parity buffer. Note that the parity buffer must
- be initialized before calling the encoder.
- </para>
- <para>
- The expanded data can be inverted on the fly by
- providing a non-zero inversion mask. The expanded data is
- XOR'ed with the mask. This is used e.g. for FLASH
- ECC, where the all 0xFF is inverted to an all 0x00.
- The Reed-Solomon code for all 0x00 is all 0x00. The
- code is inverted before storing to FLASH so it is 0xFF
- too. This prevents that reading from an erased FLASH
- results in ECC errors.
- </para>
- <para>
- The databytes are expanded to the given symbol size
- on the fly. There is no support for encoding continuous
- bitstreams with a symbol size != 8 at the moment. If
- it is necessary it should be not a big deal to implement
- such functionality.
- </para>
- <programlisting>
-/* Parity buffer. Size = number of roots */
-uint16_t par[6];
-/* Initialize the parity buffer */
-memset(par, 0, sizeof(par));
-/* Encode 512 byte in data8. Store parity in buffer par */
-encode_rs8 (rs_decoder, data8, 512, par, 0);
- </programlisting>
- </sect1>
- <sect1>
- <title>Decoding</title>
- <para>
- The decoder calculates the syndrome over
- the given data length and the received parity symbols
- and corrects errors in the data.
- </para>
- <para>
- If a syndrome is available from a hardware decoder
- then the syndrome calculation is skipped.
- </para>
- <para>
- The correction of the data buffer can be suppressed
- by providing a correction pattern buffer and an error
- location buffer to the decoder. The decoder stores the
- calculated error location and the correction bitmask
- in the given buffers. This is useful for hardware
- decoders which use a weird bit ordering scheme.
- </para>
- <para>
- The databytes are expanded to the given symbol size
- on the fly. There is no support for decoding continuous
- bitstreams with a symbolsize != 8 at the moment. If
- it is necessary it should be not a big deal to implement
- such functionality.
- </para>
-
- <sect2>
- <title>
- Decoding with syndrome calculation, direct data correction
- </title>
- <programlisting>
-/* Parity buffer. Size = number of roots */
-uint16_t par[6];
-uint8_t data[512];
-int numerr;
-/* Receive data */
-.....
-/* Receive parity */
-.....
-/* Decode 512 byte in data8.*/
-numerr = decode_rs8 (rs_decoder, data8, par, 512, NULL, 0, NULL, 0, NULL);
- </programlisting>
- </sect2>
-
- <sect2>
- <title>
- Decoding with syndrome given by hardware decoder, direct data correction
- </title>
- <programlisting>
-/* Parity buffer. Size = number of roots */
-uint16_t par[6], syn[6];
-uint8_t data[512];
-int numerr;
-/* Receive data */
-.....
-/* Receive parity */
-.....
-/* Get syndrome from hardware decoder */
-.....
-/* Decode 512 byte in data8.*/
-numerr = decode_rs8 (rs_decoder, data8, par, 512, syn, 0, NULL, 0, NULL);
- </programlisting>
- </sect2>
-
- <sect2>
- <title>
- Decoding with syndrome given by hardware decoder, no direct data correction.
- </title>
- <para>
- Note: It's not necessary to give data and received parity to the decoder.
- </para>
- <programlisting>
-/* Parity buffer. Size = number of roots */
-uint16_t par[6], syn[6], corr[8];
-uint8_t data[512];
-int numerr, errpos[8];
-/* Receive data */
-.....
-/* Receive parity */
-.....
-/* Get syndrome from hardware decoder */
-.....
-/* Decode 512 byte in data8.*/
-numerr = decode_rs8 (rs_decoder, NULL, NULL, 512, syn, 0, errpos, 0, corr);
-for (i = 0; i < numerr; i++) {
- do_error_correction_in_your_buffer(errpos[i], corr[i]);
-}
- </programlisting>
- </sect2>
- </sect1>
- <sect1>
- <title>Cleanup</title>
- <para>
- The function free_rs frees the allocated resources,
- if the caller is the last user of the decoder.
- </para>
- <programlisting>
-/* Release resources */
-free_rs(rs_decoder);
- </programlisting>
- </sect1>
-
- </chapter>
-
- <chapter id="structs">
- <title>Structures</title>
- <para>
- This chapter contains the autogenerated documentation of the structures which are
- used in the Reed-Solomon Library and are relevant for a developer.
- </para>
-!Iinclude/linux/rslib.h
- </chapter>
-
- <chapter id="pubfunctions">
- <title>Public Functions Provided</title>
- <para>
- This chapter contains the autogenerated documentation of the Reed-Solomon functions
- which are exported.
- </para>
-!Elib/reed_solomon/reed_solomon.c
- </chapter>
-
- <chapter id="credits">
- <title>Credits</title>
- <para>
- The library code for encoding and decoding was written by Phil Karn.
- </para>
- <programlisting>
- Copyright 2002, Phil Karn, KA9Q
- May be used under the terms of the GNU General Public License (GPL)
- </programlisting>
- <para>
- The wrapper functions and interfaces are written by Thomas Gleixner.
- </para>
- <para>
- Many users have provided bugfixes, improvements and helping hands for testing.
- Thanks a lot.
- </para>
- <para>
- The following people have contributed to this document:
- </para>
- <para>
- Thomas Gleixner<email>tglx@linutronix.de</email>
- </para>
- </chapter>
-</book>
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 62abd36bfffb..0606be3a3111 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -19,6 +19,7 @@ Core utilities
workqueue
genericirq
flexible-arrays
+ librs
Interfaces for kernel debugging
===============================
diff --git a/Documentation/core-api/librs.rst b/Documentation/core-api/librs.rst
new file mode 100644
index 000000000000..6010f5bc5bf9
--- /dev/null
+++ b/Documentation/core-api/librs.rst
@@ -0,0 +1,212 @@
+==========================================
+Reed-Solomon Library Programming Interface
+==========================================
+
+:Author: Thomas Gleixner
+
+Introduction
+============
+
+The generic Reed-Solomon Library provides encoding, decoding and error
+correction functions.
+
+Reed-Solomon codes are used in communication and storage applications to
+ensure data integrity.
+
+This documentation is provided for developers who want to utilize the
+functions provided by the library.
+
+Known Bugs And Assumptions
+==========================
+
+None.
+
+Usage
+=====
+
+This chapter provides examples of how to use the library.
+
+Initializing
+------------
+
+The init function init_rs returns a pointer to an rs decoder structure,
+which holds the necessary information for encoding, decoding and error
+correction with the given polynomial. It either uses an existing
+matching decoder or creates a new one. On creation all the lookup tables
+for fast en/decoding are created. The function may take a while, so make
+sure not to call it in critical code paths.
+
+::
+
+ /* the Reed Solomon control structure */
+ static struct rs_control *rs_decoder;
+
+ /* Symbolsize is 10 (bits)
+ * Primitive polynomial is x^10+x^3+1
+ * first consecutive root is 0
+ * primitive element to generate roots = 1
+ * generator polynomial degree (number of roots) = 6
+ */
+ rs_decoder = init_rs (10, 0x409, 0, 1, 6);
+
+
+Encoding
+--------
+
+The encoder calculates the Reed-Solomon code over the given data length
+and stores the result in the parity buffer. Note that the parity buffer
+must be initialized before calling the encoder.
+
+The expanded data can be inverted on the fly by providing a non-zero
+inversion mask. The expanded data is XOR'ed with the mask. This is used
+e.g. for FLASH ECC, where the all 0xFF is inverted to an all 0x00. The
+Reed-Solomon code for all 0x00 is all 0x00. The code is inverted before
+storing to FLASH so it is 0xFF too. This prevents that reading from an
+erased FLASH results in ECC errors.
+
+The databytes are expanded to the given symbol size on the fly. There is
+no support for encoding continuous bitstreams with a symbol size != 8 at
+the moment. If it is necessary it should be not a big deal to implement
+such functionality.
+
+::
+
+ /* Parity buffer. Size = number of roots */
+ uint16_t par[6];
+ /* Initialize the parity buffer */
+ memset(par, 0, sizeof(par));
+ /* Encode 512 byte in data8. Store parity in buffer par */
+ encode_rs8 (rs_decoder, data8, 512, par, 0);
+
+
+Decoding
+--------
+
+The decoder calculates the syndrome over the given data length and the
+received parity symbols and corrects errors in the data.
+
+If a syndrome is available from a hardware decoder then the syndrome
+calculation is skipped.
+
+The correction of the data buffer can be suppressed by providing a
+correction pattern buffer and an error location buffer to the decoder.
+The decoder stores the calculated error location and the correction
+bitmask in the given buffers. This is useful for hardware decoders which
+use a weird bit ordering scheme.
+
+The databytes are expanded to the given symbol size on the fly. There is
+no support for decoding continuous bitstreams with a symbolsize != 8 at
+the moment. If it is necessary it should be not a big deal to implement
+such functionality.
+
+Decoding with syndrome calculation, direct data correction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ /* Parity buffer. Size = number of roots */
+ uint16_t par[6];
+ uint8_t data[512];
+ int numerr;
+ /* Receive data */
+ .....
+ /* Receive parity */
+ .....
+ /* Decode 512 byte in data8.*/
+ numerr = decode_rs8 (rs_decoder, data8, par, 512, NULL, 0, NULL, 0, NULL);
+
+
+Decoding with syndrome given by hardware decoder, direct data correction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ /* Parity buffer. Size = number of roots */
+ uint16_t par[6], syn[6];
+ uint8_t data[512];
+ int numerr;
+ /* Receive data */
+ .....
+ /* Receive parity */
+ .....
+ /* Get syndrome from hardware decoder */
+ .....
+ /* Decode 512 byte in data8.*/
+ numerr = decode_rs8 (rs_decoder, data8, par, 512, syn, 0, NULL, 0, NULL);
+
+
+Decoding with syndrome given by hardware decoder, no direct data correction.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Note: It's not necessary to give data and received parity to the
+decoder.
+
+::
+
+ /* Parity buffer. Size = number of roots */
+ uint16_t par[6], syn[6], corr[8];
+ uint8_t data[512];
+ int numerr, errpos[8];
+ /* Receive data */
+ .....
+ /* Receive parity */
+ .....
+ /* Get syndrome from hardware decoder */
+ .....
+ /* Decode 512 byte in data8.*/
+ numerr = decode_rs8 (rs_decoder, NULL, NULL, 512, syn, 0, errpos, 0, corr);
+ for (i = 0; i < numerr; i++) {
+ do_error_correction_in_your_buffer(errpos[i], corr[i]);
+ }
+
+
+Cleanup
+-------
+
+The function free_rs frees the allocated resources, if the caller is
+the last user of the decoder.
+
+::
+
+ /* Release resources */
+ free_rs(rs_decoder);
+
+
+Structures
+==========
+
+This chapter contains the autogenerated documentation of the structures
+which are used in the Reed-Solomon Library and are relevant for a
+developer.
+
+.. kernel-doc:: include/linux/rslib.h
+ :internal:
+
+Public Functions Provided
+=========================
+
+This chapter contains the autogenerated documentation of the
+Reed-Solomon functions which are exported.
+
+.. kernel-doc:: lib/reed_solomon/reed_solomon.c
+ :export:
+
+Credits
+=======
+
+The library code for encoding and decoding was written by Phil Karn.
+
+::
+
+ Copyright 2002, Phil Karn, KA9Q
+ May be used under the terms of the GNU General Public License (GPL)
+
+
+The wrapper functions and interfaces are written by Thomas Gleixner.
+
+Many users have provided bugfixes, improvements and helping hands for
+testing. Thanks a lot.
+
+The following people have contributed to this document:
+
+Thomas Gleixner\ tglx@linutronix.de
--
2.9.3
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [PATCH 2/5] docs-rst: convert mtdnand book to ReST
2017-05-13 11:10 [PATCH 0/5] Convert more books to ReST Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 1/5] docs-rst: convert librs book " Mauro Carvalho Chehab
@ 2017-05-13 11:10 ` Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 3/5] mtdnand.rst: Fix some typos and group the "::" with previous line Mauro Carvalho Chehab
` (3 subsequent siblings)
5 siblings, 0 replies; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-13 11:10 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jani Nikula, Takashi Iwai, Greg Kroah-Hartman,
Markus Heiser, Herton R. Krzesinski
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
The tables were manually adjusted to fit into 80 columns.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DocBook/Makefile | 1 -
Documentation/DocBook/mtdnand.tmpl | 1291 ----------------------------------
Documentation/driver-api/index.rst | 1 +
Documentation/driver-api/mtdnand.rst | 1020 +++++++++++++++++++++++++++
4 files changed, 1021 insertions(+), 1292 deletions(-)
delete mode 100644 Documentation/DocBook/mtdnand.tmpl
create mode 100644 Documentation/driver-api/mtdnand.rst
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 0a82f6253682..226e5e9fc801 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -8,7 +8,6 @@
DOCBOOKS := \
lsm.xml \
- mtdnand.xml \
sh.xml
ifeq ($(DOCBOOKS),)
diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl
deleted file mode 100644
index b442921bca54..000000000000
--- a/Documentation/DocBook/mtdnand.tmpl
+++ /dev/null
@@ -1,1291 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="MTD-NAND-Guide">
- <bookinfo>
- <title>MTD NAND Driver Programming Interface</title>
-
- <authorgroup>
- <author>
- <firstname>Thomas</firstname>
- <surname>Gleixner</surname>
- <affiliation>
- <address>
- <email>tglx@linutronix.de</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2004</year>
- <holder>Thomas Gleixner</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- The generic NAND driver supports almost all NAND and AG-AND based
- chips and connects them to the Memory Technology Devices (MTD)
- subsystem of the Linux Kernel.
- </para>
- <para>
- This documentation is provided for developers who want to implement
- board drivers or filesystem drivers suitable for NAND devices.
- </para>
- </chapter>
-
- <chapter id="bugs">
- <title>Known Bugs And Assumptions</title>
- <para>
- None.
- </para>
- </chapter>
-
- <chapter id="dochints">
- <title>Documentation hints</title>
- <para>
- The function and structure docs are autogenerated. Each function and
- struct member has a short description which is marked with an [XXX] identifier.
- The following chapters explain the meaning of those identifiers.
- </para>
- <sect1 id="Function_identifiers_XXX">
- <title>Function identifiers [XXX]</title>
- <para>
- The functions are marked with [XXX] identifiers in the short
- comment. The identifiers explain the usage and scope of the
- functions. Following identifiers are used:
- </para>
- <itemizedlist>
- <listitem><para>
- [MTD Interface]</para><para>
- These functions provide the interface to the MTD kernel API.
- They are not replaceable and provide functionality
- which is complete hardware independent.
- </para></listitem>
- <listitem><para>
- [NAND Interface]</para><para>
- These functions are exported and provide the interface to the NAND kernel API.
- </para></listitem>
- <listitem><para>
- [GENERIC]</para><para>
- Generic functions are not replaceable and provide functionality
- which is complete hardware independent.
- </para></listitem>
- <listitem><para>
- [DEFAULT]</para><para>
- Default functions provide hardware related functionality which is suitable
- for most of the implementations. These functions can be replaced by the
- board driver if necessary. Those functions are called via pointers in the
- NAND chip description structure. The board driver can set the functions which
- should be replaced by board dependent functions before calling nand_scan().
- If the function pointer is NULL on entry to nand_scan() then the pointer
- is set to the default function which is suitable for the detected chip type.
- </para></listitem>
- </itemizedlist>
- </sect1>
- <sect1 id="Struct_member_identifiers_XXX">
- <title>Struct member identifiers [XXX]</title>
- <para>
- The struct members are marked with [XXX] identifiers in the
- comment. The identifiers explain the usage and scope of the
- members. Following identifiers are used:
- </para>
- <itemizedlist>
- <listitem><para>
- [INTERN]</para><para>
- These members are for NAND driver internal use only and must not be
- modified. Most of these values are calculated from the chip geometry
- information which is evaluated during nand_scan().
- </para></listitem>
- <listitem><para>
- [REPLACEABLE]</para><para>
- Replaceable members hold hardware related functions which can be
- provided by the board driver. The board driver can set the functions which
- should be replaced by board dependent functions before calling nand_scan().
- If the function pointer is NULL on entry to nand_scan() then the pointer
- is set to the default function which is suitable for the detected chip type.
- </para></listitem>
- <listitem><para>
- [BOARDSPECIFIC]</para><para>
- Board specific members hold hardware related information which must
- be provided by the board driver. The board driver must set the function
- pointers and datafields before calling nand_scan().
- </para></listitem>
- <listitem><para>
- [OPTIONAL]</para><para>
- Optional members can hold information relevant for the board driver. The
- generic NAND driver code does not use this information.
- </para></listitem>
- </itemizedlist>
- </sect1>
- </chapter>
-
- <chapter id="basicboarddriver">
- <title>Basic board driver</title>
- <para>
- For most boards it will be sufficient to provide just the
- basic functions and fill out some really board dependent
- members in the nand chip description structure.
- </para>
- <sect1 id="Basic_defines">
- <title>Basic defines</title>
- <para>
- At least you have to provide a nand_chip structure
- and a storage for the ioremap'ed chip address.
- You can allocate the nand_chip structure using
- kmalloc or you can allocate it statically.
- The NAND chip structure embeds an mtd structure
- which will be registered to the MTD subsystem.
- You can extract a pointer to the mtd structure
- from a nand_chip pointer using the nand_to_mtd()
- helper.
- </para>
- <para>
- Kmalloc based example
- </para>
- <programlisting>
-static struct mtd_info *board_mtd;
-static void __iomem *baseaddr;
- </programlisting>
- <para>
- Static example
- </para>
- <programlisting>
-static struct nand_chip board_chip;
-static void __iomem *baseaddr;
- </programlisting>
- </sect1>
- <sect1 id="Partition_defines">
- <title>Partition defines</title>
- <para>
- If you want to divide your device into partitions, then
- define a partitioning scheme suitable to your board.
- </para>
- <programlisting>
-#define NUM_PARTITIONS 2
-static struct mtd_partition partition_info[] = {
- { .name = "Flash partition 1",
- .offset = 0,
- .size = 8 * 1024 * 1024 },
- { .name = "Flash partition 2",
- .offset = MTDPART_OFS_NEXT,
- .size = MTDPART_SIZ_FULL },
-};
- </programlisting>
- </sect1>
- <sect1 id="Hardware_control_functions">
- <title>Hardware control function</title>
- <para>
- The hardware control function provides access to the
- control pins of the NAND chip(s).
- The access can be done by GPIO pins or by address lines.
- If you use address lines, make sure that the timing
- requirements are met.
- </para>
- <para>
- <emphasis>GPIO based example</emphasis>
- </para>
- <programlisting>
-static void board_hwcontrol(struct mtd_info *mtd, int cmd)
-{
- switch(cmd){
- case NAND_CTL_SETCLE: /* Set CLE pin high */ break;
- case NAND_CTL_CLRCLE: /* Set CLE pin low */ break;
- case NAND_CTL_SETALE: /* Set ALE pin high */ break;
- case NAND_CTL_CLRALE: /* Set ALE pin low */ break;
- case NAND_CTL_SETNCE: /* Set nCE pin low */ break;
- case NAND_CTL_CLRNCE: /* Set nCE pin high */ break;
- }
-}
- </programlisting>
- <para>
- <emphasis>Address lines based example.</emphasis> It's assumed that the
- nCE pin is driven by a chip select decoder.
- </para>
- <programlisting>
-static void board_hwcontrol(struct mtd_info *mtd, int cmd)
-{
- struct nand_chip *this = mtd_to_nand(mtd);
- switch(cmd){
- case NAND_CTL_SETCLE: this->IO_ADDR_W |= CLE_ADRR_BIT; break;
- case NAND_CTL_CLRCLE: this->IO_ADDR_W &= ~CLE_ADRR_BIT; break;
- case NAND_CTL_SETALE: this->IO_ADDR_W |= ALE_ADRR_BIT; break;
- case NAND_CTL_CLRALE: this->IO_ADDR_W &= ~ALE_ADRR_BIT; break;
- }
-}
- </programlisting>
- </sect1>
- <sect1 id="Device_ready_function">
- <title>Device ready function</title>
- <para>
- If the hardware interface has the ready busy pin of the NAND chip connected to a
- GPIO or other accessible I/O pin, this function is used to read back the state of the
- pin. The function has no arguments and should return 0, if the device is busy (R/B pin
- is low) and 1, if the device is ready (R/B pin is high).
- If the hardware interface does not give access to the ready busy pin, then
- the function must not be defined and the function pointer this->dev_ready is set to NULL.
- </para>
- </sect1>
- <sect1 id="Init_function">
- <title>Init function</title>
- <para>
- The init function allocates memory and sets up all the board
- specific parameters and function pointers. When everything
- is set up nand_scan() is called. This function tries to
- detect and identify then chip. If a chip is found all the
- internal data fields are initialized accordingly.
- The structure(s) have to be zeroed out first and then filled with the necessary
- information about the device.
- </para>
- <programlisting>
-static int __init board_init (void)
-{
- struct nand_chip *this;
- int err = 0;
-
- /* Allocate memory for MTD device structure and private data */
- this = kzalloc(sizeof(struct nand_chip), GFP_KERNEL);
- if (!this) {
- printk ("Unable to allocate NAND MTD device structure.\n");
- err = -ENOMEM;
- goto out;
- }
-
- board_mtd = nand_to_mtd(this);
-
- /* map physical address */
- baseaddr = ioremap(CHIP_PHYSICAL_ADDRESS, 1024);
- if (!baseaddr) {
- printk("Ioremap to access NAND chip failed\n");
- err = -EIO;
- goto out_mtd;
- }
-
- /* Set address of NAND IO lines */
- this->IO_ADDR_R = baseaddr;
- this->IO_ADDR_W = baseaddr;
- /* Reference hardware control function */
- this->hwcontrol = board_hwcontrol;
- /* Set command delay time, see datasheet for correct value */
- this->chip_delay = CHIP_DEPENDEND_COMMAND_DELAY;
- /* Assign the device ready function, if available */
- this->dev_ready = board_dev_ready;
- this->eccmode = NAND_ECC_SOFT;
-
- /* Scan to find existence of the device */
- if (nand_scan (board_mtd, 1)) {
- err = -ENXIO;
- goto out_ior;
- }
-
- add_mtd_partitions(board_mtd, partition_info, NUM_PARTITIONS);
- goto out;
-
-out_ior:
- iounmap(baseaddr);
-out_mtd:
- kfree (this);
-out:
- return err;
-}
-module_init(board_init);
- </programlisting>
- </sect1>
- <sect1 id="Exit_function">
- <title>Exit function</title>
- <para>
- The exit function is only necessary if the driver is
- compiled as a module. It releases all resources which
- are held by the chip driver and unregisters the partitions
- in the MTD layer.
- </para>
- <programlisting>
-#ifdef MODULE
-static void __exit board_cleanup (void)
-{
- /* Release resources, unregister device */
- nand_release (board_mtd);
-
- /* unmap physical address */
- iounmap(baseaddr);
-
- /* Free the MTD device structure */
- kfree (mtd_to_nand(board_mtd));
-}
-module_exit(board_cleanup);
-#endif
- </programlisting>
- </sect1>
- </chapter>
-
- <chapter id="boarddriversadvanced">
- <title>Advanced board driver functions</title>
- <para>
- This chapter describes the advanced functionality of the NAND
- driver. For a list of functions which can be overridden by the board
- driver see the documentation of the nand_chip structure.
- </para>
- <sect1 id="Multiple_chip_control">
- <title>Multiple chip control</title>
- <para>
- The nand driver can control chip arrays. Therefore the
- board driver must provide an own select_chip function. This
- function must (de)select the requested chip.
- The function pointer in the nand_chip structure must
- be set before calling nand_scan(). The maxchip parameter
- of nand_scan() defines the maximum number of chips to
- scan for. Make sure that the select_chip function can
- handle the requested number of chips.
- </para>
- <para>
- The nand driver concatenates the chips to one virtual
- chip and provides this virtual chip to the MTD layer.
- </para>
- <para>
- <emphasis>Note: The driver can only handle linear chip arrays
- of equally sized chips. There is no support for
- parallel arrays which extend the buswidth.</emphasis>
- </para>
- <para>
- <emphasis>GPIO based example</emphasis>
- </para>
- <programlisting>
-static void board_select_chip (struct mtd_info *mtd, int chip)
-{
- /* Deselect all chips, set all nCE pins high */
- GPIO(BOARD_NAND_NCE) |= 0xff;
- if (chip >= 0)
- GPIO(BOARD_NAND_NCE) &= ~ (1 << chip);
-}
- </programlisting>
- <para>
- <emphasis>Address lines based example.</emphasis>
- Its assumed that the nCE pins are connected to an
- address decoder.
- </para>
- <programlisting>
-static void board_select_chip (struct mtd_info *mtd, int chip)
-{
- struct nand_chip *this = mtd_to_nand(mtd);
-
- /* Deselect all chips */
- this->IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK;
- this->IO_ADDR_W &= ~BOARD_NAND_ADDR_MASK;
- switch (chip) {
- case 0:
- this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0;
- this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0;
- break;
- ....
- case n:
- this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn;
- this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn;
- break;
- }
-}
- </programlisting>
- </sect1>
- <sect1 id="Hardware_ECC_support">
- <title>Hardware ECC support</title>
- <sect2 id="Functions_and_constants">
- <title>Functions and constants</title>
- <para>
- The nand driver supports three different types of
- hardware ECC.
- <itemizedlist>
- <listitem><para>NAND_ECC_HW3_256</para><para>
- Hardware ECC generator providing 3 bytes ECC per
- 256 byte.
- </para> </listitem>
- <listitem><para>NAND_ECC_HW3_512</para><para>
- Hardware ECC generator providing 3 bytes ECC per
- 512 byte.
- </para> </listitem>
- <listitem><para>NAND_ECC_HW6_512</para><para>
- Hardware ECC generator providing 6 bytes ECC per
- 512 byte.
- </para> </listitem>
- <listitem><para>NAND_ECC_HW8_512</para><para>
- Hardware ECC generator providing 6 bytes ECC per
- 512 byte.
- </para> </listitem>
- </itemizedlist>
- If your hardware generator has a different functionality
- add it at the appropriate place in nand_base.c
- </para>
- <para>
- The board driver must provide following functions:
- <itemizedlist>
- <listitem><para>enable_hwecc</para><para>
- This function is called before reading / writing to
- the chip. Reset or initialize the hardware generator
- in this function. The function is called with an
- argument which let you distinguish between read
- and write operations.
- </para> </listitem>
- <listitem><para>calculate_ecc</para><para>
- This function is called after read / write from / to
- the chip. Transfer the ECC from the hardware to
- the buffer. If the option NAND_HWECC_SYNDROME is set
- then the function is only called on write. See below.
- </para> </listitem>
- <listitem><para>correct_data</para><para>
- In case of an ECC error this function is called for
- error detection and correction. Return 1 respectively 2
- in case the error can be corrected. If the error is
- not correctable return -1. If your hardware generator
- matches the default algorithm of the nand_ecc software
- generator then use the correction function provided
- by nand_ecc instead of implementing duplicated code.
- </para> </listitem>
- </itemizedlist>
- </para>
- </sect2>
- <sect2 id="Hardware_ECC_with_syndrome_calculation">
- <title>Hardware ECC with syndrome calculation</title>
- <para>
- Many hardware ECC implementations provide Reed-Solomon
- codes and calculate an error syndrome on read. The syndrome
- must be converted to a standard Reed-Solomon syndrome
- before calling the error correction code in the generic
- Reed-Solomon library.
- </para>
- <para>
- The ECC bytes must be placed immediately after the data
- bytes in order to make the syndrome generator work. This
- is contrary to the usual layout used by software ECC. The
- separation of data and out of band area is not longer
- possible. The nand driver code handles this layout and
- the remaining free bytes in the oob area are managed by
- the autoplacement code. Provide a matching oob-layout
- in this case. See rts_from4.c and diskonchip.c for
- implementation reference. In those cases we must also
- use bad block tables on FLASH, because the ECC layout is
- interfering with the bad block marker positions.
- See bad block table support for details.
- </para>
- </sect2>
- </sect1>
- <sect1 id="Bad_Block_table_support">
- <title>Bad block table support</title>
- <para>
- Most NAND chips mark the bad blocks at a defined
- position in the spare area. Those blocks must
- not be erased under any circumstances as the bad
- block information would be lost.
- It is possible to check the bad block mark each
- time when the blocks are accessed by reading the
- spare area of the first page in the block. This
- is time consuming so a bad block table is used.
- </para>
- <para>
- The nand driver supports various types of bad block
- tables.
- <itemizedlist>
- <listitem><para>Per device</para><para>
- The bad block table contains all bad block information
- of the device which can consist of multiple chips.
- </para> </listitem>
- <listitem><para>Per chip</para><para>
- A bad block table is used per chip and contains the
- bad block information for this particular chip.
- </para> </listitem>
- <listitem><para>Fixed offset</para><para>
- The bad block table is located at a fixed offset
- in the chip (device). This applies to various
- DiskOnChip devices.
- </para> </listitem>
- <listitem><para>Automatic placed</para><para>
- The bad block table is automatically placed and
- detected either at the end or at the beginning
- of a chip (device)
- </para> </listitem>
- <listitem><para>Mirrored tables</para><para>
- The bad block table is mirrored on the chip (device) to
- allow updates of the bad block table without data loss.
- </para> </listitem>
- </itemizedlist>
- </para>
- <para>
- nand_scan() calls the function nand_default_bbt().
- nand_default_bbt() selects appropriate default
- bad block table descriptors depending on the chip information
- which was retrieved by nand_scan().
- </para>
- <para>
- The standard policy is scanning the device for bad
- blocks and build a ram based bad block table which
- allows faster access than always checking the
- bad block information on the flash chip itself.
- </para>
- <sect2 id="Flash_based_tables">
- <title>Flash based tables</title>
- <para>
- It may be desired or necessary to keep a bad block table in FLASH.
- For AG-AND chips this is mandatory, as they have no factory marked
- bad blocks. They have factory marked good blocks. The marker pattern
- is erased when the block is erased to be reused. So in case of
- powerloss before writing the pattern back to the chip this block
- would be lost and added to the bad blocks. Therefore we scan the
- chip(s) when we detect them the first time for good blocks and
- store this information in a bad block table before erasing any
- of the blocks.
- </para>
- <para>
- The blocks in which the tables are stored are protected against
- accidental access by marking them bad in the memory bad block
- table. The bad block table management functions are allowed
- to circumvent this protection.
- </para>
- <para>
- The simplest way to activate the FLASH based bad block table support
- is to set the option NAND_BBT_USE_FLASH in the bbt_option field of
- the nand chip structure before calling nand_scan(). For AG-AND
- chips is this done by default.
- This activates the default FLASH based bad block table functionality
- of the NAND driver. The default bad block table options are
- <itemizedlist>
- <listitem><para>Store bad block table per chip</para></listitem>
- <listitem><para>Use 2 bits per block</para></listitem>
- <listitem><para>Automatic placement at the end of the chip</para></listitem>
- <listitem><para>Use mirrored tables with version numbers</para></listitem>
- <listitem><para>Reserve 4 blocks at the end of the chip</para></listitem>
- </itemizedlist>
- </para>
- </sect2>
- <sect2 id="User_defined_tables">
- <title>User defined tables</title>
- <para>
- User defined tables are created by filling out a
- nand_bbt_descr structure and storing the pointer in the
- nand_chip structure member bbt_td before calling nand_scan().
- If a mirror table is necessary a second structure must be
- created and a pointer to this structure must be stored
- in bbt_md inside the nand_chip structure. If the bbt_md
- member is set to NULL then only the main table is used
- and no scan for the mirrored table is performed.
- </para>
- <para>
- The most important field in the nand_bbt_descr structure
- is the options field. The options define most of the
- table properties. Use the predefined constants from
- nand.h to define the options.
- <itemizedlist>
- <listitem><para>Number of bits per block</para>
- <para>The supported number of bits is 1, 2, 4, 8.</para></listitem>
- <listitem><para>Table per chip</para>
- <para>Setting the constant NAND_BBT_PERCHIP selects that
- a bad block table is managed for each chip in a chip array.
- If this option is not set then a per device bad block table
- is used.</para></listitem>
- <listitem><para>Table location is absolute</para>
- <para>Use the option constant NAND_BBT_ABSPAGE and
- define the absolute page number where the bad block
- table starts in the field pages. If you have selected bad block
- tables per chip and you have a multi chip array then the start page
- must be given for each chip in the chip array. Note: there is no scan
- for a table ident pattern performed, so the fields
- pattern, veroffs, offs, len can be left uninitialized</para></listitem>
- <listitem><para>Table location is automatically detected</para>
- <para>The table can either be located in the first or the last good
- blocks of the chip (device). Set NAND_BBT_LASTBLOCK to place
- the bad block table at the end of the chip (device). The
- bad block tables are marked and identified by a pattern which
- is stored in the spare area of the first page in the block which
- holds the bad block table. Store a pointer to the pattern
- in the pattern field. Further the length of the pattern has to be
- stored in len and the offset in the spare area must be given
- in the offs member of the nand_bbt_descr structure. For mirrored
- bad block tables different patterns are mandatory.</para></listitem>
- <listitem><para>Table creation</para>
- <para>Set the option NAND_BBT_CREATE to enable the table creation
- if no table can be found during the scan. Usually this is done only
- once if a new chip is found. </para></listitem>
- <listitem><para>Table write support</para>
- <para>Set the option NAND_BBT_WRITE to enable the table write support.
- This allows the update of the bad block table(s) in case a block has
- to be marked bad due to wear. The MTD interface function block_markbad
- is calling the update function of the bad block table. If the write
- support is enabled then the table is updated on FLASH.</para>
- <para>
- Note: Write support should only be enabled for mirrored tables with
- version control.
- </para></listitem>
- <listitem><para>Table version control</para>
- <para>Set the option NAND_BBT_VERSION to enable the table version control.
- It's highly recommended to enable this for mirrored tables with write
- support. It makes sure that the risk of losing the bad block
- table information is reduced to the loss of the information about the
- one worn out block which should be marked bad. The version is stored in
- 4 consecutive bytes in the spare area of the device. The position of
- the version number is defined by the member veroffs in the bad block table
- descriptor.</para></listitem>
- <listitem><para>Save block contents on write</para>
- <para>
- In case that the block which holds the bad block table does contain
- other useful information, set the option NAND_BBT_SAVECONTENT. When
- the bad block table is written then the whole block is read the bad
- block table is updated and the block is erased and everything is
- written back. If this option is not set only the bad block table
- is written and everything else in the block is ignored and erased.
- </para></listitem>
- <listitem><para>Number of reserved blocks</para>
- <para>
- For automatic placement some blocks must be reserved for
- bad block table storage. The number of reserved blocks is defined
- in the maxblocks member of the bad block table description structure.
- Reserving 4 blocks for mirrored tables should be a reasonable number.
- This also limits the number of blocks which are scanned for the bad
- block table ident pattern.
- </para></listitem>
- </itemizedlist>
- </para>
- </sect2>
- </sect1>
- <sect1 id="Spare_area_placement">
- <title>Spare area (auto)placement</title>
- <para>
- The nand driver implements different possibilities for
- placement of filesystem data in the spare area,
- <itemizedlist>
- <listitem><para>Placement defined by fs driver</para></listitem>
- <listitem><para>Automatic placement</para></listitem>
- </itemizedlist>
- The default placement function is automatic placement. The
- nand driver has built in default placement schemes for the
- various chiptypes. If due to hardware ECC functionality the
- default placement does not fit then the board driver can
- provide a own placement scheme.
- </para>
- <para>
- File system drivers can provide a own placement scheme which
- is used instead of the default placement scheme.
- </para>
- <para>
- Placement schemes are defined by a nand_oobinfo structure
- <programlisting>
-struct nand_oobinfo {
- int useecc;
- int eccbytes;
- int eccpos[24];
- int oobfree[8][2];
-};
- </programlisting>
- <itemizedlist>
- <listitem><para>useecc</para><para>
- The useecc member controls the ecc and placement function. The header
- file include/mtd/mtd-abi.h contains constants to select ecc and
- placement. MTD_NANDECC_OFF switches off the ecc complete. This is
- not recommended and available for testing and diagnosis only.
- MTD_NANDECC_PLACE selects caller defined placement, MTD_NANDECC_AUTOPLACE
- selects automatic placement.
- </para></listitem>
- <listitem><para>eccbytes</para><para>
- The eccbytes member defines the number of ecc bytes per page.
- </para></listitem>
- <listitem><para>eccpos</para><para>
- The eccpos array holds the byte offsets in the spare area where
- the ecc codes are placed.
- </para></listitem>
- <listitem><para>oobfree</para><para>
- The oobfree array defines the areas in the spare area which can be
- used for automatic placement. The information is given in the format
- {offset, size}. offset defines the start of the usable area, size the
- length in bytes. More than one area can be defined. The list is terminated
- by an {0, 0} entry.
- </para></listitem>
- </itemizedlist>
- </para>
- <sect2 id="Placement_defined_by_fs_driver">
- <title>Placement defined by fs driver</title>
- <para>
- The calling function provides a pointer to a nand_oobinfo
- structure which defines the ecc placement. For writes the
- caller must provide a spare area buffer along with the
- data buffer. The spare area buffer size is (number of pages) *
- (size of spare area). For reads the buffer size is
- (number of pages) * ((size of spare area) + (number of ecc
- steps per page) * sizeof (int)). The driver stores the
- result of the ecc check for each tuple in the spare buffer.
- The storage sequence is
- </para>
- <para>
- <spare data page 0><ecc result 0>...<ecc result n>
- </para>
- <para>
- ...
- </para>
- <para>
- <spare data page n><ecc result 0>...<ecc result n>
- </para>
- <para>
- This is a legacy mode used by YAFFS1.
- </para>
- <para>
- If the spare area buffer is NULL then only the ECC placement is
- done according to the given scheme in the nand_oobinfo structure.
- </para>
- </sect2>
- <sect2 id="Automatic_placement">
- <title>Automatic placement</title>
- <para>
- Automatic placement uses the built in defaults to place the
- ecc bytes in the spare area. If filesystem data have to be stored /
- read into the spare area then the calling function must provide a
- buffer. The buffer size per page is determined by the oobfree array in
- the nand_oobinfo structure.
- </para>
- <para>
- If the spare area buffer is NULL then only the ECC placement is
- done according to the default builtin scheme.
- </para>
- </sect2>
- </sect1>
- <sect1 id="Spare_area_autoplacement_default">
- <title>Spare area autoplacement default schemes</title>
- <sect2 id="pagesize_256">
- <title>256 byte pagesize</title>
-<informaltable><tgroup cols="3"><tbody>
-<row>
-<entry>Offset</entry>
-<entry>Content</entry>
-<entry>Comment</entry>
-</row>
-<row>
-<entry>0x00</entry>
-<entry>ECC byte 0</entry>
-<entry>Error correction code byte 0</entry>
-</row>
-<row>
-<entry>0x01</entry>
-<entry>ECC byte 1</entry>
-<entry>Error correction code byte 1</entry>
-</row>
-<row>
-<entry>0x02</entry>
-<entry>ECC byte 2</entry>
-<entry>Error correction code byte 2</entry>
-</row>
-<row>
-<entry>0x03</entry>
-<entry>Autoplace 0</entry>
-<entry></entry>
-</row>
-<row>
-<entry>0x04</entry>
-<entry>Autoplace 1</entry>
-<entry></entry>
-</row>
-<row>
-<entry>0x05</entry>
-<entry>Bad block marker</entry>
-<entry>If any bit in this byte is zero, then this block is bad.
-This applies only to the first page in a block. In the remaining
-pages this byte is reserved</entry>
-</row>
-<row>
-<entry>0x06</entry>
-<entry>Autoplace 2</entry>
-<entry></entry>
-</row>
-<row>
-<entry>0x07</entry>
-<entry>Autoplace 3</entry>
-<entry></entry>
-</row>
-</tbody></tgroup></informaltable>
- </sect2>
- <sect2 id="pagesize_512">
- <title>512 byte pagesize</title>
-<informaltable><tgroup cols="3"><tbody>
-<row>
-<entry>Offset</entry>
-<entry>Content</entry>
-<entry>Comment</entry>
-</row>
-<row>
-<entry>0x00</entry>
-<entry>ECC byte 0</entry>
-<entry>Error correction code byte 0 of the lower 256 Byte data in
-this page</entry>
-</row>
-<row>
-<entry>0x01</entry>
-<entry>ECC byte 1</entry>
-<entry>Error correction code byte 1 of the lower 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x02</entry>
-<entry>ECC byte 2</entry>
-<entry>Error correction code byte 2 of the lower 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x03</entry>
-<entry>ECC byte 3</entry>
-<entry>Error correction code byte 0 of the upper 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x04</entry>
-<entry>reserved</entry>
-<entry>reserved</entry>
-</row>
-<row>
-<entry>0x05</entry>
-<entry>Bad block marker</entry>
-<entry>If any bit in this byte is zero, then this block is bad.
-This applies only to the first page in a block. In the remaining
-pages this byte is reserved</entry>
-</row>
-<row>
-<entry>0x06</entry>
-<entry>ECC byte 4</entry>
-<entry>Error correction code byte 1 of the upper 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x07</entry>
-<entry>ECC byte 5</entry>
-<entry>Error correction code byte 2 of the upper 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x08 - 0x0F</entry>
-<entry>Autoplace 0 - 7</entry>
-<entry></entry>
-</row>
-</tbody></tgroup></informaltable>
- </sect2>
- <sect2 id="pagesize_2048">
- <title>2048 byte pagesize</title>
-<informaltable><tgroup cols="3"><tbody>
-<row>
-<entry>Offset</entry>
-<entry>Content</entry>
-<entry>Comment</entry>
-</row>
-<row>
-<entry>0x00</entry>
-<entry>Bad block marker</entry>
-<entry>If any bit in this byte is zero, then this block is bad.
-This applies only to the first page in a block. In the remaining
-pages this byte is reserved</entry>
-</row>
-<row>
-<entry>0x01</entry>
-<entry>Reserved</entry>
-<entry>Reserved</entry>
-</row>
-<row>
-<entry>0x02-0x27</entry>
-<entry>Autoplace 0 - 37</entry>
-<entry></entry>
-</row>
-<row>
-<entry>0x28</entry>
-<entry>ECC byte 0</entry>
-<entry>Error correction code byte 0 of the first 256 Byte data in
-this page</entry>
-</row>
-<row>
-<entry>0x29</entry>
-<entry>ECC byte 1</entry>
-<entry>Error correction code byte 1 of the first 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2A</entry>
-<entry>ECC byte 2</entry>
-<entry>Error correction code byte 2 of the first 256 Bytes data in
-this page</entry>
-</row>
-<row>
-<entry>0x2B</entry>
-<entry>ECC byte 3</entry>
-<entry>Error correction code byte 0 of the second 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2C</entry>
-<entry>ECC byte 4</entry>
-<entry>Error correction code byte 1 of the second 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2D</entry>
-<entry>ECC byte 5</entry>
-<entry>Error correction code byte 2 of the second 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2E</entry>
-<entry>ECC byte 6</entry>
-<entry>Error correction code byte 0 of the third 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2F</entry>
-<entry>ECC byte 7</entry>
-<entry>Error correction code byte 1 of the third 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x30</entry>
-<entry>ECC byte 8</entry>
-<entry>Error correction code byte 2 of the third 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x31</entry>
-<entry>ECC byte 9</entry>
-<entry>Error correction code byte 0 of the fourth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x32</entry>
-<entry>ECC byte 10</entry>
-<entry>Error correction code byte 1 of the fourth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x33</entry>
-<entry>ECC byte 11</entry>
-<entry>Error correction code byte 2 of the fourth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x34</entry>
-<entry>ECC byte 12</entry>
-<entry>Error correction code byte 0 of the fifth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x35</entry>
-<entry>ECC byte 13</entry>
-<entry>Error correction code byte 1 of the fifth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x36</entry>
-<entry>ECC byte 14</entry>
-<entry>Error correction code byte 2 of the fifth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x37</entry>
-<entry>ECC byte 15</entry>
-<entry>Error correction code byte 0 of the sixt 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x38</entry>
-<entry>ECC byte 16</entry>
-<entry>Error correction code byte 1 of the sixt 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x39</entry>
-<entry>ECC byte 17</entry>
-<entry>Error correction code byte 2 of the sixt 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x3A</entry>
-<entry>ECC byte 18</entry>
-<entry>Error correction code byte 0 of the seventh 256 Bytes of
-data in this page</entry>
-</row>
-<row>
-<entry>0x3B</entry>
-<entry>ECC byte 19</entry>
-<entry>Error correction code byte 1 of the seventh 256 Bytes of
-data in this page</entry>
-</row>
-<row>
-<entry>0x3C</entry>
-<entry>ECC byte 20</entry>
-<entry>Error correction code byte 2 of the seventh 256 Bytes of
-data in this page</entry>
-</row>
-<row>
-<entry>0x3D</entry>
-<entry>ECC byte 21</entry>
-<entry>Error correction code byte 0 of the eighth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x3E</entry>
-<entry>ECC byte 22</entry>
-<entry>Error correction code byte 1 of the eighth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x3F</entry>
-<entry>ECC byte 23</entry>
-<entry>Error correction code byte 2 of the eighth 256 Bytes of data
-in this page</entry>
-</row>
-</tbody></tgroup></informaltable>
- </sect2>
- </sect1>
- </chapter>
-
- <chapter id="filesystems">
- <title>Filesystem support</title>
- <para>
- The NAND driver provides all necessary functions for a
- filesystem via the MTD interface.
- </para>
- <para>
- Filesystems must be aware of the NAND peculiarities and
- restrictions. One major restrictions of NAND Flash is, that you cannot
- write as often as you want to a page. The consecutive writes to a page,
- before erasing it again, are restricted to 1-3 writes, depending on the
- manufacturers specifications. This applies similar to the spare area.
- </para>
- <para>
- Therefore NAND aware filesystems must either write in page size chunks
- or hold a writebuffer to collect smaller writes until they sum up to
- pagesize. Available NAND aware filesystems: JFFS2, YAFFS.
- </para>
- <para>
- The spare area usage to store filesystem data is controlled by
- the spare area placement functionality which is described in one
- of the earlier chapters.
- </para>
- </chapter>
- <chapter id="tools">
- <title>Tools</title>
- <para>
- The MTD project provides a couple of helpful tools to handle NAND Flash.
- <itemizedlist>
- <listitem><para>flasherase, flasheraseall: Erase and format FLASH partitions</para></listitem>
- <listitem><para>nandwrite: write filesystem images to NAND FLASH</para></listitem>
- <listitem><para>nanddump: dump the contents of a NAND FLASH partitions</para></listitem>
- </itemizedlist>
- </para>
- <para>
- These tools are aware of the NAND restrictions. Please use those tools
- instead of complaining about errors which are caused by non NAND aware
- access methods.
- </para>
- </chapter>
-
- <chapter id="defines">
- <title>Constants</title>
- <para>
- This chapter describes the constants which might be relevant for a driver developer.
- </para>
- <sect1 id="Chip_option_constants">
- <title>Chip option constants</title>
- <sect2 id="Constants_for_chip_id_table">
- <title>Constants for chip id table</title>
- <para>
- These constants are defined in nand.h. They are ored together to describe
- the chip functionality.
- <programlisting>
-/* Buswitdh is 16 bit */
-#define NAND_BUSWIDTH_16 0x00000002
-/* Device supports partial programming without padding */
-#define NAND_NO_PADDING 0x00000004
-/* Chip has cache program function */
-#define NAND_CACHEPRG 0x00000008
-/* Chip has copy back function */
-#define NAND_COPYBACK 0x00000010
-/* AND Chip which has 4 banks and a confusing page / block
- * assignment. See Renesas datasheet for further information */
-#define NAND_IS_AND 0x00000020
-/* Chip has a array of 4 pages which can be read without
- * additional ready /busy waits */
-#define NAND_4PAGE_ARRAY 0x00000040
- </programlisting>
- </para>
- </sect2>
- <sect2 id="Constants_for_runtime_options">
- <title>Constants for runtime options</title>
- <para>
- These constants are defined in nand.h. They are ored together to describe
- the functionality.
- <programlisting>
-/* The hw ecc generator provides a syndrome instead a ecc value on read
- * This can only work if we have the ecc bytes directly behind the
- * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */
-#define NAND_HWECC_SYNDROME 0x00020000
- </programlisting>
- </para>
- </sect2>
- </sect1>
-
- <sect1 id="EEC_selection_constants">
- <title>ECC selection constants</title>
- <para>
- Use these constants to select the ECC algorithm.
- <programlisting>
-/* No ECC. Usage is not recommended ! */
-#define NAND_ECC_NONE 0
-/* Software ECC 3 byte ECC per 256 Byte data */
-#define NAND_ECC_SOFT 1
-/* Hardware ECC 3 byte ECC per 256 Byte data */
-#define NAND_ECC_HW3_256 2
-/* Hardware ECC 3 byte ECC per 512 Byte data */
-#define NAND_ECC_HW3_512 3
-/* Hardware ECC 6 byte ECC per 512 Byte data */
-#define NAND_ECC_HW6_512 4
-/* Hardware ECC 6 byte ECC per 512 Byte data */
-#define NAND_ECC_HW8_512 6
- </programlisting>
- </para>
- </sect1>
-
- <sect1 id="Hardware_control_related_constants">
- <title>Hardware control related constants</title>
- <para>
- These constants describe the requested hardware access function when
- the boardspecific hardware control function is called
- <programlisting>
-/* Select the chip by setting nCE to low */
-#define NAND_CTL_SETNCE 1
-/* Deselect the chip by setting nCE to high */
-#define NAND_CTL_CLRNCE 2
-/* Select the command latch by setting CLE to high */
-#define NAND_CTL_SETCLE 3
-/* Deselect the command latch by setting CLE to low */
-#define NAND_CTL_CLRCLE 4
-/* Select the address latch by setting ALE to high */
-#define NAND_CTL_SETALE 5
-/* Deselect the address latch by setting ALE to low */
-#define NAND_CTL_CLRALE 6
-/* Set write protection by setting WP to high. Not used! */
-#define NAND_CTL_SETWP 7
-/* Clear write protection by setting WP to low. Not used! */
-#define NAND_CTL_CLRWP 8
- </programlisting>
- </para>
- </sect1>
-
- <sect1 id="Bad_block_table_constants">
- <title>Bad block table related constants</title>
- <para>
- These constants describe the options used for bad block
- table descriptors.
- <programlisting>
-/* Options for the bad block table descriptors */
-
-/* The number of bits used per block in the bbt on the device */
-#define NAND_BBT_NRBITS_MSK 0x0000000F
-#define NAND_BBT_1BIT 0x00000001
-#define NAND_BBT_2BIT 0x00000002
-#define NAND_BBT_4BIT 0x00000004
-#define NAND_BBT_8BIT 0x00000008
-/* The bad block table is in the last good block of the device */
-#define NAND_BBT_LASTBLOCK 0x00000010
-/* The bbt is at the given page, else we must scan for the bbt */
-#define NAND_BBT_ABSPAGE 0x00000020
-/* bbt is stored per chip on multichip devices */
-#define NAND_BBT_PERCHIP 0x00000080
-/* bbt has a version counter at offset veroffs */
-#define NAND_BBT_VERSION 0x00000100
-/* Create a bbt if none axists */
-#define NAND_BBT_CREATE 0x00000200
-/* Write bbt if necessary */
-#define NAND_BBT_WRITE 0x00001000
-/* Read and write back block contents when writing bbt */
-#define NAND_BBT_SAVECONTENT 0x00002000
- </programlisting>
- </para>
- </sect1>
-
- </chapter>
-
- <chapter id="structs">
- <title>Structures</title>
- <para>
- This chapter contains the autogenerated documentation of the structures which are
- used in the NAND driver and might be relevant for a driver developer. Each
- struct member has a short description which is marked with an [XXX] identifier.
- See the chapter "Documentation hints" for an explanation.
- </para>
-!Iinclude/linux/mtd/nand.h
- </chapter>
-
- <chapter id="pubfunctions">
- <title>Public Functions Provided</title>
- <para>
- This chapter contains the autogenerated documentation of the NAND kernel API functions
- which are exported. Each function has a short description which is marked with an [XXX] identifier.
- See the chapter "Documentation hints" for an explanation.
- </para>
-!Edrivers/mtd/nand/nand_base.c
-!Edrivers/mtd/nand/nand_bbt.c
-!Edrivers/mtd/nand/nand_ecc.c
- </chapter>
-
- <chapter id="intfunctions">
- <title>Internal Functions Provided</title>
- <para>
- This chapter contains the autogenerated documentation of the NAND driver internal functions.
- Each function has a short description which is marked with an [XXX] identifier.
- See the chapter "Documentation hints" for an explanation.
- The functions marked with [DEFAULT] might be relevant for a board driver developer.
- </para>
-!Idrivers/mtd/nand/nand_base.c
-!Idrivers/mtd/nand/nand_bbt.c
-<!-- No internal functions for kernel-doc:
-X!Idrivers/mtd/nand/nand_ecc.c
--->
- </chapter>
-
- <chapter id="credits">
- <title>Credits</title>
- <para>
- The following people have contributed to the NAND driver:
- <orderedlist>
- <listitem><para>Steven J. Hill<email>sjhill@realitydiluted.com</email></para></listitem>
- <listitem><para>David Woodhouse<email>dwmw2@infradead.org</email></para></listitem>
- <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem>
- </orderedlist>
- A lot of users have provided bugfixes, improvements and helping hands for testing.
- Thanks a lot.
- </para>
- <para>
- The following people have contributed to this document:
- <orderedlist>
- <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem>
- </orderedlist>
- </para>
- </chapter>
-</book>
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 1f8517db39c7..3cf1acebc4ee 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -34,6 +34,7 @@ available subsections can be seen below.
edac
scsi
libata
+ mtdnand
miscellaneous
w1
rapidio
diff --git a/Documentation/driver-api/mtdnand.rst b/Documentation/driver-api/mtdnand.rst
new file mode 100644
index 000000000000..8723175f955e
--- /dev/null
+++ b/Documentation/driver-api/mtdnand.rst
@@ -0,0 +1,1020 @@
+=====================================
+MTD NAND Driver Programming Interface
+=====================================
+
+:Author: Thomas Gleixner
+
+Introduction
+============
+
+The generic NAND driver supports almost all NAND and AG-AND based chips
+and connects them to the Memory Technology Devices (MTD) subsystem of
+the Linux Kernel.
+
+This documentation is provided for developers who want to implement
+board drivers or filesystem drivers suitable for NAND devices.
+
+Known Bugs And Assumptions
+==========================
+
+None.
+
+Documentation hints
+===================
+
+The function and structure docs are autogenerated. Each function and
+struct member has a short description which is marked with an [XXX]
+identifier. The following chapters explain the meaning of those
+identifiers.
+
+Function identifiers [XXX]
+--------------------------
+
+The functions are marked with [XXX] identifiers in the short comment.
+The identifiers explain the usage and scope of the functions. Following
+identifiers are used:
+
+- [MTD Interface]
+
+ These functions provide the interface to the MTD kernel API. They are
+ not replaceable and provide functionality which is complete hardware
+ independent.
+
+- [NAND Interface]
+
+ These functions are exported and provide the interface to the NAND
+ kernel API.
+
+- [GENERIC]
+
+ Generic functions are not replaceable and provide functionality which
+ is complete hardware independent.
+
+- [DEFAULT]
+
+ Default functions provide hardware related functionality which is
+ suitable for most of the implementations. These functions can be
+ replaced by the board driver if necessary. Those functions are called
+ via pointers in the NAND chip description structure. The board driver
+ can set the functions which should be replaced by board dependent
+ functions before calling nand_scan(). If the function pointer is
+ NULL on entry to nand_scan() then the pointer is set to the default
+ function which is suitable for the detected chip type.
+
+Struct member identifiers [XXX]
+-------------------------------
+
+The struct members are marked with [XXX] identifiers in the comment. The
+identifiers explain the usage and scope of the members. Following
+identifiers are used:
+
+- [INTERN]
+
+ These members are for NAND driver internal use only and must not be
+ modified. Most of these values are calculated from the chip geometry
+ information which is evaluated during nand_scan().
+
+- [REPLACEABLE]
+
+ Replaceable members hold hardware related functions which can be
+ provided by the board driver. The board driver can set the functions
+ which should be replaced by board dependent functions before calling
+ nand_scan(). If the function pointer is NULL on entry to
+ nand_scan() then the pointer is set to the default function which is
+ suitable for the detected chip type.
+
+- [BOARDSPECIFIC]
+
+ Board specific members hold hardware related information which must
+ be provided by the board driver. The board driver must set the
+ function pointers and datafields before calling nand_scan().
+
+- [OPTIONAL]
+
+ Optional members can hold information relevant for the board driver.
+ The generic NAND driver code does not use this information.
+
+Basic board driver
+==================
+
+For most boards it will be sufficient to provide just the basic
+functions and fill out some really board dependent members in the nand
+chip description structure.
+
+Basic defines
+-------------
+
+At least you have to provide a nand_chip structure and a storage for
+the ioremap'ed chip address. You can allocate the nand_chip structure
+using kmalloc or you can allocate it statically. The NAND chip structure
+embeds an mtd structure which will be registered to the MTD subsystem.
+You can extract a pointer to the mtd structure from a nand_chip pointer
+using the nand_to_mtd() helper.
+
+Kmalloc based example
+
+::
+
+ static struct mtd_info *board_mtd;
+ static void __iomem *baseaddr;
+
+
+Static example
+
+::
+
+ static struct nand_chip board_chip;
+ static void __iomem *baseaddr;
+
+
+Partition defines
+-----------------
+
+If you want to divide your device into partitions, then define a
+partitioning scheme suitable to your board.
+
+::
+
+ #define NUM_PARTITIONS 2
+ static struct mtd_partition partition_info[] = {
+ { .name = "Flash partition 1",
+ .offset = 0,
+ .size = 8 * 1024 * 1024 },
+ { .name = "Flash partition 2",
+ .offset = MTDPART_OFS_NEXT,
+ .size = MTDPART_SIZ_FULL },
+ };
+
+
+Hardware control function
+-------------------------
+
+The hardware control function provides access to the control pins of the
+NAND chip(s). The access can be done by GPIO pins or by address lines.
+If you use address lines, make sure that the timing requirements are
+met.
+
+*GPIO based example*
+
+::
+
+ static void board_hwcontrol(struct mtd_info *mtd, int cmd)
+ {
+ switch(cmd){
+ case NAND_CTL_SETCLE: /* Set CLE pin high */ break;
+ case NAND_CTL_CLRCLE: /* Set CLE pin low */ break;
+ case NAND_CTL_SETALE: /* Set ALE pin high */ break;
+ case NAND_CTL_CLRALE: /* Set ALE pin low */ break;
+ case NAND_CTL_SETNCE: /* Set nCE pin low */ break;
+ case NAND_CTL_CLRNCE: /* Set nCE pin high */ break;
+ }
+ }
+
+
+*Address lines based example.* It's assumed that the nCE pin is driven
+by a chip select decoder.
+
+::
+
+ static void board_hwcontrol(struct mtd_info *mtd, int cmd)
+ {
+ struct nand_chip *this = mtd_to_nand(mtd);
+ switch(cmd){
+ case NAND_CTL_SETCLE: this->IO_ADDR_W |= CLE_ADRR_BIT; break;
+ case NAND_CTL_CLRCLE: this->IO_ADDR_W &= ~CLE_ADRR_BIT; break;
+ case NAND_CTL_SETALE: this->IO_ADDR_W |= ALE_ADRR_BIT; break;
+ case NAND_CTL_CLRALE: this->IO_ADDR_W &= ~ALE_ADRR_BIT; break;
+ }
+ }
+
+
+Device ready function
+---------------------
+
+If the hardware interface has the ready busy pin of the NAND chip
+connected to a GPIO or other accessible I/O pin, this function is used
+to read back the state of the pin. The function has no arguments and
+should return 0, if the device is busy (R/B pin is low) and 1, if the
+device is ready (R/B pin is high). If the hardware interface does not
+give access to the ready busy pin, then the function must not be defined
+and the function pointer this->dev_ready is set to NULL.
+
+Init function
+-------------
+
+The init function allocates memory and sets up all the board specific
+parameters and function pointers. When everything is set up nand_scan()
+is called. This function tries to detect and identify then chip. If a
+chip is found all the internal data fields are initialized accordingly.
+The structure(s) have to be zeroed out first and then filled with the
+necessary information about the device.
+
+::
+
+ static int __init board_init (void)
+ {
+ struct nand_chip *this;
+ int err = 0;
+
+ /* Allocate memory for MTD device structure and private data */
+ this = kzalloc(sizeof(struct nand_chip), GFP_KERNEL);
+ if (!this) {
+ printk ("Unable to allocate NAND MTD device structure.\n");
+ err = -ENOMEM;
+ goto out;
+ }
+
+ board_mtd = nand_to_mtd(this);
+
+ /* map physical address */
+ baseaddr = ioremap(CHIP_PHYSICAL_ADDRESS, 1024);
+ if (!baseaddr) {
+ printk("Ioremap to access NAND chip failed\n");
+ err = -EIO;
+ goto out_mtd;
+ }
+
+ /* Set address of NAND IO lines */
+ this->IO_ADDR_R = baseaddr;
+ this->IO_ADDR_W = baseaddr;
+ /* Reference hardware control function */
+ this->hwcontrol = board_hwcontrol;
+ /* Set command delay time, see datasheet for correct value */
+ this->chip_delay = CHIP_DEPENDEND_COMMAND_DELAY;
+ /* Assign the device ready function, if available */
+ this->dev_ready = board_dev_ready;
+ this->eccmode = NAND_ECC_SOFT;
+
+ /* Scan to find existence of the device */
+ if (nand_scan (board_mtd, 1)) {
+ err = -ENXIO;
+ goto out_ior;
+ }
+
+ add_mtd_partitions(board_mtd, partition_info, NUM_PARTITIONS);
+ goto out;
+
+ out_ior:
+ iounmap(baseaddr);
+ out_mtd:
+ kfree (this);
+ out:
+ return err;
+ }
+ module_init(board_init);
+
+
+Exit function
+-------------
+
+The exit function is only necessary if the driver is compiled as a
+module. It releases all resources which are held by the chip driver and
+unregisters the partitions in the MTD layer.
+
+::
+
+ #ifdef MODULE
+ static void __exit board_cleanup (void)
+ {
+ /* Release resources, unregister device */
+ nand_release (board_mtd);
+
+ /* unmap physical address */
+ iounmap(baseaddr);
+
+ /* Free the MTD device structure */
+ kfree (mtd_to_nand(board_mtd));
+ }
+ module_exit(board_cleanup);
+ #endif
+
+
+Advanced board driver functions
+===============================
+
+This chapter describes the advanced functionality of the NAND driver.
+For a list of functions which can be overridden by the board driver see
+the documentation of the nand_chip structure.
+
+Multiple chip control
+---------------------
+
+The nand driver can control chip arrays. Therefore the board driver must
+provide an own select_chip function. This function must (de)select the
+requested chip. The function pointer in the nand_chip structure must be
+set before calling nand_scan(). The maxchip parameter of nand_scan()
+defines the maximum number of chips to scan for. Make sure that the
+select_chip function can handle the requested number of chips.
+
+The nand driver concatenates the chips to one virtual chip and provides
+this virtual chip to the MTD layer.
+
+*Note: The driver can only handle linear chip arrays of equally sized
+chips. There is no support for parallel arrays which extend the
+buswidth.*
+
+*GPIO based example*
+
+::
+
+ static void board_select_chip (struct mtd_info *mtd, int chip)
+ {
+ /* Deselect all chips, set all nCE pins high */
+ GPIO(BOARD_NAND_NCE) |= 0xff;
+ if (chip >= 0)
+ GPIO(BOARD_NAND_NCE) &= ~ (1 << chip);
+ }
+
+
+*Address lines based example.* Its assumed that the nCE pins are
+connected to an address decoder.
+
+::
+
+ static void board_select_chip (struct mtd_info *mtd, int chip)
+ {
+ struct nand_chip *this = mtd_to_nand(mtd);
+
+ /* Deselect all chips */
+ this->IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK;
+ this->IO_ADDR_W &= ~BOARD_NAND_ADDR_MASK;
+ switch (chip) {
+ case 0:
+ this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0;
+ this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0;
+ break;
+ ....
+ case n:
+ this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn;
+ this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn;
+ break;
+ }
+ }
+
+
+Hardware ECC support
+--------------------
+
+Functions and constants
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The nand driver supports three different types of hardware ECC.
+
+- NAND_ECC_HW3_256
+
+ Hardware ECC generator providing 3 bytes ECC per 256 byte.
+
+- NAND_ECC_HW3_512
+
+ Hardware ECC generator providing 3 bytes ECC per 512 byte.
+
+- NAND_ECC_HW6_512
+
+ Hardware ECC generator providing 6 bytes ECC per 512 byte.
+
+- NAND_ECC_HW8_512
+
+ Hardware ECC generator providing 6 bytes ECC per 512 byte.
+
+If your hardware generator has a different functionality add it at the
+appropriate place in nand_base.c
+
+The board driver must provide following functions:
+
+- enable_hwecc
+
+ This function is called before reading / writing to the chip. Reset
+ or initialize the hardware generator in this function. The function
+ is called with an argument which let you distinguish between read and
+ write operations.
+
+- calculate_ecc
+
+ This function is called after read / write from / to the chip.
+ Transfer the ECC from the hardware to the buffer. If the option
+ NAND_HWECC_SYNDROME is set then the function is only called on
+ write. See below.
+
+- correct_data
+
+ In case of an ECC error this function is called for error detection
+ and correction. Return 1 respectively 2 in case the error can be
+ corrected. If the error is not correctable return -1. If your
+ hardware generator matches the default algorithm of the nand_ecc
+ software generator then use the correction function provided by
+ nand_ecc instead of implementing duplicated code.
+
+Hardware ECC with syndrome calculation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many hardware ECC implementations provide Reed-Solomon codes and
+calculate an error syndrome on read. The syndrome must be converted to a
+standard Reed-Solomon syndrome before calling the error correction code
+in the generic Reed-Solomon library.
+
+The ECC bytes must be placed immediately after the data bytes in order
+to make the syndrome generator work. This is contrary to the usual
+layout used by software ECC. The separation of data and out of band area
+is not longer possible. The nand driver code handles this layout and the
+remaining free bytes in the oob area are managed by the autoplacement
+code. Provide a matching oob-layout in this case. See rts_from4.c and
+diskonchip.c for implementation reference. In those cases we must also
+use bad block tables on FLASH, because the ECC layout is interfering
+with the bad block marker positions. See bad block table support for
+details.
+
+Bad block table support
+-----------------------
+
+Most NAND chips mark the bad blocks at a defined position in the spare
+area. Those blocks must not be erased under any circumstances as the bad
+block information would be lost. It is possible to check the bad block
+mark each time when the blocks are accessed by reading the spare area of
+the first page in the block. This is time consuming so a bad block table
+is used.
+
+The nand driver supports various types of bad block tables.
+
+- Per device
+
+ The bad block table contains all bad block information of the device
+ which can consist of multiple chips.
+
+- Per chip
+
+ A bad block table is used per chip and contains the bad block
+ information for this particular chip.
+
+- Fixed offset
+
+ The bad block table is located at a fixed offset in the chip
+ (device). This applies to various DiskOnChip devices.
+
+- Automatic placed
+
+ The bad block table is automatically placed and detected either at
+ the end or at the beginning of a chip (device)
+
+- Mirrored tables
+
+ The bad block table is mirrored on the chip (device) to allow updates
+ of the bad block table without data loss.
+
+nand_scan() calls the function nand_default_bbt().
+nand_default_bbt() selects appropriate default bad block table
+descriptors depending on the chip information which was retrieved by
+nand_scan().
+
+The standard policy is scanning the device for bad blocks and build a
+ram based bad block table which allows faster access than always
+checking the bad block information on the flash chip itself.
+
+Flash based tables
+~~~~~~~~~~~~~~~~~~
+
+It may be desired or necessary to keep a bad block table in FLASH. For
+AG-AND chips this is mandatory, as they have no factory marked bad
+blocks. They have factory marked good blocks. The marker pattern is
+erased when the block is erased to be reused. So in case of powerloss
+before writing the pattern back to the chip this block would be lost and
+added to the bad blocks. Therefore we scan the chip(s) when we detect
+them the first time for good blocks and store this information in a bad
+block table before erasing any of the blocks.
+
+The blocks in which the tables are stored are protected against
+accidental access by marking them bad in the memory bad block table. The
+bad block table management functions are allowed to circumvent this
+protection.
+
+The simplest way to activate the FLASH based bad block table support is
+to set the option NAND_BBT_USE_FLASH in the bbt_option field of the
+nand chip structure before calling nand_scan(). For AG-AND chips is
+this done by default. This activates the default FLASH based bad block
+table functionality of the NAND driver. The default bad block table
+options are
+
+- Store bad block table per chip
+
+- Use 2 bits per block
+
+- Automatic placement at the end of the chip
+
+- Use mirrored tables with version numbers
+
+- Reserve 4 blocks at the end of the chip
+
+User defined tables
+~~~~~~~~~~~~~~~~~~~
+
+User defined tables are created by filling out a nand_bbt_descr
+structure and storing the pointer in the nand_chip structure member
+bbt_td before calling nand_scan(). If a mirror table is necessary a
+second structure must be created and a pointer to this structure must be
+stored in bbt_md inside the nand_chip structure. If the bbt_md member
+is set to NULL then only the main table is used and no scan for the
+mirrored table is performed.
+
+The most important field in the nand_bbt_descr structure is the
+options field. The options define most of the table properties. Use the
+predefined constants from nand.h to define the options.
+
+- Number of bits per block
+
+ The supported number of bits is 1, 2, 4, 8.
+
+- Table per chip
+
+ Setting the constant NAND_BBT_PERCHIP selects that a bad block
+ table is managed for each chip in a chip array. If this option is not
+ set then a per device bad block table is used.
+
+- Table location is absolute
+
+ Use the option constant NAND_BBT_ABSPAGE and define the absolute
+ page number where the bad block table starts in the field pages. If
+ you have selected bad block tables per chip and you have a multi chip
+ array then the start page must be given for each chip in the chip
+ array. Note: there is no scan for a table ident pattern performed, so
+ the fields pattern, veroffs, offs, len can be left uninitialized
+
+- Table location is automatically detected
+
+ The table can either be located in the first or the last good blocks
+ of the chip (device). Set NAND_BBT_LASTBLOCK to place the bad block
+ table at the end of the chip (device). The bad block tables are
+ marked and identified by a pattern which is stored in the spare area
+ of the first page in the block which holds the bad block table. Store
+ a pointer to the pattern in the pattern field. Further the length of
+ the pattern has to be stored in len and the offset in the spare area
+ must be given in the offs member of the nand_bbt_descr structure.
+ For mirrored bad block tables different patterns are mandatory.
+
+- Table creation
+
+ Set the option NAND_BBT_CREATE to enable the table creation if no
+ table can be found during the scan. Usually this is done only once if
+ a new chip is found.
+
+- Table write support
+
+ Set the option NAND_BBT_WRITE to enable the table write support.
+ This allows the update of the bad block table(s) in case a block has
+ to be marked bad due to wear. The MTD interface function
+ block_markbad is calling the update function of the bad block table.
+ If the write support is enabled then the table is updated on FLASH.
+
+ Note: Write support should only be enabled for mirrored tables with
+ version control.
+
+- Table version control
+
+ Set the option NAND_BBT_VERSION to enable the table version
+ control. It's highly recommended to enable this for mirrored tables
+ with write support. It makes sure that the risk of losing the bad
+ block table information is reduced to the loss of the information
+ about the one worn out block which should be marked bad. The version
+ is stored in 4 consecutive bytes in the spare area of the device. The
+ position of the version number is defined by the member veroffs in
+ the bad block table descriptor.
+
+- Save block contents on write
+
+ In case that the block which holds the bad block table does contain
+ other useful information, set the option NAND_BBT_SAVECONTENT. When
+ the bad block table is written then the whole block is read the bad
+ block table is updated and the block is erased and everything is
+ written back. If this option is not set only the bad block table is
+ written and everything else in the block is ignored and erased.
+
+- Number of reserved blocks
+
+ For automatic placement some blocks must be reserved for bad block
+ table storage. The number of reserved blocks is defined in the
+ maxblocks member of the bad block table description structure.
+ Reserving 4 blocks for mirrored tables should be a reasonable number.
+ This also limits the number of blocks which are scanned for the bad
+ block table ident pattern.
+
+Spare area (auto)placement
+--------------------------
+
+The nand driver implements different possibilities for placement of
+filesystem data in the spare area,
+
+- Placement defined by fs driver
+
+- Automatic placement
+
+The default placement function is automatic placement. The nand driver
+has built in default placement schemes for the various chiptypes. If due
+to hardware ECC functionality the default placement does not fit then
+the board driver can provide a own placement scheme.
+
+File system drivers can provide a own placement scheme which is used
+instead of the default placement scheme.
+
+Placement schemes are defined by a nand_oobinfo structure
+
+::
+
+ struct nand_oobinfo {
+ int useecc;
+ int eccbytes;
+ int eccpos[24];
+ int oobfree[8][2];
+ };
+
+
+- useecc
+
+ The useecc member controls the ecc and placement function. The header
+ file include/mtd/mtd-abi.h contains constants to select ecc and
+ placement. MTD_NANDECC_OFF switches off the ecc complete. This is
+ not recommended and available for testing and diagnosis only.
+ MTD_NANDECC_PLACE selects caller defined placement,
+ MTD_NANDECC_AUTOPLACE selects automatic placement.
+
+- eccbytes
+
+ The eccbytes member defines the number of ecc bytes per page.
+
+- eccpos
+
+ The eccpos array holds the byte offsets in the spare area where the
+ ecc codes are placed.
+
+- oobfree
+
+ The oobfree array defines the areas in the spare area which can be
+ used for automatic placement. The information is given in the format
+ {offset, size}. offset defines the start of the usable area, size the
+ length in bytes. More than one area can be defined. The list is
+ terminated by an {0, 0} entry.
+
+Placement defined by fs driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The calling function provides a pointer to a nand_oobinfo structure
+which defines the ecc placement. For writes the caller must provide a
+spare area buffer along with the data buffer. The spare area buffer size
+is (number of pages) \* (size of spare area). For reads the buffer size
+is (number of pages) \* ((size of spare area) + (number of ecc steps per
+page) \* sizeof (int)). The driver stores the result of the ecc check
+for each tuple in the spare buffer. The storage sequence is::
+
+ <spare data page 0><ecc result 0>...<ecc result n>
+
+ ...
+
+ <spare data page n><ecc result 0>...<ecc result n>
+
+This is a legacy mode used by YAFFS1.
+
+If the spare area buffer is NULL then only the ECC placement is done
+according to the given scheme in the nand_oobinfo structure.
+
+Automatic placement
+~~~~~~~~~~~~~~~~~~~
+
+Automatic placement uses the built in defaults to place the ecc bytes in
+the spare area. If filesystem data have to be stored / read into the
+spare area then the calling function must provide a buffer. The buffer
+size per page is determined by the oobfree array in the nand_oobinfo
+structure.
+
+If the spare area buffer is NULL then only the ECC placement is done
+according to the default builtin scheme.
+
+Spare area autoplacement default schemes
+----------------------------------------
+
+256 byte pagesize
+~~~~~~~~~~~~~~~~~
+
+======== ================== ===================================================
+Offset Content Comment
+======== ================== ===================================================
+0x00 ECC byte 0 Error correction code byte 0
+0x01 ECC byte 1 Error correction code byte 1
+0x02 ECC byte 2 Error correction code byte 2
+0x03 Autoplace 0
+0x04 Autoplace 1
+0x05 Bad block marker If any bit in this byte is zero, then this
+ block is bad. This applies only to the first
+ page in a block. In the remaining pages this
+ byte is reserved
+0x06 Autoplace 2
+0x07 Autoplace 3
+======== ================== ===================================================
+
+512 byte pagesize
+~~~~~~~~~~~~~~~~~
+
+
+============= ================== ==============================================
+Offset Content Comment
+============= ================== ==============================================
+0x00 ECC byte 0 Error correction code byte 0 of the lower
+ 256 Byte data in this page
+0x01 ECC byte 1 Error correction code byte 1 of the lower
+ 256 Bytes of data in this page
+0x02 ECC byte 2 Error correction code byte 2 of the lower
+ 256 Bytes of data in this page
+0x03 ECC byte 3 Error correction code byte 0 of the upper
+ 256 Bytes of data in this page
+0x04 reserved reserved
+0x05 Bad block marker If any bit in this byte is zero, then this
+ block is bad. This applies only to the first
+ page in a block. In the remaining pages this
+ byte is reserved
+0x06 ECC byte 4 Error correction code byte 1 of the upper
+ 256 Bytes of data in this page
+0x07 ECC byte 5 Error correction code byte 2 of the upper
+ 256 Bytes of data in this page
+0x08 - 0x0F Autoplace 0 - 7
+============= ================== ==============================================
+
+2048 byte pagesize
+~~~~~~~~~~~~~~~~~~
+
+=========== ================== ================================================
+Offset Content Comment
+=========== ================== ================================================
+0x00 Bad block marker If any bit in this byte is zero, then this block
+ is bad. This applies only to the first page in a
+ block. In the remaining pages this byte is
+ reserved
+0x01 Reserved Reserved
+0x02-0x27 Autoplace 0 - 37
+0x28 ECC byte 0 Error correction code byte 0 of the first
+ 256 Byte data in this page
+0x29 ECC byte 1 Error correction code byte 1 of the first
+ 256 Bytes of data in this page
+0x2A ECC byte 2 Error correction code byte 2 of the first
+ 256 Bytes data in this page
+0x2B ECC byte 3 Error correction code byte 0 of the second
+ 256 Bytes of data in this page
+0x2C ECC byte 4 Error correction code byte 1 of the second
+ 256 Bytes of data in this page
+0x2D ECC byte 5 Error correction code byte 2 of the second
+ 256 Bytes of data in this page
+0x2E ECC byte 6 Error correction code byte 0 of the third
+ 256 Bytes of data in this page
+0x2F ECC byte 7 Error correction code byte 1 of the third
+ 256 Bytes of data in this page
+0x30 ECC byte 8 Error correction code byte 2 of the third
+ 256 Bytes of data in this page
+0x31 ECC byte 9 Error correction code byte 0 of the fourth
+ 256 Bytes of data in this page
+0x32 ECC byte 10 Error correction code byte 1 of the fourth
+ 256 Bytes of data in this page
+0x33 ECC byte 11 Error correction code byte 2 of the fourth
+ 256 Bytes of data in this page
+0x34 ECC byte 12 Error correction code byte 0 of the fifth
+ 256 Bytes of data in this page
+0x35 ECC byte 13 Error correction code byte 1 of the fifth
+ 256 Bytes of data in this page
+0x36 ECC byte 14 Error correction code byte 2 of the fifth
+ 256 Bytes of data in this page
+0x37 ECC byte 15 Error correction code byte 0 of the sixth
+ 256 Bytes of data in this page
+0x38 ECC byte 16 Error correction code byte 1 of the sixth
+ 256 Bytes of data in this page
+0x39 ECC byte 17 Error correction code byte 2 of the sixth
+ 256 Bytes of data in this page
+0x3A ECC byte 18 Error correction code byte 0 of the seventh
+ 256 Bytes of data in this page
+0x3B ECC byte 19 Error correction code byte 1 of the seventh
+ 256 Bytes of data in this page
+0x3C ECC byte 20 Error correction code byte 2 of the seventh
+ 256 Bytes of data in this page
+0x3D ECC byte 21 Error correction code byte 0 of the eighth
+ 256 Bytes of data in this page
+0x3E ECC byte 22 Error correction code byte 1 of the eighth
+ 256 Bytes of data in this page
+0x3F ECC byte 23 Error correction code byte 2 of the eighth
+ 256 Bytes of data in this page
+=========== ================== ================================================
+
+Filesystem support
+==================
+
+The NAND driver provides all necessary functions for a filesystem via
+the MTD interface.
+
+Filesystems must be aware of the NAND peculiarities and restrictions.
+One major restrictions of NAND Flash is, that you cannot write as often
+as you want to a page. The consecutive writes to a page, before erasing
+it again, are restricted to 1-3 writes, depending on the manufacturers
+specifications. This applies similar to the spare area.
+
+Therefore NAND aware filesystems must either write in page size chunks
+or hold a writebuffer to collect smaller writes until they sum up to
+pagesize. Available NAND aware filesystems: JFFS2, YAFFS.
+
+The spare area usage to store filesystem data is controlled by the spare
+area placement functionality which is described in one of the earlier
+chapters.
+
+Tools
+=====
+
+The MTD project provides a couple of helpful tools to handle NAND Flash.
+
+- flasherase, flasheraseall: Erase and format FLASH partitions
+
+- nandwrite: write filesystem images to NAND FLASH
+
+- nanddump: dump the contents of a NAND FLASH partitions
+
+These tools are aware of the NAND restrictions. Please use those tools
+instead of complaining about errors which are caused by non NAND aware
+access methods.
+
+Constants
+=========
+
+This chapter describes the constants which might be relevant for a
+driver developer.
+
+Chip option constants
+---------------------
+
+Constants for chip id table
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These constants are defined in nand.h. They are ored together to
+describe the chip functionality.
+
+::
+
+ /* Buswitdh is 16 bit */
+ #define NAND_BUSWIDTH_16 0x00000002
+ /* Device supports partial programming without padding */
+ #define NAND_NO_PADDING 0x00000004
+ /* Chip has cache program function */
+ #define NAND_CACHEPRG 0x00000008
+ /* Chip has copy back function */
+ #define NAND_COPYBACK 0x00000010
+ /* AND Chip which has 4 banks and a confusing page / block
+ * assignment. See Renesas datasheet for further information */
+ #define NAND_IS_AND 0x00000020
+ /* Chip has a array of 4 pages which can be read without
+ * additional ready /busy waits */
+ #define NAND_4PAGE_ARRAY 0x00000040
+
+
+Constants for runtime options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These constants are defined in nand.h. They are ored together to
+describe the functionality.
+
+::
+
+ /* The hw ecc generator provides a syndrome instead a ecc value on read
+ * This can only work if we have the ecc bytes directly behind the
+ * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */
+ #define NAND_HWECC_SYNDROME 0x00020000
+
+
+ECC selection constants
+-----------------------
+
+Use these constants to select the ECC algorithm.
+
+::
+
+ /* No ECC. Usage is not recommended ! */
+ #define NAND_ECC_NONE 0
+ /* Software ECC 3 byte ECC per 256 Byte data */
+ #define NAND_ECC_SOFT 1
+ /* Hardware ECC 3 byte ECC per 256 Byte data */
+ #define NAND_ECC_HW3_256 2
+ /* Hardware ECC 3 byte ECC per 512 Byte data */
+ #define NAND_ECC_HW3_512 3
+ /* Hardware ECC 6 byte ECC per 512 Byte data */
+ #define NAND_ECC_HW6_512 4
+ /* Hardware ECC 6 byte ECC per 512 Byte data */
+ #define NAND_ECC_HW8_512 6
+
+
+Hardware control related constants
+----------------------------------
+
+These constants describe the requested hardware access function when the
+boardspecific hardware control function is called
+
+::
+
+ /* Select the chip by setting nCE to low */
+ #define NAND_CTL_SETNCE 1
+ /* Deselect the chip by setting nCE to high */
+ #define NAND_CTL_CLRNCE 2
+ /* Select the command latch by setting CLE to high */
+ #define NAND_CTL_SETCLE 3
+ /* Deselect the command latch by setting CLE to low */
+ #define NAND_CTL_CLRCLE 4
+ /* Select the address latch by setting ALE to high */
+ #define NAND_CTL_SETALE 5
+ /* Deselect the address latch by setting ALE to low */
+ #define NAND_CTL_CLRALE 6
+ /* Set write protection by setting WP to high. Not used! */
+ #define NAND_CTL_SETWP 7
+ /* Clear write protection by setting WP to low. Not used! */
+ #define NAND_CTL_CLRWP 8
+
+
+Bad block table related constants
+---------------------------------
+
+These constants describe the options used for bad block table
+descriptors.
+
+::
+
+ /* Options for the bad block table descriptors */
+
+ /* The number of bits used per block in the bbt on the device */
+ #define NAND_BBT_NRBITS_MSK 0x0000000F
+ #define NAND_BBT_1BIT 0x00000001
+ #define NAND_BBT_2BIT 0x00000002
+ #define NAND_BBT_4BIT 0x00000004
+ #define NAND_BBT_8BIT 0x00000008
+ /* The bad block table is in the last good block of the device */
+ #define NAND_BBT_LASTBLOCK 0x00000010
+ /* The bbt is at the given page, else we must scan for the bbt */
+ #define NAND_BBT_ABSPAGE 0x00000020
+ /* bbt is stored per chip on multichip devices */
+ #define NAND_BBT_PERCHIP 0x00000080
+ /* bbt has a version counter at offset veroffs */
+ #define NAND_BBT_VERSION 0x00000100
+ /* Create a bbt if none axists */
+ #define NAND_BBT_CREATE 0x00000200
+ /* Write bbt if necessary */
+ #define NAND_BBT_WRITE 0x00001000
+ /* Read and write back block contents when writing bbt */
+ #define NAND_BBT_SAVECONTENT 0x00002000
+
+
+Structures
+==========
+
+This chapter contains the autogenerated documentation of the structures
+which are used in the NAND driver and might be relevant for a driver
+developer. Each struct member has a short description which is marked
+with an [XXX] identifier. See the chapter "Documentation hints" for an
+explanation.
+
+.. kernel-doc:: include/linux/mtd/nand.h
+ :internal:
+
+Public Functions Provided
+=========================
+
+This chapter contains the autogenerated documentation of the NAND kernel
+API functions which are exported. Each function has a short description
+which is marked with an [XXX] identifier. See the chapter "Documentation
+hints" for an explanation.
+
+.. kernel-doc:: drivers/mtd/nand/nand_base.c
+ :export:
+
+.. kernel-doc:: drivers/mtd/nand/nand_bbt.c
+ :export:
+
+.. kernel-doc:: drivers/mtd/nand/nand_ecc.c
+ :export:
+
+Internal Functions Provided
+===========================
+
+This chapter contains the autogenerated documentation of the NAND driver
+internal functions. Each function has a short description which is
+marked with an [XXX] identifier. See the chapter "Documentation hints"
+for an explanation. The functions marked with [DEFAULT] might be
+relevant for a board driver developer.
+
+.. kernel-doc:: drivers/mtd/nand/nand_base.c
+ :internal:
+
+.. kernel-doc:: drivers/mtd/nand/nand_bbt.c
+ :internal:
+
+Credits
+=======
+
+The following people have contributed to the NAND driver:
+
+1. Steven J. Hill\ sjhill@realitydiluted.com
+
+2. David Woodhouse\ dwmw2@infradead.org
+
+3. Thomas Gleixner\ tglx@linutronix.de
+
+A lot of users have provided bugfixes, improvements and helping hands
+for testing. Thanks a lot.
+
+The following people have contributed to this document:
+
+1. Thomas Gleixner\ tglx@linutronix.de
--
2.9.3
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [PATCH 3/5] mtdnand.rst: Fix some typos and group the "::" with previous line
2017-05-13 11:10 [PATCH 0/5] Convert more books to ReST Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 1/5] docs-rst: convert librs book " Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 2/5] docs-rst: convert mtdnand " Mauro Carvalho Chehab
@ 2017-05-13 11:10 ` Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 4/5] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings Mauro Carvalho Chehab
` (2 subsequent siblings)
5 siblings, 0 replies; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-13 11:10 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Typo:
ored -> ordered
While here, group the :: with the previous paragraph, in order
to make it visually better when reading as a text file.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/driver-api/mtdnand.rst | 24 +++++++-----------------
1 file changed, 7 insertions(+), 17 deletions(-)
diff --git a/Documentation/driver-api/mtdnand.rst b/Documentation/driver-api/mtdnand.rst
index 8723175f955e..e670f8b15a79 100644
--- a/Documentation/driver-api/mtdnand.rst
+++ b/Documentation/driver-api/mtdnand.rst
@@ -843,10 +843,8 @@ Chip option constants
Constants for chip id table
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-These constants are defined in nand.h. They are ored together to
-describe the chip functionality.
-
-::
+These constants are defined in nand.h. They are ordered together to
+describe the chip functionality::
/* Buswitdh is 16 bit */
#define NAND_BUSWIDTH_16 0x00000002
@@ -867,10 +865,8 @@ describe the chip functionality.
Constants for runtime options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-These constants are defined in nand.h. They are ored together to
-describe the functionality.
-
-::
+These constants are defined in nand.h. They are ordered together to
+describe the functionality::
/* The hw ecc generator provides a syndrome instead a ecc value on read
* This can only work if we have the ecc bytes directly behind the
@@ -881,9 +877,7 @@ describe the functionality.
ECC selection constants
-----------------------
-Use these constants to select the ECC algorithm.
-
-::
+Use these constants to select the ECC algorithm::
/* No ECC. Usage is not recommended ! */
#define NAND_ECC_NONE 0
@@ -903,9 +897,7 @@ Hardware control related constants
----------------------------------
These constants describe the requested hardware access function when the
-boardspecific hardware control function is called
-
-::
+boardspecific hardware control function is called::
/* Select the chip by setting nCE to low */
#define NAND_CTL_SETNCE 1
@@ -929,9 +921,7 @@ Bad block table related constants
---------------------------------
These constants describe the options used for bad block table
-descriptors.
-
-::
+descriptors::
/* Options for the bad block table descriptors */
--
2.9.3
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [PATCH 4/5] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings
2017-05-13 11:10 [PATCH 0/5] Convert more books to ReST Mauro Carvalho Chehab
` (2 preceding siblings ...)
2017-05-13 11:10 ` [PATCH 3/5] mtdnand.rst: Fix some typos and group the "::" with previous line Mauro Carvalho Chehab
@ 2017-05-13 11:10 ` Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 5/5] docs-rst: convert sh book to ReST Mauro Carvalho Chehab
2017-05-15 12:09 ` [PATCH 0/5] Convert more books " Boris Brezillon
5 siblings, 0 replies; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-13 11:10 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Boris Brezillon, Richard Weinberger,
David Woodhouse, Brian Norris, Marek Vasut, Cyrille Pitchen,
linux-mtd
./drivers/mtd/nand/nand_bbt.c:1: warning: no structured comments found
./include/linux/mtd/nand.h:785: ERROR: Unexpected indentation.
./drivers/mtd/nand/nand_base.c:449: WARNING: Definition list ends without a blank line; unexpected unindent.
./drivers/mtd/nand/nand_base.c:1161: ERROR: Unexpected indentation.
./drivers/mtd/nand/nand_base.c:1162: WARNING: Block quote ends without a blank line; unexpected unindent.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/driver-api/mtdnand.rst | 3 ---
drivers/mtd/nand/nand_base.c | 7 +++++--
include/linux/mtd/nand.h | 2 +-
3 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/driver-api/mtdnand.rst b/Documentation/driver-api/mtdnand.rst
index e670f8b15a79..4fe3bf00299b 100644
--- a/Documentation/driver-api/mtdnand.rst
+++ b/Documentation/driver-api/mtdnand.rst
@@ -970,9 +970,6 @@ hints" for an explanation.
.. kernel-doc:: drivers/mtd/nand/nand_base.c
:export:
-.. kernel-doc:: drivers/mtd/nand/nand_bbt.c
- :export:
-
.. kernel-doc:: drivers/mtd/nand/nand_ecc.c
:export:
diff --git a/drivers/mtd/nand/nand_base.c b/drivers/mtd/nand/nand_base.c
index b0524f8accb6..c8988c01e0d7 100644
--- a/drivers/mtd/nand/nand_base.c
+++ b/drivers/mtd/nand/nand_base.c
@@ -442,10 +442,12 @@ static int nand_default_block_markbad(struct mtd_info *mtd, loff_t ofs)
* specify how to write bad block markers to OOB (chip->block_markbad).
*
* We try operations in the following order:
+ *
* (1) erase the affected block, to allow OOB marker to be written cleanly
* (2) write bad block marker to OOB area of affected block (unless flag
* NAND_BBT_NO_OOB_BBM is present)
* (3) update the BBT
+ *
* Note that we retain the first error encountered in (2) or (3), finish the
* procedures, and dump the error in the end.
*/
@@ -1155,9 +1157,10 @@ int nand_reset(struct nand_chip *chip, int chipnr)
* @mtd: mtd info
* @ofs: offset to start unlock from
* @len: length to unlock
- * @invert: when = 0, unlock the range of blocks within the lower and
+ * @invert:
+ * - when = 0, unlock the range of blocks within the lower and
* upper boundary address
- * when = 1, unlock the range of blocks outside the boundaries
+ * - when = 1, unlock the range of blocks outside the boundaries
* of the lower and upper boundary address
*
* Returs unlock status.
diff --git a/include/linux/mtd/nand.h b/include/linux/mtd/nand.h
index 9591e0fbe5bd..3d5b20379ba3 100644
--- a/include/linux/mtd/nand.h
+++ b/include/linux/mtd/nand.h
@@ -779,7 +779,7 @@ nand_get_sdr_timings(const struct nand_data_interface *conf)
* Minimum amount of bit errors per @ecc_step_ds guaranteed
* to be correctable. If unknown, set to zero.
* @ecc_step_ds: [INTERN] ECC step required by the @ecc_strength_ds,
- * also from the datasheet. It is the recommended ECC step
+ * also from the datasheet. It is the recommended ECC step
* size, if known; if unknown, set to zero.
* @onfi_timing_mode_default: [INTERN] default ONFI timing mode. This field is
* set to the actually used ONFI mode if the chip is
--
2.9.3
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [PATCH 5/5] docs-rst: convert sh book to ReST
2017-05-13 11:10 [PATCH 0/5] Convert more books to ReST Mauro Carvalho Chehab
` (3 preceding siblings ...)
2017-05-13 11:10 ` [PATCH 4/5] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings Mauro Carvalho Chehab
@ 2017-05-13 11:10 ` Mauro Carvalho Chehab
2017-05-15 12:09 ` [PATCH 0/5] Convert more books " Boris Brezillon
5 siblings, 0 replies; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-13 11:10 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Yoshinori Sato, Rich Felker, Jani Nikula,
Greg Kroah-Hartman, Markus Heiser, Takashi Iwai,
Herton R. Krzesinski, linux-sh
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DocBook/Makefile | 4 +-
Documentation/DocBook/sh.tmpl | 105 -----------------------------------------
Documentation/conf.py | 2 +
Documentation/index.rst | 11 +++++
Documentation/sh/index.rst | 59 +++++++++++++++++++++++
5 files changed, 73 insertions(+), 108 deletions(-)
delete mode 100644 Documentation/DocBook/sh.tmpl
create mode 100644 Documentation/sh/index.rst
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 226e5e9fc801..efba7f980895 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -6,9 +6,7 @@
# To add a new book the only step required is to add the book to the
# list of DOCBOOKS.
-DOCBOOKS := \
- lsm.xml \
- sh.xml
+DOCBOOKS := lsm.xml
ifeq ($(DOCBOOKS),)
diff --git a/Documentation/DocBook/sh.tmpl b/Documentation/DocBook/sh.tmpl
deleted file mode 100644
index 4a38f604fa66..000000000000
--- a/Documentation/DocBook/sh.tmpl
+++ /dev/null
@@ -1,105 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="sh-drivers">
- <bookinfo>
- <title>SuperH Interfaces Guide</title>
-
- <authorgroup>
- <author>
- <firstname>Paul</firstname>
- <surname>Mundt</surname>
- <affiliation>
- <address>
- <email>lethal@linux-sh.org</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2008-2010</year>
- <holder>Paul Mundt</holder>
- </copyright>
- <copyright>
- <year>2008-2010</year>
- <holder>Renesas Technology Corp.</holder>
- </copyright>
- <copyright>
- <year>2010</year>
- <holder>Renesas Electronics Corp.</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="mm">
- <title>Memory Management</title>
- <sect1 id="sh4">
- <title>SH-4</title>
- <sect2 id="sq">
- <title>Store Queue API</title>
-!Earch/sh/kernel/cpu/sh4/sq.c
- </sect2>
- </sect1>
- <sect1 id="sh5">
- <title>SH-5</title>
- <sect2 id="tlb">
- <title>TLB Interfaces</title>
-!Iarch/sh/mm/tlb-sh5.c
-!Iarch/sh/include/asm/tlb_64.h
- </sect2>
- </sect1>
- </chapter>
- <chapter id="mach">
- <title>Machine Specific Interfaces</title>
- <sect1 id="dreamcast">
- <title>mach-dreamcast</title>
-!Iarch/sh/boards/mach-dreamcast/rtc.c
- </sect1>
- <sect1 id="x3proto">
- <title>mach-x3proto</title>
-!Earch/sh/boards/mach-x3proto/ilsel.c
- </sect1>
- </chapter>
- <chapter id="busses">
- <title>Busses</title>
- <sect1 id="superhyway">
- <title>SuperHyway</title>
-!Edrivers/sh/superhyway/superhyway.c
- </sect1>
-
- <sect1 id="maple">
- <title>Maple</title>
-!Edrivers/sh/maple/maple.c
- </sect1>
- </chapter>
-</book>
diff --git a/Documentation/conf.py b/Documentation/conf.py
index dfe14f7525d0..77d47bb1df1d 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -375,6 +375,8 @@ latex_documents = [
'The kernel development community', 'manual'),
('security/index', 'security.tex', 'The kernel security subsystem manual',
'The kernel development community', 'manual'),
+ ('sh/index', 'sh.tex', 'SuperH architecture implementation manual',
+ 'The kernel development community', 'manual'),
('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
'The kernel development community', 'manual'),
('userspace-api/index', 'userspace-api.tex', 'The Linux kernel user-space API guide',
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 25c4da41da6b..e9017bb3a6ce 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -76,6 +76,17 @@ needed).
crypto/index
filesystems/index
+Architecture-specific documentation
+-----------------------------------
+
+These books provide programming details about architecture-specific
+implementation.
+
+.. toctree::
+ :maxdepth: 2
+
+ sh/index
+
Korean translations
-------------------
diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
new file mode 100644
index 000000000000..bc8db7ba894a
--- /dev/null
+++ b/Documentation/sh/index.rst
@@ -0,0 +1,59 @@
+=======================
+SuperH Interfaces Guide
+=======================
+
+:Author: Paul Mundt
+
+Memory Management
+=================
+
+SH-4
+----
+
+Store Queue API
+~~~~~~~~~~~~~~~
+
+.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
+ :export:
+
+SH-5
+----
+
+TLB Interfaces
+~~~~~~~~~~~~~~
+
+.. kernel-doc:: arch/sh/mm/tlb-sh5.c
+ :internal:
+
+.. kernel-doc:: arch/sh/include/asm/tlb_64.h
+ :internal:
+
+Machine Specific Interfaces
+===========================
+
+mach-dreamcast
+--------------
+
+.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
+ :internal:
+
+mach-x3proto
+------------
+
+.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
+ :export:
+
+Busses
+======
+
+SuperHyway
+----------
+
+.. kernel-doc:: drivers/sh/superhyway/superhyway.c
+ :export:
+
+Maple
+-----
+
+.. kernel-doc:: drivers/sh/maple/maple.c
+ :export:
--
2.9.3
^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH 0/5] Convert more books to ReST
2017-05-13 11:10 [PATCH 0/5] Convert more books to ReST Mauro Carvalho Chehab
` (4 preceding siblings ...)
2017-05-13 11:10 ` [PATCH 5/5] docs-rst: convert sh book to ReST Mauro Carvalho Chehab
@ 2017-05-15 12:09 ` Boris Brezillon
2017-05-15 17:15 ` Jonathan Corbet
2017-05-16 10:38 ` Mauro Carvalho Chehab
5 siblings, 2 replies; 10+ messages in thread
From: Boris Brezillon @ 2017-05-15 12:09 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Rich Felker, linux-sh, Takashi Iwai,
Sebastian Andrzej Siewior, Herton R. Krzesinski, linux-mtd,
Cyrille Pitchen, Markus Heiser, Yoshinori Sato, Jonathan Corbet,
Richard Weinberger, Marek Vasut, sayli karnik, Jani Nikula,
Mauro Carvalho Chehab, Greg Kroah-Hartman, linux-kernel,
linux-security-module, Silvio Fricke, Brian Norris,
David Woodhouse
On Sat, 13 May 2017 08:10:53 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> This patch series convert the following books to ReST:
> - librs
> - mtdnand
> - sh
>
> And it is based on my previous series of conversion patches.
>
> After this series, there will be just one DocBook pending conversion:
> - lsm (Linux Security Modules)
>
> This book is very outdated: no changes since the Kernel moved
> to git, in 2005 (except for a minor editorial fix in 2008).
>
> I took a look on the described API: it doesn't seem to be describing
> the current security implementation.
>
> The best here is if someone that works with LSM to convert it to
> ReST with:
> $ Documentation/sphinx/tmplcvt Documentation/DocBook/lsm.tmpl lsm.rst
>
> And fix the document to produce something that reflects the current
> implementation. If nobody is interested, then maybe we could just
> drop it.
>
> -
>
> This patch series is based on my past 00/36 patch series, applied on
> the top of docs tree (next branch).
>
> The full patch series is on this tree is at:
>
> https://git.linuxtv.org//mchehab/experimental.git/log/?h=docbook
>
> And the HTML output at:
>
> http://www.infradead.org/~mchehab/kernel_docs/
> https://mchehab.fedorapeople.org/kernel_docs/
>
> Mauro Carvalho Chehab (5):
> docs-rst: convert librs book to ReST
> docs-rst: convert mtdnand book to ReST
> mtdnand.rst: Fix some typos and group the "::" with previous line
MTD maintainers did not receive the above patch. Can you Cc us the
whole series next time.
BTW, I had a look at your branch and it seems the typo you're fixing is
actually not a type. Flags are *OR-ed* (with the | operator) to form a
valid combination of flags.
> mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings
Not sure how you plan to merge these changes, but if it goes through
a single tree I'll probably need an immutable topic branch, because I
plan to change a few things in nand_base.c nand.h for the next release.
> docs-rst: convert sh book to ReST
>
> Documentation/DocBook/Makefile | 5 +-
> Documentation/DocBook/librs.tmpl | 289 --------
> Documentation/DocBook/mtdnand.tmpl | 1291 ----------------------------------
> Documentation/DocBook/sh.tmpl | 105 ---
> Documentation/conf.py | 2 +
> Documentation/core-api/index.rst | 1 +
> Documentation/core-api/librs.rst | 212 ++++++
> Documentation/driver-api/index.rst | 1 +
> Documentation/driver-api/mtdnand.rst | 1007 ++++++++++++++++++++++++++
> Documentation/index.rst | 11 +
> Documentation/sh/index.rst | 59 ++
> drivers/mtd/nand/nand_base.c | 7 +-
> include/linux/mtd/nand.h | 2 +-
> 13 files changed, 1300 insertions(+), 1692 deletions(-)
> delete mode 100644 Documentation/DocBook/librs.tmpl
> delete mode 100644 Documentation/DocBook/mtdnand.tmpl
> delete mode 100644 Documentation/DocBook/sh.tmpl
> create mode 100644 Documentation/core-api/librs.rst
> create mode 100644 Documentation/driver-api/mtdnand.rst
> create mode 100644 Documentation/sh/index.rst
>
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 0/5] Convert more books to ReST
2017-05-15 12:09 ` [PATCH 0/5] Convert more books " Boris Brezillon
@ 2017-05-15 17:15 ` Jonathan Corbet
2017-05-16 7:01 ` Boris Brezillon
2017-05-16 10:38 ` Mauro Carvalho Chehab
1 sibling, 1 reply; 10+ messages in thread
From: Jonathan Corbet @ 2017-05-15 17:15 UTC (permalink / raw)
To: Boris Brezillon
Cc: Mauro Carvalho Chehab, Linux Doc Mailing List, Rich Felker,
linux-sh, Takashi Iwai, Sebastian Andrzej Siewior,
Herton R. Krzesinski, linux-mtd, Cyrille Pitchen, Markus Heiser,
Yoshinori Sato, Richard Weinberger, Marek Vasut, sayli karnik,
Jani Nikula, Mauro Carvalho Chehab, Greg Kroah-Hartman,
linux-kernel, linux-security-module, Silvio Fricke, Brian Norris,
David Woodhouse
On Mon, 15 May 2017 14:09:12 +0200
Boris Brezillon <boris.brezillon@free-electrons.com> wrote:
> > mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings
>
> Not sure how you plan to merge these changes, but if it goes through
> a single tree I'll probably need an immutable topic branch, because I
> plan to change a few things in nand_base.c nand.h for the next release.
docs-next doesn't rebase, so there shouldn't be trouble there. But we
could also just separate this patch into two pieces. I suspect we could
live with a couple of warnings for a period during the 4.13 merge window
without too much pain...
jon
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 0/5] Convert more books to ReST
2017-05-15 17:15 ` Jonathan Corbet
@ 2017-05-16 7:01 ` Boris Brezillon
0 siblings, 0 replies; 10+ messages in thread
From: Boris Brezillon @ 2017-05-16 7:01 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Rich Felker, linux-sh, Takashi Iwai, Sebastian Andrzej Siewior,
Herton R. Krzesinski, linux-mtd, Cyrille Pitchen, Markus Heiser,
Yoshinori Sato, Richard Weinberger, Linux Doc Mailing List,
Mauro Carvalho Chehab, Marek Vasut, sayli karnik, Jani Nikula,
Mauro Carvalho Chehab, Greg Kroah-Hartman, linux-kernel,
linux-security-module, Silvio Fricke, Brian Norris,
David Woodhouse
Hi Jonathan,
On Mon, 15 May 2017 11:15:19 -0600
Jonathan Corbet <corbet@lwn.net> wrote:
> On Mon, 15 May 2017 14:09:12 +0200
> Boris Brezillon <boris.brezillon@free-electrons.com> wrote:
>
> > > mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings
> >
> > Not sure how you plan to merge these changes, but if it goes through
> > a single tree I'll probably need an immutable topic branch, because I
> > plan to change a few things in nand_base.c nand.h for the next release.
>
> docs-next doesn't rebase, so there shouldn't be trouble there. But we
> could also just separate this patch into two pieces. I suspect we could
> live with a couple of warnings for a period during the 4.13 merge window
> without too much pain...
I like this idea. This way I can take the nand_base.c/nand.h changes
through my tree and let you pick the Doc migration bits.
Thanks,
Boris
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 0/5] Convert more books to ReST
2017-05-15 12:09 ` [PATCH 0/5] Convert more books " Boris Brezillon
2017-05-15 17:15 ` Jonathan Corbet
@ 2017-05-16 10:38 ` Mauro Carvalho Chehab
1 sibling, 0 replies; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-16 10:38 UTC (permalink / raw)
To: Boris Brezillon
Cc: Linux Doc Mailing List, Rich Felker, linux-sh, Takashi Iwai,
Sebastian Andrzej Siewior, Herton R. Krzesinski, linux-mtd,
Cyrille Pitchen, Markus Heiser, Yoshinori Sato, Jonathan Corbet,
Richard Weinberger, Marek Vasut, sayli karnik, Jani Nikula,
Mauro Carvalho Chehab, Greg Kroah-Hartman, linux-kernel,
linux-security-module, Silvio Fricke, Brian Norris,
David Woodhouse
Em Mon, 15 May 2017 14:09:12 +0200
Boris Brezillon <boris.brezillon@free-electrons.com> escreveu:
> On Sat, 13 May 2017 08:10:53 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
>
> > This patch series convert the following books to ReST:
> > - librs
> > - mtdnand
> > - sh
> >
> > And it is based on my previous series of conversion patches.
> >
> > After this series, there will be just one DocBook pending conversion:
> > - lsm (Linux Security Modules)
> >
> > This book is very outdated: no changes since the Kernel moved
> > to git, in 2005 (except for a minor editorial fix in 2008).
> >
> > I took a look on the described API: it doesn't seem to be describing
> > the current security implementation.
> >
> > The best here is if someone that works with LSM to convert it to
> > ReST with:
> > $ Documentation/sphinx/tmplcvt Documentation/DocBook/lsm.tmpl lsm.rst
> >
> > And fix the document to produce something that reflects the current
> > implementation. If nobody is interested, then maybe we could just
> > drop it.
> >
> > -
> >
> > This patch series is based on my past 00/36 patch series, applied on
> > the top of docs tree (next branch).
> >
> > The full patch series is on this tree is at:
> >
> > https://git.linuxtv.org//mchehab/experimental.git/log/?h=docbook
> >
> > And the HTML output at:
> >
> > http://www.infradead.org/~mchehab/kernel_docs/
> > https://mchehab.fedorapeople.org/kernel_docs/
> >
> > Mauro Carvalho Chehab (5):
> > docs-rst: convert librs book to ReST
> > docs-rst: convert mtdnand book to ReST
> > mtdnand.rst: Fix some typos and group the "::" with previous line
>
> MTD maintainers did not receive the above patch. Can you Cc us the
> whole series next time.
Sorry. I'll add you on the whole series. It will be a big one, though,
as it will contain the other docbook conversions on it (~50+ patches).
> BTW, I had a look at your branch and it seems the typo you're fixing is
> actually not a type. Flags are *OR-ed* (with the | operator) to form a
> valid combination of flags.
Ah! Ok, I updated the patch (see enclosed). Would that be OK for you?
> > mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings
>
> Not sure how you plan to merge these changes, but if it goes through
> a single tree I'll probably need an immutable topic branch, because I
> plan to change a few things in nand_base.c nand.h for the next release.
At least the patches that touch at Documentation/* should go, IMHO,
via a single tree:
git://git.lwn.net/linux.git docs-next
As Jon mentioned, he doesn't rebase it, so you should be able to get an
immutable branch from it.
Thanks,
Mauro
---
[PATCH] mtdnand.rst: group the "::" with previous line
Group the :: with the previous paragraph, in order to make it
visually better when reading as a text file.
While here, replace:
ored (with means "Covered or adorned with ore or metal")
by:
OR-ed
To reflect its true meaning.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
diff --git a/Documentation/driver-api/mtdnand.rst b/Documentation/driver-api/mtdnand.rst
index 8723175f955e..7c19795ebb4a 100644
--- a/Documentation/driver-api/mtdnand.rst
+++ b/Documentation/driver-api/mtdnand.rst
@@ -843,10 +843,8 @@ Chip option constants
Constants for chip id table
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-These constants are defined in nand.h. They are ored together to
-describe the chip functionality.
-
-::
+These constants are defined in nand.h. They are OR-ed together to
+describe the chip functionality::
/* Buswitdh is 16 bit */
#define NAND_BUSWIDTH_16 0x00000002
@@ -867,10 +865,8 @@ describe the chip functionality.
Constants for runtime options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-These constants are defined in nand.h. They are ored together to
-describe the functionality.
-
-::
+These constants are defined in nand.h. They are OR-ed together to
+describe the functionality::
/* The hw ecc generator provides a syndrome instead a ecc value on read
* This can only work if we have the ecc bytes directly behind the
@@ -881,9 +877,7 @@ describe the functionality.
ECC selection constants
-----------------------
-Use these constants to select the ECC algorithm.
-
-::
+Use these constants to select the ECC algorithm::
/* No ECC. Usage is not recommended ! */
#define NAND_ECC_NONE 0
@@ -903,9 +897,7 @@ Hardware control related constants
----------------------------------
These constants describe the requested hardware access function when the
-boardspecific hardware control function is called
-
-::
+boardspecific hardware control function is called::
/* Select the chip by setting nCE to low */
#define NAND_CTL_SETNCE 1
@@ -929,9 +921,7 @@ Bad block table related constants
---------------------------------
These constants describe the options used for bad block table
-descriptors.
-
-::
+descriptors::
/* Options for the bad block table descriptors */
^ permalink raw reply related [flat|nested] 10+ messages in thread
end of thread, other threads:[~2017-05-16 10:39 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-05-13 11:10 [PATCH 0/5] Convert more books to ReST Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 1/5] docs-rst: convert librs book " Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 2/5] docs-rst: convert mtdnand " Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 3/5] mtdnand.rst: Fix some typos and group the "::" with previous line Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 4/5] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings Mauro Carvalho Chehab
2017-05-13 11:10 ` [PATCH 5/5] docs-rst: convert sh book to ReST Mauro Carvalho Chehab
2017-05-15 12:09 ` [PATCH 0/5] Convert more books " Boris Brezillon
2017-05-15 17:15 ` Jonathan Corbet
2017-05-16 7:01 ` Boris Brezillon
2017-05-16 10:38 ` Mauro Carvalho Chehab
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).