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>

doc/arch/index.rst

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

doc/arch/sandbox.rst

@@ -1,10 +1,12 @@
-/* SPDX-License-Identifier: GPL-2.0+ */
+.. SPDX-License-Identifier: GPL-2.0+ */
-/*
+.. Copyright (c) 2014 The Chromium OS Authors.
- * 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,23 +37,21 @@ 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:
+Note: If you get errors about 'sdl-config: Command not found' you may need to
-   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:
+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)
 
@@ -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
+sandbox:
-sandbox64 - special build that forces a 64-bit host
+  should be used for most tests
-sandbox_flattree - builds with dev_read_...() functions defined as inline.
+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,7 +239,7 @@ 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
 
@@ -242,6 +247,8 @@ 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.
 
+.. code-block:: none
+
    sudo /path/to/u-boot -D
 
    DHCP
@@ -287,6 +294,8 @@ 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.
 
+.. code-block:: none
+
    TFTP
    ....
 
@@ -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,21 +318,20 @@ 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
-=>
 
 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
@@ -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
+CONFIG_SANDBOX_SPI_MAX_CS:
-	The maximum number of chip selects supported by the driver
+  The maximum number of chip selects supported by the driver (default 10).
-	(default 10).
 
-CONFIG_SPI_IDLE_VAL
+CONFIG_SPI_IDLE_VAL:
   The idle value on the SPI bus
 
 
@@ -354,12 +361,12 @@ 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
 
-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
@@ -367,7 +374,7 @@ $> 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
+command_ut:
-     - Unit tests for command parsing and handling
+  Unit tests for command parsing and handling
-  compression
+compression:
-     - Unit tests for U-Boot's compression algorithms, useful for
+  Unit tests for U-Boot's compression algorithms, useful for
   security checking. It supports gzip, bzip2, lzma and lzo.
-  driver model
+driver model:
-     - Run this pytest
+  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
+tracing:
-     - test/trace/test-trace.sh tests the tracing system (see README.trace)
+  test/trace/test-trace.sh tests the tracing system (see README.trace)
-  verified boot
+verified boot:
-      - See test/vboot/vboot_test.sh for this
+  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