+/* SPDX-License-Identifier: GPL-2.0+ */
/*
* Copyright (c) 2014 The Chromium OS Authors.
- *
- * SPDX-License-Identifier: GPL-2.0+
*/
Native Execution of U-Boot
CONFIG_SANDBOX is defined when building a native board.
-The chosen vendor and board names are also 'sandbox', so there is a single
-board in board/sandbox/sandbox.
+The board name is 'sandbox' but the vendor name is unset, so there is a
+single board in board/sandbox.
CONFIG_SANDBOX_BIG_ENDIAN should be defined when running on big-endian
machines.
+There are two versions of the sandbox: One using 32-bit-wide integers, and one
+using 64-bit-wide integers. The 32-bit version can be build and run on either
+32 or 64-bit hosts by either selecting or deselecting CONFIG_SANDBOX_32BIT; by
+default, the sandbox it built for a 32-bit host. The sandbox using 64-bit-wide
+integers can only be built on 64-bit hosts.
+
Note that standalone/API support is not available at present.
To run sandbox U-Boot use something like:
- make sandbox_config all
+ make sandbox_defconfig all
./u-boot
Note:
build sandbox without SDL (i.e. no display/keyboard support) by removing
the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using:
- make sandbox_config all NO_SDL=1
+ make sandbox_defconfig all NO_SDL=1
./u-boot
-
U-Boot will start on your computer, showing a sandbox emulation of the serial
console:
To execute commands directly, use the -c option. You can specify a single
command, or multiple commands separated by a semicolon, as is normal in
-U-Boot. Be careful with quoting as the shall will normally process and
-swallow quotes. When -c is used, U-Boot exists after the command is complete,
+U-Boot. Be careful with quoting as the shell will normally process and
+swallow quotes. When -c is used, U-Boot exits after the command is complete,
but you can force it to go to interactive mode instead with -i.
- Chrome OS EC
- GPIO
- Host filesystem (access files on the host from within U-Boot)
+- I2C
- Keyboard (Chrome OS)
- LCD
+- Network
- Serial (for console only)
- Sound (incomplete - see sandbox_sdl_sound_init() for details)
- SPI
- SPI flash
- TPM (Trusted Platform Module)
-Notable omissions are networking and I2C.
-
-A wide range of commands is implemented. Filesystems which use a block
+A wide range of commands are implemented. Filesystems which use a block
device are supported.
-Also sandbox uses generic board (CONFIG_SYS_GENERIC_BOARD) and supports
-driver model (CONFIG_DM) and associated commands.
+Also sandbox supports driver model (CONFIG_DM) and associated commands.
+
+
+Sandbox Variants
+----------------
+
+There are unfortunately quite a few variants at present:
+
+sandbox - should be used for most tests
+sandbox64 - special build that forces a 64-bit host
+sandbox_flattree - builds with dev_read_...() functions defined as inline.
+ We need this build so that we can test those inline functions, and we
+ cannot build with both the inline functions and the non-inline functions
+ since they are named the same.
+sandbox_noblk - builds without CONFIG_BLK, which means the legacy block
+ drivers are used. We cannot use both the legacy and driver-model block
+ drivers since they implement the same functions
+sandbox_spl - builds sandbox with SPL support, so you can run spl/u-boot-spl
+ and it will start up and then load ./u-boot. It is also possible to
+ run ./u-boot directly.
+
+Of these sandbox_noblk can be removed once CONFIG_BLK is used everwhere, and
+sandbox_spl can probably be removed since it is a superset of sandbox.
+
+Most of the config options should be identical between these variants.
+
+
+Linux RAW Networking Bridge
+---------------------------
+
+The sandbox_eth_raw driver bridges traffic between the bottom of the network
+stack and the RAW sockets API in Linux. This allows much of the U-Boot network
+functionality to be tested in sandbox against real network traffic.
+
+For Ethernet network adapters, the bridge utilizes the RAW AF_PACKET API. This
+is needed to get access to the lowest level of the network stack in Linux. This
+means that all of the Ethernet frame is included. This allows the U-Boot network
+stack to be fully used. In other words, nothing about the Linux network stack is
+involved in forming the packets that end up on the wire. To receive the
+responses to packets sent from U-Boot the network interface has to be set to
+promiscuous mode so that the network card won't filter out packets not destined
+for its configured (on Linux) MAC address.
+
+The RAW sockets Ethernet API requires elevated privileges in Linux. You can
+either run as root, or you can add the capability needed like so:
+
+sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot
+
+The default device tree for sandbox includes an entry for eth0 on the sandbox
+host machine whose alias is "eth1". The following are a few examples of network
+operations being tested on the eth0 interface.
+
+sudo /path/to/u-boot -D
+
+DHCP
+....
+
+setenv autoload no
+setenv ethrotate no
+setenv ethact eth1
+dhcp
+
+PING
+....
+
+setenv autoload no
+setenv ethrotate no
+setenv ethact eth1
+dhcp
+ping $gatewayip
+
+TFTP
+....
+
+setenv autoload no
+setenv ethrotate no
+setenv ethact eth1
+dhcp
+setenv serverip WWW.XXX.YYY.ZZZ
+tftpboot u-boot.bin
+
+The bridge also supports (to a lesser extent) the localhost interface, 'lo'.
+
+The 'lo' interface cannot use the RAW AF_PACKET API because the lo interface
+doesn't support Ethernet-level traffic. It is a higher-level interface that is
+expected only to be used at the AF_INET level of the API. As such, the most raw
+we can get on that interface is the RAW AF_INET API on UDP. This allows us to
+set the IP_HDRINCL option to include everything except the Ethernet header in
+the packets we send and receive.
+
+Because only UDP is supported, ICMP traffic will not work, so expect that ping
+commands will time out.
+
+The default device tree for sandbox includes an entry for lo on the sandbox
+host machine whose alias is "eth5". The following is an example of a network
+operation being tested on the lo interface.
+
+TFTP
+....
+
+setenv ethrotate no
+setenv ethact eth5
+tftpboot u-boot.bin
SPI Emulation
The idle value on the SPI bus
+Block Device Emulation
+----------------------
+
+U-Boot can use raw disk images for block device emulation. To e.g. list
+the contents of the root directory on the second partion of the image
+"disk.raw", you can use the following commands:
+
+=>host bind 0 ./disk.raw
+=>ls host 0:2
+
+A disk image can be created using the following commands:
+
+$> truncate -s 1200M ./disk.raw
+$> echo -e "label: gpt\n,64M,U\n,,L" | /usr/sbin/sgdisk ./disk.raw
+$> lodev=`sudo losetup -P -f --show ./disk.raw`
+$> sudo mkfs.vfat -n EFI -v ${lodev}p1
+$> sudo mkfs.ext4 -L ROOT -v ${lodev}p2
+
+or utilize the device described in test/py/make_test_disk.py:
+
+ #!/usr/bin/python
+ import make_test_disk
+ make_test_disk.makeDisk()
+
Writing Sandbox Drivers
-----------------------
space. See existing code for examples.
+Debugging the init sequence
+---------------------------
+
+If you get a failure in the initcall sequence, like this:
+
+ initcall sequence 0000560775957c80 failed at call 0000000000048134 (err=-96)
+
+Then you use can use grep to see which init call failed, e.g.:
+
+ $ grep 0000000000048134 u-boot.map
+ stdio_add_devices
+
+Of course another option is to run it with a debugger such as gdb:
+
+ $ gdb u-boot
+ ...
+ (gdb) br initcall.h:41
+ Breakpoint 1 at 0x4db9d: initcall.h:41. (2 locations)
+
+Note that two locations are reported, since this function is used in both
+board_init_f() and board_init_r().
+
+ (gdb) r
+ Starting program: /tmp/b/sandbox/u-boot
+ [Thread debugging using libthread_db enabled]
+ Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
+
+ U-Boot 2018.09-00264-ge0c2ba9814-dirty (Sep 22 2018 - 12:21:46 -0600)
+
+ DRAM: 128 MiB
+ MMC:
+
+ Breakpoint 1, initcall_run_list (init_sequence=0x5555559619e0 <init_sequence_f>)
+ at /scratch/sglass/cosarm/src/third_party/u-boot/files/include/initcall.h:41
+ 41 printf("initcall sequence %p failed at call %p (err=%d)\n",
+ (gdb) print *init_fnc_ptr
+ $1 = (const init_fnc_t) 0x55555559c114 <stdio_add_devices>
+ (gdb)
+
+
+This approach can be used on normal boards as well as sandbox.
+
+
Testing
-------
- Unit tests for U-Boot's compression algorithms, useful for
security checking. It supports gzip, bzip2, lzma and lzo.
driver model
- - test/dm/test-dm.sh to run these.
+ - Run this pytest
+ ./test/py/test.py --bd sandbox --build -k ut_dm -v
image
- Unit tests for images:
test/image/test-imagetools.sh - multi-file images
Note that many of these tests are implemented as commands which you can
run natively on your board if desired (and enabled).
-It would be useful to have a central script to run all of these.
+To run all tests use "make check".
+
+
+Memory Map
+----------
+
+Sandbox has its own emulated memory starting at 0. Here are some of the things
+that are mapped into that memory:
+
+ 0 CONFIG_SYS_FDT_LOAD_ADDR Device tree
+ e000 CONFIG_BLOBLIST_ADDR Blob list
+ 10000 CONFIG_MALLOC_F_ADDR Early memory allocation
+ f0000 CONFIG_PRE_CON_BUF_ADDR Pre-console buffer
+ 100000 CONFIG_TRACE_EARLY_ADDR Early trace buffer (if enabled)
+=
+
--
Simon Glass <sjg@chromium.org>
git.openpandora.org / pandora-u-boot.git / blobdiff