1 ================= 1 =================
2 SPI NOR framework 2 SPI NOR framework
3 ================= 3 =================
4 4
5 How to propose a new flash addition 5 How to propose a new flash addition
6 ----------------------------------- 6 -----------------------------------
7 7
8 Most SPI NOR flashes comply with the JEDEC JES 8 Most SPI NOR flashes comply with the JEDEC JESD216
9 Serial Flash Discoverable Parameter (SFDP) sta 9 Serial Flash Discoverable Parameter (SFDP) standard. SFDP describes
10 the functional and feature capabilities of ser 10 the functional and feature capabilities of serial flash devices in a
11 standard set of internal read-only parameter t 11 standard set of internal read-only parameter tables.
12 12
13 The SPI NOR driver queries the SFDP tables in 13 The SPI NOR driver queries the SFDP tables in order to determine the
14 flash's parameters and settings. If the flash 14 flash's parameters and settings. If the flash defines the SFDP tables
15 it's likely that you won't need a flash entry 15 it's likely that you won't need a flash entry at all, and instead
16 rely on the generic flash driver which probes 16 rely on the generic flash driver which probes the flash solely based
17 on its SFDP data. All one has to do is to spec 17 on its SFDP data. All one has to do is to specify the "jedec,spi-nor"
18 compatible in the device tree. 18 compatible in the device tree.
19 19
20 There are cases however where you need to defi 20 There are cases however where you need to define an explicit flash
21 entry. This typically happens when the flash h 21 entry. This typically happens when the flash has settings or support
22 that is not covered by the SFDP tables (e.g. B 22 that is not covered by the SFDP tables (e.g. Block Protection), or
23 when the flash contains mangled SFDP data. If 23 when the flash contains mangled SFDP data. If the later, one needs
24 to implement the ``spi_nor_fixups`` hooks in o 24 to implement the ``spi_nor_fixups`` hooks in order to amend the SFDP
25 parameters with the correct values. 25 parameters with the correct values.
26 26
27 Minimum testing requirements 27 Minimum testing requirements
28 ----------------------------- 28 -----------------------------
29 29
30 Do all the tests from below and paste them in 30 Do all the tests from below and paste them in the commit's comments
31 section, after the ``---`` marker. 31 section, after the ``---`` marker.
32 32
33 1) Specify the controller that you used to tes 33 1) Specify the controller that you used to test the flash and specify
34 the frequency at which the flash was operat 34 the frequency at which the flash was operated, e.g.::
35 35
36 This flash is populated on the X board and 36 This flash is populated on the X board and was tested at Y
37 frequency using the Z (put compatible) SPI 37 frequency using the Z (put compatible) SPI controller.
38 38
39 2) Dump the sysfs entries and print the md5/sh 39 2) Dump the sysfs entries and print the md5/sha1/sha256 SFDP checksum::
40 40
41 root@1:~# cat /sys/bus/spi/devices/spi0.0/ 41 root@1:~# cat /sys/bus/spi/devices/spi0.0/spi-nor/partname
42 sst26vf064b 42 sst26vf064b
43 root@1:~# cat /sys/bus/spi/devices/spi0.0/ 43 root@1:~# cat /sys/bus/spi/devices/spi0.0/spi-nor/jedec_id
44 bf2643 44 bf2643
45 root@1:~# cat /sys/bus/spi/devices/spi0.0/ 45 root@1:~# cat /sys/bus/spi/devices/spi0.0/spi-nor/manufacturer
46 sst 46 sst
47 root@1:~# xxd -p /sys/bus/spi/devices/spi0 47 root@1:~# xxd -p /sys/bus/spi/devices/spi0.0/spi-nor/sfdp
48 53464450060102ff00060110300000ff8100010600 48 53464450060102ff00060110300000ff81000106000100ffbf0001180002
49 0001fffffffffffffffffffffffffffffffffd20f1 49 0001fffffffffffffffffffffffffffffffffd20f1ffffffff0344eb086b
50 083b80bbfeffffffffff00ffffff440b0c200dd80f 50 083b80bbfeffffffffff00ffffff440b0c200dd80fd810d820914824806f
51 1d81ed0f773830b030b0f7ffffff29c25cfff030c0 51 1d81ed0f773830b030b0f7ffffff29c25cfff030c080ffffffffffffffff
52 ffffffffffffffffffffffffffffffffffffffffff 52 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
53 ffffffffffffffffffffffffffffffffffffffffff 53 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
54 ffffffffffffffffffffffffffffffffffffffffff 54 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
55 ffffffffffffffffffffffffffffffffffffffffff 55 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
56 ffffffffffffffffffffffffffffffffff0004fff3 56 ffffffffffffffffffffffffffffffffff0004fff37f0000f57f0000f9ff
57 7d00f57f0000f37f0000ffffffffffffffffffffff 57 7d00f57f0000f37f0000ffffffffffffffffffffffffffffffffffffffff
58 ffffffffffffffffffffffffffffffffffffffffff 58 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
59 ffffffffffffffffffffffffffffffffffffffffff 59 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
60 ffffffffffffffffffffffffffffffffffffffffff 60 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
61 ffffffffffffffffffffffffffffffffffffffffff 61 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
62 ffffffffffffffffffffffffffffffffffffffffff 62 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
63 ffffffffffffffffffffffffffffffffffffffffff 63 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
64 ffffffffffffffffffffffffffffffffffffffffff 64 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
65 ffffbf2643ffb95ffdff30f260f332ff0a122346ff 65 ffffbf2643ffb95ffdff30f260f332ff0a122346ff0f19320f1919ffffff
66 ffffffff00669938ff05013506040232b03072428d 66 ffffffff00669938ff05013506040232b03072428de89888a585c09faf5a
67 ffff06ec060c0003080bffffffffff07ffff0202ff 67 ffff06ec060c0003080bffffffffff07ffff0202ff060300fdfd040700fc
68 0300fefe0202070e 68 0300fefe0202070e
69 root@1:~# sha256sum /sys/bus/spi/devices/s 69 root@1:~# sha256sum /sys/bus/spi/devices/spi0.0/spi-nor/sfdp
70 428f34d0461876f189ac97f93e68a05fa6428c6650 70 428f34d0461876f189ac97f93e68a05fa6428c6650b3b7baf736a921e5898ed1 /sys/bus/spi/devices/spi0.0/spi-nor/sfdp
71 71
72 Please dump the SFDP tables using ``xxd -p` 72 Please dump the SFDP tables using ``xxd -p``. It enables us to do
73 the reverse operation and convert the hexdu 73 the reverse operation and convert the hexdump to binary with
74 ``xxd -rp``. Dumping the SFDP data with ``h 74 ``xxd -rp``. Dumping the SFDP data with ``hexdump -Cv`` is accepted,
75 but less desirable. 75 but less desirable.
76 76
77 3) Dump debugfs data:: 77 3) Dump debugfs data::
78 78
79 root@1:~# cat /sys/kernel/debug/spi-nor/sp 79 root@1:~# cat /sys/kernel/debug/spi-nor/spi0.0/capabilities
80 Supported read modes by the flash 80 Supported read modes by the flash
81 1S-1S-1S 81 1S-1S-1S
82 opcode 0x03 82 opcode 0x03
83 mode cycles 0 83 mode cycles 0
84 dummy cycles 0 84 dummy cycles 0
85 1S-1S-1S (fast read) 85 1S-1S-1S (fast read)
86 opcode 0x0b 86 opcode 0x0b
87 mode cycles 0 87 mode cycles 0
88 dummy cycles 8 88 dummy cycles 8
89 1S-1S-2S 89 1S-1S-2S
90 opcode 0x3b 90 opcode 0x3b
91 mode cycles 0 91 mode cycles 0
92 dummy cycles 8 92 dummy cycles 8
93 1S-2S-2S 93 1S-2S-2S
94 opcode 0xbb 94 opcode 0xbb
95 mode cycles 4 95 mode cycles 4
96 dummy cycles 0 96 dummy cycles 0
97 1S-1S-4S 97 1S-1S-4S
98 opcode 0x6b 98 opcode 0x6b
99 mode cycles 0 99 mode cycles 0
100 dummy cycles 8 100 dummy cycles 8
101 1S-4S-4S 101 1S-4S-4S
102 opcode 0xeb 102 opcode 0xeb
103 mode cycles 2 103 mode cycles 2
104 dummy cycles 4 104 dummy cycles 4
105 4S-4S-4S 105 4S-4S-4S
106 opcode 0x0b 106 opcode 0x0b
107 mode cycles 2 107 mode cycles 2
108 dummy cycles 4 108 dummy cycles 4
109 109
110 Supported page program modes by the flash 110 Supported page program modes by the flash
111 1S-1S-1S 111 1S-1S-1S
112 opcode 0x02 112 opcode 0x02
113 113
114 root@1:~# cat /sys/kernel/debug/spi-nor/sp 114 root@1:~# cat /sys/kernel/debug/spi-nor/spi0.0/params
115 name sst26vf064b 115 name sst26vf064b
116 id bf 26 43 bf 26 43 116 id bf 26 43 bf 26 43
117 size 8.00 MiB 117 size 8.00 MiB
118 write size 1 118 write size 1
119 page size 256 119 page size 256
120 address nbytes 3 120 address nbytes 3
121 flags HAS_LOCK | HAS_16BIT_S 121 flags HAS_LOCK | HAS_16BIT_SR | SOFT_RESET | SWP_IS_VOLATILE
122 122
123 opcodes 123 opcodes
124 read 0xeb 124 read 0xeb
125 dummy cycles 6 125 dummy cycles 6
126 erase 0x20 126 erase 0x20
127 program 0x02 127 program 0x02
128 8D extension none 128 8D extension none
129 129
130 protocols 130 protocols
131 read 1S-4S-4S 131 read 1S-4S-4S
132 write 1S-1S-1S 132 write 1S-1S-1S
133 register 1S-1S-1S 133 register 1S-1S-1S
134 134
135 erase commands 135 erase commands
136 20 (4.00 KiB) [0] 136 20 (4.00 KiB) [0]
137 d8 (8.00 KiB) [1] 137 d8 (8.00 KiB) [1]
138 d8 (32.0 KiB) [2] 138 d8 (32.0 KiB) [2]
139 d8 (64.0 KiB) [3] 139 d8 (64.0 KiB) [3]
140 c7 (8.00 MiB) 140 c7 (8.00 MiB)
141 141
142 sector map 142 sector map
143 region (in hex) | erase mask | flags 143 region (in hex) | erase mask | flags
144 ------------------+------------+--------- 144 ------------------+------------+----------
145 00000000-00007fff | [01 ] | 145 00000000-00007fff | [01 ] |
146 00008000-0000ffff | [0 2 ] | 146 00008000-0000ffff | [0 2 ] |
147 00010000-007effff | [0 3] | 147 00010000-007effff | [0 3] |
148 007f0000-007f7fff | [0 2 ] | 148 007f0000-007f7fff | [0 2 ] |
149 007f8000-007fffff | [01 ] | 149 007f8000-007fffff | [01 ] |
150 150
151 4) Use `mtd-utils <https://git.infradead.org/m 151 4) Use `mtd-utils <https://git.infradead.org/mtd-utils.git>`__
152 and verify that erase, read and page progra 152 and verify that erase, read and page program operations work fine::
153 153
154 root@1:~# dd if=/dev/urandom of=./spi_test 154 root@1:~# dd if=/dev/urandom of=./spi_test bs=1M count=2
155 2+0 records in 155 2+0 records in
156 2+0 records out 156 2+0 records out
157 2097152 bytes (2.1 MB, 2.0 MiB) copied, 0. 157 2097152 bytes (2.1 MB, 2.0 MiB) copied, 0.848566 s, 2.5 MB/s
158 158
159 root@1:~# mtd_debug erase /dev/mtd0 0 2097 159 root@1:~# mtd_debug erase /dev/mtd0 0 2097152
160 Erased 2097152 bytes from address 0x000000 160 Erased 2097152 bytes from address 0x00000000 in flash
161 161
162 root@1:~# mtd_debug read /dev/mtd0 0 20971 162 root@1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read
163 Copied 2097152 bytes from address 0x000000 163 Copied 2097152 bytes from address 0x00000000 in flash to spi_read
164 164
165 root@1:~# hexdump spi_read 165 root@1:~# hexdump spi_read
166 0000000 ffff ffff ffff ffff ffff ffff ffff 166 0000000 ffff ffff ffff ffff ffff ffff ffff ffff
167 * 167 *
168 0200000 168 0200000
169 169
170 root@1:~# sha256sum spi_read 170 root@1:~# sha256sum spi_read
171 4bda3a28f4ffe603c0ec1258c0034d65a1a0d35ab7 171 4bda3a28f4ffe603c0ec1258c0034d65a1a0d35ab7bd523a834608adabf03cc5 spi_read
172 172
173 root@1:~# mtd_debug write /dev/mtd0 0 2097 173 root@1:~# mtd_debug write /dev/mtd0 0 2097152 spi_test
174 Copied 2097152 bytes from spi_test to addr 174 Copied 2097152 bytes from spi_test to address 0x00000000 in flash
175 175
176 root@1:~# mtd_debug read /dev/mtd0 0 20971 176 root@1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read
177 Copied 2097152 bytes from address 0x000000 177 Copied 2097152 bytes from address 0x00000000 in flash to spi_read
178 178
179 root@1:~# sha256sum spi* 179 root@1:~# sha256sum spi*
180 c444216a6ba2a4a66cccd60a0dd062bce4b865dd52 180 c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8 spi_read
181 c444216a6ba2a4a66cccd60a0dd062bce4b865dd52 181 c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8 spi_test
182 182
183 If the flash comes erased by default and th 183 If the flash comes erased by default and the previous erase was ignored,
184 we won't catch it, thus test the erase agai 184 we won't catch it, thus test the erase again::
185 185
186 root@1:~# mtd_debug erase /dev/mtd0 0 2097 186 root@1:~# mtd_debug erase /dev/mtd0 0 2097152
187 Erased 2097152 bytes from address 0x000000 187 Erased 2097152 bytes from address 0x00000000 in flash
188 188
189 root@1:~# mtd_debug read /dev/mtd0 0 20971 189 root@1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read
190 Copied 2097152 bytes from address 0x000000 190 Copied 2097152 bytes from address 0x00000000 in flash to spi_read
191 191
192 root@1:~# sha256sum spi* 192 root@1:~# sha256sum spi*
193 4bda3a28f4ffe603c0ec1258c0034d65a1a0d35ab7 193 4bda3a28f4ffe603c0ec1258c0034d65a1a0d35ab7bd523a834608adabf03cc5 spi_read
194 c444216a6ba2a4a66cccd60a0dd062bce4b865dd52 194 c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8 spi_test
195 195
196 Dump some other relevant data:: 196 Dump some other relevant data::
197 197
198 root@1:~# mtd_debug info /dev/mtd0 198 root@1:~# mtd_debug info /dev/mtd0
199 mtd.type = MTD_NORFLASH 199 mtd.type = MTD_NORFLASH
200 mtd.flags = MTD_CAP_NORFLASH 200 mtd.flags = MTD_CAP_NORFLASH
201 mtd.size = 8388608 (8M) 201 mtd.size = 8388608 (8M)
202 mtd.erasesize = 4096 (4K) 202 mtd.erasesize = 4096 (4K)
203 mtd.writesize = 1 203 mtd.writesize = 1
204 mtd.oobsize = 0 204 mtd.oobsize = 0
205 regions = 0 205 regions = 0
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.