README.sandbox 12 KB

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