1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
|
.. SPDX-License-Identifier: GPL-2.0+:
sf command
==========
Synopis
-------
::
sf probe [[[<bus>:]<cs>] [<hz> [<mode>]]]
sf read <addr> <offset>|<partition> <len>
sf write <addr> <offset>|<partition> <len>
sf erase <offset>|<partition> <len>
sf update <addr> <offset>|<partition> <len>
sf protect lock|unlock <sector> <len>
sf test <offset>|<partition> <len>
Description
-----------
The *sf* command is used to access SPI flash, supporting read/write/erase and
a few other functions.
Probe
-----
The flash must first be probed with *sf probe* before any of the other
subcommands can be used. All of the parameters are optional:
bus
SPI bus number containing the SPI-flash chip, e.g. 0. If you don't know
the number, you can use 'dm uclass' to see all the spi devices,
and check the value for 'seq' for each one (here 0 and 2)::
uclass 89: spi
0 spi@0 @ 05484960, seq 0
1 spi@1 @ 05484b40, seq 2
cs
SPI chip-select to use for the chip. This is often 0 and can be omitted,
but in some cases multiple slaves are attached to a SPI controller,
selected by a chip-select line for each one.
hz
Speed of the SPI bus in hertz. This normally defaults to 100000, i.e.
100KHz, which is very slow. Note that if the device exists in the
device tree, there might be a speed provided there, in which case this
setting is ignored.
mode
SPI mode to use:
===== ================
Mode Meaning
===== ================
0 CPOL=0, CPHA=0
1 CPOL=0, CPHA=1
2 CPOL=1, CPHA=0
3 CPOL=1, CPHA=1
===== ================
Clock phase (CPHA) 0 means that data is transferred (sampled) on the
first clock edge; 1 means the second.
Clock polarity (CPOL) controls the idle state of the clock, 0 for low,
1 for high.
The active state is the opposite of idle.
You may find this `SPI documentation`_ useful.
Parameters for other subcommands (described below) are as follows:
addr
Memory address to start transfer
offset
Flash offset to start transfer
partition
If the parameter is not numeric, it is assumed to be a partition
description in the format <dev_type><dev_num>,<part_num> which is not
covered here. This requires CONFIG_CMD_MTDPARTS.
len
Number of bytes to transfer
Read
~~~~
Use *sf read* to read from SPI flash to memory. The read will fail if an
attempt is made to read past the end of the flash.
Write
~~~~~
Use *sf write* to write from memory to SPI flash. The SPI flash should be
erased first, since otherwise the result is undefined.
The write will fail if an attempt is made to read past the end of the flash.
Erase
~~~~~
Use *sf erase* to erase a region of SPI flash. The erase will fail if any part
of the region to be erased is protected or lies past the end of the flash. It
may also fail if the start offset or length are not aligned to an erase region
(e.g. 256 bytes).
Update
~~~~~~
Use *sf update* to automatically erase and update a region of SPI flash from
memory. This works a sector at a time (typical 4KB or 64KB). For each
sector it first checks if the sector already has the right data. If so it is
skipped. If not, the sector is erased and the new data written. Note that if
the length is not a multiple of the erase size, the space after the data in
the last sector will be erased. If the offset does not start at the beginning
of an erase block, the operation will fail.
Speed statistics are shown including the number of bytes that were already
correct.
Protect
~~~~~~~
SPI-flash chips often have a protection feature where the chip is split up into
regions which can be locked or unlocked. With *sf protect* it is possible to
change these settings, if supported by the driver.
lock|unlock
Selects whether to lock or unlock the sectors
<sector>
Start sector number to lock/unlock. This may be the byte offset or some
other value, depending on the chip.
<len>
Number of bytes to lock/unlock
Test
~~~~
A convenient and fast *sf test* subcommand provides a way to check that SPI
flash is working as expected. This works in four stages:
* erase - erases the entire region
* check - checks that the region is erased
* write - writes a test pattern to the region, consisting of the U-Boot code
* read - reads back the test pattern to check that it was written correctly
Memory is allocated for two buffers, each <len> bytes in size. At typical
size is 64KB to 1MB. The offset and size must be aligned to an erase boundary.
Note that this test will fail if any part of the SPI flash is write-protected.
Examples
--------
This first example uses sandbox::
=> sf probe
SF: Detected m25p16 with page size 256 Bytes, erase size 64 KiB, total 2 MiB
=> sf read 1000 1100 80000
device 0 offset 0x1100, size 0x80000
SF: 524288 bytes @ 0x1100 Read: OK
=> md 1000
00001000: edfe0dd0 f33a0000 78000000 84250000 ......:....x..%.
00001010: 28000000 11000000 10000000 00000000 ...(............
00001020: 6f050000 0c250000 00000000 00000000 ...o..%.........
00001030: 00000000 00000000 00000000 00000000 ................
00001040: 00000000 00000000 00000000 00000000 ................
00001050: 00000000 00000000 00000000 00000000 ................
00001060: 00000000 00000000 00000000 00000000 ................
00001070: 00000000 00000000 01000000 00000000 ................
00001080: 03000000 04000000 00000000 01000000 ................
00001090: 03000000 04000000 0f000000 01000000 ................
000010a0: 03000000 08000000 1b000000 646e6173 ............sand
000010b0: 00786f62 03000000 08000000 21000000 box............!
000010c0: 646e6173 00786f62 01000000 61696c61 sandbox.....alia
000010d0: 00736573 03000000 07000000 2c000000 ses............,
000010e0: 6332692f 00003040 03000000 07000000 /i2c@0..........
000010f0: 31000000 6963702f 00003040 03000000 ...1/pci@0......
=> sf erase 0 80000
SF: 524288 bytes @ 0x0 Erased: OK
=> sf read 1000 1100 80000
device 0 offset 0x1100, size 0x80000
SF: 524288 bytes @ 0x1100 Read: OK
=> md 1000
00001000: ffffffff ffffffff ffffffff ffffffff ................
00001010: ffffffff ffffffff ffffffff ffffffff ................
00001020: ffffffff ffffffff ffffffff ffffffff ................
00001030: ffffffff ffffffff ffffffff ffffffff ................
00001040: ffffffff ffffffff ffffffff ffffffff ................
00001050: ffffffff ffffffff ffffffff ffffffff ................
00001060: ffffffff ffffffff ffffffff ffffffff ................
00001070: ffffffff ffffffff ffffffff ffffffff ................
00001080: ffffffff ffffffff ffffffff ffffffff ................
00001090: ffffffff ffffffff ffffffff ffffffff ................
000010a0: ffffffff ffffffff ffffffff ffffffff ................
000010b0: ffffffff ffffffff ffffffff ffffffff ................
000010c0: ffffffff ffffffff ffffffff ffffffff ................
000010d0: ffffffff ffffffff ffffffff ffffffff ................
000010e0: ffffffff ffffffff ffffffff ffffffff ................
000010f0: ffffffff ffffffff ffffffff ffffffff ................
This second example is running on coral, an x86 Chromebook::
=> sf probe
SF: Detected w25q128fw with page size 256 Bytes, erase size 4 KiB, total 16 MiB
=> sf erase 300000 80000
SF: 524288 bytes @ 0x300000 Erased: OK
=> sf update 1110000 300000 80000
device 0 offset 0x300000, size 0x80000
524288 bytes written, 0 bytes skipped in 0.457s, speed 1164578 B/s
# This does nothing as the flash is already updated
=> sf update 1110000 300000 80000
device 0 offset 0x300000, size 0x80000
0 bytes written, 524288 bytes skipped in 0.196s, speed 2684354 B/s
=> sf test 00000 80000 # try a protected region
SPI flash test:
Erase failed (err = -5)
Test failed
=> sf test 800000 80000
SPI flash test:
0 erase: 18 ticks, 28444 KiB/s 227.552 Mbps
1 check: 192 ticks, 2666 KiB/s 21.328 Mbps
2 write: 227 ticks, 2255 KiB/s 18.040 Mbps
3 read: 189 ticks, 2708 KiB/s 21.664 Mbps
Test passed
0 erase: 18 ticks, 28444 KiB/s 227.552 Mbps
1 check: 192 ticks, 2666 KiB/s 21.328 Mbps
2 write: 227 ticks, 2255 KiB/s 18.040 Mbps
3 read: 189 ticks, 2708 KiB/s 21.664 Mbps
.. _SPI documentation:
https://en.wikipedia.org/wiki/Serial_Peripheral_Interface
|