From 49116e6d236da39bf2695775dc0c8377e4e7a809 Mon Sep 17 00:00:00 2001 From: Bin Meng Date: Thu, 18 Jul 2019 00:34:33 -0700 Subject: [PATCH] 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 --- doc/arch/index.rst | 1 + .../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 d24662e361..2980b77dec 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 c10dd444df..5c0caebcbf 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 + +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 -Updated 22-Mar-14 +======= ======================== =============================== -- 2.25.1