blob: 760866f1c3be5aedf496495227f00a6c773e57d5 [file] [log] [blame]
Simon Glass744d9852011-10-10 08:22:14 +00001/*
Simon Glass75b3c3a2014-03-22 17:12:59 -06002 * Copyright (c) 2014 The Chromium OS Authors.
Simon Glass744d9852011-10-10 08:22:14 +00003 *
Wolfgang Denk3765b3e2013-10-07 13:07:26 +02004 * SPDX-License-Identifier: GPL-2.0+
Simon Glass744d9852011-10-10 08:22:14 +00005 */
6
7Native Execution of U-Boot
8==========================
9
10The 'sandbox' architecture is designed to allow U-Boot to run under Linux on
11almost any hardware. To achieve this it builds U-Boot (so far as possible)
12as a normal C application with a main() and normal C libraries.
13
14All of U-Boot's architecture-specific code therefore cannot be built as part
15of the sandbox U-Boot. The purpose of running U-Boot under Linux is to test
16all the generic code, not specific to any one architecture. The idea is to
17create unit tests which we can run to test this upper level code.
18
19CONFIG_SANDBOX is defined when building a native board.
20
Simon Glass9b250ac2014-09-23 13:05:59 -060021The board name is 'sandbox' but the vendor name is unset, so there is a
22single board in board/sandbox.
Simon Glass744d9852011-10-10 08:22:14 +000023
24CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian
25machines.
26
Mario Sixc6b89f32018-02-12 08:05:57 +010027There are two versions of the sandbox: One using 32-bit-wide integers, and one
28using 64-bit-wide integers. The 32-bit version can be build and run on either
2932 or 64-bit hosts by either selecting or deselecting CONFIG_SANDBOX_32BIT; by
30default, the sandbox it built for a 32-bit host. The sandbox using 64-bit-wide
31integers can only be built on 64-bit hosts.
Bin Meng226b50b2017-08-01 16:33:34 -070032
Simon Glass744d9852011-10-10 08:22:14 +000033Note that standalone/API support is not available at present.
34
Simon Glass75b3c3a2014-03-22 17:12:59 -060035
36Basic Operation
37---------------
38
39To run sandbox U-Boot use something like:
40
Jagannadha Sutradharudu Teki6b1978f2014-08-31 21:19:43 +053041 make sandbox_defconfig all
Simon Glass75b3c3a2014-03-22 17:12:59 -060042 ./u-boot
43
44Note:
45 If you get errors about 'sdl-config: Command not found' you may need to
46 install libsdl1.2-dev or similar to get SDL support. Alternatively you can
47 build sandbox without SDL (i.e. no display/keyboard support) by removing
48 the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using:
49
Jagannadha Sutradharudu Teki6b1978f2014-08-31 21:19:43 +053050 make sandbox_defconfig all NO_SDL=1
Simon Glass75b3c3a2014-03-22 17:12:59 -060051 ./u-boot
52
Simon Glass75b3c3a2014-03-22 17:12:59 -060053U-Boot will start on your computer, showing a sandbox emulation of the serial
54console:
55
56
57U-Boot 2014.04 (Mar 20 2014 - 19:06:00)
58
59DRAM: 128 MiB
60Using default environment
61
62In: serial
63Out: lcd
64Err: lcd
65=>
66
67You can issue commands as your would normally. If the command you want is
68not supported you can add it to include/configs/sandbox.h.
69
70To exit, type 'reset' or press Ctrl-C.
71
72
73Console / LCD support
74---------------------
75
76Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the
77sandbox with LCD and keyboard emulation, using something like:
78
79 ./u-boot -d u-boot.dtb -l
80
81This will start U-Boot with a window showing the contents of the LCD. If
82that window has the focus then you will be able to type commands as you
83would on the console. You can adjust the display settings in the device
84tree file - see arch/sandbox/dts/sandbox.dts.
85
86
87Command-line Options
88--------------------
89
90Various options are available, mostly for test purposes. Use -h to see
91available options. Some of these are described below.
92
93The terminal is normally in what is called 'raw-with-sigs' mode. This means
94that you can use arrow keys for command editing and history, but if you
95press Ctrl-C, U-Boot will exit instead of handling this as a keypress.
96
97Other options are 'raw' (so Ctrl-C is handled within U-Boot) and 'cooked'
98(where the terminal is in cooked mode and cursor keys will not work, Ctrl-C
99will exit).
100
101As mentioned above, -l causes the LCD emulation window to be shown.
102
103A device tree binary file can be provided with -d. If you edit the source
104(it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to
105recreate the binary file.
106
107To execute commands directly, use the -c option. You can specify a single
108command, or multiple commands separated by a semicolon, as is normal in
109U-Boot. Be careful with quoting as the shall will normally process and
110swallow quotes. When -c is used, U-Boot exists after the command is complete,
111but you can force it to go to interactive mode instead with -i.
112
113
114Memory Emulation
115----------------
116
117Memory emulation is supported, with the size set by CONFIG_SYS_SDRAM_SIZE.
118The -m option can be used to read memory from a file on start-up and write
119it when shutting down. This allows preserving of memory contents across
120test runs. You can tell U-Boot to remove the memory file after it is read
121(on start-up) with the --rm_memory option.
122
123To access U-Boot's emulated memory within the code, use map_sysmem(). This
124function is used throughout U-Boot to ensure that emulated memory is used
125rather than the U-Boot application memory. This provides memory starting
126at 0 and extending to the size of the emulation.
127
128
129Storing State
130-------------
131
132With sandbox you can write drivers which emulate the operation of drivers on
133real devices. Some of these drivers may want to record state which is
134preserved across U-Boot runs. This is particularly useful for testing. For
135example, the contents of a SPI flash chip should not disappear just because
136U-Boot exits.
137
138State is stored in a device tree file in a simple format which is driver-
139specific. You then use the -s option to specify the state file. Use -r to
140make U-Boot read the state on start-up (otherwise it starts empty) and -w
141to write it on exit (otherwise the stored state is left unchanged and any
142changes U-Boot made will be lost). You can also use -n to tell U-Boot to
143ignore any problems with missing state. This is useful when first running
144since the state file will be empty.
145
146The device tree file has one node for each driver - the driver can store
147whatever properties it likes in there. See 'Writing Sandbox Drivers' below
148for more details on how to get drivers to read and write their state.
149
150
151Running and Booting
152-------------------
153
154Since there is no machine architecture, sandbox U-Boot cannot actually boot
155a kernel, but it does support the bootm command. Filesystems, memory
156commands, hashing, FIT images, verified boot and many other features are
157supported.
158
159When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real
160machine. Of course in this case, no kernel is run.
161
162It is also possible to tell U-Boot that it has jumped from a temporary
163previous U-Boot binary, with the -j option. That binary is automatically
164removed by the U-Boot that gets the -j option. This allows you to write
165tests which emulate the action of chain-loading U-Boot, typically used in
166a situation where a second 'updatable' U-Boot is stored on your board. It
167is very risky to overwrite or upgrade the only U-Boot on a board, since a
168power or other failure will brick the board and require return to the
169manufacturer in the case of a consumer device.
170
171
172Supported Drivers
173-----------------
174
175U-Boot sandbox supports these emulations:
176
177- Block devices
178- Chrome OS EC
179- GPIO
180- Host filesystem (access files on the host from within U-Boot)
Joe Hershberger3ea143a2015-03-22 17:09:13 -0500181- I2C
Simon Glass75b3c3a2014-03-22 17:12:59 -0600182- Keyboard (Chrome OS)
183- LCD
Joe Hershberger3ea143a2015-03-22 17:09:13 -0500184- Network
Simon Glass75b3c3a2014-03-22 17:12:59 -0600185- Serial (for console only)
186- Sound (incomplete - see sandbox_sdl_sound_init() for details)
187- SPI
188- SPI flash
189- TPM (Trusted Platform Module)
190
Simon Glass75b3c3a2014-03-22 17:12:59 -0600191A wide range of commands is implemented. Filesystems which use a block
192device are supported.
193
Simon Glass89b199c2016-05-14 18:49:27 -0600194Also sandbox supports driver model (CONFIG_DM) and associated commands.
Simon Glass744d9852011-10-10 08:22:14 +0000195
196
Joe Hershbergera346ca72015-03-22 17:09:21 -0500197Linux RAW Networking Bridge
198---------------------------
199
200The sandbox_eth_raw driver bridges traffic between the bottom of the network
201stack and the RAW sockets API in Linux. This allows much of the U-Boot network
202functionality to be tested in sandbox against real network traffic.
203
204For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API. This
205is needed to get access to the lowest level of the network stack in Linux. This
206means that all of the Ethernet frame is included. This allows the U-Boot network
207stack to be fully used. In other words, nothing about the Linux network stack is
208involved in forming the packets that end up on the wire. To receive the
209responses to packets sent from U-Boot the network interface has to be set to
210promiscuous mode so that the network card won't filter out packets not destined
211for its configured (on Linux) MAC address.
212
213The RAW sockets Ethernet API requires elevated privileges in Linux. You can
214either run as root, or you can add the capability needed like so:
215
216sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot
217
218The default device tree for sandbox includes an entry for eth0 on the sandbox
219host machine whose alias is "eth1". The following are a few examples of network
220operations being tested on the eth0 interface.
221
222sudo /path/to/u-boot -D
223
224DHCP
225....
226
227set autoload no
228set ethact eth1
229dhcp
230
231PING
232....
233
234set autoload no
235set ethact eth1
236dhcp
237ping $gatewayip
238
239TFTP
240....
241
242set autoload no
243set ethact eth1
244dhcp
245set serverip WWW.XXX.YYY.ZZZ
246tftpboot u-boot.bin
247
Joe Hershberger22f68522015-03-22 17:09:23 -0500248The bridge also support (to a lesser extent) the localhost inderface, 'lo'.
249
250The 'lo' interface cannot use the RAW AF_PACKET API because the lo interface
251doesn't support Ethernet-level traffic. It is a higher-level interface that is
252expected only to be used at the AF_INET level of the API. As such, the most raw
253we can get on that interface is the RAW AF_INET API on UDP. This allows us to
254set the IP_HDRINCL option to include everything except the Ethernet header in
255the packets we send and receive.
256
257Because only UDP is supported, ICMP traffic will not work, so expect that ping
258commands will time out.
259
260The default device tree for sandbox includes an entry for lo on the sandbox
261host machine whose alias is "eth5". The following is an example of a network
262operation being tested on the lo interface.
263
264TFTP
265....
266
267set ethact eth5
268tftpboot u-boot.bin
269
Joe Hershbergera346ca72015-03-22 17:09:21 -0500270
Mike Frysingerffdb20b2013-12-03 16:43:27 -0700271SPI Emulation
272-------------
273
274Sandbox supports SPI and SPI flash emulation.
275
276This is controlled by the spi_sf argument, the format of which is:
277
278 bus:cs:device:file
279
280 bus - SPI bus number
281 cs - SPI chip select number
282 device - SPI device emulation name
283 file - File on disk containing the data
284
285For example:
286
287 dd if=/dev/zero of=spi.bin bs=1M count=4
288 ./u-boot --spi_sf 0:0:M25P16:spi.bin
289
290With this setup you can issue SPI flash commands as normal:
291
292=>sf probe
293SF: Detected M25P16 with page size 64 KiB, total 2 MiB
294=>sf read 0 0 10000
295SF: 65536 bytes @ 0x0 Read: OK
296=>
297
298Since this is a full SPI emulation (rather than just flash), you can
299also use low-level SPI commands:
300
301=>sspi 0:0 32 9f
302FF202015
303
304This is issuing a READ_ID command and getting back 20 (ST Micro) part
3050x2015 (the M25P16).
306
307Drivers are connected to a particular bus/cs using sandbox's state
308structure (see the 'spi' member). A set of operations must be provided
309for each driver.
310
311
312Configuration settings for the curious are:
313
314CONFIG_SANDBOX_SPI_MAX_BUS
315 The maximum number of SPI buses supported by the driver (default 1).
316
317CONFIG_SANDBOX_SPI_MAX_CS
318 The maximum number of chip selects supported by the driver
319 (default 10).
320
321CONFIG_SPI_IDLE_VAL
322 The idle value on the SPI bus
323
324
Stefan Brüns2945eb72016-08-11 22:52:03 +0200325Block Device Emulation
326----------------------
327
328U-Boot can use raw disk images for block device emulation. To e.g. list
329the contents of the root directory on the second partion of the image
330"disk.raw", you can use the following commands:
331
332=>host bind 0 ./disk.raw
333=>ls host 0:2
334
335A disk image can be created using the following commands:
336
337$> truncate -s 1200M ./disk.raw
Alison Chaiken6b20c342017-06-04 15:11:20 -0700338$> echo -e "label: gpt\n,64M,U\n,,L" | /usr/sbin/sgdisk ./disk.raw
Stefan Brüns2945eb72016-08-11 22:52:03 +0200339$> lodev=`sudo losetup -P -f --show ./disk.raw`
340$> sudo mkfs.vfat -n EFI -v ${lodev}p1
341$> sudo mkfs.ext4 -L ROOT -v ${lodev}p2
342
Alison Chaikenbf6d76b2017-09-09 23:47:12 -0700343or utilize the device described in test/py/make_test_disk.py:
344
345 #!/usr/bin/python
346 import make_test_disk
347 make_test_disk.makeDisk()
Stefan Brüns2945eb72016-08-11 22:52:03 +0200348
Simon Glass75b3c3a2014-03-22 17:12:59 -0600349Writing Sandbox Drivers
350-----------------------
Simon Glass744d9852011-10-10 08:22:14 +0000351
Simon Glass75b3c3a2014-03-22 17:12:59 -0600352Generally you should put your driver in a file containing the word 'sandbox'
353and put it in the same directory as other drivers of its type. You can then
354implement the same hooks as the other drivers.
355
356To access U-Boot's emulated memory, use map_sysmem() as mentioned above.
357
358If your driver needs to store configuration or state (such as SPI flash
359contents or emulated chip registers), you can use the device tree as
360described above. Define handlers for this with the SANDBOX_STATE_IO macro.
361See arch/sandbox/include/asm/state.h for documentation. In short you provide
362a node name, compatible string and functions to read and write the state.
363Since writing the state can expand the device tree, you may need to use
364state_setprop() which does this automatically and avoids running out of
365space. See existing code for examples.
366
367
368Testing
369-------
370
371U-Boot sandbox can be used to run various tests, mostly in the test/
372directory. These include:
373
374 command_ut
375 - Unit tests for command parsing and handling
376 compression
377 - Unit tests for U-Boot's compression algorithms, useful for
378 security checking. It supports gzip, bzip2, lzma and lzo.
379 driver model
Jagan Teki7b3dc452016-03-17 12:23:19 +0530380 - Run this pytest
381 ./test/py/test.py --bd sandbox --build -k ut_dm -v
Simon Glass75b3c3a2014-03-22 17:12:59 -0600382 image
383 - Unit tests for images:
384 test/image/test-imagetools.sh - multi-file images
385 test/image/test-fit.py - FIT images
386 tracing
387 - test/trace/test-trace.sh tests the tracing system (see README.trace)
388 verified boot
389 - See test/vboot/vboot_test.sh for this
390
391If you change or enhance any of the above subsystems, you shold write or
392expand a test and include it with your patch series submission. Test
393coverage in U-Boot is limited, as we need to work to improve it.
394
395Note that many of these tests are implemented as commands which you can
396run natively on your board if desired (and enabled).
397
398It would be useful to have a central script to run all of these.
399
400--
401Simon Glass <sjg@chromium.org>
402Updated 22-Mar-14