board/sandbox/README.sandbox

1 /* SPDX-License-Identifier: GPL-2.0+ */
6 Native Execution of U-Boot
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)
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
16 create unit tests which we can run to test this upper level code.
23 CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian
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.
36 ---------------
38 To run sandbox U-Boot use something like:
41    ./u-boot
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
50       ./u-boot
52 U-Boot will start on your computer, showing a sandbox emulation of the serial
56 U-Boot 2014.04 (Mar 20 2014 - 19:06:00)
61 In:    serial
69 To exit, type 'reset' or press Ctrl-C.
73 ---------------------
78    ./u-boot -d u-boot.dtb -l
80 This will start U-Boot with a window showing the contents of the LCD. If
83 tree file - see arch/sandbox/dts/sandbox.dts.
86 Command-line Options
87 --------------------
89 Various options are available, mostly for test purposes. Use -h to see
92 The terminal is normally in what is called 'raw-with-sigs' mode. This means
94 press Ctrl-C, U-Boot will exit instead of handling this as a keypress.
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
100 As mentioned above, -l causes the LCD emulation window to be shown.
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
106 To execute commands directly, use the -c option. You can specify a single
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.
114 ----------------
117 The -m option can be used to read memory from a file on start-up and write
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.
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
129 -------------
133 preserved across U-Boot runs. This is particularly useful for testing. For
135 U-Boot exits.
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
141 changes U-Boot made will be lost). You can also use -n to tell U-Boot to
145 The device tree file has one node for each driver - the driver can store
151 -------------------
153 Since there is no machine architecture, sandbox U-Boot cannot actually boot
155 commands, hashing, FIT images, verified boot and many other features are
158 When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real
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
172 -----------------
174 U-Boot sandbox supports these emulations:
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)
197 ----------------
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
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
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.
221 ---------------------------
224 stack and the RAW sockets API in Linux. This allows much of the U-Boot network
229 means that all of the Ethernet frame is included. This allows the U-Boot network
232 responses to packets sent from U-Boot the network interface has to be set to
239 sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot
245 sudo /path/to/u-boot -D
272 tftpboot u-boot.bin
277 doesn't support Ethernet-level traffic. It is a higher-level interface that is
295 tftpboot u-boot.bin
299 -------------
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
315  ./u-boot --spi_sf 0:0:M25P16:spi.bin
326 also use low-level SPI commands:
353 ----------------------
355 U-Boot can use raw disk images for block device emulation. To e.g. list
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
370 or utilize the device described in test/py/make_test_disk.py:
377 -----------------------
383 To access U-Boot's emulated memory, use map_sysmem() as mentioned above.
396 -------
398 U-Boot sandbox can be used to run various tests, mostly in the test/
402      - Unit tests for command parsing and handling
404      - Unit tests for U-Boot's compression algorithms, useful for
407      - Run this pytest
408 	  ./test/py/test.py --bd sandbox --build -k ut_dm -v
410      - Unit tests for images:
411           test/image/test-imagetools.sh - multi-file images
412           test/image/test-fit.py        - FIT images
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
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.
429 ----------
439 --
441 Updated 22-Mar-14