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