board/sandbox/README.sandbox

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