[U-Boot] [PATCH 48/50] doc: arch: Convert README.sandbox to reST
Bin Meng
bmeng.cn at gmail.com
Thu Jul 18 07:34:33 UTC 2019
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 at gmail.com>
---
doc/arch/index.rst | 1 +
.../sandbox/README.sandbox => doc/arch/sandbox.rst | 251 +++++++++++----------
2 files changed, 131 insertions(+), 121 deletions(-)
rename board/sandbox/README.sandbox => doc/arch/sandbox.rst (76%)
diff --git a/doc/arch/index.rst b/doc/arch/index.rst
index d24662e..2980b77 100644
--- a/doc/arch/index.rst
+++ b/doc/arch/index.rst
@@ -12,5 +12,6 @@ Architecture-specific doc
mips
nds32
nios2
+ sandbox
sh
x86
diff --git a/board/sandbox/README.sandbox b/doc/arch/sandbox.rst
similarity index 76%
rename from board/sandbox/README.sandbox
rename to doc/arch/sandbox.rst
index c10dd44..5c0caeb 100644
--- a/board/sandbox/README.sandbox
+++ b/doc/arch/sandbox.rst
@@ -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 at 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
+ 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,18 +198,23 @@ 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.
+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.
@@ -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
+
+ sudo /path/to/u-boot -D
-DHCP
-....
+ DHCP
+ ....
-setenv autoload no
-setenv ethrotate no
-setenv ethact eth1
-dhcp
+ setenv autoload no
+ setenv ethrotate no
+ setenv ethact eth1
+ dhcp
-PING
-....
+ PING
+ ....
-setenv autoload no
-setenv ethrotate no
-setenv ethact eth1
-dhcp
-ping $gatewayip
+ setenv autoload no
+ setenv ethrotate no
+ setenv ethact eth1
+ dhcp
+ ping $gatewayip
-TFTP
-....
+ TFTP
+ ....
-setenv autoload no
-setenv ethrotate no
-setenv ethact eth1
-dhcp
-setenv serverip WWW.XXX.YYY.ZZZ
-tftpboot u-boot.bin
+ 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
+ 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,15 +346,14 @@ for each driver.
Configuration settings for the curious are:
-CONFIG_SANDBOX_SPI_MAX_BUS
- The maximum number of SPI buses supported by the driver (default 1).
+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
- The idle value on the SPI bus
+CONFIG_SPI_IDLE_VAL:
+ The idle value on the SPI bus
Block Device Emulation
@@ -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
- security checking. It supports gzip, bzip2, lzma and lzo.
- driver model
- - 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
- 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
+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::
+
+ ./test/py/test.py --bd sandbox --build -k ut_dm -v
+
+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
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 at chromium.org>
-Updated 22-Mar-14
+======= ======================== ===============================
--
2.7.4
More information about the U-Boot
mailing list