doc: arch: Convert README.sandbox to reST

Convert plain text documentation to reStructuredText format and add
it to Sphinx TOC tree. No essential content change.

Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
This commit is contained in:
Bin Meng 2019-07-18 00:34:33 -07:00 committed by Tom Rini
parent f25c369096
commit 49116e6d23
2 changed files with 131 additions and 121 deletions

View File

@ -12,5 +12,6 @@ Architecture-specific doc
mips
nds32
nios2
sandbox
sh
x86

View File

@ -1,10 +1,12 @@
/* SPDX-License-Identifier: GPL-2.0+ */
/*
* Copyright (c) 2014 The Chromium OS Authors.
*/
.. SPDX-License-Identifier: GPL-2.0+ */
.. Copyright (c) 2014 The Chromium OS Authors.
.. sectionauthor:: Simon Glass <sjg@chromium.org>
Sandbox
=======
Native Execution of U-Boot
==========================
--------------------------
The 'sandbox' architecture is designed to allow U-Boot to run under Linux on
almost any hardware. To achieve this it builds U-Boot (so far as possible)
@ -35,33 +37,31 @@ Note that standalone/API support is not available at present.
Basic Operation
---------------
To run sandbox U-Boot use something like:
To run sandbox U-Boot use something like::
make sandbox_defconfig all
./u-boot
Note:
If you get errors about 'sdl-config: Command not found' you may need to
install libsdl1.2-dev or similar to get SDL support. Alternatively you can
build sandbox without SDL (i.e. no display/keyboard support) by removing
the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using:
Note: If you get errors about 'sdl-config: Command not found' you may need to
install libsdl1.2-dev or similar to get SDL support. Alternatively you can
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_defconfig all NO_SDL=1
./u-boot
U-Boot will start on your computer, showing a sandbox emulation of the serial
console:
console::
U-Boot 2014.04 (Mar 20 2014 - 19:06:00)
U-Boot 2014.04 (Mar 20 2014 - 19:06:00)
DRAM: 128 MiB
Using default environment
DRAM: 128 MiB
Using default environment
In: serial
Out: lcd
Err: lcd
=>
In: serial
Out: lcd
Err: lcd
=>
You can issue commands as your would normally. If the command you want is
not supported you can add it to include/configs/sandbox.h.
@ -73,7 +73,7 @@ Console / LCD support
---------------------
Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the
sandbox with LCD and keyboard emulation, using something like:
sandbox with LCD and keyboard emulation, using something like::
./u-boot -d u-boot.dtb -l
@ -198,16 +198,21 @@ 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.
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
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
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.
@ -234,42 +239,44 @@ 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:
either run as root, or you can add the capability needed like so::
sudo /sbin/setcap "CAP_NET_RAW+ep" /path/to/u-boot
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
.. code-block:: none
DHCP
....
sudo /path/to/u-boot -D
setenv autoload no
setenv ethrotate no
setenv ethact eth1
dhcp
DHCP
....
PING
....
setenv autoload no
setenv ethrotate no
setenv ethact eth1
dhcp
setenv autoload no
setenv ethrotate no
setenv ethact eth1
dhcp
ping $gatewayip
PING
....
TFTP
....
setenv autoload no
setenv ethrotate no
setenv ethact eth1
dhcp
ping $gatewayip
setenv autoload no
setenv ethrotate no
setenv ethact eth1
dhcp
setenv serverip WWW.XXX.YYY.ZZZ
tftpboot u-boot.bin
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'.
@ -287,12 +294,14 @@ 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
....
.. code-block:: none
setenv ethrotate no
setenv ethact eth5
tftpboot u-boot.bin
TFTP
....
setenv ethrotate no
setenv ethact eth5
tftpboot u-boot.bin
SPI Emulation
@ -300,7 +309,7 @@ SPI Emulation
Sandbox supports SPI and SPI flash emulation.
This is controlled by the spi_sf argument, the format of which is:
This is controlled by the spi_sf argument, the format of which is::
bus:cs:device:file
@ -309,24 +318,23 @@ This is controlled by the spi_sf argument, the format of which is:
device - SPI device emulation name
file - File on disk containing the data
For example:
For example::
dd if=/dev/zero of=spi.bin bs=1M count=4
./u-boot --spi_sf 0:0:M25P16:spi.bin
With this setup you can issue SPI flash commands as normal:
With this setup you can issue SPI flash commands as normal::
=>sf probe
SF: Detected M25P16 with page size 64 KiB, total 2 MiB
=>sf read 0 0 10000
SF: 65536 bytes @ 0x0 Read: OK
=>
=>sf probe
SF: Detected M25P16 with page size 64 KiB, total 2 MiB
=>sf read 0 0 10000
SF: 65536 bytes @ 0x0 Read: OK
Since this is a full SPI emulation (rather than just flash), you can
also use low-level SPI commands:
also use low-level SPI commands::
=>sspi 0:0 32 9f
FF202015
=>sspi 0:0 32 9f
FF202015
This is issuing a READ_ID command and getting back 20 (ST Micro) part
0x2015 (the M25P16).
@ -338,14 +346,13 @@ for each driver.
Configuration settings for the curious are:
CONFIG_SANDBOX_SPI_MAX_BUS
CONFIG_SANDBOX_SPI_MAX_BUS:
The maximum number of SPI buses supported by the driver (default 1).
CONFIG_SANDBOX_SPI_MAX_CS
The maximum number of chip selects supported by the driver
(default 10).
CONFIG_SANDBOX_SPI_MAX_CS:
The maximum number of chip selects supported by the driver (default 10).
CONFIG_SPI_IDLE_VAL
CONFIG_SPI_IDLE_VAL:
The idle value on the SPI bus
@ -354,20 +361,20 @@ 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:
"disk.raw", you can use the following commands::
=>host bind 0 ./disk.raw
=>ls host 0:2
=>host bind 0 ./disk.raw
=>ls host 0:2
A disk image can be created using the following commands:
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
$> 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:
or utilize the device described in test/py/make_test_disk.py::
#!/usr/bin/python
import make_test_disk
@ -395,16 +402,16 @@ space. See existing code for examples.
Debugging the init sequence
---------------------------
If you get a failure in the initcall sequence, like this:
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.:
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:
Of course another option is to run it with a debugger such as gdb::
$ gdb u-boot
...
@ -414,6 +421,8 @@ Of course another option is to run it with a debugger such as gdb:
Note that two locations are reported, since this function is used in both
board_init_f() and board_init_r().
.. code-block:: none
(gdb) r
Starting program: /tmp/b/sandbox/u-boot
[Thread debugging using libthread_db enabled]
@ -445,13 +454,13 @@ environment variable to the correct pathname before building U-Boot.
Using valgrind / memcheck
-------------------------
It is possible to run U-Boot under valgrind to check memory allocations:
It is possible to run U-Boot under valgrind to check memory allocations::
valgrind u-boot
If you are running sandbox SPL or TPL, then valgrind will not by default
notice when U-Boot jumps from TPL to SPL, or from SPL to U-Boot proper. To
fix this, use:
fix this, use::
valgrind --trace-children=yes u-boot
@ -462,22 +471,24 @@ Testing
U-Boot sandbox can be used to run various tests, mostly in the test/
directory. These include:
command_ut
- Unit tests for command parsing and handling
compression
- Unit tests for U-Boot's compression algorithms, useful for
command_ut:
Unit tests for command parsing and handling
compression:
Unit tests for U-Boot's compression algorithms, useful for
security checking. It supports gzip, bzip2, lzma and lzo.
driver model
- Run this pytest
driver model:
Run this pytest::
./test/py/test.py --bd sandbox --build -k ut_dm -v
image
- Unit tests for images:
image:
Unit tests for images:
test/image/test-imagetools.sh - multi-file images
test/image/test-fit.py - FIT images
tracing
- test/trace/test-trace.sh tests the tracing system (see README.trace)
verified boot
- See test/vboot/vboot_test.sh for this
tracing:
test/trace/test-trace.sh tests the tracing system (see README.trace)
verified boot:
See test/vboot/vboot_test.sh for this
If you change or enhance any of the above subsystems, you shold write or
expand a test and include it with your patch series submission. Test
@ -495,14 +506,12 @@ Memory Map
Sandbox has its own emulated memory starting at 0. Here are some of the things
that are mapped into that memory:
======= ======================== ===============================
Addr Config Usage
======= ======================== ===============================
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>
Updated 22-Mar-14
======= ======================== ===============================