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