]>
Commit | Line | Data |
---|---|---|
744d9859 | 1 | /* |
75b3c3aa | 2 | * Copyright (c) 2014 The Chromium OS Authors. |
744d9859 | 3 | * |
3765b3e7 | 4 | * SPDX-License-Identifier: GPL-2.0+ |
744d9859 SG |
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 | ||
9b250ac4 SG |
21 | The board name is 'sandbox' but the vendor name is unset, so there is a |
22 | single board in board/sandbox. | |
744d9859 SG |
23 | |
24 | CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian | |
25 | machines. | |
26 | ||
226b50bb BM |
27 | By default sandbox builds and runs on 64-bit hosts. If you are going to build |
28 | and run sandbox on a 32-bit host, select CONFIG_SANDBOX_32BIT. | |
29 | ||
744d9859 SG |
30 | Note that standalone/API support is not available at present. |
31 | ||
75b3c3aa SG |
32 | |
33 | Basic Operation | |
34 | --------------- | |
35 | ||
36 | To run sandbox U-Boot use something like: | |
37 | ||
6b1978f8 | 38 | make sandbox_defconfig all |
75b3c3aa SG |
39 | ./u-boot |
40 | ||
41 | Note: | |
42 | If you get errors about 'sdl-config: Command not found' you may need to | |
43 | install libsdl1.2-dev or similar to get SDL support. Alternatively you can | |
44 | build sandbox without SDL (i.e. no display/keyboard support) by removing | |
45 | the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using: | |
46 | ||
6b1978f8 | 47 | make sandbox_defconfig all NO_SDL=1 |
75b3c3aa SG |
48 | ./u-boot |
49 | ||
75b3c3aa SG |
50 | U-Boot will start on your computer, showing a sandbox emulation of the serial |
51 | console: | |
52 | ||
53 | ||
54 | U-Boot 2014.04 (Mar 20 2014 - 19:06:00) | |
55 | ||
56 | DRAM: 128 MiB | |
57 | Using default environment | |
58 | ||
59 | In: serial | |
60 | Out: lcd | |
61 | Err: lcd | |
62 | => | |
63 | ||
64 | You can issue commands as your would normally. If the command you want is | |
65 | not supported you can add it to include/configs/sandbox.h. | |
66 | ||
67 | To exit, type 'reset' or press Ctrl-C. | |
68 | ||
69 | ||
70 | Console / LCD support | |
71 | --------------------- | |
72 | ||
73 | Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the | |
74 | sandbox with LCD and keyboard emulation, using something like: | |
75 | ||
76 | ./u-boot -d u-boot.dtb -l | |
77 | ||
78 | This will start U-Boot with a window showing the contents of the LCD. If | |
79 | that window has the focus then you will be able to type commands as you | |
80 | would on the console. You can adjust the display settings in the device | |
81 | tree file - see arch/sandbox/dts/sandbox.dts. | |
82 | ||
83 | ||
84 | Command-line Options | |
85 | -------------------- | |
86 | ||
87 | Various options are available, mostly for test purposes. Use -h to see | |
88 | available options. Some of these are described below. | |
89 | ||
90 | The terminal is normally in what is called 'raw-with-sigs' mode. This means | |
91 | that you can use arrow keys for command editing and history, but if you | |
92 | press Ctrl-C, U-Boot will exit instead of handling this as a keypress. | |
93 | ||
94 | Other options are 'raw' (so Ctrl-C is handled within U-Boot) and 'cooked' | |
95 | (where the terminal is in cooked mode and cursor keys will not work, Ctrl-C | |
96 | will exit). | |
97 | ||
98 | As mentioned above, -l causes the LCD emulation window to be shown. | |
99 | ||
100 | A device tree binary file can be provided with -d. If you edit the source | |
101 | (it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to | |
102 | recreate the binary file. | |
103 | ||
104 | To execute commands directly, use the -c option. You can specify a single | |
105 | command, or multiple commands separated by a semicolon, as is normal in | |
106 | U-Boot. Be careful with quoting as the shall will normally process and | |
107 | swallow quotes. When -c is used, U-Boot exists after the command is complete, | |
108 | but you can force it to go to interactive mode instead with -i. | |
109 | ||
110 | ||
111 | Memory Emulation | |
112 | ---------------- | |
113 | ||
114 | Memory emulation is supported, with the size set by CONFIG_SYS_SDRAM_SIZE. | |
115 | The -m option can be used to read memory from a file on start-up and write | |
116 | it when shutting down. This allows preserving of memory contents across | |
117 | test runs. You can tell U-Boot to remove the memory file after it is read | |
118 | (on start-up) with the --rm_memory option. | |
119 | ||
120 | To access U-Boot's emulated memory within the code, use map_sysmem(). This | |
121 | function is used throughout U-Boot to ensure that emulated memory is used | |
122 | rather than the U-Boot application memory. This provides memory starting | |
123 | at 0 and extending to the size of the emulation. | |
124 | ||
125 | ||
126 | Storing State | |
127 | ------------- | |
128 | ||
129 | With sandbox you can write drivers which emulate the operation of drivers on | |
130 | real devices. Some of these drivers may want to record state which is | |
131 | preserved across U-Boot runs. This is particularly useful for testing. For | |
132 | example, the contents of a SPI flash chip should not disappear just because | |
133 | U-Boot exits. | |
134 | ||
135 | State is stored in a device tree file in a simple format which is driver- | |
136 | specific. You then use the -s option to specify the state file. Use -r to | |
137 | make U-Boot read the state on start-up (otherwise it starts empty) and -w | |
138 | to write it on exit (otherwise the stored state is left unchanged and any | |
139 | changes U-Boot made will be lost). You can also use -n to tell U-Boot to | |
140 | ignore any problems with missing state. This is useful when first running | |
141 | since the state file will be empty. | |
142 | ||
143 | The device tree file has one node for each driver - the driver can store | |
144 | whatever properties it likes in there. See 'Writing Sandbox Drivers' below | |
145 | for more details on how to get drivers to read and write their state. | |
146 | ||
147 | ||
148 | Running and Booting | |
149 | ------------------- | |
150 | ||
151 | Since there is no machine architecture, sandbox U-Boot cannot actually boot | |
152 | a kernel, but it does support the bootm command. Filesystems, memory | |
153 | commands, hashing, FIT images, verified boot and many other features are | |
154 | supported. | |
155 | ||
156 | When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real | |
157 | machine. Of course in this case, no kernel is run. | |
158 | ||
159 | It is also possible to tell U-Boot that it has jumped from a temporary | |
160 | previous U-Boot binary, with the -j option. That binary is automatically | |
161 | removed by the U-Boot that gets the -j option. This allows you to write | |
162 | tests which emulate the action of chain-loading U-Boot, typically used in | |
163 | a situation where a second 'updatable' U-Boot is stored on your board. It | |
164 | is very risky to overwrite or upgrade the only U-Boot on a board, since a | |
165 | power or other failure will brick the board and require return to the | |
166 | manufacturer in the case of a consumer device. | |
167 | ||
168 | ||
169 | Supported Drivers | |
170 | ----------------- | |
171 | ||
172 | U-Boot sandbox supports these emulations: | |
173 | ||
174 | - Block devices | |
175 | - Chrome OS EC | |
176 | - GPIO | |
177 | - Host filesystem (access files on the host from within U-Boot) | |
3ea143ab | 178 | - I2C |
75b3c3aa SG |
179 | - Keyboard (Chrome OS) |
180 | - LCD | |
3ea143ab | 181 | - Network |
75b3c3aa SG |
182 | - Serial (for console only) |
183 | - Sound (incomplete - see sandbox_sdl_sound_init() for details) | |
184 | - SPI | |
185 | - SPI flash | |
186 | - TPM (Trusted Platform Module) | |
187 | ||
75b3c3aa SG |
188 | A wide range of commands is implemented. Filesystems which use a block |
189 | device are supported. | |
190 | ||
89b199c3 | 191 | Also sandbox supports driver model (CONFIG_DM) and associated commands. |
744d9859 SG |
192 | |
193 | ||
a346ca79 JH |
194 | Linux RAW Networking Bridge |
195 | --------------------------- | |
196 | ||
197 | The sandbox_eth_raw driver bridges traffic between the bottom of the network | |
198 | stack and the RAW sockets API in Linux. This allows much of the U-Boot network | |
199 | functionality to be tested in sandbox against real network traffic. | |
200 | ||
201 | For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API. This | |
202 | is needed to get access to the lowest level of the network stack in Linux. This | |
203 | means that all of the Ethernet frame is included. This allows the U-Boot network | |
204 | stack to be fully used. In other words, nothing about the Linux network stack is | |
205 | involved in forming the packets that end up on the wire. To receive the | |
206 | responses to packets sent from U-Boot the network interface has to be set to | |
207 | promiscuous mode so that the network card won't filter out packets not destined | |
208 | for its configured (on Linux) MAC address. | |
209 | ||
210 | The RAW sockets Ethernet API requires elevated privileges in Linux. You can | |
211 | either run as root, or you can add the capability needed like so: | |
212 | ||
213 | sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot | |
214 | ||
215 | The default device tree for sandbox includes an entry for eth0 on the sandbox | |
216 | host machine whose alias is "eth1". The following are a few examples of network | |
217 | operations being tested on the eth0 interface. | |
218 | ||
219 | sudo /path/to/u-boot -D | |
220 | ||
221 | DHCP | |
222 | .... | |
223 | ||
224 | set autoload no | |
225 | set ethact eth1 | |
226 | dhcp | |
227 | ||
228 | PING | |
229 | .... | |
230 | ||
231 | set autoload no | |
232 | set ethact eth1 | |
233 | dhcp | |
234 | ping $gatewayip | |
235 | ||
236 | TFTP | |
237 | .... | |
238 | ||
239 | set autoload no | |
240 | set ethact eth1 | |
241 | dhcp | |
242 | set serverip WWW.XXX.YYY.ZZZ | |
243 | tftpboot u-boot.bin | |
244 | ||
22f68524 JH |
245 | The bridge also support (to a lesser extent) the localhost inderface, 'lo'. |
246 | ||
247 | The 'lo' interface cannot use the RAW AF_PACKET API because the lo interface | |
248 | doesn't support Ethernet-level traffic. It is a higher-level interface that is | |
249 | expected only to be used at the AF_INET level of the API. As such, the most raw | |
250 | we can get on that interface is the RAW AF_INET API on UDP. This allows us to | |
251 | set the IP_HDRINCL option to include everything except the Ethernet header in | |
252 | the packets we send and receive. | |
253 | ||
254 | Because only UDP is supported, ICMP traffic will not work, so expect that ping | |
255 | commands will time out. | |
256 | ||
257 | The default device tree for sandbox includes an entry for lo on the sandbox | |
258 | host machine whose alias is "eth5". The following is an example of a network | |
259 | operation being tested on the lo interface. | |
260 | ||
261 | TFTP | |
262 | .... | |
263 | ||
264 | set ethact eth5 | |
265 | tftpboot u-boot.bin | |
266 | ||
a346ca79 | 267 | |
ffdb20be MF |
268 | SPI Emulation |
269 | ------------- | |
270 | ||
271 | Sandbox supports SPI and SPI flash emulation. | |
272 | ||
273 | This is controlled by the spi_sf argument, the format of which is: | |
274 | ||
275 | bus:cs:device:file | |
276 | ||
277 | bus - SPI bus number | |
278 | cs - SPI chip select number | |
279 | device - SPI device emulation name | |
280 | file - File on disk containing the data | |
281 | ||
282 | For example: | |
283 | ||
284 | dd if=/dev/zero of=spi.bin bs=1M count=4 | |
285 | ./u-boot --spi_sf 0:0:M25P16:spi.bin | |
286 | ||
287 | With this setup you can issue SPI flash commands as normal: | |
288 | ||
289 | =>sf probe | |
290 | SF: Detected M25P16 with page size 64 KiB, total 2 MiB | |
291 | =>sf read 0 0 10000 | |
292 | SF: 65536 bytes @ 0x0 Read: OK | |
293 | => | |
294 | ||
295 | Since this is a full SPI emulation (rather than just flash), you can | |
296 | also use low-level SPI commands: | |
297 | ||
298 | =>sspi 0:0 32 9f | |
299 | FF202015 | |
300 | ||
301 | This is issuing a READ_ID command and getting back 20 (ST Micro) part | |
302 | 0x2015 (the M25P16). | |
303 | ||
304 | Drivers are connected to a particular bus/cs using sandbox's state | |
305 | structure (see the 'spi' member). A set of operations must be provided | |
306 | for each driver. | |
307 | ||
308 | ||
309 | Configuration settings for the curious are: | |
310 | ||
311 | CONFIG_SANDBOX_SPI_MAX_BUS | |
312 | The maximum number of SPI buses supported by the driver (default 1). | |
313 | ||
314 | CONFIG_SANDBOX_SPI_MAX_CS | |
315 | The maximum number of chip selects supported by the driver | |
316 | (default 10). | |
317 | ||
318 | CONFIG_SPI_IDLE_VAL | |
319 | The idle value on the SPI bus | |
320 | ||
321 | ||
2945eb73 SB |
322 | Block Device Emulation |
323 | ---------------------- | |
324 | ||
325 | U-Boot can use raw disk images for block device emulation. To e.g. list | |
326 | the contents of the root directory on the second partion of the image | |
327 | "disk.raw", you can use the following commands: | |
328 | ||
329 | =>host bind 0 ./disk.raw | |
330 | =>ls host 0:2 | |
331 | ||
332 | A disk image can be created using the following commands: | |
333 | ||
334 | $> truncate -s 1200M ./disk.raw | |
6b20c347 | 335 | $> echo -e "label: gpt\n,64M,U\n,,L" | /usr/sbin/sgdisk ./disk.raw |
2945eb73 SB |
336 | $> lodev=`sudo losetup -P -f --show ./disk.raw` |
337 | $> sudo mkfs.vfat -n EFI -v ${lodev}p1 | |
338 | $> sudo mkfs.ext4 -L ROOT -v ${lodev}p2 | |
339 | ||
bf6d76b8 AC |
340 | or utilize the device described in test/py/make_test_disk.py: |
341 | ||
342 | #!/usr/bin/python | |
343 | import make_test_disk | |
344 | make_test_disk.makeDisk() | |
2945eb73 | 345 | |
75b3c3aa SG |
346 | Writing Sandbox Drivers |
347 | ----------------------- | |
348 | ||
349 | Generally you should put your driver in a file containing the word 'sandbox' | |
350 | and put it in the same directory as other drivers of its type. You can then | |
351 | implement the same hooks as the other drivers. | |
352 | ||
353 | To access U-Boot's emulated memory, use map_sysmem() as mentioned above. | |
354 | ||
355 | If your driver needs to store configuration or state (such as SPI flash | |
356 | contents or emulated chip registers), you can use the device tree as | |
357 | described above. Define handlers for this with the SANDBOX_STATE_IO macro. | |
358 | See arch/sandbox/include/asm/state.h for documentation. In short you provide | |
359 | a node name, compatible string and functions to read and write the state. | |
360 | Since writing the state can expand the device tree, you may need to use | |
361 | state_setprop() which does this automatically and avoids running out of | |
362 | space. See existing code for examples. | |
363 | ||
364 | ||
365 | Testing | |
366 | ------- | |
367 | ||
368 | U-Boot sandbox can be used to run various tests, mostly in the test/ | |
369 | directory. These include: | |
370 | ||
371 | command_ut | |
372 | - Unit tests for command parsing and handling | |
373 | compression | |
374 | - Unit tests for U-Boot's compression algorithms, useful for | |
375 | security checking. It supports gzip, bzip2, lzma and lzo. | |
376 | driver model | |
7b3dc45e JT |
377 | - Run this pytest |
378 | ./test/py/test.py --bd sandbox --build -k ut_dm -v | |
75b3c3aa SG |
379 | image |
380 | - Unit tests for images: | |
381 | test/image/test-imagetools.sh - multi-file images | |
382 | test/image/test-fit.py - FIT images | |
383 | tracing | |
384 | - test/trace/test-trace.sh tests the tracing system (see README.trace) | |
385 | verified boot | |
386 | - See test/vboot/vboot_test.sh for this | |
387 | ||
388 | If you change or enhance any of the above subsystems, you shold write or | |
389 | expand a test and include it with your patch series submission. Test | |
390 | coverage in U-Boot is limited, as we need to work to improve it. | |
391 | ||
392 | Note that many of these tests are implemented as commands which you can | |
393 | run natively on your board if desired (and enabled). | |
394 | ||
395 | It would be useful to have a central script to run all of these. | |
744d9859 | 396 | |
75b3c3aa SG |
397 | -- |
398 | Simon Glass <sjg@chromium.org> | |
399 | Updated 22-Mar-14 |