board/sandbox/README.sandbox

4  * SPDX-License-Identifier:	GPL-2.0+
7 Native Execution of U-Boot
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)
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
24 CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian
31 ---------------
33 To run sandbox U-Boot use something like:
36    ./u-boot
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
45       ./u-boot
47    If you are building on a 32-bit machine you may get errors from __ffs.h
51 U-Boot will start on your computer, showing a sandbox emulation of the serial
55 U-Boot 2014.04 (Mar 20 2014 - 19:06:00)
68 To exit, type 'reset' or press Ctrl-C.
72 ---------------------
77    ./u-boot -d u-boot.dtb -l
79 This will start U-Boot with a window showing the contents of the LCD. If
81 would on the console. You can adjust the display settings in the device
82 tree file - see arch/sandbox/dts/sandbox.dts.
85 Command-line Options
86 --------------------
88 Various options are available, mostly for test purposes. Use -h to see
91 The terminal is normally in what is called 'raw-with-sigs' mode. This means
93 press Ctrl-C, U-Boot will exit instead of handling this as a keypress.
95 Other options are 'raw' (so Ctrl-C is handled within U-Boot) and 'cooked'
96 (where the terminal is in cooked mode and cursor keys will not work, Ctrl-C
99 As mentioned above, -l causes the LCD emulation window to be shown.
101 A device tree binary file can be provided with -d. If you edit the source
102 (it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to
105 To execute commands directly, use the -c option. You can specify a single
107 U-Boot. Be careful with quoting as the shall will normally process and
108 swallow quotes. When -c is used, U-Boot exists after the command is complete,
109 but you can force it to go to interactive mode instead with -i.
113 ----------------
116 The -m option can be used to read memory from a file on start-up and write
118 test runs. You can tell U-Boot to remove the memory file after it is read
119 (on start-up) with the --rm_memory option.
121 To access U-Boot's emulated memory within the code, use map_sysmem(). This
122 function is used throughout U-Boot to ensure that emulated memory is used
123 rather than the U-Boot application memory. This provides memory starting
128 -------------
130 With sandbox you can write drivers which emulate the operation of drivers on
132 preserved across U-Boot runs. This is particularly useful for testing. For
133 example, the contents of a SPI flash chip should not disappear just because
134 U-Boot exits.
136 State is stored in a device tree file in a simple format which is driver-
137 specific. You then use the -s option to specify the state file. Use -r to
138 make U-Boot read the state on start-up (otherwise it starts empty) and -w
139 to write it on exit (otherwise the stored state is left unchanged and any
140 changes U-Boot made will be lost). You can also use -n to tell U-Boot to
144 The device tree file has one node for each driver - the driver can store
146 for more details on how to get drivers to read and write their state.
150 -------------------
152 Since there is no machine architecture, sandbox U-Boot cannot actually boot
157 When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real
160 It is also possible to tell U-Boot that it has jumped from a temporary
161 previous U-Boot binary, with the -j option. That binary is automatically
162 removed by the U-Boot that gets the -j option. This allows you to write
163 tests which emulate the action of chain-loading U-Boot, typically used in
164 a situation where a second 'updatable' U-Boot is stored on your board. It
165 is very risky to overwrite or upgrade the only U-Boot on a board, since a
171 -----------------
173 U-Boot sandbox supports these emulations:
175 - Block devices
176 - Chrome OS EC
177 - GPIO
178 - Host filesystem (access files on the host from within U-Boot)
179 - I2C
180 - Keyboard (Chrome OS)
181 - LCD
182 - Network
183 - Serial (for console only)
184 - Sound (incomplete - see sandbox_sdl_sound_init() for details)
185 - SPI
186 - SPI flash
187 - TPM (Trusted Platform Module)
196 ---------------------------
198 The sandbox_eth_raw driver bridges traffic between the bottom of the network
199 stack and the RAW sockets API in Linux. This allows much of the U-Boot network
200 functionality to be tested in sandbox against real network traffic.
202 For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API.  This
203 is needed to get access to the lowest level of the network stack in Linux. This
204 means that all of the Ethernet frame is included. This allows the U-Boot network
205 stack to be fully used. In other words, nothing about the Linux network stack is
206 involved in forming the packets that end up on the wire. To receive the
207 responses to packets sent from U-Boot the network interface has to be set to
208 promiscuous mode so that the network card won't filter out packets not destined
209 for its configured (on Linux) MAC address.
214 sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot
216 The default device tree for sandbox includes an entry for eth0 on the sandbox
217 host machine whose alias is "eth1". The following are a few examples of network
218 operations being tested on the eth0 interface.
220 sudo /path/to/u-boot -D
244 tftpboot u-boot.bin
249 doesn't support Ethernet-level traffic. It is a higher-level interface that is
251 we can get on that interface is the RAW AF_INET API on UDP. This allows us to
258 The default device tree for sandbox includes an entry for lo on the sandbox
259 host machine whose alias is "eth5". The following is an example of a network
260 operation being tested on the lo interface.
266 tftpboot u-boot.bin
270 -------------
278    bus    - SPI bus number
279    cs     - SPI chip select number
280    device - SPI device emulation name
281    file   - File on disk containing the data
286  ./u-boot --spi_sf 0:0:M25P16:spi.bin
297 also use low-level SPI commands:
316 	The maximum number of chip selects supported by the driver
320 	The idle value on the SPI bus
324 ----------------------
326 U-Boot can use raw disk images for block device emulation. To e.g. list
327 the contents of the root directory on the second partion of the image
335 $> truncate -s 1200M ./disk.raw
336 $> echo -e "label: gpt\n,64M,U\n,,L" | /usr/sbin/sgdisk  ./disk.raw
337 $> lodev=`sudo losetup -P -f --show ./disk.raw`
338 $> sudo mkfs.vfat -n EFI -v ${lodev}p1
339 $> sudo mkfs.ext4 -L ROOT -v ${lodev}p2
348 -----------------------
354 To access U-Boot's emulated memory, use map_sysmem() as mentioned above.
357 contents or emulated chip registers), you can use the device tree as
367 -------
369 U-Boot sandbox can be used to run various tests, mostly in the test/
373      - Unit tests for command parsing and handling
375      - Unit tests for U-Boot's compression algorithms, useful for
378      - Run this pytest
379 	  ./test/py/test.py --bd sandbox --build -k ut_dm -v
381      - Unit tests for images:
382           test/image/test-imagetools.sh - multi-file images
383           test/image/test-fit.py        - FIT images
385      - test/trace/test-trace.sh tests the tracing system (see README.trace)
387       - See test/vboot/vboot_test.sh for this
391 coverage in U-Boot is limited, as we need to work to improve it.
394 run natively on your board if desired (and enabled).
398 --
400 Updated 22-Mar-14