xref: /openbmc/u-boot/board/sandbox/README.sandbox (revision c66f5620)
1/* SPDX-License-Identifier: GPL-2.0+ */
2/*
3 * Copyright (c) 2014 The Chromium OS Authors.
4 */
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
20The board name is 'sandbox' but the vendor name is unset, so there is a
21single board in board/sandbox.
22
23CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian
24machines.
25
26There 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.
31
32Note that standalone/API support is not available at present.
33
34
35Basic Operation
36---------------
37
38To run sandbox U-Boot use something like:
39
40   make sandbox_defconfig all
41   ./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
49      make sandbox_defconfig all NO_SDL=1
50      ./u-boot
51
52U-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
108U-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,
110but 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)
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)
189
190A wide range of commands are implemented. Filesystems which use a block
191device are supported.
192
193Also sandbox supports driver model (CONFIG_DM) and associated commands.
194
195
196Linux RAW Networking Bridge
197---------------------------
198
199The sandbox_eth_raw driver bridges traffic between the bottom of the network
200stack and the RAW sockets API in Linux. This allows much of the U-Boot network
201functionality to be tested in sandbox against real network traffic.
202
203For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API.  This
204is needed to get access to the lowest level of the network stack in Linux. This
205means that all of the Ethernet frame is included. This allows the U-Boot network
206stack to be fully used. In other words, nothing about the Linux network stack is
207involved in forming the packets that end up on the wire. To receive the
208responses to packets sent from U-Boot the network interface has to be set to
209promiscuous mode so that the network card won't filter out packets not destined
210for its configured (on Linux) MAC address.
211
212The RAW sockets Ethernet API requires elevated privileges in Linux. You can
213either run as root, or you can add the capability needed like so:
214
215sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot
216
217The default device tree for sandbox includes an entry for eth0 on the sandbox
218host machine whose alias is "eth1". The following are a few examples of network
219operations being tested on the eth0 interface.
220
221sudo /path/to/u-boot -D
222
223DHCP
224....
225
226set autoload no
227set ethact eth1
228dhcp
229
230PING
231....
232
233set autoload no
234set ethact eth1
235dhcp
236ping $gatewayip
237
238TFTP
239....
240
241set autoload no
242set ethact eth1
243dhcp
244set serverip WWW.XXX.YYY.ZZZ
245tftpboot u-boot.bin
246
247The bridge also supports (to a lesser extent) the localhost interface, 'lo'.
248
249The 'lo' interface cannot use the RAW AF_PACKET API because the lo interface
250doesn't support Ethernet-level traffic. It is a higher-level interface that is
251expected only to be used at the AF_INET level of the API. As such, the most raw
252we can get on that interface is the RAW AF_INET API on UDP. This allows us to
253set the IP_HDRINCL option to include everything except the Ethernet header in
254the packets we send and receive.
255
256Because only UDP is supported, ICMP traffic will not work, so expect that ping
257commands will time out.
258
259The default device tree for sandbox includes an entry for lo on the sandbox
260host machine whose alias is "eth5". The following is an example of a network
261operation being tested on the lo interface.
262
263TFTP
264....
265
266set ethact eth5
267tftpboot u-boot.bin
268
269
270SPI Emulation
271-------------
272
273Sandbox supports SPI and SPI flash emulation.
274
275This is controlled by the spi_sf argument, the format of which is:
276
277   bus:cs:device:file
278
279   bus    - SPI bus number
280   cs     - SPI chip select number
281   device - SPI device emulation name
282   file   - File on disk containing the data
283
284For example:
285
286 dd if=/dev/zero of=spi.bin bs=1M count=4
287 ./u-boot --spi_sf 0:0:M25P16:spi.bin
288
289With this setup you can issue SPI flash commands as normal:
290
291=>sf probe
292SF: Detected M25P16 with page size 64 KiB, total 2 MiB
293=>sf read 0 0 10000
294SF: 65536 bytes @ 0x0 Read: OK
295=>
296
297Since this is a full SPI emulation (rather than just flash), you can
298also use low-level SPI commands:
299
300=>sspi 0:0 32 9f
301FF202015
302
303This is issuing a READ_ID command and getting back 20 (ST Micro) part
3040x2015 (the M25P16).
305
306Drivers are connected to a particular bus/cs using sandbox's state
307structure (see the 'spi' member). A set of operations must be provided
308for each driver.
309
310
311Configuration settings for the curious are:
312
313CONFIG_SANDBOX_SPI_MAX_BUS
314	The maximum number of SPI buses supported by the driver (default 1).
315
316CONFIG_SANDBOX_SPI_MAX_CS
317	The maximum number of chip selects supported by the driver
318	(default 10).
319
320CONFIG_SPI_IDLE_VAL
321	The idle value on the SPI bus
322
323
324Block Device Emulation
325----------------------
326
327U-Boot can use raw disk images for block device emulation. To e.g. list
328the contents of the root directory on the second partion of the image
329"disk.raw", you can use the following commands:
330
331=>host bind 0 ./disk.raw
332=>ls host 0:2
333
334A disk image can be created using the following commands:
335
336$> truncate -s 1200M ./disk.raw
337$> echo -e "label: gpt\n,64M,U\n,,L" | /usr/sbin/sgdisk  ./disk.raw
338$> lodev=`sudo losetup -P -f --show ./disk.raw`
339$> sudo mkfs.vfat -n EFI -v ${lodev}p1
340$> sudo mkfs.ext4 -L ROOT -v ${lodev}p2
341
342or utilize the device described in test/py/make_test_disk.py:
343
344   #!/usr/bin/python
345   import make_test_disk
346   make_test_disk.makeDisk()
347
348Writing Sandbox Drivers
349-----------------------
350
351Generally you should put your driver in a file containing the word 'sandbox'
352and put it in the same directory as other drivers of its type. You can then
353implement the same hooks as the other drivers.
354
355To access U-Boot's emulated memory, use map_sysmem() as mentioned above.
356
357If your driver needs to store configuration or state (such as SPI flash
358contents or emulated chip registers), you can use the device tree as
359described above. Define handlers for this with the SANDBOX_STATE_IO macro.
360See arch/sandbox/include/asm/state.h for documentation. In short you provide
361a node name, compatible string and functions to read and write the state.
362Since writing the state can expand the device tree, you may need to use
363state_setprop() which does this automatically and avoids running out of
364space. See existing code for examples.
365
366
367Testing
368-------
369
370U-Boot sandbox can be used to run various tests, mostly in the test/
371directory. These include:
372
373  command_ut
374     - Unit tests for command parsing and handling
375  compression
376     - Unit tests for U-Boot's compression algorithms, useful for
377       security checking. It supports gzip, bzip2, lzma and lzo.
378  driver model
379     - Run this pytest
380	  ./test/py/test.py --bd sandbox --build -k ut_dm -v
381  image
382     - Unit tests for images:
383          test/image/test-imagetools.sh - multi-file images
384          test/image/test-fit.py        - FIT images
385  tracing
386     - test/trace/test-trace.sh tests the tracing system (see README.trace)
387  verified boot
388      - See test/vboot/vboot_test.sh for this
389
390If you change or enhance any of the above subsystems, you shold write or
391expand a test and include it with your patch series submission. Test
392coverage in U-Boot is limited, as we need to work to improve it.
393
394Note that many of these tests are implemented as commands which you can
395run natively on your board if desired (and enabled).
396
397It would be useful to have a central script to run all of these.
398
399--
400Simon Glass <sjg@chromium.org>
401Updated 22-Mar-14
402