blob: 9b0940429431cbe3d7a5ba12c82fbb45cd354352 [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001/* SPDX-License-Identifier: GPL-2.0+ */
Simon Glass744d9852011-10-10 08:22:14 +00002/*
Simon Glass75b3c3a2014-03-22 17:12:59 -06003 * Copyright (c) 2014 The Chromium OS Authors.
Simon Glass744d9852011-10-10 08:22:14 +00004 */
5
6Native Execution of U-Boot
7==========================
8
9The 'sandbox' architecture is designed to allow U-Boot to run under Linux on
10almost any hardware. To achieve this it builds U-Boot (so far as possible)
11as a normal C application with a main() and normal C libraries.
12
13All of U-Boot's architecture-specific code therefore cannot be built as part
14of the sandbox U-Boot. The purpose of running U-Boot under Linux is to test
15all the generic code, not specific to any one architecture. The idea is to
16create unit tests which we can run to test this upper level code.
17
18CONFIG_SANDBOX is defined when building a native board.
19
Simon Glass9b250ac2014-09-23 13:05:59 -060020The board name is 'sandbox' but the vendor name is unset, so there is a
21single board in board/sandbox.
Simon Glass744d9852011-10-10 08:22:14 +000022
23CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian
24machines.
25
Mario Sixc6b89f32018-02-12 08:05:57 +010026There are two versions of the sandbox: One using 32-bit-wide integers, and one
27using 64-bit-wide integers. The 32-bit version can be build and run on either
2832 or 64-bit hosts by either selecting or deselecting CONFIG_SANDBOX_32BIT; by
29default, the sandbox it built for a 32-bit host. The sandbox using 64-bit-wide
30integers can only be built on 64-bit hosts.
Bin Meng226b50b2017-08-01 16:33:34 -070031
Simon Glass744d9852011-10-10 08:22:14 +000032Note that standalone/API support is not available at present.
33
Simon Glass75b3c3a2014-03-22 17:12:59 -060034
35Basic Operation
36---------------
37
38To run sandbox U-Boot use something like:
39
Jagannadha Sutradharudu Teki6b1978f2014-08-31 21:19:43 +053040 make sandbox_defconfig all
Simon Glass75b3c3a2014-03-22 17:12:59 -060041 ./u-boot
42
43Note:
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
46 build sandbox without SDL (i.e. no display/keyboard support) by removing
47 the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using:
48
Jagannadha Sutradharudu Teki6b1978f2014-08-31 21:19:43 +053049 make sandbox_defconfig all NO_SDL=1
Simon Glass75b3c3a2014-03-22 17:12:59 -060050 ./u-boot
51
Simon Glass75b3c3a2014-03-22 17:12:59 -060052U-Boot will start on your computer, showing a sandbox emulation of the serial
53console:
54
55
56U-Boot 2014.04 (Mar 20 2014 - 19:06:00)
57
58DRAM: 128 MiB
59Using default environment
60
61In: serial
62Out: lcd
63Err: lcd
64=>
65
66You can issue commands as your would normally. If the command you want is
67not supported you can add it to include/configs/sandbox.h.
68
69To exit, type 'reset' or press Ctrl-C.
70
71
72Console / LCD support
73---------------------
74
75Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the
76sandbox with LCD and keyboard emulation, using something like:
77
78 ./u-boot -d u-boot.dtb -l
79
80This will start U-Boot with a window showing the contents of the LCD. If
81that window has the focus then you will be able to type commands as you
82would on the console. You can adjust the display settings in the device
83tree file - see arch/sandbox/dts/sandbox.dts.
84
85
86Command-line Options
87--------------------
88
89Various options are available, mostly for test purposes. Use -h to see
90available options. Some of these are described below.
91
92The terminal is normally in what is called 'raw-with-sigs' mode. This means
93that you can use arrow keys for command editing and history, but if you
94press Ctrl-C, U-Boot will exit instead of handling this as a keypress.
95
96Other 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
98will exit).
99
100As mentioned above, -l causes the LCD emulation window to be shown.
101
102A 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
104recreate the binary file.
105
106To execute commands directly, use the -c option. You can specify a single
107command, or multiple commands separated by a semicolon, as is normal in
Trevor Woerner1f154a62018-04-30 19:13:05 -0400108U-Boot. Be careful with quoting as the shell will normally process and
109swallow quotes. When -c is used, U-Boot exits after the command is complete,
Simon Glass75b3c3a2014-03-22 17:12:59 -0600110but you can force it to go to interactive mode instead with -i.
111
112
113Memory Emulation
114----------------
115
116Memory emulation is supported, with the size set by CONFIG_SYS_SDRAM_SIZE.
117The -m option can be used to read memory from a file on start-up and write
118it when shutting down. This allows preserving of memory contents across
119test runs. You can tell U-Boot to remove the memory file after it is read
120(on start-up) with the --rm_memory option.
121
122To access U-Boot's emulated memory within the code, use map_sysmem(). This
123function is used throughout U-Boot to ensure that emulated memory is used
124rather than the U-Boot application memory. This provides memory starting
125at 0 and extending to the size of the emulation.
126
127
128Storing State
129-------------
130
131With sandbox you can write drivers which emulate the operation of drivers on
132real devices. Some of these drivers may want to record state which is
133preserved across U-Boot runs. This is particularly useful for testing. For
134example, the contents of a SPI flash chip should not disappear just because
135U-Boot exits.
136
137State is stored in a device tree file in a simple format which is driver-
138specific. You then use the -s option to specify the state file. Use -r to
139make U-Boot read the state on start-up (otherwise it starts empty) and -w
140to write it on exit (otherwise the stored state is left unchanged and any
141changes U-Boot made will be lost). You can also use -n to tell U-Boot to
142ignore any problems with missing state. This is useful when first running
143since the state file will be empty.
144
145The device tree file has one node for each driver - the driver can store
146whatever properties it likes in there. See 'Writing Sandbox Drivers' below
147for more details on how to get drivers to read and write their state.
148
149
150Running and Booting
151-------------------
152
153Since there is no machine architecture, sandbox U-Boot cannot actually boot
154a kernel, but it does support the bootm command. Filesystems, memory
155commands, hashing, FIT images, verified boot and many other features are
156supported.
157
158When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real
159machine. Of course in this case, no kernel is run.
160
161It is also possible to tell U-Boot that it has jumped from a temporary
162previous U-Boot binary, with the -j option. That binary is automatically
163removed by the U-Boot that gets the -j option. This allows you to write
164tests which emulate the action of chain-loading U-Boot, typically used in
165a situation where a second 'updatable' U-Boot is stored on your board. It
166is very risky to overwrite or upgrade the only U-Boot on a board, since a
167power or other failure will brick the board and require return to the
168manufacturer in the case of a consumer device.
169
170
171Supported Drivers
172-----------------
173
174U-Boot sandbox supports these emulations:
175
176- Block devices
177- Chrome OS EC
178- GPIO
179- Host filesystem (access files on the host from within U-Boot)
Joe Hershberger3ea143a2015-03-22 17:09:13 -0500180- I2C
Simon Glass75b3c3a2014-03-22 17:12:59 -0600181- Keyboard (Chrome OS)
182- LCD
Joe Hershberger3ea143a2015-03-22 17:09:13 -0500183- Network
Simon Glass75b3c3a2014-03-22 17:12:59 -0600184- Serial (for console only)
185- Sound (incomplete - see sandbox_sdl_sound_init() for details)
186- SPI
187- SPI flash
188- TPM (Trusted Platform Module)
189
Trevor Woerner1f154a62018-04-30 19:13:05 -0400190A wide range of commands are implemented. Filesystems which use a block
Simon Glass75b3c3a2014-03-22 17:12:59 -0600191device are supported.
192
Simon Glass89b199c2016-05-14 18:49:27 -0600193Also sandbox supports driver model (CONFIG_DM) and associated commands.
Simon Glass744d9852011-10-10 08:22:14 +0000194
195
Simon Glass969c8f42018-09-18 18:43:28 -0600196Sandbox Variants
197----------------
198
199There are unfortunately quite a few variants at present:
200
201sandbox - should be used for most tests
202sandbox64 - special build that forces a 64-bit host
203sandbox_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
206 since they are named the same.
207sandbox_noblk - builds without CONFIG_BLK, which means the legacy block
208 drivers are used. We cannot use both the legacy and driver-model block
209 drivers since they implement the same functions
210sandbox_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.
213
214Of these sandbox_noblk can be removed once CONFIG_BLK is used everwhere, and
215sandbox_spl can probably be removed since it is a superset of sandbox.
216
217Most of the config options should be identical between these variants.
218
219
Joe Hershbergera346ca72015-03-22 17:09:21 -0500220Linux RAW Networking Bridge
221---------------------------
222
223The sandbox_eth_raw driver bridges traffic between the bottom of the network
224stack and the RAW sockets API in Linux. This allows much of the U-Boot network
225functionality to be tested in sandbox against real network traffic.
226
227For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API. This
228is needed to get access to the lowest level of the network stack in Linux. This
229means that all of the Ethernet frame is included. This allows the U-Boot network
230stack to be fully used. In other words, nothing about the Linux network stack is
231involved in forming the packets that end up on the wire. To receive the
232responses to packets sent from U-Boot the network interface has to be set to
233promiscuous mode so that the network card won't filter out packets not destined
234for its configured (on Linux) MAC address.
235
236The RAW sockets Ethernet API requires elevated privileges in Linux. You can
237either run as root, or you can add the capability needed like so:
238
239sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot
240
241The default device tree for sandbox includes an entry for eth0 on the sandbox
242host machine whose alias is "eth1". The following are a few examples of network
243operations being tested on the eth0 interface.
244
245sudo /path/to/u-boot -D
246
247DHCP
248....
249
Heinrich Schuchardt6c6260e2018-10-14 21:40:02 +0200250setenv autoload no
Heinrich Schuchardt0c943e52018-10-14 22:01:28 +0200251setenv ethrotate no
Heinrich Schuchardt6c6260e2018-10-14 21:40:02 +0200252setenv ethact eth1
Joe Hershbergera346ca72015-03-22 17:09:21 -0500253dhcp
254
255PING
256....
257
Heinrich Schuchardt6c6260e2018-10-14 21:40:02 +0200258setenv autoload no
Heinrich Schuchardt0c943e52018-10-14 22:01:28 +0200259setenv ethrotate no
Heinrich Schuchardt6c6260e2018-10-14 21:40:02 +0200260setenv ethact eth1
Joe Hershbergera346ca72015-03-22 17:09:21 -0500261dhcp
262ping $gatewayip
263
264TFTP
265....
266
Heinrich Schuchardt6c6260e2018-10-14 21:40:02 +0200267setenv autoload no
Heinrich Schuchardt0c943e52018-10-14 22:01:28 +0200268setenv ethrotate no
Heinrich Schuchardt6c6260e2018-10-14 21:40:02 +0200269setenv ethact eth1
Joe Hershbergera346ca72015-03-22 17:09:21 -0500270dhcp
Heinrich Schuchardt6c6260e2018-10-14 21:40:02 +0200271setenv serverip WWW.XXX.YYY.ZZZ
Joe Hershbergera346ca72015-03-22 17:09:21 -0500272tftpboot u-boot.bin
273
Trevor Woerner1f154a62018-04-30 19:13:05 -0400274The bridge also supports (to a lesser extent) the localhost interface, 'lo'.
Joe Hershberger22f68522015-03-22 17:09:23 -0500275
276The 'lo' interface cannot use the RAW AF_PACKET API because the lo interface
277doesn't support Ethernet-level traffic. It is a higher-level interface that is
278expected only to be used at the AF_INET level of the API. As such, the most raw
279we can get on that interface is the RAW AF_INET API on UDP. This allows us to
280set the IP_HDRINCL option to include everything except the Ethernet header in
281the packets we send and receive.
282
283Because only UDP is supported, ICMP traffic will not work, so expect that ping
284commands will time out.
285
286The default device tree for sandbox includes an entry for lo on the sandbox
287host machine whose alias is "eth5". The following is an example of a network
288operation being tested on the lo interface.
289
290TFTP
291....
292
Heinrich Schuchardt0c943e52018-10-14 22:01:28 +0200293setenv ethrotate no
Heinrich Schuchardt6c6260e2018-10-14 21:40:02 +0200294setenv ethact eth5
Joe Hershberger22f68522015-03-22 17:09:23 -0500295tftpboot u-boot.bin
296
Joe Hershbergera346ca72015-03-22 17:09:21 -0500297
Mike Frysingerffdb20b2013-12-03 16:43:27 -0700298SPI Emulation
299-------------
300
301Sandbox supports SPI and SPI flash emulation.
302
303This is controlled by the spi_sf argument, the format of which is:
304
305 bus:cs:device:file
306
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
311
312For example:
313
314 dd if=/dev/zero of=spi.bin bs=1M count=4
315 ./u-boot --spi_sf 0:0:M25P16:spi.bin
316
317With this setup you can issue SPI flash commands as normal:
318
319=>sf probe
320SF: Detected M25P16 with page size 64 KiB, total 2 MiB
321=>sf read 0 0 10000
322SF: 65536 bytes @ 0x0 Read: OK
323=>
324
325Since this is a full SPI emulation (rather than just flash), you can
326also use low-level SPI commands:
327
328=>sspi 0:0 32 9f
329FF202015
330
331This is issuing a READ_ID command and getting back 20 (ST Micro) part
3320x2015 (the M25P16).
333
334Drivers are connected to a particular bus/cs using sandbox's state
335structure (see the 'spi' member). A set of operations must be provided
336for each driver.
337
338
339Configuration settings for the curious are:
340
341CONFIG_SANDBOX_SPI_MAX_BUS
342 The maximum number of SPI buses supported by the driver (default 1).
343
344CONFIG_SANDBOX_SPI_MAX_CS
345 The maximum number of chip selects supported by the driver
346 (default 10).
347
348CONFIG_SPI_IDLE_VAL
349 The idle value on the SPI bus
350
351
Stefan Brüns2945eb72016-08-11 22:52:03 +0200352Block Device Emulation
353----------------------
354
355U-Boot can use raw disk images for block device emulation. To e.g. list
356the contents of the root directory on the second partion of the image
357"disk.raw", you can use the following commands:
358
359=>host bind 0 ./disk.raw
360=>ls host 0:2
361
362A disk image can be created using the following commands:
363
364$> truncate -s 1200M ./disk.raw
Alison Chaiken6b20c342017-06-04 15:11:20 -0700365$> echo -e "label: gpt\n,64M,U\n,,L" | /usr/sbin/sgdisk ./disk.raw
Stefan Brüns2945eb72016-08-11 22:52:03 +0200366$> 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
369
Alison Chaikenbf6d76b2017-09-09 23:47:12 -0700370or utilize the device described in test/py/make_test_disk.py:
371
372 #!/usr/bin/python
373 import make_test_disk
374 make_test_disk.makeDisk()
Stefan Brüns2945eb72016-08-11 22:52:03 +0200375
Simon Glass75b3c3a2014-03-22 17:12:59 -0600376Writing Sandbox Drivers
377-----------------------
Simon Glass744d9852011-10-10 08:22:14 +0000378
Simon Glass75b3c3a2014-03-22 17:12:59 -0600379Generally you should put your driver in a file containing the word 'sandbox'
380and put it in the same directory as other drivers of its type. You can then
381implement the same hooks as the other drivers.
382
383To access U-Boot's emulated memory, use map_sysmem() as mentioned above.
384
385If your driver needs to store configuration or state (such as SPI flash
386contents or emulated chip registers), you can use the device tree as
387described above. Define handlers for this with the SANDBOX_STATE_IO macro.
388See arch/sandbox/include/asm/state.h for documentation. In short you provide
389a node name, compatible string and functions to read and write the state.
390Since writing the state can expand the device tree, you may need to use
391state_setprop() which does this automatically and avoids running out of
392space. See existing code for examples.
393
394
395Testing
396-------
397
398U-Boot sandbox can be used to run various tests, mostly in the test/
399directory. These include:
400
401 command_ut
402 - Unit tests for command parsing and handling
403 compression
404 - Unit tests for U-Boot's compression algorithms, useful for
405 security checking. It supports gzip, bzip2, lzma and lzo.
406 driver model
Jagan Teki7b3dc452016-03-17 12:23:19 +0530407 - Run this pytest
408 ./test/py/test.py --bd sandbox --build -k ut_dm -v
Simon Glass75b3c3a2014-03-22 17:12:59 -0600409 image
410 - Unit tests for images:
411 test/image/test-imagetools.sh - multi-file images
412 test/image/test-fit.py - FIT images
413 tracing
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
417
418If you change or enhance any of the above subsystems, you shold write or
419expand a test and include it with your patch series submission. Test
420coverage in U-Boot is limited, as we need to work to improve it.
421
422Note that many of these tests are implemented as commands which you can
423run natively on your board if desired (and enabled).
424
Simon Glass9946d552018-11-15 18:43:59 -0700425To run all tests use "make check".
426
427
428Memory Map
429----------
430
431Sandbox has its own emulated memory starting at 0. Here are some of the things
432that are mapped into that memory:
433
434 0 CONFIG_SYS_FDT_LOAD_ADDR Device tree
435 e000 CONFIG_BLOBLIST_ADDR Blob list
436 10000 CONFIG_MALLOC_F_ADDR Early memory allocation
437
Simon Glass75b3c3a2014-03-22 17:12:59 -0600438
439--
440Simon Glass <sjg@chromium.org>
441Updated 22-Mar-14