docs: mtd: convert to ReST

:orphan:

==============================

Memory Technology Device (MTD)

==============================

.. toctree::

   :maxdepth: 1

   intel-spi

   nand_ecc

   spi-nor

==============================

Upgrading BIOS using intel-spi

------------------------------

==============================

Many Intel CPUs like Baytrail and Braswell include SPI serial flash host

controller which is used to hold BIOS and other platform specific data.

    module parameter to modprobe).

 4) Once the board is up and running again, find the right MTD partition

    (it is named as "BIOS"):

    (it is named as "BIOS")::

	# cat /proc/mtd

	dev:    size   erasesize  name

    So here it will be /dev/mtd0 but it may vary.

 5) Make backup of the existing image first:

 5) Make backup of the existing image first::

	# dd if=/dev/mtd0ro of=bios.bak

	16384+0 records in

	16384+0 records out

	8388608 bytes (8.4 MB) copied, 10.0269 s, 837 kB/s

 6) Verify the backup

 6) Verify the backup:

	# sha1sum /dev/mtd0ro bios.bak

	fdbb011920572ca6c991377c4b418a0502668b73  /dev/mtd0ro

    The SHA1 sums must match. Otherwise do not continue any further!

 7) Erase the SPI serial flash. After this step, do not reboot the

    board! Otherwise it will not start anymore.

    board! Otherwise it will not start anymore::

	# flash_erase /dev/mtd0 0 0

	Erasing 4 Kibyte @ 7ff000 -- 100 % complete

    # dd if=MNW2MAX1.X64.0092.R01.1605221712.bin of=/dev/mtd0

 9) Verify that the new content of the SPI serial flash matches the new

    BIOS image:

    BIOS image::

	# sha1sum /dev/mtd0ro MNW2MAX1.X64.0092.R01.1605221712.bin

	9b4df9e4be2057fceec3a5529ec3d950836c87a2  /dev/mtd0ro

References

----------

[1] https://firmware.intel.com/sites/default/files/MinnowBoard.MAX_.X64.92.R01.zip

[1] https://firmware.intel.com/sites/default/files/MinnowBoard%2EMAX_%2EX64%2E92%2ER01%2Ezip

[2] http://www.linux-mtd.infradead.org/

==========================

NAND Error-correction Code

==========================

Introduction

============

Back to ecc.

Let's give a small figure:

=========  ==== ==== ==== ==== ==== ==== ==== ====   === === === === ====

byte   0:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp0 rp2 rp4 ... rp14

byte   1:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp1 rp2 rp4 ... rp14

byte   2:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp0 rp3 rp4 ... rp14

byte   3:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp1 rp3 rp4 ... rp14

byte   4:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp0 rp2 rp5 ... rp14

....

...

byte 254:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp0 rp3 rp5 ... rp15

byte 255:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp1 rp3 rp5 ... rp15

           cp1  cp0  cp1  cp0  cp1  cp0  cp1  cp0

           cp3  cp3  cp2  cp2  cp3  cp3  cp2  cp2

           cp5  cp5  cp5  cp5  cp4  cp4  cp4  cp4

=========  ==== ==== ==== ==== ==== ==== ==== ====   === === === === ====

This figure represents a sector of 256 bytes.

cp is my abbreviation for column parity, rp for row parity.

Let's start to explain column parity.

cp0 is the parity that belongs to all bit0, bit2, bit4, bit6.

- cp0 is the parity that belongs to all bit0, bit2, bit4, bit6.

  so the sum of all bit0, bit2, bit4 and bit6 values + cp0 itself is even.

Similarly cp1 is the sum of all bit1, bit3, bit5 and bit7.

cp2 is the parity over bit0, bit1, bit4 and bit5

cp3 is the parity over bit2, bit3, bit6 and bit7.

cp4 is the parity over bit0, bit1, bit2 and bit3.

cp5 is the parity over bit4, bit5, bit6 and bit7.

- cp2 is the parity over bit0, bit1, bit4 and bit5

- cp3 is the parity over bit2, bit3, bit6 and bit7.

- cp4 is the parity over bit0, bit1, bit2 and bit3.

- cp5 is the parity over bit4, bit5, bit6 and bit7.

Note that each of cp0 .. cp5 is exactly one bit.

Row parity actually works almost the same.

rp0 is the parity of all even bytes (0, 2, 4, 6, ... 252, 254)

rp1 is the parity of all odd bytes (1, 3, 5, 7, ..., 253, 255)

rp2 is the parity of all bytes 0, 1, 4, 5, 8, 9, ...

- rp0 is the parity of all even bytes (0, 2, 4, 6, ... 252, 254)

- rp1 is the parity of all odd bytes (1, 3, 5, 7, ..., 253, 255)

- rp2 is the parity of all bytes 0, 1, 4, 5, 8, 9, ...

  (so handle two bytes, then skip 2 bytes).

rp3 is covers the half rp2 does not cover (bytes 2, 3, 6, 7, 10, 11, ...)

for rp4 the rule is cover 4 bytes, skip 4 bytes, cover 4 bytes, skip 4 etc.

- rp3 is covers the half rp2 does not cover (bytes 2, 3, 6, 7, 10, 11, ...)

- for rp4 the rule is cover 4 bytes, skip 4 bytes, cover 4 bytes, skip 4 etc.

  so rp4 calculates parity over bytes 0, 1, 2, 3, 8, 9, 10, 11, 16, ...)

and rp5 covers the other half, so bytes 4, 5, 6, 7, 12, 13, 14, 15, 20, ..

- and rp5 covers the other half, so bytes 4, 5, 6, 7, 12, 13, 14, 15, 20, ..

The story now becomes quite boring. I guess you get the idea.

rp6 covers 8 bytes then skips 8 etc

rp7 skips 8 bytes then covers 8 etc

rp8 covers 16 bytes then skips 16 etc

rp9 skips 16 bytes then covers 16 etc

rp10 covers 32 bytes then skips 32 etc

rp11 skips 32 bytes then covers 32 etc

rp12 covers 64 bytes then skips 64 etc

rp13 skips 64 bytes then covers 64 etc

rp14 covers 128 bytes then skips 128

rp15 skips 128 bytes then covers 128

- rp6 covers 8 bytes then skips 8 etc

- rp7 skips 8 bytes then covers 8 etc

- rp8 covers 16 bytes then skips 16 etc

- rp9 skips 16 bytes then covers 16 etc

- rp10 covers 32 bytes then skips 32 etc

- rp11 skips 32 bytes then covers 32 etc

- rp12 covers 64 bytes then skips 64 etc

- rp13 skips 64 bytes then covers 64 etc

- rp14 covers 128 bytes then skips 128

- rp15 skips 128 bytes then covers 128

In the end the parity bits are grouped together in three bytes as

follows:

=====  ===== ===== ===== ===== ===== ===== ===== =====

ECC    Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0

=====  ===== ===== ===== ===== ===== ===== ===== =====

ECC 0   rp07  rp06  rp05  rp04  rp03  rp02  rp01  rp00

ECC 1   rp15  rp14  rp13  rp12  rp11  rp10  rp09  rp08

ECC 2   cp5   cp4   cp3   cp2   cp1   cp0      1     1

=====  ===== ===== ===== ===== ===== ===== ===== =====

I detected after writing this that ST application note AN1823

(http://www.st.com/stonline/) gives a much

nicer picture.(but they use line parity as term where I use row parity)

Oh well, I'm graphically challenged, so suffer with me for a moment :-)

And I could not reuse the ST picture anyway for copyright reasons.

=========

Implementing the parity calculation is pretty simple.

In C pseudocode:

In C pseudocode::

  for (i = 0; i < 256; i++)

  {

    if (i & 0x01)

Attempt 1

=========

::

  const char parity[256] = {

      0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,

      1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,

Attempt 2

=========

::

  extern const char parity[256];

  void ecc2(const unsigned char *buf, unsigned char *code)

Attempt 3

=========

Odd replaced:

Odd replaced::

          if (i & 0x01) rp5 ^= cur; else rp4 ^= cur;

          if (i & 0x02) rp7 ^= cur; else rp6 ^= cur;

          if (i & 0x04) rp9 ^= cur; else rp8 ^= cur;

          if (i & 0x08) rp11 ^= cur; else rp10 ^= cur;

          if (i & 0x10) rp13 ^= cur; else rp12 ^= cur;

          if (i & 0x20) rp15 ^= cur; else rp14 ^= cur;

with

with::

          if (i & 0x01) rp5 ^= cur;

          if (i & 0x02) rp7 ^= cur;

          if (i & 0x04) rp9 ^= cur;

          if (i & 0x10) rp13 ^= cur;

          if (i & 0x20) rp15 ^= cur;

        and outside the loop added:

and outside the loop added::

          rp4  = par ^ rp5;

          rp6  = par ^ rp7;

          rp8  = par ^ rp9;

=========

Unrolled the loop 1, 2, 3 and 4 times.

For 4 the code starts with:

For 4 the code starts with::

    for (i = 0; i < 4; i++)

    {

==========

Unrolling once gains about 15%

Unrolling twice keeps the gain at about 15%

Unrolling three times gives a gain of 30% compared to attempt 2.

Unrolling four times gives a marginal improvement compared to unrolling

three times.

Effectively so all odd digit rp assignments in the loop were removed.

This included the else clause of the if statements.

Of course after the loop we need to correct things by adding code like:

Of course after the loop we need to correct things by adding code like::

    rp5 = par ^ rp4;

Also the initial assignments (rp5 = 0; etc) could be removed.

Along the line I also removed the initialisation of rp0/1/2/3.

Attempt 6

=========

THe code within the for loop was changed to:

THe code within the for loop was changed to::

    for (i = 0; i < 4; i++)

    {

definitely seemed to be the jackpot!

There is a little bit more room for improvement though. There are three

places with statements:

places with statements::

	rp4 ^= cur; rp6 ^= cur;

It seems more efficient to also maintain a variable rp4_6 in the while

loop; This eliminates 3 statements per loop. Of course after the loop we

need to correct by adding:

need to correct by adding::

	rp4 ^= rp4_6;

	rp6 ^= rp4_6

Furthermore there are 4 sequential assignments to rp8. This can be

encoded slightly more efficiently by saving tmppar before those 4 lines

and later do rp8 = rp8 ^ tmppar ^ notrp8;

Attempt 7

=========

The new code now looks like:

The new code now looks like::

    for (i = 0; i < 4; i++)

    {

further there is still room to optimize the generation of the ecc codes.

We can simply calculate the total parity. If this is 0 then rp4 = rp5

etc. If the parity is 1, then rp4 = !rp5;

But if rp4 = rp5 we do not need rp5 etc. We can just write the even bits

in the result byte and then do something like

in the result byte and then do something like::

    code[0] |= (code[0] << 1);

Lets test this.

kind of other things, like having dedicated parity arrays to avoid the

shift after parity[rp7] << 7; No gain.

Change the lookup using the parity array by using shift operators (e.g.

replace parity[rp7] << 7 with:

replace parity[rp7] << 7 with::

	rp7 ^= (rp7 << 4);

	rp7 ^= (rp7 << 2);

	rp7 ^= (rp7 << 1);

	rp7 &= 0x80;

No gain.

The only marginal change was inverting the parity bits, so we can remove

For correcting errors I again used the ST application note as a starter,

but I also peeked at the existing code.

The algorithm itself is pretty straightforward. Just xor the given and

the calculated ecc. If all bytes are 0 there is no problem. If 11 bits

are 1 we have one correctable bit error. If there is 1 bit 1, we have an

error in the given ecc code.

It proved to be fastest to do some table lookups. Performance gain

introduced by this is about a factor 2 on my system when a repair had to

be done, and 1% or so if no repair had to be done.

Code size increased from 330 bytes to 686 bytes for this function.

(gcc 4.2, -O3)

The gain when calculating the ecc is tremendous. Om my development hardware

a speedup of a factor of 18 for ecc calculation was achieved. On a test on an

embedded system with a MIPS core a factor 7 was obtained.

On a test with a Linksys NSLU2 (ARMv5TE processor) the speedup was a factor

5 (big endian mode, gcc 4.1.2, -O3)

For correction not much gain could be obtained (as bitflips are rare). Then

again there are also much less cycles spent there.

this is very tricky (at least for intel hw).

Author: Frans Meulenbroeks

Copyright (C) 2008 Koninklijke Philips Electronics NV.

=================

SPI NOR framework

               ============================================

=================

Part I - Why do we need this framework?

---------------------------------------

With this new layer, the SPI NOR controller driver does not depend on the

m25p80 code anymore.

   Before this framework, the layer is like:

Before this framework, the layer is like::

                   MTD

         ------------------------

 *   Thomas Gleixner (tglx@linutronix.de)

 *

 * Information on how this algorithm works and how it was developed

 * can be found in Documentation/mtd/nand_ecc.txt

 * can be found in Documentation/mtd/nand_ecc.rst

 */

#include <linux/types.h>