xref: /linux/Documentation/driver-api/mtd/spi-nor.rst (revision bba2c3615bd6cfee7456d1130f2e6b01b3f4e9ba) 
1=================
2SPI NOR framework
3=================
4
5How to propose a new flash addition
6-----------------------------------
7
8Most SPI NOR flashes comply with the JEDEC JESD216
9Serial Flash Discoverable Parameter (SFDP) standard. SFDP describes
10the functional and feature capabilities of serial flash devices in a
11standard set of internal read-only parameter tables.
12
13The SPI NOR driver queries the SFDP tables in order to determine the
14flash's parameters and settings. If the flash defines the SFDP tables
15it's likely that you won't need a flash entry at all, and instead
16rely on the generic flash driver which probes the flash solely based
17on its SFDP data. All one has to do is to specify the "jedec,spi-nor"
18compatible in the device tree.
19
20There are cases however where you need to define an explicit flash
21entry. This typically happens when the flash has settings or support
22that is not covered by the SFDP tables (e.g. Block Protection), or
23when the flash contains mangled SFDP data. If the later, one needs
24to implement the ``spi_nor_fixups`` hooks in order to amend the SFDP
25parameters with the correct values.
26
27Minimum testing requirements
28-----------------------------
29
30Do all the tests from below and paste them in the commit's comments
31section, after the ``---`` marker.
32
331) Specify the controller that you used to test the flash and specify
34   the frequency at which the flash was operated, e.g.::
35
36    This flash is populated on the X board and was tested at Y
37    frequency using the Z (put compatible) SPI controller.
38
392) Dump the sysfs entries and print the md5/sha1/sha256 SFDP checksum::
40
41    root@1:~# cat /sys/bus/spi/devices/spi0.0/spi-nor/partname
42    sst26vf064b
43    root@1:~# cat /sys/bus/spi/devices/spi0.0/spi-nor/jedec_id
44    bf2643
45    root@1:~# cat /sys/bus/spi/devices/spi0.0/spi-nor/manufacturer
46    sst
47    root@1:~# xxd -p /sys/bus/spi/devices/spi0.0/spi-nor/sfdp
48    53464450060102ff00060110300000ff81000106000100ffbf0001180002
49    0001fffffffffffffffffffffffffffffffffd20f1ffffffff0344eb086b
50    083b80bbfeffffffffff00ffffff440b0c200dd80fd810d820914824806f
51    1d81ed0f773830b030b0f7ffffff29c25cfff030c080ffffffffffffffff
52    ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
53    ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
54    ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
55    ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
56    ffffffffffffffffffffffffffffffffff0004fff37f0000f57f0000f9ff
57    7d00f57f0000f37f0000ffffffffffffffffffffffffffffffffffffffff
58    ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
59    ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
60    ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
61    ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
62    ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
63    ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
64    ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
65    ffffbf2643ffb95ffdff30f260f332ff0a122346ff0f19320f1919ffffff
66    ffffffff00669938ff05013506040232b03072428de89888a585c09faf5a
67    ffff06ec060c0003080bffffffffff07ffff0202ff060300fdfd040700fc
68    0300fefe0202070e
69    root@1:~# sha256sum /sys/bus/spi/devices/spi0.0/spi-nor/sfdp
70    428f34d0461876f189ac97f93e68a05fa6428c6650b3b7baf736a921e5898ed1  /sys/bus/spi/devices/spi0.0/spi-nor/sfdp
71
72   Please dump the SFDP tables using ``xxd -p``. It enables us to do
73   the reverse operation and convert the hexdump to binary with
74   ``xxd -rp``. Dumping the SFDP data with ``hexdump -Cv`` is accepted,
75   but less desirable.
76
773) Dump debugfs data::
78
79    root@1:~# cat /sys/kernel/debug/spi-nor/spi0.0/capabilities
80    Supported read modes by the flash
81     1S-1S-1S
82      opcode		0x03
83      mode cycles	0
84      dummy cycles	0
85     1S-1S-1S (fast read)
86      opcode		0x0b
87      mode cycles	0
88      dummy cycles	8
89     1S-1S-2S
90      opcode		0x3b
91      mode cycles	0
92      dummy cycles	8
93     1S-2S-2S
94      opcode		0xbb
95      mode cycles	4
96      dummy cycles	0
97     1S-1S-4S
98      opcode		0x6b
99      mode cycles	0
100      dummy cycles	8
101     1S-4S-4S
102      opcode		0xeb
103      mode cycles	2
104      dummy cycles	4
105     4S-4S-4S
106      opcode		0x0b
107      mode cycles	2
108      dummy cycles	4
109
110    Supported page program modes by the flash
111     1S-1S-1S
112      opcode	0x02
113
114    root@1:~# cat /sys/kernel/debug/spi-nor/spi0.0/params
115    name		sst26vf064b
116    id			bf 26 43 bf 26 43
117    size		8.00 MiB
118    write size		1
119    page size		256
120    address nbytes	3
121    flags		HAS_LOCK | HAS_16BIT_SR | SOFT_RESET | SWP_IS_VOLATILE
122
123    opcodes
124     read		0xeb
125      dummy cycles	6
126     erase		0x20
127     program		0x02
128     8D extension	none
129
130    protocols
131     read		1S-4S-4S
132     write		1S-1S-1S
133     register		1S-1S-1S
134
135    erase commands
136     20 (4.00 KiB) [0]
137     d8 (8.00 KiB) [1]
138     d8 (32.0 KiB) [2]
139     d8 (64.0 KiB) [3]
140     c7 (8.00 MiB)
141
142    sector map
143     region (in hex)   | erase mask | flags
144     ------------------+------------+----------
145     00000000-00007fff |     [01  ] |
146     00008000-0000ffff |     [0 2 ] |
147     00010000-007effff |     [0  3] |
148     007f0000-007f7fff |     [0 2 ] |
149     007f8000-007fffff |     [01  ] |
150
1514) Use `mtd-utils <https://git.infradead.org/mtd-utils.git>`__
152   and verify that erase, read and page program operations work fine::
153
154    root@1:~# dd if=/dev/urandom of=./spi_test bs=1M count=2
155    2+0 records in
156    2+0 records out
157    2097152 bytes (2.1 MB, 2.0 MiB) copied, 0.848566 s, 2.5 MB/s
158
159    root@1:~# mtd_debug erase /dev/mtd0 0 2097152
160    Erased 2097152 bytes from address 0x00000000 in flash
161
162    root@1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read
163    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
164
165    root@1:~# hexdump spi_read
166    0000000 ffff ffff ffff ffff ffff ffff ffff ffff
167    *
168    0200000
169
170    root@1:~# sha256sum spi_read
171    4bda3a28f4ffe603c0ec1258c0034d65a1a0d35ab7bd523a834608adabf03cc5  spi_read
172
173    root@1:~# mtd_debug write /dev/mtd0 0 2097152 spi_test
174    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
175
176    root@1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read
177    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
178
179    root@1:~# sha256sum spi*
180    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_read
181    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_test
182
183   If the flash comes erased by default and the previous erase was ignored,
184   we won't catch it, thus test the erase again::
185
186    root@1:~# mtd_debug erase /dev/mtd0 0 2097152
187    Erased 2097152 bytes from address 0x00000000 in flash
188
189    root@1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read
190    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
191
192    root@1:~# sha256sum spi*
193    4bda3a28f4ffe603c0ec1258c0034d65a1a0d35ab7bd523a834608adabf03cc5  spi_read
194    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_test
195
196   Dump some other relevant data::
197
198    root@1:~# mtd_debug info /dev/mtd0
199    mtd.type = MTD_NORFLASH
200    mtd.flags = MTD_CAP_NORFLASH
201    mtd.size = 8388608 (8M)
202    mtd.erasesize = 4096 (4K)
203    mtd.writesize = 1
204    mtd.oobsize = 0
205    regions = 0
206
2075) If your flash supports locking, please go through the following test
208   procedure to make sure it correctly behaves. The below example
209   expects the typical situation where eraseblocks and lock sectors have
210   the same size. In case you enabled MTD_SPI_NOR_USE_4K_SECTORS, you
211   must adapt `bs` accordingly.
212
213   Warning: These tests may hard lock your device! Make sure:
214
215   - The device is not hard locked already (#WP strapped to low and
216     SR_SRWD bit set)
217   - If you have a WPn pin, you may want to set `no-wp` in your DT for
218     the time of the test, to only make use of software protection.
219     Otherwise, clearing the locking state depends on the WPn
220     signal and if it is tied to low, the flash will be permanently
221     locked.
222
223   Test full chip locking and make sure expectations, the MEMISLOCKED
224   ioctl output, the debugfs output and experimental results are all
225   aligned::
226
227    root@1:~# alias show_sectors='grep -A4 "locked sectors" /sys/kernel/debug/spi-nor/spi0.0/params'
228    root@1:~# flash_lock -u /dev/mtd0
229    root@1:~# flash_lock -i /dev/mtd0
230    Device: /dev/mtd0
231    Start: 0
232    Len: 0x4000000
233    Lock status: unlocked
234    Return code: 0
235    root@1:~# mtd_debug erase /dev/mtd0 0 2097152
236    Erased 2097152 bytes from address 0x00000000 in flash
237    root@1:~# mtd_debug write /dev/mtd0 0 2097152 spi_test
238    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
239    root@1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read
240    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
241    root@1:~# sha256sum spi*
242    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_read
243    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_test
244    root@1:~# show_sectors
245    software locked sectors
246     region (in hex)   | status   | #sectors
247     ------------------+----------+---------
248     00000000-03ffffff | unlocked | 1024
249
250    root@1:~# flash_lock -l /dev/mtd0
251    root@1:~# flash_lock -i /dev/mtd0
252    Device: /dev/mtd0
253    Start: 0
254    Len: 0x4000000
255    Lock status: locked
256    Return code: 1
257    root@1:~# mtd_debug erase /dev/mtd0 0 2097152
258    Erased 2097152 bytes from address 0x00000000 in flash
259    root@1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read
260    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
261    root@1:~# sha256sum spi*
262    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_read
263    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_test
264    root@1:~# dd if=/dev/urandom of=./spi_test2 bs=1M count=2
265    2+0 records in
266    2+0 records out
267    root@1:~# mtd_debug write /dev/mtd0 0 2097152 spi_test2
268    Copied 2097152 bytes from spi_test2 to address 0x00000000 in flash
269    root@1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read2
270    Copied 2097152 bytes from address 0x00000000 in flash to spi_read2
271    root@1:~# sha256sum spi*
272    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_read
273    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_read2
274    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_test
275    bea9334df51c620440f86751cba0799214a016329f1736f9456d40cf40efdc88  spi_test2
276    root@1:~# show_sectors
277    software locked sectors
278     region (in hex)   | status   | #sectors
279     ------------------+----------+---------
280     00000000-03ffffff |   locked | 1024
281    root@1:~# flash_lock -u /dev/mtd0
282
283   Once we trust the debugfs output we can use it to test various
284   situations. Check top locking/unlocking (end of the device)::
285
286    root@1:~# size=$(cat /sys/class/mtd/mtd0/size)
287    root@1:~# bs=$(cat /sys/class/mtd/mtd0/erasesize)
288    root@1:~# nsectors=$(grep unlocked /sys/kernel/debug/spi-nor/spi0.0/params | sed -e 's/.*unlocked | //')
289    root@1:~# ss=$(($size / $nsectors))
290    root@1:~# bps=$(($ss / $bs))
291
292    root@1:~# flash_lock -u /dev/mtd0
293    root@1:~# flash_lock -l /dev/mtd0 $(($size - (2 * $ss))) $((2 * $bps)) # last two
294    root@1:~# show_sectors
295    software locked sectors
296     region (in hex)   | status   | #sectors
297     ------------------+----------+---------
298     00000000-03fdffff | unlocked | 1022
299     03fe0000-03ffffff |   locked | 2
300    root@1:~# flash_lock -u /dev/mtd0 $(($size - (2 * $ss))) $((1 * $bps)) # last one
301    root@1:~# show_sectors
302    software locked sectors
303     region (in hex)   | status   | #sectors
304     ------------------+----------+---------
305     00000000-03feffff | unlocked | 1023
306     03ff0000-03ffffff |   locked | 1
307
308   If the flash features 4 block protection bits (BP), we can protect
309   more than 4MB (typically 128 64kiB-blocks or more), with a finer
310   grain than locking the entire device::
311
312    root@1:~# flash_lock -u /dev/mtd0
313    root@1:~# flash_lock -l /dev/mtd0 $(($size - (2**7 * $ss))) $((2**7 * $bps))
314    root@1:~# show_sectors
315    software locked sectors
316     region (in hex)   | status   | #sectors
317     ------------------+----------+---------
318     00000000-037fffff | unlocked | 896
319     03800000-03ffffff |   locked | 128
320
321   If the flash features a Top/Bottom (TB) bit, we can protect the
322   beginning of the flash::
323
324    root@1:~# flash_lock -u /dev/mtd0
325    root@1:~# flash_lock -l /dev/mtd0 0 $((2 * $bps)) # first two
326    root@1:~# show_sectors
327    software locked sectors
328     region (in hex)   | status   | #sectors
329     ------------------+----------+---------
330     00000000-0001ffff |   locked | 2
331     00020000-03ffffff | unlocked | 1022
332    root@1:~# flash_lock -u /dev/mtd0 $ss $((1 * $bps)) # first one
333    root@1:~# show_sectors
334    software locked sectors
335     region (in hex)   | status   | #sectors
336     ------------------+----------+---------
337     00000000-0000ffff |   locked | 1
338     00010000-03ffffff | unlocked | 1023
339
340   If the flash features a Complement (CMP) bit, we can protect with
341   more granularity above half of the capacity. Let's lock all but one
342   block, then unlock one more block::
343
344    root@1:~# all_but_one=$((($size / $bs) - ($ss / $bs)))
345
346    root@1:~# flash_lock -u /dev/mtd0
347    root@1:~# flash_lock -l /dev/mtd0 $ss $all_but_one # all but the first
348    root@1:~# show_sectors
349    software locked sectors
350     region (in hex)   | status   | #sectors
351     ------------------+----------+---------
352     00000000-0000ffff | unlocked | 1
353     00010000-03ffffff |   locked | 1023
354    root@1:~# flash_lock -u /dev/mtd0 $ss $(($ss / $bs)) # all but the two first
355    root@1:~# show_sectors
356    software locked sectors
357     region (in hex)   | status   | #sectors
358     ------------------+----------+---------
359     00000000-0001ffff | unlocked | 2
360     00020000-03ffffff |   locked | 1022
361    root@1:~# flash_lock -u /dev/mtd0
362    root@1:~# flash_lock -l /dev/mtd0 0 $all_but_one # same from the other side
363    root@1:~# show_sectors
364    software locked sectors
365     region (in hex)   | status   | #sectors
366     ------------------+----------+---------
367     00000000-03feffff |   locked | 1023
368     03ff0000-03ffffff | unlocked | 1
369    root@1:~# flash_lock -u /dev/mtd0 $(($size - (2 * $ss))) $(($ss / $bs)) # all but two
370    root@1:~# show_sectors
371    software locked sectors
372     region (in hex)   | status   | #sectors
373     ------------------+----------+---------
374     00000000-03fdffff |   locked | 1022
375     03fe0000-03ffffff | unlocked | 2
376