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 Here are some packages that are worth installing if you are doing sandbox or
47 tools development in U-Boot:
49 python3-pytest lzma lzma-alone lz4 python3 python3-virtualenv
56 To run sandbox U-Boot use something like::
58 make sandbox_defconfig all
61 Note: If you get errors about 'sdl-config: Command not found' you may need to
62 install libsdl2.0-dev or similar to get SDL support. Alternatively you can
63 build sandbox without SDL (i.e. no display/keyboard support) by removing
64 the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using::
66 make sandbox_defconfig all NO_SDL=1
69 U-Boot will start on your computer, showing a sandbox emulation of the serial
72 U-Boot 2014.04 (Mar 20 2014 - 19:06:00)
75 Using default environment
82 You can issue commands as your would normally. If the command you want is
83 not supported you can add it to include/configs/sandbox.h.
85 To exit, type 'poweroff' or press Ctrl-C.
91 Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the
92 sandbox with LCD and keyboard emulation, using something like::
94 ./u-boot -d u-boot.dtb -l
96 This will start U-Boot with a window showing the contents of the LCD. If
97 that window has the focus then you will be able to type commands as you
98 would on the console. You can adjust the display settings in the device
99 tree file - see arch/sandbox/dts/sandbox.dts.
105 Various options are available, mostly for test purposes. Use -h to see
106 available options. Some of these are described below:
109 The terminal is normally in what is called 'raw-with-sigs' mode. This means
110 that you can use arrow keys for command editing and history, but if you
111 press Ctrl-C, U-Boot will exit instead of handling this as a keypress.
112 Other options are 'raw' (so Ctrl-C is handled within U-Boot) and 'cooked'
113 (where the terminal is in cooked mode and cursor keys will not work, Ctrl-C
117 Show the LCD emulation window.
120 A device tree binary file can be provided with -d. If you edit the source
121 (it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to
122 recreate the binary file.
125 To use the default device tree, use -D.
128 To use the test device tree, use -T.
131 To execute commands directly, use the -c option. You can specify a single
132 command, or multiple commands separated by a semicolon, as is normal in
133 U-Boot. Be careful with quoting as the shell will normally process and
134 swallow quotes. When -c is used, U-Boot exits after the command is complete,
135 but you can force it to go to interactive mode instead with -i.
138 Go to interactive mode after executing the commands specified by -c.
140 Environment Variables
141 ---------------------
144 This environment variable stores the offset of the emulated real time clock
145 to the host's real time clock in seconds. The offset defaults to zero.
150 Memory emulation is supported, with the size set by CONFIG_SYS_SDRAM_SIZE.
151 The -m option can be used to read memory from a file on start-up and write
152 it when shutting down. This allows preserving of memory contents across
153 test runs. You can tell U-Boot to remove the memory file after it is read
154 (on start-up) with the --rm_memory option.
156 To access U-Boot's emulated memory within the code, use map_sysmem(). This
157 function is used throughout U-Boot to ensure that emulated memory is used
158 rather than the U-Boot application memory. This provides memory starting
159 at 0 and extending to the size of the emulation.
165 With sandbox you can write drivers which emulate the operation of drivers on
166 real devices. Some of these drivers may want to record state which is
167 preserved across U-Boot runs. This is particularly useful for testing. For
168 example, the contents of a SPI flash chip should not disappear just because
171 State is stored in a device tree file in a simple format which is driver-
172 specific. You then use the -s option to specify the state file. Use -r to
173 make U-Boot read the state on start-up (otherwise it starts empty) and -w
174 to write it on exit (otherwise the stored state is left unchanged and any
175 changes U-Boot made will be lost). You can also use -n to tell U-Boot to
176 ignore any problems with missing state. This is useful when first running
177 since the state file will be empty.
179 The device tree file has one node for each driver - the driver can store
180 whatever properties it likes in there. See 'Writing Sandbox Drivers' below
181 for more details on how to get drivers to read and write their state.
187 Since there is no machine architecture, sandbox U-Boot cannot actually boot
188 a kernel, but it does support the bootm command. Filesystems, memory
189 commands, hashing, FIT images, verified boot and many other features are
192 When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real
193 machine. Of course in this case, no kernel is run.
195 It is also possible to tell U-Boot that it has jumped from a temporary
196 previous U-Boot binary, with the -j option. That binary is automatically
197 removed by the U-Boot that gets the -j option. This allows you to write
198 tests which emulate the action of chain-loading U-Boot, typically used in
199 a situation where a second 'updatable' U-Boot is stored on your board. It
200 is very risky to overwrite or upgrade the only U-Boot on a board, since a
201 power or other failure will brick the board and require return to the
202 manufacturer in the case of a consumer device.
208 U-Boot sandbox supports these emulations:
213 - Host filesystem (access files on the host from within U-Boot)
215 - Keyboard (Chrome OS)
218 - Serial (for console only)
219 - Sound (incomplete - see sandbox_sdl_sound_init() for details)
222 - TPM (Trusted Platform Module)
224 A wide range of commands are implemented. Filesystems which use a block
225 device are supported.
227 Also sandbox supports driver model (CONFIG_DM) and associated commands.
233 There are unfortunately quite a few variants at present:
236 should be used for most tests
238 special build that forces a 64-bit host
240 builds with dev_read\_...() functions defined as inline.
241 We need this build so that we can test those inline functions, and we
242 cannot build with both the inline functions and the non-inline functions
243 since they are named the same.
245 builds sandbox with SPL support, so you can run spl/u-boot-spl
246 and it will start up and then load ./u-boot. It is also possible to
247 run ./u-boot directly.
249 Of these sandbox_spl can probably be removed since it is a superset of sandbox.
251 Most of the config options should be identical between these variants.
254 Linux RAW Networking Bridge
255 ---------------------------
257 The sandbox_eth_raw driver bridges traffic between the bottom of the network
258 stack and the RAW sockets API in Linux. This allows much of the U-Boot network
259 functionality to be tested in sandbox against real network traffic.
261 For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API. This
262 is needed to get access to the lowest level of the network stack in Linux. This
263 means that all of the Ethernet frame is included. This allows the U-Boot network
264 stack to be fully used. In other words, nothing about the Linux network stack is
265 involved in forming the packets that end up on the wire. To receive the
266 responses to packets sent from U-Boot the network interface has to be set to
267 promiscuous mode so that the network card won't filter out packets not destined
268 for its configured (on Linux) MAC address.
270 The RAW sockets Ethernet API requires elevated privileges in Linux. You can
271 either run as root, or you can add the capability needed like so::
273 sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot
275 The default device tree for sandbox includes an entry for eth0 on the sandbox
276 host machine whose alias is "eth1". The following are a few examples of network
277 operations being tested on the eth0 interface.
281 sudo /path/to/u-boot -D
307 setenv serverip WWW.XXX.YYY.ZZZ
310 The bridge also supports (to a lesser extent) the localhost interface, 'lo'.
312 The 'lo' interface cannot use the RAW AF_PACKET API because the lo interface
313 doesn't support Ethernet-level traffic. It is a higher-level interface that is
314 expected only to be used at the AF_INET level of the API. As such, the most raw
315 we can get on that interface is the RAW AF_INET API on UDP. This allows us to
316 set the IP_HDRINCL option to include everything except the Ethernet header in
317 the packets we send and receive.
319 Because only UDP is supported, ICMP traffic will not work, so expect that ping
320 commands will time out.
322 The default device tree for sandbox includes an entry for lo on the sandbox
323 host machine whose alias is "eth5". The following is an example of a network
324 operation being tested on the lo interface.
339 Sandbox supports SPI and SPI flash emulation.
341 The device can be enabled via a device tree, for example::
344 #address-cells = <1>;
347 compatible = "sandbox,spi";
348 cs-gpios = <0>, <&gpio_a 0>;
351 compatible = "spansion,m25p16", "jedec,spi-nor";
352 spi-max-frequency = <40000000>;
353 sandbox,filename = "spi.bin";
357 The file must be created in advance::
359 $ dd if=/dev/zero of=spi.bin bs=1M count=2
362 Here, you can use "-T" or "-D" option to specify test.dtb or u-boot.dtb,
363 respectively, or "-d <file>" for your own dtb.
365 With this setup you can issue SPI flash commands as normal::
368 SF: Detected M25P16 with page size 64 KiB, total 2 MiB
370 SF: 65536 bytes @ 0x0 Read: OK
372 Since this is a full SPI emulation (rather than just flash), you can
373 also use low-level SPI commands::
378 This is issuing a READ_ID command and getting back 20 (ST Micro) part
382 Block Device Emulation
383 ----------------------
385 U-Boot can use raw disk images for block device emulation. To e.g. list
386 the contents of the root directory on the second partion of the image
387 "disk.raw", you can use the following commands::
389 =>host bind 0 ./disk.raw
392 The device can be marked removeable with 'host bind -r'.
394 A disk image can be created using the following commands::
396 $> truncate -s 1200M ./disk.raw
397 $> echo -e "label: gpt\n,64M,U\n,,L" | /usr/sbin/sgdisk ./disk.raw
398 $> lodev=`sudo losetup -P -f --show ./disk.raw`
399 $> sudo mkfs.vfat -n EFI -v ${lodev}p1
400 $> sudo mkfs.ext4 -L ROOT -v ${lodev}p2
402 or utilize the device described in test/py/make_test_disk.py::
405 import make_test_disk
406 make_test_disk.makeDisk()
408 Writing Sandbox Drivers
409 -----------------------
411 Generally you should put your driver in a file containing the word 'sandbox'
412 and put it in the same directory as other drivers of its type. You can then
413 implement the same hooks as the other drivers.
415 To access U-Boot's emulated memory, use map_sysmem() as mentioned above.
417 If your driver needs to store configuration or state (such as SPI flash
418 contents or emulated chip registers), you can use the device tree as
419 described above. Define handlers for this with the SANDBOX_STATE_IO macro.
420 See arch/sandbox/include/asm/state.h for documentation. In short you provide
421 a node name, compatible string and functions to read and write the state.
422 Since writing the state can expand the device tree, you may need to use
423 state_setprop() which does this automatically and avoids running out of
424 space. See existing code for examples.
427 Debugging the init sequence
428 ---------------------------
430 If you get a failure in the initcall sequence, like this::
432 initcall sequence 0000560775957c80 failed at call 0000000000048134 (err=-96)
434 Then you use can use grep to see which init call failed, e.g.::
436 $ grep 0000000000048134 u-boot.map
439 Of course another option is to run it with a debugger such as gdb::
443 (gdb) br initcall.h:41
444 Breakpoint 1 at 0x4db9d: initcall.h:41. (2 locations)
446 Note that two locations are reported, since this function is used in both
447 board_init_f() and board_init_r().
452 Starting program: /tmp/b/sandbox/u-boot
453 [Thread debugging using libthread_db enabled]
454 Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
456 U-Boot 2018.09-00264-ge0c2ba9814-dirty (Sep 22 2018 - 12:21:46 -0600)
461 Breakpoint 1, initcall_run_list (init_sequence=0x5555559619e0 <init_sequence_f>)
462 at /scratch/sglass/cosarm/src/third_party/u-boot/files/include/initcall.h:41
463 41 printf("initcall sequence %p failed at call %p (err=%d)\n",
464 (gdb) print *init_fnc_ptr
465 $1 = (const init_fnc_t) 0x55555559c114 <stdio_add_devices>
469 This approach can be used on normal boards as well as sandbox.
475 If sdl-config is on a different path from the default, set the SDL_CONFIG
476 environment variable to the correct pathname before building U-Boot.
479 Using valgrind / memcheck
480 -------------------------
482 It is possible to run U-Boot under valgrind to check memory allocations::
486 If you are running sandbox SPL or TPL, then valgrind will not by default
487 notice when U-Boot jumps from TPL to SPL, or from SPL to U-Boot proper. To
490 valgrind --trace-children=yes u-boot
496 U-Boot sandbox can be used to run various tests, mostly in the test/
499 See :doc:`../develop/tests_sandbox` for more information and
500 :doc:`../develop/testing` for information about testing generally.
506 Sandbox has its own emulated memory starting at 0. Here are some of the things
507 that are mapped into that memory:
509 ======= ======================== ===============================
511 ======= ======================== ===============================
512 0 CONFIG_SYS_FDT_LOAD_ADDR Device tree
513 c000 CONFIG_BLOBLIST_ADDR Blob list
514 10000 CONFIG_MALLOC_F_ADDR Early memory allocation
515 f0000 CONFIG_PRE_CON_BUF_ADDR Pre-console buffer
516 100000 CONFIG_TRACE_EARLY_ADDR Early trace buffer (if enabled). Also used
517 as the SPL load buffer in spl_test_load().
518 200000 CONFIG_SYS_TEXT_BASE Load buffer for U-Boot (sandbox_spl only)
519 ======= ======================== ===============================