+/* 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_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.
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.
+
+
+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
+....
+
+set autoload no
+set ethact eth1
+dhcp
+
+PING
+....
+
+set autoload no
+set ethact eth1
+dhcp
+ping $gatewayip
+
+TFTP
+....
+
+set autoload no
+set ethact eth1
+dhcp
+set 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
+....
+
+set 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
-----------------------
- 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