1 .. SPDX-License-Identifier: GPL-2.0+ */
2 .. Copyright (c) 2014 The Chromium OS Authors.
3 .. sectionauthor:: Simon Glass <sjg@chromium.org>
8 Native Execution of U-Boot
9 --------------------------
11 The 'sandbox' architecture is designed to allow U-Boot to run under Linux on
12 almost any hardware. To achieve this it builds U-Boot (so far as possible)
13 as a normal C application with a main() and normal C libraries.
15 All of U-Boot's architecture-specific code therefore cannot be built as part
16 of the sandbox U-Boot. The purpose of running U-Boot under Linux is to test
17 all the generic code, not specific to any one architecture. The idea is to
18 create unit tests which we can run to test this upper level code.
20 CONFIG_SANDBOX is defined when building a native board.
22 The board name is 'sandbox' but the vendor name is unset, so there is a
23 single board in board/sandbox.
25 CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian
28 There are two versions of the sandbox: One using 32-bit-wide integers, and one
29 using 64-bit-wide integers. The 32-bit version can be build and run on either
30 32 or 64-bit hosts by either selecting or deselecting CONFIG_SANDBOX_32BIT; by
31 default, the sandbox it built for a 32-bit host. The sandbox using 64-bit-wide
32 integers can only be built on 64-bit hosts.
34 Note that standalone/API support is not available at present.
40 Here are some packages that are worth installing if you are doing sandbox or
41 tools development in U-Boot:
43 python3-pytest lzma lzma-alone lz4 python3 python3-virtualenv
50 To run sandbox U-Boot use something like::
52 make sandbox_defconfig all
55 Note: If you get errors about 'sdl-config: Command not found' you may need to
56 install libsdl2.0-dev or similar to get SDL support. Alternatively you can
57 build sandbox without SDL (i.e. no display/keyboard support) by removing
58 the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using::
60 make sandbox_defconfig all NO_SDL=1
63 U-Boot will start on your computer, showing a sandbox emulation of the serial
66 U-Boot 2014.04 (Mar 20 2014 - 19:06:00)
69 Using default environment
76 You can issue commands as your would normally. If the command you want is
77 not supported you can add it to include/configs/sandbox.h.
79 To exit, type 'reset' or press Ctrl-C.
85 Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the
86 sandbox with LCD and keyboard emulation, using something like::
88 ./u-boot -d u-boot.dtb -l
90 This will start U-Boot with a window showing the contents of the LCD. If
91 that window has the focus then you will be able to type commands as you
92 would on the console. You can adjust the display settings in the device
93 tree file - see arch/sandbox/dts/sandbox.dts.
99 Various options are available, mostly for test purposes. Use -h to see
100 available options. Some of these are described below:
102 * -t, --terminal <arg>
103 - The terminal is normally in what is called 'raw-with-sigs' mode. This means
104 that you can use arrow keys for command editing and history, but if you
105 press Ctrl-C, U-Boot will exit instead of handling this as a keypress.
106 Other options are 'raw' (so Ctrl-C is handled within U-Boot) and 'cooked'
107 (where the terminal is in cooked mode and cursor keys will not work, Ctrl-C
111 - Show the LCD emulation window.
114 - A device tree binary file can be provided with -d. If you edit the source
115 (it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to
116 recreate the binary file.
119 - To use the default device tree, use -D.
122 - To use the test device tree, use -T.
125 - To execute commands directly, use the -c option. You can specify a single
126 command, or multiple commands separated by a semicolon, as is normal in
127 U-Boot. Be careful with quoting as the shell will normally process and
128 swallow quotes. When -c is used, U-Boot exits after the command is complete,
129 but you can force it to go to interactive mode instead with -i.
132 - Go to interactive mode after executing the commands specified by -c.
137 Memory emulation is supported, with the size set by CONFIG_SYS_SDRAM_SIZE.
138 The -m option can be used to read memory from a file on start-up and write
139 it when shutting down. This allows preserving of memory contents across
140 test runs. You can tell U-Boot to remove the memory file after it is read
141 (on start-up) with the --rm_memory option.
143 To access U-Boot's emulated memory within the code, use map_sysmem(). This
144 function is used throughout U-Boot to ensure that emulated memory is used
145 rather than the U-Boot application memory. This provides memory starting
146 at 0 and extending to the size of the emulation.
152 With sandbox you can write drivers which emulate the operation of drivers on
153 real devices. Some of these drivers may want to record state which is
154 preserved across U-Boot runs. This is particularly useful for testing. For
155 example, the contents of a SPI flash chip should not disappear just because
158 State is stored in a device tree file in a simple format which is driver-
159 specific. You then use the -s option to specify the state file. Use -r to
160 make U-Boot read the state on start-up (otherwise it starts empty) and -w
161 to write it on exit (otherwise the stored state is left unchanged and any
162 changes U-Boot made will be lost). You can also use -n to tell U-Boot to
163 ignore any problems with missing state. This is useful when first running
164 since the state file will be empty.
166 The device tree file has one node for each driver - the driver can store
167 whatever properties it likes in there. See 'Writing Sandbox Drivers' below
168 for more details on how to get drivers to read and write their state.
174 Since there is no machine architecture, sandbox U-Boot cannot actually boot
175 a kernel, but it does support the bootm command. Filesystems, memory
176 commands, hashing, FIT images, verified boot and many other features are
179 When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real
180 machine. Of course in this case, no kernel is run.
182 It is also possible to tell U-Boot that it has jumped from a temporary
183 previous U-Boot binary, with the -j option. That binary is automatically
184 removed by the U-Boot that gets the -j option. This allows you to write
185 tests which emulate the action of chain-loading U-Boot, typically used in
186 a situation where a second 'updatable' U-Boot is stored on your board. It
187 is very risky to overwrite or upgrade the only U-Boot on a board, since a
188 power or other failure will brick the board and require return to the
189 manufacturer in the case of a consumer device.
195 U-Boot sandbox supports these emulations:
200 - Host filesystem (access files on the host from within U-Boot)
202 - Keyboard (Chrome OS)
205 - Serial (for console only)
206 - Sound (incomplete - see sandbox_sdl_sound_init() for details)
209 - TPM (Trusted Platform Module)
211 A wide range of commands are implemented. Filesystems which use a block
212 device are supported.
214 Also sandbox supports driver model (CONFIG_DM) and associated commands.
220 There are unfortunately quite a few variants at present:
223 should be used for most tests
225 special build that forces a 64-bit host
227 builds with dev_read\_...() functions defined as inline.
228 We need this build so that we can test those inline functions, and we
229 cannot build with both the inline functions and the non-inline functions
230 since they are named the same.
232 builds sandbox with SPL support, so you can run spl/u-boot-spl
233 and it will start up and then load ./u-boot. It is also possible to
234 run ./u-boot directly.
236 Of these sandbox_spl can probably be removed since it is a superset of sandbox.
238 Most of the config options should be identical between these variants.
241 Linux RAW Networking Bridge
242 ---------------------------
244 The sandbox_eth_raw driver bridges traffic between the bottom of the network
245 stack and the RAW sockets API in Linux. This allows much of the U-Boot network
246 functionality to be tested in sandbox against real network traffic.
248 For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API. This
249 is needed to get access to the lowest level of the network stack in Linux. This
250 means that all of the Ethernet frame is included. This allows the U-Boot network
251 stack to be fully used. In other words, nothing about the Linux network stack is
252 involved in forming the packets that end up on the wire. To receive the
253 responses to packets sent from U-Boot the network interface has to be set to
254 promiscuous mode so that the network card won't filter out packets not destined
255 for its configured (on Linux) MAC address.
257 The RAW sockets Ethernet API requires elevated privileges in Linux. You can
258 either run as root, or you can add the capability needed like so::
260 sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot
262 The default device tree for sandbox includes an entry for eth0 on the sandbox
263 host machine whose alias is "eth1". The following are a few examples of network
264 operations being tested on the eth0 interface.
268 sudo /path/to/u-boot -D
294 setenv serverip WWW.XXX.YYY.ZZZ
297 The bridge also supports (to a lesser extent) the localhost interface, 'lo'.
299 The 'lo' interface cannot use the RAW AF_PACKET API because the lo interface
300 doesn't support Ethernet-level traffic. It is a higher-level interface that is
301 expected only to be used at the AF_INET level of the API. As such, the most raw
302 we can get on that interface is the RAW AF_INET API on UDP. This allows us to
303 set the IP_HDRINCL option to include everything except the Ethernet header in
304 the packets we send and receive.
306 Because only UDP is supported, ICMP traffic will not work, so expect that ping
307 commands will time out.
309 The default device tree for sandbox includes an entry for lo on the sandbox
310 host machine whose alias is "eth5". The following is an example of a network
311 operation being tested on the lo interface.
326 Sandbox supports SPI and SPI flash emulation.
328 The device can be enabled via a device tree, for example::
331 #address-cells = <1>;
334 compatible = "sandbox,spi";
335 cs-gpios = <0>, <&gpio_a 0>;
338 compatible = "spansion,m25p16", "jedec,spi-nor";
339 spi-max-frequency = <40000000>;
340 sandbox,filename = "spi.bin";
344 The file must be created in advance::
346 $ dd if=/dev/zero of=spi.bin bs=1M count=2
349 Here, you can use "-T" or "-D" option to specify test.dtb or u-boot.dtb,
350 respectively, or "-d <file>" for your own dtb.
352 With this setup you can issue SPI flash commands as normal::
355 SF: Detected M25P16 with page size 64 KiB, total 2 MiB
357 SF: 65536 bytes @ 0x0 Read: OK
359 Since this is a full SPI emulation (rather than just flash), you can
360 also use low-level SPI commands::
365 This is issuing a READ_ID command and getting back 20 (ST Micro) part
369 Block Device Emulation
370 ----------------------
372 U-Boot can use raw disk images for block device emulation. To e.g. list
373 the contents of the root directory on the second partion of the image
374 "disk.raw", you can use the following commands::
376 =>host bind 0 ./disk.raw
379 A disk image can be created using the following commands::
381 $> truncate -s 1200M ./disk.raw
382 $> echo -e "label: gpt\n,64M,U\n,,L" | /usr/sbin/sgdisk ./disk.raw
383 $> lodev=`sudo losetup -P -f --show ./disk.raw`
384 $> sudo mkfs.vfat -n EFI -v ${lodev}p1
385 $> sudo mkfs.ext4 -L ROOT -v ${lodev}p2
387 or utilize the device described in test/py/make_test_disk.py::
390 import make_test_disk
391 make_test_disk.makeDisk()
393 Writing Sandbox Drivers
394 -----------------------
396 Generally you should put your driver in a file containing the word 'sandbox'
397 and put it in the same directory as other drivers of its type. You can then
398 implement the same hooks as the other drivers.
400 To access U-Boot's emulated memory, use map_sysmem() as mentioned above.
402 If your driver needs to store configuration or state (such as SPI flash
403 contents or emulated chip registers), you can use the device tree as
404 described above. Define handlers for this with the SANDBOX_STATE_IO macro.
405 See arch/sandbox/include/asm/state.h for documentation. In short you provide
406 a node name, compatible string and functions to read and write the state.
407 Since writing the state can expand the device tree, you may need to use
408 state_setprop() which does this automatically and avoids running out of
409 space. See existing code for examples.
412 Debugging the init sequence
413 ---------------------------
415 If you get a failure in the initcall sequence, like this::
417 initcall sequence 0000560775957c80 failed at call 0000000000048134 (err=-96)
419 Then you use can use grep to see which init call failed, e.g.::
421 $ grep 0000000000048134 u-boot.map
424 Of course another option is to run it with a debugger such as gdb::
428 (gdb) br initcall.h:41
429 Breakpoint 1 at 0x4db9d: initcall.h:41. (2 locations)
431 Note that two locations are reported, since this function is used in both
432 board_init_f() and board_init_r().
437 Starting program: /tmp/b/sandbox/u-boot
438 [Thread debugging using libthread_db enabled]
439 Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
441 U-Boot 2018.09-00264-ge0c2ba9814-dirty (Sep 22 2018 - 12:21:46 -0600)
446 Breakpoint 1, initcall_run_list (init_sequence=0x5555559619e0 <init_sequence_f>)
447 at /scratch/sglass/cosarm/src/third_party/u-boot/files/include/initcall.h:41
448 41 printf("initcall sequence %p failed at call %p (err=%d)\n",
449 (gdb) print *init_fnc_ptr
450 $1 = (const init_fnc_t) 0x55555559c114 <stdio_add_devices>
454 This approach can be used on normal boards as well as sandbox.
460 If sdl-config is on a different path from the default, set the SDL_CONFIG
461 environment variable to the correct pathname before building U-Boot.
464 Using valgrind / memcheck
465 -------------------------
467 It is possible to run U-Boot under valgrind to check memory allocations::
471 If you are running sandbox SPL or TPL, then valgrind will not by default
472 notice when U-Boot jumps from TPL to SPL, or from SPL to U-Boot proper. To
475 valgrind --trace-children=yes u-boot
481 U-Boot sandbox can be used to run various tests, mostly in the test/
482 directory. These include:
485 Unit tests for command parsing and handling
487 Unit tests for U-Boot's compression algorithms, useful for
488 security checking. It supports gzip, bzip2, lzma and lzo.
492 ./test/py/test.py --bd sandbox --build -k ut_dm -v
495 Unit tests for images:
496 test/image/test-imagetools.sh - multi-file images
497 test/image/test-fit.py - FIT images
499 test/trace/test-trace.sh tests the tracing system (see README.trace)
501 See test/vboot/vboot_test.sh for this
503 If you change or enhance any of the above subsystems, you shold write or
504 expand a test and include it with your patch series submission. Test
505 coverage in U-Boot is limited, as we need to work to improve it.
507 Note that many of these tests are implemented as commands which you can
508 run natively on your board if desired (and enabled).
510 To run all tests use "make check".
512 To run a single test in an existing sandbox build, you can use -T to use the
513 test device tree, and -c to select the test:
515 /tmp/b/sandbox/u-boot -T -c "ut dm pci_busdev"
517 This runs dm_test_pci_busdev() which is in test/dm/pci.c
523 Sandbox has its own emulated memory starting at 0. Here are some of the things
524 that are mapped into that memory:
526 ======= ======================== ===============================
528 ======= ======================== ===============================
529 0 CONFIG_SYS_FDT_LOAD_ADDR Device tree
530 e000 CONFIG_BLOBLIST_ADDR Blob list
531 10000 CONFIG_MALLOC_F_ADDR Early memory allocation
532 f0000 CONFIG_PRE_CON_BUF_ADDR Pre-console buffer
533 100000 CONFIG_TRACE_EARLY_ADDR Early trace buffer (if enabled)
534 ======= ======================== ===============================