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