1.. SPDX-License-Identifier: GPL-2.0+ */ 2.. Copyright (c) 2014 The Chromium OS Authors. 3.. sectionauthor:: Simon Glass <sjg@chromium.org> 4 5Sandbox 6======= 7 8Native Execution of U-Boot 9-------------------------- 10 11The 'sandbox' architecture is designed to allow U-Boot to run under Linux on 12almost any hardware. To achieve this it builds U-Boot (so far as possible) 13as a normal C application with a main() and normal C libraries. 14 15All of U-Boot's architecture-specific code therefore cannot be built as part 16of the sandbox U-Boot. The purpose of running U-Boot under Linux is to test 17all the generic code, not specific to any one architecture. The idea is to 18create unit tests which we can run to test this upper level code. 19 20Sandbox allows development of many types of new features in a traditional way, 21rather than needing to test each iteration on real hardware. Many U-Boot 22features were developed on sandbox, including the core driver model, most 23uclasses, verified boot, bloblist, logging and dozens of others. Sandbox has 24enabled many large-scale code refactors as well. 25 26CONFIG_SANDBOX is defined when building a native board. 27 28The board name is 'sandbox' but the vendor name is unset, so there is a 29single board in board/sandbox. 30 31CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian 32machines. 33 34There are two versions of the sandbox: One using 32-bit-wide integers, and one 35using 64-bit-wide integers. The 32-bit version can be build and run on either 3632 or 64-bit hosts by either selecting or deselecting CONFIG_SANDBOX_32BIT; by 37default, the sandbox it built for a 32-bit host. The sandbox using 64-bit-wide 38integers can only be built on 64-bit hosts. 39 40Note that standalone/API support is not available at present. 41 42 43Prerequisites 44------------- 45 46Here are some packages that are worth installing if you are doing sandbox or 47tools development in U-Boot: 48 49 python3-pytest lzma lzma-alone lz4 python3 python3-virtualenv 50 libssl1.0-dev 51 52 53Basic Operation 54--------------- 55 56To run sandbox U-Boot use something like:: 57 58 make sandbox_defconfig all 59 ./u-boot 60 61Note: If you get errors about 'sdl-config: Command not found' you may need to 62install libsdl2.0-dev or similar to get SDL support. Alternatively you can 63build sandbox without SDL (i.e. no display/keyboard support) by removing 64the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using:: 65 66 make sandbox_defconfig all NO_SDL=1 67 ./u-boot 68 69U-Boot will start on your computer, showing a sandbox emulation of the serial 70console:: 71 72 U-Boot 2014.04 (Mar 20 2014 - 19:06:00) 73 74 DRAM: 128 MiB 75 Using default environment 76 77 In: serial 78 Out: lcd 79 Err: lcd 80 => 81 82You can issue commands as your would normally. If the command you want is 83not supported you can add it to include/configs/sandbox.h. 84 85To exit, type 'poweroff' or press Ctrl-C. 86 87 88Console / LCD support 89--------------------- 90 91Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the 92sandbox with LCD and keyboard emulation, using something like:: 93 94 ./u-boot -d u-boot.dtb -l 95 96This will start U-Boot with a window showing the contents of the LCD. If 97that window has the focus then you will be able to type commands as you 98would on the console. You can adjust the display settings in the device 99tree file - see arch/sandbox/dts/sandbox.dts. 100 101 102Command-line Options 103-------------------- 104 105Various options are available, mostly for test purposes. Use -h to see 106available options. Some of these are described below: 107 108-t, --terminal <arg> 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 114 will exit). 115 116-l 117 Show the LCD emulation window. 118 119-d <device_tree> 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. 123 124-D 125 To use the default device tree, use -D. 126 127-T 128 To use the test device tree, use -T. 129 130-c [<cmd>;]<cmd> 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. 136 137-i 138 Go to interactive mode after executing the commands specified by -c. 139 140Environment Variables 141--------------------- 142 143UBOOT_SB_TIME_OFFSET 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. 146 147Memory Emulation 148---------------- 149 150Memory emulation is supported, with the size set by CONFIG_SYS_SDRAM_SIZE. 151The -m option can be used to read memory from a file on start-up and write 152it when shutting down. This allows preserving of memory contents across 153test runs. You can tell U-Boot to remove the memory file after it is read 154(on start-up) with the --rm_memory option. 155 156To access U-Boot's emulated memory within the code, use map_sysmem(). This 157function is used throughout U-Boot to ensure that emulated memory is used 158rather than the U-Boot application memory. This provides memory starting 159at 0 and extending to the size of the emulation. 160 161 162Storing State 163------------- 164 165With sandbox you can write drivers which emulate the operation of drivers on 166real devices. Some of these drivers may want to record state which is 167preserved across U-Boot runs. This is particularly useful for testing. For 168example, the contents of a SPI flash chip should not disappear just because 169U-Boot exits. 170 171State is stored in a device tree file in a simple format which is driver- 172specific. You then use the -s option to specify the state file. Use -r to 173make U-Boot read the state on start-up (otherwise it starts empty) and -w 174to write it on exit (otherwise the stored state is left unchanged and any 175changes U-Boot made will be lost). You can also use -n to tell U-Boot to 176ignore any problems with missing state. This is useful when first running 177since the state file will be empty. 178 179The device tree file has one node for each driver - the driver can store 180whatever properties it likes in there. See 'Writing Sandbox Drivers' below 181for more details on how to get drivers to read and write their state. 182 183 184Running and Booting 185------------------- 186 187Since there is no machine architecture, sandbox U-Boot cannot actually boot 188a kernel, but it does support the bootm command. Filesystems, memory 189commands, hashing, FIT images, verified boot and many other features are 190supported. 191 192When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real 193machine. Of course in this case, no kernel is run. 194 195It is also possible to tell U-Boot that it has jumped from a temporary 196previous U-Boot binary, with the -j option. That binary is automatically 197removed by the U-Boot that gets the -j option. This allows you to write 198tests which emulate the action of chain-loading U-Boot, typically used in 199a situation where a second 'updatable' U-Boot is stored on your board. It 200is very risky to overwrite or upgrade the only U-Boot on a board, since a 201power or other failure will brick the board and require return to the 202manufacturer in the case of a consumer device. 203 204 205Supported Drivers 206----------------- 207 208U-Boot sandbox supports these emulations: 209 210- Block devices 211- Chrome OS EC 212- GPIO 213- Host filesystem (access files on the host from within U-Boot) 214- I2C 215- Keyboard (Chrome OS) 216- LCD 217- Network 218- Serial (for console only) 219- Sound (incomplete - see sandbox_sdl_sound_init() for details) 220- SPI 221- SPI flash 222- TPM (Trusted Platform Module) 223 224A wide range of commands are implemented. Filesystems which use a block 225device are supported. 226 227Also sandbox supports driver model (CONFIG_DM) and associated commands. 228 229 230Sandbox Variants 231---------------- 232 233There are unfortunately quite a few variants at present: 234 235sandbox: 236 should be used for most tests 237sandbox64: 238 special build that forces a 64-bit host 239sandbox_flattree: 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. 244sandbox_spl: 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. 248 249Of these sandbox_spl can probably be removed since it is a superset of sandbox. 250 251Most of the config options should be identical between these variants. 252 253 254Linux RAW Networking Bridge 255--------------------------- 256 257The sandbox_eth_raw driver bridges traffic between the bottom of the network 258stack and the RAW sockets API in Linux. This allows much of the U-Boot network 259functionality to be tested in sandbox against real network traffic. 260 261For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API. This 262is needed to get access to the lowest level of the network stack in Linux. This 263means that all of the Ethernet frame is included. This allows the U-Boot network 264stack to be fully used. In other words, nothing about the Linux network stack is 265involved in forming the packets that end up on the wire. To receive the 266responses to packets sent from U-Boot the network interface has to be set to 267promiscuous mode so that the network card won't filter out packets not destined 268for its configured (on Linux) MAC address. 269 270The RAW sockets Ethernet API requires elevated privileges in Linux. You can 271either run as root, or you can add the capability needed like so:: 272 273 sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot 274 275The default device tree for sandbox includes an entry for eth0 on the sandbox 276host machine whose alias is "eth1". The following are a few examples of network 277operations being tested on the eth0 interface. 278 279.. code-block:: none 280 281 sudo /path/to/u-boot -D 282 283 DHCP 284 .... 285 286 setenv autoload no 287 setenv ethrotate no 288 setenv ethact eth1 289 dhcp 290 291 PING 292 .... 293 294 setenv autoload no 295 setenv ethrotate no 296 setenv ethact eth1 297 dhcp 298 ping $gatewayip 299 300 TFTP 301 .... 302 303 setenv autoload no 304 setenv ethrotate no 305 setenv ethact eth1 306 dhcp 307 setenv serverip WWW.XXX.YYY.ZZZ 308 tftpboot u-boot.bin 309 310The bridge also supports (to a lesser extent) the localhost interface, 'lo'. 311 312The 'lo' interface cannot use the RAW AF_PACKET API because the lo interface 313doesn't support Ethernet-level traffic. It is a higher-level interface that is 314expected only to be used at the AF_INET level of the API. As such, the most raw 315we can get on that interface is the RAW AF_INET API on UDP. This allows us to 316set the IP_HDRINCL option to include everything except the Ethernet header in 317the packets we send and receive. 318 319Because only UDP is supported, ICMP traffic will not work, so expect that ping 320commands will time out. 321 322The default device tree for sandbox includes an entry for lo on the sandbox 323host machine whose alias is "eth5". The following is an example of a network 324operation being tested on the lo interface. 325 326.. code-block:: none 327 328 TFTP 329 .... 330 331 setenv ethrotate no 332 setenv ethact eth5 333 tftpboot u-boot.bin 334 335 336SPI Emulation 337------------- 338 339Sandbox supports SPI and SPI flash emulation. 340 341The device can be enabled via a device tree, for example:: 342 343 spi@0 { 344 #address-cells = <1>; 345 #size-cells = <0>; 346 reg = <0 1>; 347 compatible = "sandbox,spi"; 348 cs-gpios = <0>, <&gpio_a 0>; 349 spi.bin@0 { 350 reg = <0>; 351 compatible = "spansion,m25p16", "jedec,spi-nor"; 352 spi-max-frequency = <40000000>; 353 sandbox,filename = "spi.bin"; 354 }; 355 }; 356 357The file must be created in advance:: 358 359 $ dd if=/dev/zero of=spi.bin bs=1M count=2 360 $ u-boot -T 361 362Here, you can use "-T" or "-D" option to specify test.dtb or u-boot.dtb, 363respectively, or "-d <file>" for your own dtb. 364 365With this setup you can issue SPI flash commands as normal:: 366 367 =>sf probe 368 SF: Detected M25P16 with page size 64 KiB, total 2 MiB 369 =>sf read 0 0 10000 370 SF: 65536 bytes @ 0x0 Read: OK 371 372Since this is a full SPI emulation (rather than just flash), you can 373also use low-level SPI commands:: 374 375 =>sspi 0:0 32 9f 376 FF202015 377 378This is issuing a READ_ID command and getting back 20 (ST Micro) part 3790x2015 (the M25P16). 380 381 382Block Device Emulation 383---------------------- 384 385U-Boot can use raw disk images for block device emulation. To e.g. list 386the contents of the root directory on the second partion of the image 387"disk.raw", you can use the following commands:: 388 389 =>host bind 0 ./disk.raw 390 =>ls host 0:2 391 392The device can be marked removeable with 'host bind -r'. 393 394A disk image can be created using the following commands:: 395 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 401 402or utilize the device described in test/py/make_test_disk.py:: 403 404 #!/usr/bin/python 405 import make_test_disk 406 make_test_disk.makeDisk() 407 408Writing Sandbox Drivers 409----------------------- 410 411Generally you should put your driver in a file containing the word 'sandbox' 412and put it in the same directory as other drivers of its type. You can then 413implement the same hooks as the other drivers. 414 415To access U-Boot's emulated memory, use map_sysmem() as mentioned above. 416 417If your driver needs to store configuration or state (such as SPI flash 418contents or emulated chip registers), you can use the device tree as 419described above. Define handlers for this with the SANDBOX_STATE_IO macro. 420See arch/sandbox/include/asm/state.h for documentation. In short you provide 421a node name, compatible string and functions to read and write the state. 422Since writing the state can expand the device tree, you may need to use 423state_setprop() which does this automatically and avoids running out of 424space. See existing code for examples. 425 426 427Debugging the init sequence 428--------------------------- 429 430If you get a failure in the initcall sequence, like this:: 431 432 initcall sequence 0000560775957c80 failed at call 0000000000048134 (err=-96) 433 434Then you use can use grep to see which init call failed, e.g.:: 435 436 $ grep 0000000000048134 u-boot.map 437 stdio_add_devices 438 439Of course another option is to run it with a debugger such as gdb:: 440 441 $ gdb u-boot 442 ... 443 (gdb) br initcall.h:41 444 Breakpoint 1 at 0x4db9d: initcall.h:41. (2 locations) 445 446Note that two locations are reported, since this function is used in both 447board_init_f() and board_init_r(). 448 449.. code-block:: none 450 451 (gdb) 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". 455 456 U-Boot 2018.09-00264-ge0c2ba9814-dirty (Sep 22 2018 - 12:21:46 -0600) 457 458 DRAM: 128 MiB 459 MMC: 460 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> 466 (gdb) 467 468 469This approach can be used on normal boards as well as sandbox. 470 471 472SDL_CONFIG 473---------- 474 475If sdl-config is on a different path from the default, set the SDL_CONFIG 476environment variable to the correct pathname before building U-Boot. 477 478 479Using valgrind / memcheck 480------------------------- 481 482It is possible to run U-Boot under valgrind to check memory allocations:: 483 484 valgrind u-boot 485 486If you are running sandbox SPL or TPL, then valgrind will not by default 487notice when U-Boot jumps from TPL to SPL, or from SPL to U-Boot proper. To 488fix this, use:: 489 490 valgrind --trace-children=yes u-boot 491 492 493Testing 494------- 495 496U-Boot sandbox can be used to run various tests, mostly in the test/ 497directory. 498 499See :doc:`../develop/tests_sandbox` for more information and 500:doc:`../develop/testing` for information about testing generally. 501 502 503Memory Map 504---------- 505 506Sandbox has its own emulated memory starting at 0. Here are some of the things 507that are mapped into that memory: 508 509======= ======================== =============================== 510Addr Config Usage 511======= ======================== =============================== 512 0 CONFIG_SYS_FDT_LOAD_ADDR Device tree 513 e000 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======= ======================== =============================== 520