]> git.ipfire.org Git - people/ms/u-boot.git/blob - doc/README.sandbox
sandbox: move source files from board/ to arch/sandbox/
[people/ms/u-boot.git] / doc / README.sandbox
1 /*
2 * Copyright (c) 2014 The Chromium OS Authors.
3 *
4 * SPDX-License-Identifier: GPL-2.0+
5 */
6
7 Native Execution of U-Boot
8 ==========================
9
10 The 'sandbox' architecture is designed to allow U-Boot to run under Linux on
11 almost any hardware. To achieve this it builds U-Boot (so far as possible)
12 as a normal C application with a main() and normal C libraries.
13
14 All of U-Boot's architecture-specific code therefore cannot be built as part
15 of the sandbox U-Boot. The purpose of running U-Boot under Linux is to test
16 all the generic code, not specific to any one architecture. The idea is to
17 create unit tests which we can run to test this upper level code.
18
19 CONFIG_SANDBOX is defined when building a native board.
20
21 The chosen vendor and board names are also 'sandbox', so there is a single
22 board in board/sandbox/sandbox.
23
24 CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian
25 machines.
26
27 Note that standalone/API support is not available at present.
28
29
30 Basic Operation
31 ---------------
32
33 To run sandbox U-Boot use something like:
34
35 make sandbox_config all
36 ./u-boot
37
38 Note:
39 If you get errors about 'sdl-config: Command not found' you may need to
40 install libsdl1.2-dev or similar to get SDL support. Alternatively you can
41 build sandbox without SDL (i.e. no display/keyboard support) by removing
42 the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using:
43
44 make sandbox_config all NO_SDL=1
45 ./u-boot
46
47
48 U-Boot will start on your computer, showing a sandbox emulation of the serial
49 console:
50
51
52 U-Boot 2014.04 (Mar 20 2014 - 19:06:00)
53
54 DRAM: 128 MiB
55 Using default environment
56
57 In: serial
58 Out: lcd
59 Err: lcd
60 =>
61
62 You can issue commands as your would normally. If the command you want is
63 not supported you can add it to include/configs/sandbox.h.
64
65 To exit, type 'reset' or press Ctrl-C.
66
67
68 Console / LCD support
69 ---------------------
70
71 Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the
72 sandbox with LCD and keyboard emulation, using something like:
73
74 ./u-boot -d u-boot.dtb -l
75
76 This will start U-Boot with a window showing the contents of the LCD. If
77 that window has the focus then you will be able to type commands as you
78 would on the console. You can adjust the display settings in the device
79 tree file - see arch/sandbox/dts/sandbox.dts.
80
81
82 Command-line Options
83 --------------------
84
85 Various options are available, mostly for test purposes. Use -h to see
86 available options. Some of these are described below.
87
88 The terminal is normally in what is called 'raw-with-sigs' mode. This means
89 that you can use arrow keys for command editing and history, but if you
90 press Ctrl-C, U-Boot will exit instead of handling this as a keypress.
91
92 Other options are 'raw' (so Ctrl-C is handled within U-Boot) and 'cooked'
93 (where the terminal is in cooked mode and cursor keys will not work, Ctrl-C
94 will exit).
95
96 As mentioned above, -l causes the LCD emulation window to be shown.
97
98 A device tree binary file can be provided with -d. If you edit the source
99 (it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to
100 recreate the binary file.
101
102 To execute commands directly, use the -c option. You can specify a single
103 command, or multiple commands separated by a semicolon, as is normal in
104 U-Boot. Be careful with quoting as the shall will normally process and
105 swallow quotes. When -c is used, U-Boot exists after the command is complete,
106 but you can force it to go to interactive mode instead with -i.
107
108
109 Memory Emulation
110 ----------------
111
112 Memory emulation is supported, with the size set by CONFIG_SYS_SDRAM_SIZE.
113 The -m option can be used to read memory from a file on start-up and write
114 it when shutting down. This allows preserving of memory contents across
115 test runs. You can tell U-Boot to remove the memory file after it is read
116 (on start-up) with the --rm_memory option.
117
118 To access U-Boot's emulated memory within the code, use map_sysmem(). This
119 function is used throughout U-Boot to ensure that emulated memory is used
120 rather than the U-Boot application memory. This provides memory starting
121 at 0 and extending to the size of the emulation.
122
123
124 Storing State
125 -------------
126
127 With sandbox you can write drivers which emulate the operation of drivers on
128 real devices. Some of these drivers may want to record state which is
129 preserved across U-Boot runs. This is particularly useful for testing. For
130 example, the contents of a SPI flash chip should not disappear just because
131 U-Boot exits.
132
133 State is stored in a device tree file in a simple format which is driver-
134 specific. You then use the -s option to specify the state file. Use -r to
135 make U-Boot read the state on start-up (otherwise it starts empty) and -w
136 to write it on exit (otherwise the stored state is left unchanged and any
137 changes U-Boot made will be lost). You can also use -n to tell U-Boot to
138 ignore any problems with missing state. This is useful when first running
139 since the state file will be empty.
140
141 The device tree file has one node for each driver - the driver can store
142 whatever properties it likes in there. See 'Writing Sandbox Drivers' below
143 for more details on how to get drivers to read and write their state.
144
145
146 Running and Booting
147 -------------------
148
149 Since there is no machine architecture, sandbox U-Boot cannot actually boot
150 a kernel, but it does support the bootm command. Filesystems, memory
151 commands, hashing, FIT images, verified boot and many other features are
152 supported.
153
154 When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real
155 machine. Of course in this case, no kernel is run.
156
157 It is also possible to tell U-Boot that it has jumped from a temporary
158 previous U-Boot binary, with the -j option. That binary is automatically
159 removed by the U-Boot that gets the -j option. This allows you to write
160 tests which emulate the action of chain-loading U-Boot, typically used in
161 a situation where a second 'updatable' U-Boot is stored on your board. It
162 is very risky to overwrite or upgrade the only U-Boot on a board, since a
163 power or other failure will brick the board and require return to the
164 manufacturer in the case of a consumer device.
165
166
167 Supported Drivers
168 -----------------
169
170 U-Boot sandbox supports these emulations:
171
172 - Block devices
173 - Chrome OS EC
174 - GPIO
175 - Host filesystem (access files on the host from within U-Boot)
176 - Keyboard (Chrome OS)
177 - LCD
178 - Serial (for console only)
179 - Sound (incomplete - see sandbox_sdl_sound_init() for details)
180 - SPI
181 - SPI flash
182 - TPM (Trusted Platform Module)
183
184 Notable omissions are networking and I2C.
185
186 A wide range of commands is implemented. Filesystems which use a block
187 device are supported.
188
189 Also sandbox uses generic board (CONFIG_SYS_GENERIC_BOARD) and supports
190 driver model (CONFIG_DM) and associated commands.
191
192
193 SPI Emulation
194 -------------
195
196 Sandbox supports SPI and SPI flash emulation.
197
198 This is controlled by the spi_sf argument, the format of which is:
199
200 bus:cs:device:file
201
202 bus - SPI bus number
203 cs - SPI chip select number
204 device - SPI device emulation name
205 file - File on disk containing the data
206
207 For example:
208
209 dd if=/dev/zero of=spi.bin bs=1M count=4
210 ./u-boot --spi_sf 0:0:M25P16:spi.bin
211
212 With this setup you can issue SPI flash commands as normal:
213
214 =>sf probe
215 SF: Detected M25P16 with page size 64 KiB, total 2 MiB
216 =>sf read 0 0 10000
217 SF: 65536 bytes @ 0x0 Read: OK
218 =>
219
220 Since this is a full SPI emulation (rather than just flash), you can
221 also use low-level SPI commands:
222
223 =>sspi 0:0 32 9f
224 FF202015
225
226 This is issuing a READ_ID command and getting back 20 (ST Micro) part
227 0x2015 (the M25P16).
228
229 Drivers are connected to a particular bus/cs using sandbox's state
230 structure (see the 'spi' member). A set of operations must be provided
231 for each driver.
232
233
234 Configuration settings for the curious are:
235
236 CONFIG_SANDBOX_SPI_MAX_BUS
237 The maximum number of SPI buses supported by the driver (default 1).
238
239 CONFIG_SANDBOX_SPI_MAX_CS
240 The maximum number of chip selects supported by the driver
241 (default 10).
242
243 CONFIG_SPI_IDLE_VAL
244 The idle value on the SPI bus
245
246
247 Writing Sandbox Drivers
248 -----------------------
249
250 Generally you should put your driver in a file containing the word 'sandbox'
251 and put it in the same directory as other drivers of its type. You can then
252 implement the same hooks as the other drivers.
253
254 To access U-Boot's emulated memory, use map_sysmem() as mentioned above.
255
256 If your driver needs to store configuration or state (such as SPI flash
257 contents or emulated chip registers), you can use the device tree as
258 described above. Define handlers for this with the SANDBOX_STATE_IO macro.
259 See arch/sandbox/include/asm/state.h for documentation. In short you provide
260 a node name, compatible string and functions to read and write the state.
261 Since writing the state can expand the device tree, you may need to use
262 state_setprop() which does this automatically and avoids running out of
263 space. See existing code for examples.
264
265
266 Testing
267 -------
268
269 U-Boot sandbox can be used to run various tests, mostly in the test/
270 directory. These include:
271
272 command_ut
273 - Unit tests for command parsing and handling
274 compression
275 - Unit tests for U-Boot's compression algorithms, useful for
276 security checking. It supports gzip, bzip2, lzma and lzo.
277 driver model
278 - test/dm/test-dm.sh to run these.
279 image
280 - Unit tests for images:
281 test/image/test-imagetools.sh - multi-file images
282 test/image/test-fit.py - FIT images
283 tracing
284 - test/trace/test-trace.sh tests the tracing system (see README.trace)
285 verified boot
286 - See test/vboot/vboot_test.sh for this
287
288 If you change or enhance any of the above subsystems, you shold write or
289 expand a test and include it with your patch series submission. Test
290 coverage in U-Boot is limited, as we need to work to improve it.
291
292 Note that many of these tests are implemented as commands which you can
293 run natively on your board if desired (and enabled).
294
295 It would be useful to have a central script to run all of these.
296
297 --
298 Simon Glass <sjg@chromium.org>
299 Updated 22-Mar-14