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
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)
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
82 would on the console. You can adjust the display settings in the device
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 -------------
131 With sandbox you can write drivers which emulate the operation of drivers on
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.
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
145 The device tree file has one node for each driver - the driver can store
147 for more details on how to get drivers to read and write their state.
151 -------------------
153 Since there is no machine architecture, sandbox U-Boot cannot actually boot
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.
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 ---------------------------
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.
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.
239 sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot
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.
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
279 we can get on that interface is the RAW AF_INET API on UDP. This allows us to
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.
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:
345 	The maximum number of chip selects supported by the driver
349 	The idle value on the SPI bus
353 ----------------------
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
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
377 -----------------------
383 To access U-Boot's emulated memory, use map_sysmem() as mentioned above.
386 contents or emulated chip registers), you can use the device tree as
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)
416       - See test/vboot/vboot_test.sh for this
420 coverage in U-Boot is limited, as we need to work to improve it.
423 run natively on your board if desired (and enabled).
429 ----------
439 --
441 Updated 22-Mar-14