1 /* SPDX-License-Identifier: GPL-2.0+ */ 2 /* 3 * Copyright (c) 2014 The Chromium OS Authors. 4 */ 5 6 Native Execution of U-Boot 7 ========================== 8 9 The 'sandbox' architecture is designed to allow U-Boot to run under Linux on 10 almost any hardware. To achieve this it builds U-Boot (so far as possible) 11 as a normal C application with a main() and normal C libraries. 12 13 All of U-Boot's architecture-specific code therefore cannot be built as part 14 of the sandbox U-Boot. The purpose of running U-Boot under Linux is to test 15 all the generic code, not specific to any one architecture. The idea is to 16 create unit tests which we can run to test this upper level code. 17 18 CONFIG_SANDBOX is defined when building a native board. 19 20 The board name is 'sandbox' but the vendor name is unset, so there is a 21 single board in board/sandbox. 22 23 CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian 24 machines. 25 26 There are two versions of the sandbox: One using 32-bit-wide integers, and one 27 using 64-bit-wide integers. The 32-bit version can be build and run on either 28 32 or 64-bit hosts by either selecting or deselecting CONFIG_SANDBOX_32BIT; by 29 default, the sandbox it built for a 32-bit host. The sandbox using 64-bit-wide 30 integers can only be built on 64-bit hosts. 31 32 Note that standalone/API support is not available at present. 33 34 35 Basic Operation 36 --------------- 37 38 To run sandbox U-Boot use something like: 39 40 make sandbox_defconfig all 41 ./u-boot 42 43 Note: 44 If you get errors about 'sdl-config: Command not found' you may need to 45 install libsdl1.2-dev or similar to get SDL support. Alternatively you can 46 build sandbox without SDL (i.e. no display/keyboard support) by removing 47 the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using: 48 49 make sandbox_defconfig all NO_SDL=1 50 ./u-boot 51 52 U-Boot will start on your computer, showing a sandbox emulation of the serial 53 console: 54 55 56 U-Boot 2014.04 (Mar 20 2014 - 19:06:00) 57 58 DRAM: 128 MiB 59 Using default environment 60 61 In: serial 62 Out: lcd 63 Err: lcd 64 => 65 66 You can issue commands as your would normally. If the command you want is 67 not supported you can add it to include/configs/sandbox.h. 68 69 To exit, type 'reset' or press Ctrl-C. 70 71 72 Console / LCD support 73 --------------------- 74 75 Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the 76 sandbox with LCD and keyboard emulation, using something like: 77 78 ./u-boot -d u-boot.dtb -l 79 80 This will start U-Boot with a window showing the contents of the LCD. If 81 that window has the focus then you will be able to type commands as you 82 would on the console. You can adjust the display settings in the device 83 tree file - see arch/sandbox/dts/sandbox.dts. 84 85 86 Command-line Options 87 -------------------- 88 89 Various options are available, mostly for test purposes. Use -h to see 90 available options. Some of these are described below. 91 92 The terminal is normally in what is called 'raw-with-sigs' mode. This means 93 that you can use arrow keys for command editing and history, but if you 94 press Ctrl-C, U-Boot will exit instead of handling this as a keypress. 95 96 Other options are 'raw' (so Ctrl-C is handled within U-Boot) and 'cooked' 97 (where the terminal is in cooked mode and cursor keys will not work, Ctrl-C 98 will exit). 99 100 As mentioned above, -l causes the LCD emulation window to be shown. 101 102 A device tree binary file can be provided with -d. If you edit the source 103 (it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to 104 recreate the binary file. 105 106 To execute commands directly, use the -c option. You can specify a single 107 command, or multiple commands separated by a semicolon, as is normal in 108 U-Boot. Be careful with quoting as the shell will normally process and 109 swallow quotes. When -c is used, U-Boot exits after the command is complete, 110 but you can force it to go to interactive mode instead with -i. 111 112 113 Memory Emulation 114 ---------------- 115 116 Memory emulation is supported, with the size set by CONFIG_SYS_SDRAM_SIZE. 117 The -m option can be used to read memory from a file on start-up and write 118 it when shutting down. This allows preserving of memory contents across 119 test runs. You can tell U-Boot to remove the memory file after it is read 120 (on start-up) with the --rm_memory option. 121 122 To access U-Boot's emulated memory within the code, use map_sysmem(). This 123 function is used throughout U-Boot to ensure that emulated memory is used 124 rather than the U-Boot application memory. This provides memory starting 125 at 0 and extending to the size of the emulation. 126 127 128 Storing State 129 ------------- 130 131 With sandbox you can write drivers which emulate the operation of drivers on 132 real devices. Some of these drivers may want to record state which is 133 preserved across U-Boot runs. This is particularly useful for testing. For 134 example, the contents of a SPI flash chip should not disappear just because 135 U-Boot exits. 136 137 State is stored in a device tree file in a simple format which is driver- 138 specific. You then use the -s option to specify the state file. Use -r to 139 make U-Boot read the state on start-up (otherwise it starts empty) and -w 140 to write it on exit (otherwise the stored state is left unchanged and any 141 changes U-Boot made will be lost). You can also use -n to tell U-Boot to 142 ignore any problems with missing state. This is useful when first running 143 since the state file will be empty. 144 145 The device tree file has one node for each driver - the driver can store 146 whatever properties it likes in there. See 'Writing Sandbox Drivers' below 147 for more details on how to get drivers to read and write their state. 148 149 150 Running and Booting 151 ------------------- 152 153 Since there is no machine architecture, sandbox U-Boot cannot actually boot 154 a kernel, but it does support the bootm command. Filesystems, memory 155 commands, hashing, FIT images, verified boot and many other features are 156 supported. 157 158 When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real 159 machine. Of course in this case, no kernel is run. 160 161 It is also possible to tell U-Boot that it has jumped from a temporary 162 previous U-Boot binary, with the -j option. That binary is automatically 163 removed by the U-Boot that gets the -j option. This allows you to write 164 tests which emulate the action of chain-loading U-Boot, typically used in 165 a situation where a second 'updatable' U-Boot is stored on your board. It 166 is very risky to overwrite or upgrade the only U-Boot on a board, since a 167 power or other failure will brick the board and require return to the 168 manufacturer in the case of a consumer device. 169 170 171 Supported Drivers 172 ----------------- 173 174 U-Boot sandbox supports these emulations: 175 176 - Block devices 177 - Chrome OS EC 178 - GPIO 179 - Host filesystem (access files on the host from within U-Boot) 180 - I2C 181 - Keyboard (Chrome OS) 182 - LCD 183 - Network 184 - Serial (for console only) 185 - Sound (incomplete - see sandbox_sdl_sound_init() for details) 186 - SPI 187 - SPI flash 188 - TPM (Trusted Platform Module) 189 190 A wide range of commands are implemented. Filesystems which use a block 191 device are supported. 192 193 Also sandbox supports driver model (CONFIG_DM) and associated commands. 194 195 196 Sandbox Variants 197 ---------------- 198 199 There are unfortunately quite a few variants at present: 200 201 sandbox - should be used for most tests 202 sandbox64 - special build that forces a 64-bit host 203 sandbox_flattree - builds with dev_read_...() functions defined as inline. 204 We need this build so that we can test those inline functions, and we 205 cannot build with both the inline functions and the non-inline functions 206 since they are named the same. 207 sandbox_noblk - builds without CONFIG_BLK, which means the legacy block 208 drivers are used. We cannot use both the legacy and driver-model block 209 drivers since they implement the same functions 210 sandbox_spl - builds sandbox with SPL support, so you can run spl/u-boot-spl 211 and it will start up and then load ./u-boot. It is also possible to 212 run ./u-boot directly. 213 214 Of these sandbox_noblk can be removed once CONFIG_BLK is used everwhere, and 215 sandbox_spl can probably be removed since it is a superset of sandbox. 216 217 Most of the config options should be identical between these variants. 218 219 220 Linux RAW Networking Bridge 221 --------------------------- 222 223 The sandbox_eth_raw driver bridges traffic between the bottom of the network 224 stack and the RAW sockets API in Linux. This allows much of the U-Boot network 225 functionality to be tested in sandbox against real network traffic. 226 227 For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API. This 228 is needed to get access to the lowest level of the network stack in Linux. This 229 means that all of the Ethernet frame is included. This allows the U-Boot network 230 stack to be fully used. In other words, nothing about the Linux network stack is 231 involved in forming the packets that end up on the wire. To receive the 232 responses to packets sent from U-Boot the network interface has to be set to 233 promiscuous mode so that the network card won't filter out packets not destined 234 for its configured (on Linux) MAC address. 235 236 The RAW sockets Ethernet API requires elevated privileges in Linux. You can 237 either run as root, or you can add the capability needed like so: 238 239 sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot 240 241 The default device tree for sandbox includes an entry for eth0 on the sandbox 242 host machine whose alias is "eth1". The following are a few examples of network 243 operations being tested on the eth0 interface. 244 245 sudo /path/to/u-boot -D 246 247 DHCP 248 .... 249 250 setenv autoload no 251 setenv ethrotate no 252 setenv ethact eth1 253 dhcp 254 255 PING 256 .... 257 258 setenv autoload no 259 setenv ethrotate no 260 setenv ethact eth1 261 dhcp 262 ping $gatewayip 263 264 TFTP 265 .... 266 267 setenv autoload no 268 setenv ethrotate no 269 setenv ethact eth1 270 dhcp 271 setenv serverip WWW.XXX.YYY.ZZZ 272 tftpboot u-boot.bin 273 274 The bridge also supports (to a lesser extent) the localhost interface, 'lo'. 275 276 The 'lo' interface cannot use the RAW AF_PACKET API because the lo interface 277 doesn't support Ethernet-level traffic. It is a higher-level interface that is 278 expected only to be used at the AF_INET level of the API. As such, the most raw 279 we can get on that interface is the RAW AF_INET API on UDP. This allows us to 280 set the IP_HDRINCL option to include everything except the Ethernet header in 281 the packets we send and receive. 282 283 Because only UDP is supported, ICMP traffic will not work, so expect that ping 284 commands will time out. 285 286 The default device tree for sandbox includes an entry for lo on the sandbox 287 host machine whose alias is "eth5". The following is an example of a network 288 operation being tested on the lo interface. 289 290 TFTP 291 .... 292 293 setenv ethrotate no 294 setenv ethact eth5 295 tftpboot u-boot.bin 296 297 298 SPI Emulation 299 ------------- 300 301 Sandbox supports SPI and SPI flash emulation. 302 303 This is controlled by the spi_sf argument, the format of which is: 304 305 bus:cs:device:file 306 307 bus - SPI bus number 308 cs - SPI chip select number 309 device - SPI device emulation name 310 file - File on disk containing the data 311 312 For example: 313 314 dd if=/dev/zero of=spi.bin bs=1M count=4 315 ./u-boot --spi_sf 0:0:M25P16:spi.bin 316 317 With this setup you can issue SPI flash commands as normal: 318 319 =>sf probe 320 SF: Detected M25P16 with page size 64 KiB, total 2 MiB 321 =>sf read 0 0 10000 322 SF: 65536 bytes @ 0x0 Read: OK 323 => 324 325 Since this is a full SPI emulation (rather than just flash), you can 326 also use low-level SPI commands: 327 328 =>sspi 0:0 32 9f 329 FF202015 330 331 This is issuing a READ_ID command and getting back 20 (ST Micro) part 332 0x2015 (the M25P16). 333 334 Drivers are connected to a particular bus/cs using sandbox's state 335 structure (see the 'spi' member). A set of operations must be provided 336 for each driver. 337 338 339 Configuration settings for the curious are: 340 341 CONFIG_SANDBOX_SPI_MAX_BUS 342 The maximum number of SPI buses supported by the driver (default 1). 343 344 CONFIG_SANDBOX_SPI_MAX_CS 345 The maximum number of chip selects supported by the driver 346 (default 10). 347 348 CONFIG_SPI_IDLE_VAL 349 The idle value on the SPI bus 350 351 352 Block Device Emulation 353 ---------------------- 354 355 U-Boot can use raw disk images for block device emulation. To e.g. list 356 the contents of the root directory on the second partion of the image 357 "disk.raw", you can use the following commands: 358 359 =>host bind 0 ./disk.raw 360 =>ls host 0:2 361 362 A disk image can be created using the following commands: 363 364 $> truncate -s 1200M ./disk.raw 365 $> echo -e "label: gpt\n,64M,U\n,,L" | /usr/sbin/sgdisk ./disk.raw 366 $> lodev=`sudo losetup -P -f --show ./disk.raw` 367 $> sudo mkfs.vfat -n EFI -v ${lodev}p1 368 $> sudo mkfs.ext4 -L ROOT -v ${lodev}p2 369 370 or utilize the device described in test/py/make_test_disk.py: 371 372 #!/usr/bin/python 373 import make_test_disk 374 make_test_disk.makeDisk() 375 376 Writing Sandbox Drivers 377 ----------------------- 378 379 Generally you should put your driver in a file containing the word 'sandbox' 380 and put it in the same directory as other drivers of its type. You can then 381 implement the same hooks as the other drivers. 382 383 To access U-Boot's emulated memory, use map_sysmem() as mentioned above. 384 385 If your driver needs to store configuration or state (such as SPI flash 386 contents or emulated chip registers), you can use the device tree as 387 described above. Define handlers for this with the SANDBOX_STATE_IO macro. 388 See arch/sandbox/include/asm/state.h for documentation. In short you provide 389 a node name, compatible string and functions to read and write the state. 390 Since writing the state can expand the device tree, you may need to use 391 state_setprop() which does this automatically and avoids running out of 392 space. See existing code for examples. 393 394 395 Testing 396 ------- 397 398 U-Boot sandbox can be used to run various tests, mostly in the test/ 399 directory. These include: 400 401 command_ut 402 - Unit tests for command parsing and handling 403 compression 404 - Unit tests for U-Boot's compression algorithms, useful for 405 security checking. It supports gzip, bzip2, lzma and lzo. 406 driver model 407 - Run this pytest 408 ./test/py/test.py --bd sandbox --build -k ut_dm -v 409 image 410 - Unit tests for images: 411 test/image/test-imagetools.sh - multi-file images 412 test/image/test-fit.py - FIT images 413 tracing 414 - test/trace/test-trace.sh tests the tracing system (see README.trace) 415 verified boot 416 - See test/vboot/vboot_test.sh for this 417 418 If you change or enhance any of the above subsystems, you shold write or 419 expand a test and include it with your patch series submission. Test 420 coverage in U-Boot is limited, as we need to work to improve it. 421 422 Note that many of these tests are implemented as commands which you can 423 run natively on your board if desired (and enabled). 424 425 To run all tests use "make check". 426 427 428 Memory Map 429 ---------- 430 431 Sandbox has its own emulated memory starting at 0. Here are some of the things 432 that are mapped into that memory: 433 434 0 CONFIG_SYS_FDT_LOAD_ADDR Device tree 435 e000 CONFIG_BLOBLIST_ADDR Blob list 436 10000 CONFIG_MALLOC_F_ADDR Early memory allocation 437 438 439 -- 440 Simon Glass <sjg@chromium.org> 441 Updated 22-Mar-14 442