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