sandbox.rst 17 KB

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