Re: [PATCH 1/2] mtd: rawnand: marvell: document a bit more the driver

[Boris Brezillon <boris.brezillon@bootlin.com>]

On Sat, 14 Jul 2018 15:54:27 +0200
Miquel Raynal <miquel.raynal@bootlin.com> wrote:

> A stale document about the old pxa3cc_nand.c driver is available in
> Documentation/mtd/nand/. Rewrite the parts that explain the IP itself
> and some non-trivial choices made in the driver directly in
> marvell_nand.c to then be able to remove this file.
> 
> Signed-off-by: Miquel Raynal <miquel.raynal@bootlin.com>
> ---
>  drivers/mtd/nand/raw/marvell_nand.c | 31 +++++++++++++++++++++++++++++++
>  1 file changed, 31 insertions(+)
> 
> diff --git a/drivers/mtd/nand/raw/marvell_nand.c b/drivers/mtd/nand/raw/marvell_nand.c
> index ba6889bbe802..a50ea47baa4f 100644
> --- a/drivers/mtd/nand/raw/marvell_nand.c
> +++ b/drivers/mtd/nand/raw/marvell_nand.c
> @@ -5,6 +5,37 @@
>   * Copyright (C) 2017 Marvell
>   * Author: Miquel RAYNAL <miquel.raynal@free-electrons.com>
>   *
> + *
> + * This NAND controller driver handles two versions of the hardware,
> + * one is called NFCv1 and is available on PXA SoCs and the other is
> + * called NFCv2 and is available on almost all the Armada SoCs.
> + *
> + * The main differences are that the NFCv1 has DMA support and only
> + * has Hamming ECC capabilities, while NFCv2 does not support DMA but
> + * has hardware BCH support.
> + *
> + * The internal ECC operations are depicted in details in Marvell
> + * AN-379.
> + *
> + * The controller has certain limitations that are handled by the
> + * driver:
> + *   - It can only read 2k at a time. To overcome this limitation, the
> + *     driver makes use of 'naked' operations.
> + *   - The ECC strength in BCH mode cannot be tuned easily. It is a
> + *     fixed 16 bytes. What can be tuned is the area on which this

		   ^ bits

> + *     correction occurs. Hence, using 2048B ECC chunks makes the
> + *     strength to be 4b/512B.

I'd mention that max ECC step size is 2k here. So you can actually
choose something between 512 and 2k based on the chip requirements.

> + *   - The controller will always treat data bytes, spare bytes and

Some people call OOB bytes, spare bytes, what you refer to here are
free OOB bytes. I think it's worth clarifying that somewhere.

> + *     ECC bytes in that order, no matter the real factory layout
> + *     (which is usually all data then all OOB bytes). But depending
> + *     on the chosen layout, the areas of each section may vary or be
> + *     absent. The same data/spare/ecc layout is repeated until the
> + *     next chunk were each section may be different again. The
> + *     marvell_nfc_layouts array below contains the currently
> + *     supported layouts.
> + *   - Because of these weird layouts, the Bad Block Markers can be
> + *     located in data. In this case, the NAND_BBT_NO_OOB_BBM option
> + *     must be set.
>   */
>  
>  #include <linux/module.h>