Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1640876 > unrolled thread

[PATCH 0/5] Convert more books to ReST

Started byMauro Carvalho Chehab <mchehab@s-opensource.com>
First post2017-05-13 13:20 +0200
Last post2017-05-16 12:40 +0200
Articles 9 — 3 participants

Back to article view | Back to linux.kernel

Contents

  [PATCH 0/5] Convert more books to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-13 13:20 +0200
    [PATCH 4/5] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-13 13:20 +0200
    [PATCH 1/5] docs-rst: convert librs book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-13 13:20 +0200
    [PATCH 5/5] docs-rst: convert sh book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-13 13:20 +0200
    [PATCH 3/5] mtdnand.rst: Fix some typos and group the "::" with previous line Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-13 13:20 +0200
    Re: [PATCH 0/5] Convert more books to ReST Boris Brezillon <boris.brezillon@free-electrons.com> - 2017-05-15 14:10 +0200
      Re: [PATCH 0/5] Convert more books to ReST Jonathan Corbet <corbet@lwn.net> - 2017-05-15 19:20 +0200
        Re: [PATCH 0/5] Convert more books to ReST Boris Brezillon <boris.brezillon@free-electrons.com> - 2017-05-16 09:10 +0200
      Re: [PATCH 0/5] Convert more books to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 12:40 +0200

#1640876 — [PATCH 0/5] Convert more books to ReST

FromMauro Carvalho Chehab <mchehab@s-opensource.com>
Date2017-05-13 13:20 +0200
Subject[PATCH 0/5] Convert more books to ReST
Message-ID<tGDfz-2Vb-3@gated-at.bofh.it>
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

[toc] | [next] | [standalone]

#1640877 — [PATCH 4/5] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings

FromMauro Carvalho Chehab <mchehab@s-opensource.com>
Date2017-05-13 13:20 +0200
Subject[PATCH 4/5] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings
Message-ID<tGDfA-2Vb-5@gated-at.bofh.it>
In reply to#1640876
./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

[toc] | [prev] | [next] | [standalone]

#1640878 — [PATCH 1/5] docs-rst: convert librs book to ReST

FromMauro Carvalho Chehab <mchehab@s-opensource.com>
Date2017-05-13 13:20 +0200
Subject[PATCH 1/5] docs-rst: convert librs book to ReST
Message-ID<tGDfA-2Vb-9@gated-at.bofh.it>
In reply to#1640876
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 &lt; 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

[toc] | [prev] | [next] | [standalone]

#1640879 — [PATCH 5/5] docs-rst: convert sh book to ReST

FromMauro Carvalho Chehab <mchehab@s-opensource.com>
Date2017-05-13 13:20 +0200
Subject[PATCH 5/5] docs-rst: convert sh book to ReST
Message-ID<tGDfA-2Vb-11@gated-at.bofh.it>
In reply to#1640876
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

[toc] | [prev] | [next] | [standalone]

#1640880 — [PATCH 3/5] mtdnand.rst: Fix some typos and group the "::" with previous line

FromMauro Carvalho Chehab <mchehab@s-opensource.com>
Date2017-05-13 13:20 +0200
Subject[PATCH 3/5] mtdnand.rst: Fix some typos and group the "::" with previous line
Message-ID<tGDfA-2Vb-15@gated-at.bofh.it>
In reply to#1640876
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

[toc] | [prev] | [next] | [standalone]

#1641593

FromBoris Brezillon <boris.brezillon@free-electrons.com>
Date2017-05-15 14:10 +0200
Message-ID<tHmZ4-82O-15@gated-at.bofh.it>
In reply to#1640876
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
>

[toc] | [prev] | [next] | [standalone]

#1641900

FromJonathan Corbet <corbet@lwn.net>
Date2017-05-15 19:20 +0200
Message-ID<tHrP4-2Cq-19@gated-at.bofh.it>
In reply to#1641593
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

[toc] | [prev] | [next] | [standalone]

#1642258

FromBoris Brezillon <boris.brezillon@free-electrons.com>
Date2017-05-16 09:10 +0200
Message-ID<tHEMi-2u3-7@gated-at.bofh.it>
In reply to#1641900
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

[toc] | [prev] | [next] | [standalone]

#1642397

FromMauro Carvalho Chehab <mchehab@s-opensource.com>
Date2017-05-16 12:40 +0200
Message-ID<tHI3v-4o0-1@gated-at.bofh.it>
In reply to#1641593
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 */

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web