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