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 Sandbox allows development of many types of new features in a traditional way,
21 rather than needing to test each iteration on real hardware. Many U-Boot
22 features were developed on sandbox, including the core driver model, most
23 uclasses, verified boot, bloblist, logging and dozens of others. Sandbox has
24 enabled many large-scale code refactors as well.
26 CONFIG_SANDBOX is defined when building a native board.
28 The board name is 'sandbox' but the vendor name is unset, so there is a
29 single board in board/sandbox.
31 CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian
34 There are two versions of the sandbox: One using 32-bit-wide integers, and one
35 using 64-bit-wide integers. The 32-bit version can be build and run on either
36 32 or 64-bit hosts by either selecting or deselecting CONFIG_SANDBOX_32BIT; by
37 default, the sandbox it built for a 32-bit host. The sandbox using 64-bit-wide
38 integers can only be built on 64-bit hosts.
40 Note that standalone/API support is not available at present.
46 Install the dependencies noted in :doc:`../build/gcc`.
52 To run sandbox U-Boot use something like::
54 make sandbox_defconfig all
57 Note: If you get errors about 'sdl-config: Command not found' you may need to
58 install libsdl2.0-dev or similar to get SDL support. Alternatively you can
59 build sandbox without SDL (i.e. no display/keyboard support) by removing
60 the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using::
62 make sandbox_defconfig all NO_SDL=1
65 U-Boot will start on your computer, showing a sandbox emulation of the serial
68 U-Boot 2014.04 (Mar 20 2014 - 19:06:00)
71 Using default environment
78 You can issue commands as your would normally. If the command you want is
79 not supported you can add it to include/configs/sandbox.h.
81 To exit, type 'poweroff' or press Ctrl-C.
87 Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the
88 sandbox with LCD and keyboard emulation, using something like::
90 ./u-boot -d u-boot.dtb -l
92 This will start U-Boot with a window showing the contents of the LCD. If
93 that window has the focus then you will be able to type commands as you
94 would on the console. You can adjust the display settings in the device
95 tree file - see arch/sandbox/dts/sandbox.dts.
101 Various options are available, mostly for test purposes. Use -h to see
102 available options. Some of these are described below:
105 The terminal is normally in what is called 'raw-with-sigs' mode. This means
106 that you can use arrow keys for command editing and history, but if you
107 press Ctrl-C, U-Boot will exit instead of handling this as a keypress.
108 Other options are 'raw' (so Ctrl-C is handled within U-Boot) and 'cooked'
109 (where the terminal is in cooked mode and cursor keys will not work, Ctrl-C
113 Show the LCD emulation window.
116 A device tree binary file can be provided with -d. If you edit the source
117 (it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to
118 recreate the binary file.
121 To use the default device tree, use -D.
124 To use the test device tree, use -T.
127 To execute commands directly, use the -c option. You can specify a single
128 command, or multiple commands separated by a semicolon, as is normal in
129 U-Boot. Be careful with quoting as the shell will normally process and
130 swallow quotes. When -c is used, U-Boot exits after the command is complete,
131 but you can force it to go to interactive mode instead with -i.
134 Go to interactive mode after executing the commands specified by -c.
136 Environment Variables
137 ---------------------
140 This environment variable stores the offset of the emulated real time clock
141 to the host's real time clock in seconds. The offset defaults to zero.
146 Memory emulation is supported, with the size set by CONFIG_SANDBOX_RAM_SIZE_MB.
147 The -m option can be used to read memory from a file on start-up and write
148 it when shutting down. This allows preserving of memory contents across
149 test runs. You can tell U-Boot to remove the memory file after it is read
150 (on start-up) with the --rm_memory option.
152 To access U-Boot's emulated memory within the code, use map_sysmem(). This
153 function is used throughout U-Boot to ensure that emulated memory is used
154 rather than the U-Boot application memory. This provides memory starting
155 at 0 and extending to the size of the emulation.
161 With sandbox you can write drivers which emulate the operation of drivers on
162 real devices. Some of these drivers may want to record state which is
163 preserved across U-Boot runs. This is particularly useful for testing. For
164 example, the contents of a SPI flash chip should not disappear just because
167 State is stored in a device tree file in a simple format which is driver-
168 specific. You then use the -s option to specify the state file. Use -r to
169 make U-Boot read the state on start-up (otherwise it starts empty) and -w
170 to write it on exit (otherwise the stored state is left unchanged and any
171 changes U-Boot made will be lost). You can also use -n to tell U-Boot to
172 ignore any problems with missing state. This is useful when first running
173 since the state file will be empty.
175 The device tree file has one node for each driver - the driver can store
176 whatever properties it likes in there. See 'Writing Sandbox Drivers' below
177 for more details on how to get drivers to read and write their state.
183 Since there is no machine architecture, sandbox U-Boot cannot actually boot
184 a kernel, but it does support the bootm command. Filesystems, memory
185 commands, hashing, FIT images, verified boot and many other features are
188 When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real
189 machine. Of course in this case, no kernel is run.
191 It is also possible to tell U-Boot that it has jumped from a temporary
192 previous U-Boot binary, with the -j option. That binary is automatically
193 removed by the U-Boot that gets the -j option. This allows you to write
194 tests which emulate the action of chain-loading U-Boot, typically used in
195 a situation where a second 'updatable' U-Boot is stored on your board. It
196 is very risky to overwrite or upgrade the only U-Boot on a board, since a
197 power or other failure will brick the board and require return to the
198 manufacturer in the case of a consumer device.
204 U-Boot sandbox supports these emulations:
209 - Host filesystem (access files on the host from within U-Boot)
211 - Keyboard (Chrome OS)
214 - Serial (for console only)
215 - Sound (incomplete - see sandbox_sdl_sound_init() for details)
218 - TPM (Trusted Platform Module)
220 A wide range of commands are implemented. Filesystems which use a block
221 device are supported.
223 Also sandbox supports driver model (CONFIG_DM) and associated commands.
229 There are unfortunately quite a few variants at present:
232 should be used for most tests
234 special build that forces a 64-bit host
236 builds with dev_read\_...() functions defined as inline.
237 We need this build so that we can test those inline functions, and we
238 cannot build with both the inline functions and the non-inline functions
239 since they are named the same.
241 builds sandbox with SPL support, so you can run spl/u-boot-spl
242 and it will start up and then load ./u-boot. It is also possible to
243 run ./u-boot directly.
245 Of these sandbox_spl can probably be removed since it is a superset of sandbox.
247 Most of the config options should be identical between these variants.
250 Linux RAW Networking Bridge
251 ---------------------------
253 The sandbox_eth_raw driver bridges traffic between the bottom of the network
254 stack and the RAW sockets API in Linux. This allows much of the U-Boot network
255 functionality to be tested in sandbox against real network traffic.
257 For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API. This
258 is needed to get access to the lowest level of the network stack in Linux. This
259 means that all of the Ethernet frame is included. This allows the U-Boot network
260 stack to be fully used. In other words, nothing about the Linux network stack is
261 involved in forming the packets that end up on the wire. To receive the
262 responses to packets sent from U-Boot the network interface has to be set to
263 promiscuous mode so that the network card won't filter out packets not destined
264 for its configured (on Linux) MAC address.
266 The RAW sockets Ethernet API requires elevated privileges in Linux. You can
267 either run as root, or you can add the capability needed like so::
269 sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot
271 The default device tree for sandbox includes an entry for eth0 on the sandbox
272 host machine whose alias is "eth1". The following are a few examples of network
273 operations being tested on the eth0 interface.
277 sudo /path/to/u-boot -D
303 setenv serverip WWW.XXX.YYY.ZZZ
306 The bridge also supports (to a lesser extent) the localhost interface, 'lo'.
308 The 'lo' interface cannot use the RAW AF_PACKET API because the lo interface
309 doesn't support Ethernet-level traffic. It is a higher-level interface that is
310 expected only to be used at the AF_INET level of the API. As such, the most raw
311 we can get on that interface is the RAW AF_INET API on UDP. This allows us to
312 set the IP_HDRINCL option to include everything except the Ethernet header in
313 the packets we send and receive.
315 Because only UDP is supported, ICMP traffic will not work, so expect that ping
316 commands will time out.
318 The default device tree for sandbox includes an entry for lo on the sandbox
319 host machine whose alias is "eth5". The following is an example of a network
320 operation being tested on the lo interface.
335 Sandbox supports SPI and SPI flash emulation.
337 The device can be enabled via a device tree, for example::
340 #address-cells = <1>;
343 compatible = "sandbox,spi";
344 cs-gpios = <0>, <&gpio_a 0>;
347 compatible = "spansion,m25p16", "jedec,spi-nor";
348 spi-max-frequency = <40000000>;
349 sandbox,filename = "spi.bin";
353 The file must be created in advance::
355 $ dd if=/dev/zero of=spi.bin bs=1M count=2
358 Here, you can use "-T" or "-D" option to specify test.dtb or u-boot.dtb,
359 respectively, or "-d <file>" for your own dtb.
361 With this setup you can issue SPI flash commands as normal::
364 SF: Detected M25P16 with page size 64 KiB, total 2 MiB
366 SF: 65536 bytes @ 0x0 Read: OK
368 Since this is a full SPI emulation (rather than just flash), you can
369 also use low-level SPI commands::
374 This is issuing a READ_ID command and getting back 20 (ST Micro) part
378 Block Device Emulation
379 ----------------------
381 U-Boot can use raw disk images for block device emulation. To e.g. list
382 the contents of the root directory on the second partion of the image
383 "disk.raw", you can use the following commands::
385 =>host bind 0 ./disk.raw
388 The device can be marked removeable with 'host bind -r'.
390 A disk image can be created using the following commands::
392 $> truncate -s 1200M ./disk.raw
393 $> echo -e "label: gpt\n,64M,U\n,,L" | /usr/sbin/sgdisk ./disk.raw
394 $> lodev=`sudo losetup -P -f --show ./disk.raw`
395 $> sudo mkfs.vfat -n EFI -v ${lodev}p1
396 $> sudo mkfs.ext4 -L ROOT -v ${lodev}p2
398 or utilize the device described in test/py/make_test_disk.py::
401 import make_test_disk
402 make_test_disk.makeDisk()
404 Writing Sandbox Drivers
405 -----------------------
407 Generally you should put your driver in a file containing the word 'sandbox'
408 and put it in the same directory as other drivers of its type. You can then
409 implement the same hooks as the other drivers.
411 To access U-Boot's emulated memory, use map_sysmem() as mentioned above.
413 If your driver needs to store configuration or state (such as SPI flash
414 contents or emulated chip registers), you can use the device tree as
415 described above. Define handlers for this with the SANDBOX_STATE_IO macro.
416 See arch/sandbox/include/asm/state.h for documentation. In short you provide
417 a node name, compatible string and functions to read and write the state.
418 Since writing the state can expand the device tree, you may need to use
419 state_setprop() which does this automatically and avoids running out of
420 space. See existing code for examples.
423 VPL (Verifying Program Loader)
424 ------------------------------
426 Sandbox provides an example build of vpl called `sandbox_vpl`. This can be run
429 /path/to/sandbox_vpl/tpl/u-boot-tpl -D
431 It starts up TPL (first-stage init), then VPL, then runs SPL and finally U-Boot
432 proper, following the normal flow for a verified boot. At present, no
433 verification is actually implemented.
436 Debugging the init sequence
437 ---------------------------
439 If you get a failure in the initcall sequence, like this::
441 initcall sequence 0000560775957c80 failed at call 0000000000048134 (err=-96)
443 Then you use can use grep to see which init call failed, e.g.::
445 $ grep 0000000000048134 u-boot.map
448 Of course another option is to run it with a debugger such as gdb::
452 (gdb) br initcall.h:41
453 Breakpoint 1 at 0x4db9d: initcall.h:41. (2 locations)
455 Note that two locations are reported, since this function is used in both
456 board_init_f() and board_init_r().
461 Starting program: /tmp/b/sandbox/u-boot
462 [Thread debugging using libthread_db enabled]
463 Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
465 U-Boot 2018.09-00264-ge0c2ba9814-dirty (Sep 22 2018 - 12:21:46 -0600)
470 Breakpoint 1, initcall_run_list (init_sequence=0x5555559619e0 <init_sequence_f>)
471 at /scratch/sglass/cosarm/src/third_party/u-boot/files/include/initcall.h:41
472 41 printf("initcall sequence %p failed at call %p (err=%d)\n",
473 (gdb) print *init_fnc_ptr
474 $1 = (const init_fnc_t) 0x55555559c114 <stdio_add_devices>
478 This approach can be used on normal boards as well as sandbox.
480 For debugging with GDB or LLDB, it is preferable to reduce the compiler
481 optimization level (CONFIG_CC_OPTIMIZE_FOR_DEBUG=y) and to disable Link Time
482 Optimization (CONFIG_LTO=n).
487 If sdl-config is on a different path from the default, set the SDL_CONFIG
488 environment variable to the correct pathname before building U-Boot.
491 Using valgrind / memcheck
492 -------------------------
494 It is possible to run U-Boot under valgrind to check memory allocations::
498 However, this does not give very useful results. The sandbox allocates a memory
499 pool via mmap(). U-Boot's internal malloc() and free() work on this memory pool.
500 Custom allocators and deallocators are invisible to valgrind by default. To
501 expose U-Boot's malloc() and free() to valgrind, enable ``CONFIG_VALGRIND``.
502 Enabling this option will inject placeholder assembler code which valgrind
503 interprets. This is used to annotate sections of memory as safe or unsafe, and
504 to inform valgrind about malloc()s and free()s. There are currently no standard
505 placeholder assembly sequences for RISC-V, so this option cannot be enabled on
508 Malloc's bookkeeping information is marked as unsafe by default. However, this
509 will generate many false positives when malloc itself accesses this information.
510 These warnings can be suppressed with::
512 valgrind --suppressions=scripts/u-boot.supp ./u-boot
514 Additionally, you may experience false positives if U-Boot is using a smaller
515 pointer size than your host architecture. This is because the pointers used by
516 U-Boot will only contain 32 bits of addressing information. When interpreted as
517 64-bit pointers, valgrind will think that they are not initialized properly. To
518 fix this, enable ``CONFIG_SANDBOX64`` (such as via ``sandbox64_defconfig``)
519 when running on a 64-bit host.
524 The following valgrind options are useful in addition to the above examples:
526 ``--trace-childen=yes``
527 tells valgrind to keep tracking subprocesses, such
528 as when U-Boot jumps from TPL to SPL, or from SPL to U-Boot proper.
530 ``--track-origins=yes``
531 will (for a small overhead) tell valgrind to keep
532 track of who allocated some troublesome memory.
535 will enable printing more than 1000 errors in a single session.
537 ``--vgdb=yes --vgdb-error=0``
538 will let you use GDB to attach like::
540 gdb -ex "target remote | vgdb" u-boot
542 This is very helpful for inspecting the program state when there is
545 The following U-Boot option are also helpful:
548 lets U-Boot run unit tests automatically. Note
549 that not all unit tests will succeed in the default configuration.
552 will keep the console in a sane state if you
553 terminate it early (instead of having to run tset).
558 The biggest limitation to the current approach is that supressions don't
559 "un-taint" uninitialized memory accesses. Currently, dlmalloc's bookkeeping
560 information is marked as a "red zone." This means that all reads to that zone
561 are marked as illegal by valgrind. This is fine for regular code, but dlmalloc
562 really does need to access this area, so we suppress its violations. However, if
563 dlmalloc then passes a result calculated from a "tainted" access, that result is
564 still tainted. So the first accessor will raise a warning. This means that every
569 foo = malloc(sizeof(*foo));
573 will raise a warning when we check the result of malloc. Whoops.
575 There are at least four possible ways to address this:
577 * Don't mark dlmalloc bookkeeping information as a red zone. This is the
578 simplest solution, but reduces the power of valgrind immensely, since we can
579 no longer determine that (e.g.) access past the end of an array is undefined.
580 * Implement red zones properly. This would involve growing every allocation by a
581 fixed amount (16 bytes or so) and then using that extra space for a real red
582 zone that neither regular code nor dlmalloc needs to access. Unfortunately,
583 this would probably some fairly intensive surgery to dlmalloc to add/remove
584 the offset appropriately.
585 * Mark bookkeeping information as valid before we use it in dlmalloc, and then
586 mark it invalid before returning. This would be the most correct, but it would
587 be very tricky to implement since there are so many code paths to mark. I
588 think it would be the most effort out of the three options here.
589 * Use the host malloc and free instead of U-Boot's custom allocator. This will
590 eliminate the need to annotate dlmalloc. However, using a different allocator
591 for sandbox will mean that bugs in dlmalloc will only be tested when running
592 on read (or emulated) hardware.
594 Until one of the above options are implemented, it will remain difficult
595 to sift through the massive amount of spurious warnings.
600 U-Boot sandbox can be used to run various tests, mostly in the test/
603 See :doc:`../develop/tests_sandbox` for more information and
604 :doc:`../develop/testing` for information about testing generally.
610 Sandbox has its own emulated memory starting at 0. Here are some of the things
611 that are mapped into that memory:
613 ======= ======================== ===============================
615 ======= ======================== ===============================
616 0 CONFIG_SYS_FDT_LOAD_ADDR Device tree
617 c000 CONFIG_BLOBLIST_ADDR Blob list
618 10000 CONFIG_MALLOC_F_ADDR Early memory allocation
619 f0000 CONFIG_PRE_CON_BUF_ADDR Pre-console buffer
620 100000 CONFIG_TRACE_EARLY_ADDR Early trace buffer (if enabled). Also used
621 as the SPL load buffer in spl_test_load().
622 200000 CONFIG_TEXT_BASE Load buffer for U-Boot (sandbox_spl only)
623 ======= ======================== ===============================