2 * Copyright (c) 2014 The Chromium OS Authors.
4 * SPDX-License-Identifier: GPL-2.0+
7 Native Execution of U-Boot
8 ==========================
10 The 'sandbox' architecture is designed to allow U-Boot to run under Linux on
11 almost any hardware. To achieve this it builds U-Boot (so far as possible)
12 as a normal C application with a main() and normal C libraries.
14 All of U-Boot's architecture-specific code therefore cannot be built as part
15 of the sandbox U-Boot. The purpose of running U-Boot under Linux is to test
16 all the generic code, not specific to any one architecture. The idea is to
17 create unit tests which we can run to test this upper level code.
19 CONFIG_SANDBOX is defined when building a native board.
21 The board name is 'sandbox' but the vendor name is unset, so there is a
22 single board in board/sandbox.
24 CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian
27 By default sandbox builds and runs on 64-bit hosts. If you are going to build
28 and run sandbox on a 32-bit host, select CONFIG_SANDBOX_32BIT.
30 Note that standalone/API support is not available at present.
36 To run sandbox U-Boot use something like:
38 make sandbox_defconfig all
42 If you get errors about 'sdl-config: Command not found' you may need to
43 install libsdl1.2-dev or similar to get SDL support. Alternatively you can
44 build sandbox without SDL (i.e. no display/keyboard support) by removing
45 the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using:
47 make sandbox_defconfig all NO_SDL=1
50 U-Boot will start on your computer, showing a sandbox emulation of the serial
54 U-Boot 2014.04 (Mar 20 2014 - 19:06:00)
57 Using default environment
64 You can issue commands as your would normally. If the command you want is
65 not supported you can add it to include/configs/sandbox.h.
67 To exit, type 'reset' or press Ctrl-C.
73 Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the
74 sandbox with LCD and keyboard emulation, using something like:
76 ./u-boot -d u-boot.dtb -l
78 This will start U-Boot with a window showing the contents of the LCD. If
79 that window has the focus then you will be able to type commands as you
80 would on the console. You can adjust the display settings in the device
81 tree file - see arch/sandbox/dts/sandbox.dts.
87 Various options are available, mostly for test purposes. Use -h to see
88 available options. Some of these are described below.
90 The terminal is normally in what is called 'raw-with-sigs' mode. This means
91 that you can use arrow keys for command editing and history, but if you
92 press Ctrl-C, U-Boot will exit instead of handling this as a keypress.
94 Other options are 'raw' (so Ctrl-C is handled within U-Boot) and 'cooked'
95 (where the terminal is in cooked mode and cursor keys will not work, Ctrl-C
98 As mentioned above, -l causes the LCD emulation window to be shown.
100 A device tree binary file can be provided with -d. If you edit the source
101 (it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to
102 recreate the binary file.
104 To execute commands directly, use the -c option. You can specify a single
105 command, or multiple commands separated by a semicolon, as is normal in
106 U-Boot. Be careful with quoting as the shall will normally process and
107 swallow quotes. When -c is used, U-Boot exists after the command is complete,
108 but you can force it to go to interactive mode instead with -i.
114 Memory emulation is supported, with the size set by CONFIG_SYS_SDRAM_SIZE.
115 The -m option can be used to read memory from a file on start-up and write
116 it when shutting down. This allows preserving of memory contents across
117 test runs. You can tell U-Boot to remove the memory file after it is read
118 (on start-up) with the --rm_memory option.
120 To access U-Boot's emulated memory within the code, use map_sysmem(). This
121 function is used throughout U-Boot to ensure that emulated memory is used
122 rather than the U-Boot application memory. This provides memory starting
123 at 0 and extending to the size of the emulation.
129 With sandbox you can write drivers which emulate the operation of drivers on
130 real devices. Some of these drivers may want to record state which is
131 preserved across U-Boot runs. This is particularly useful for testing. For
132 example, the contents of a SPI flash chip should not disappear just because
135 State is stored in a device tree file in a simple format which is driver-
136 specific. You then use the -s option to specify the state file. Use -r to
137 make U-Boot read the state on start-up (otherwise it starts empty) and -w
138 to write it on exit (otherwise the stored state is left unchanged and any
139 changes U-Boot made will be lost). You can also use -n to tell U-Boot to
140 ignore any problems with missing state. This is useful when first running
141 since the state file will be empty.
143 The device tree file has one node for each driver - the driver can store
144 whatever properties it likes in there. See 'Writing Sandbox Drivers' below
145 for more details on how to get drivers to read and write their state.
151 Since there is no machine architecture, sandbox U-Boot cannot actually boot
152 a kernel, but it does support the bootm command. Filesystems, memory
153 commands, hashing, FIT images, verified boot and many other features are
156 When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real
157 machine. Of course in this case, no kernel is run.
159 It is also possible to tell U-Boot that it has jumped from a temporary
160 previous U-Boot binary, with the -j option. That binary is automatically
161 removed by the U-Boot that gets the -j option. This allows you to write
162 tests which emulate the action of chain-loading U-Boot, typically used in
163 a situation where a second 'updatable' U-Boot is stored on your board. It
164 is very risky to overwrite or upgrade the only U-Boot on a board, since a
165 power or other failure will brick the board and require return to the
166 manufacturer in the case of a consumer device.
172 U-Boot sandbox supports these emulations:
177 - Host filesystem (access files on the host from within U-Boot)
179 - Keyboard (Chrome OS)
182 - Serial (for console only)
183 - Sound (incomplete - see sandbox_sdl_sound_init() for details)
186 - TPM (Trusted Platform Module)
188 A wide range of commands is implemented. Filesystems which use a block
189 device are supported.
191 Also sandbox supports driver model (CONFIG_DM) and associated commands.
194 Linux RAW Networking Bridge
195 ---------------------------
197 The sandbox_eth_raw driver bridges traffic between the bottom of the network
198 stack and the RAW sockets API in Linux. This allows much of the U-Boot network
199 functionality to be tested in sandbox against real network traffic.
201 For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API. This
202 is needed to get access to the lowest level of the network stack in Linux. This
203 means that all of the Ethernet frame is included. This allows the U-Boot network
204 stack to be fully used. In other words, nothing about the Linux network stack is
205 involved in forming the packets that end up on the wire. To receive the
206 responses to packets sent from U-Boot the network interface has to be set to
207 promiscuous mode so that the network card won't filter out packets not destined
208 for its configured (on Linux) MAC address.
210 The RAW sockets Ethernet API requires elevated privileges in Linux. You can
211 either run as root, or you can add the capability needed like so:
213 sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot
215 The default device tree for sandbox includes an entry for eth0 on the sandbox
216 host machine whose alias is "eth1". The following are a few examples of network
217 operations being tested on the eth0 interface.
219 sudo /path/to/u-boot -D
242 set serverip WWW.XXX.YYY.ZZZ
245 The bridge also support (to a lesser extent) the localhost inderface, 'lo'.
247 The 'lo' interface cannot use the RAW AF_PACKET API because the lo interface
248 doesn't support Ethernet-level traffic. It is a higher-level interface that is
249 expected only to be used at the AF_INET level of the API. As such, the most raw
250 we can get on that interface is the RAW AF_INET API on UDP. This allows us to
251 set the IP_HDRINCL option to include everything except the Ethernet header in
252 the packets we send and receive.
254 Because only UDP is supported, ICMP traffic will not work, so expect that ping
255 commands will time out.
257 The default device tree for sandbox includes an entry for lo on the sandbox
258 host machine whose alias is "eth5". The following is an example of a network
259 operation being tested on the lo interface.
271 Sandbox supports SPI and SPI flash emulation.
273 This is controlled by the spi_sf argument, the format of which is:
278 cs - SPI chip select number
279 device - SPI device emulation name
280 file - File on disk containing the data
284 dd if=/dev/zero of=spi.bin bs=1M count=4
285 ./u-boot --spi_sf 0:0:M25P16:spi.bin
287 With this setup you can issue SPI flash commands as normal:
290 SF: Detected M25P16 with page size 64 KiB, total 2 MiB
292 SF: 65536 bytes @ 0x0 Read: OK
295 Since this is a full SPI emulation (rather than just flash), you can
296 also use low-level SPI commands:
301 This is issuing a READ_ID command and getting back 20 (ST Micro) part
304 Drivers are connected to a particular bus/cs using sandbox's state
305 structure (see the 'spi' member). A set of operations must be provided
309 Configuration settings for the curious are:
311 CONFIG_SANDBOX_SPI_MAX_BUS
312 The maximum number of SPI buses supported by the driver (default 1).
314 CONFIG_SANDBOX_SPI_MAX_CS
315 The maximum number of chip selects supported by the driver
319 The idle value on the SPI bus
322 Block Device Emulation
323 ----------------------
325 U-Boot can use raw disk images for block device emulation. To e.g. list
326 the contents of the root directory on the second partion of the image
327 "disk.raw", you can use the following commands:
329 =>host bind 0 ./disk.raw
332 A disk image can be created using the following commands:
334 $> truncate -s 1200M ./disk.raw
335 $> echo -e "label: gpt\n,64M,U\n,,L" | /usr/sbin/sgdisk ./disk.raw
336 $> lodev=`sudo losetup -P -f --show ./disk.raw`
337 $> sudo mkfs.vfat -n EFI -v ${lodev}p1
338 $> sudo mkfs.ext4 -L ROOT -v ${lodev}p2
341 Writing Sandbox Drivers
342 -----------------------
344 Generally you should put your driver in a file containing the word 'sandbox'
345 and put it in the same directory as other drivers of its type. You can then
346 implement the same hooks as the other drivers.
348 To access U-Boot's emulated memory, use map_sysmem() as mentioned above.
350 If your driver needs to store configuration or state (such as SPI flash
351 contents or emulated chip registers), you can use the device tree as
352 described above. Define handlers for this with the SANDBOX_STATE_IO macro.
353 See arch/sandbox/include/asm/state.h for documentation. In short you provide
354 a node name, compatible string and functions to read and write the state.
355 Since writing the state can expand the device tree, you may need to use
356 state_setprop() which does this automatically and avoids running out of
357 space. See existing code for examples.
363 U-Boot sandbox can be used to run various tests, mostly in the test/
364 directory. These include:
367 - Unit tests for command parsing and handling
369 - Unit tests for U-Boot's compression algorithms, useful for
370 security checking. It supports gzip, bzip2, lzma and lzo.
373 ./test/py/test.py --bd sandbox --build -k ut_dm -v
375 - Unit tests for images:
376 test/image/test-imagetools.sh - multi-file images
377 test/image/test-fit.py - FIT images
379 - test/trace/test-trace.sh tests the tracing system (see README.trace)
381 - See test/vboot/vboot_test.sh for this
383 If you change or enhance any of the above subsystems, you shold write or
384 expand a test and include it with your patch series submission. Test
385 coverage in U-Boot is limited, as we need to work to improve it.
387 Note that many of these tests are implemented as commands which you can
388 run natively on your board if desired (and enabled).
390 It would be useful to have a central script to run all of these.
393 Simon Glass <sjg@chromium.org>