Now that sandbox has a good base of features, the README is quite out of date. Update it, and document the new features.

Signed-off-by: Simon Glass sjg@chromium.org ---

README | 11 ++ board/sandbox/sandbox/README.sandbox | 222 +++++++++++++++++++++++++++++++++-- 2 files changed, 226 insertions(+), 7 deletions(-)

diff --git a/README b/README index 216f0c7..61b0b83 100644 --- a/README +++ b/README @@ -260,6 +260,17 @@ e.g. "make cogent_mpc8xx_config". And also configure the cogent directory according to the instructions in cogent/README.

+Sandbox Environment: +-------------------- + +U-Boot can be built natively to run on a Linux host using the 'sandbox' +board. This allows feature development which is not board- or architecture- +specific to be undertaken on a native platform. The sandbox is also used to +run some of U-Boot's tests. + +See board/sandbox/sandbox/README.sandbox for more details. + + Configuration Options: ----------------------

diff --git a/board/sandbox/sandbox/README.sandbox b/board/sandbox/sandbox/README.sandbox index 6989557..529c447 100644 --- a/board/sandbox/sandbox/README.sandbox +++ b/board/sandbox/sandbox/README.sandbox @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011 The Chromium OS Authors. + * Copyright (c) 2014 The Chromium OS Authors. * * SPDX-License-Identifier: GPL-2.0+ */ @@ -26,9 +26,168 @@ machines.

Note that standalone/API support is not available at present.

-The serial driver is a very simple implementation which reads and writes to -the console. It does not set the terminal into raw mode, so cursor keys and -history will not work yet. + +Basic Operation +--------------- + +To run sandbox U-Boot use something like: + + make sandbox_config 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: + + make sandbox_config all NO_SDL=1 + ./u-boot + + +U-Boot will start on your computer, showing a sandbox emulation of the serial +console: + + +U-Boot 2014.04 (Mar 20 2014 - 19:06:00) + +DRAM: 128 MiB +Using default environment + +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. + +To exit, type 'reset' or press Ctrl-C. + + +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: + + ./u-boot -d u-boot.dtb -l + +This will start U-Boot with a window showing the contents of the LCD. If +that window has the focus then you will be able to type commands as you +would on the console. You can adjust the display settings in the device +tree file - see arch/sandbox/dts/sandbox.dts. + + +Command-line Options +-------------------- + +Various options are available, mostly for test purposes. Use -h to see +available options. Some of these are described below. + +The terminal is normally in what is called 'raw-with-sigs' mode. This means +that you can use arrow keys for command editing and history, but if you +press Ctrl-C, U-Boot will exit instead of handling this as a keypress. + +Other options are 'raw' (so Ctrl-C is handled within U-Boot) and 'cooked' +(where the terminal is in cooked mode and cursor keys will not work, Ctrl-C +will exit). + +As mentioned above, -l causes the LCD emulation window to be shown. + +A device tree binary file can be provided with -d. If you edit the source +(it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to +recreate the binary file. + +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, +but you can force it to go to interactive mode instead with -i. + + +Memory Emulation +---------------- + +Memory emulation is supported, with the size set by CONFIG_SYS_SDRAM_SIZE. +The -m option can be used to read memory from a file on start-up and write +it when shutting down. This allows preserving of memory contents across +test runs. You can tell U-Boot to remove the memory file after it is read +(on start-up) with the --rm_memory option. + +To access U-Boot's emulated memory within the code, use map_sysmem(). This +function is used throughout U-Boot to ensure that emulated memory is used +rather than the U-Boot application memory. This provides memory starting +at 0 and extending to the size of the emulation. + + +Storing State +------------- + +With sandbox you can write drivers which emulate the operation of drivers on +real devices. Some of these drivers may want to record state which is +preserved across U-Boot runs. This is particularly useful for testing. For +example, the contents of a SPI flash chip should not disappear just because +U-Boot exits. + +State is stored in a device tree file in a simple format which is driver- +specific. You then use the -s option to specify the state file. Use -r to +make U-Boot read the state on start-up (otherwise it starts empty) and -w +to write it on exit (otherwise the stored state is left unchanged and any +changes U-Boot made will be lost). You can also use -n to tell U-Boot to +ignore any problems with missing state. This is useful when first running +since the state file will be empty. + +The device tree file has one node for each driver - the driver can store +whatever properties it likes in there. See 'Writing Sandbox Drivers' below +for more details on how to get drivers to read and write their state. + + +Running and Booting +------------------- + +Since there is no machine architecture, sandbox U-Boot cannot actually boot +a kernel, but it does support the bootm command. Filesystems, memory +commands, hashing, FIT images, verified boot and many other features are +supported. + +When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real +machine. Of course in this case, no kernel is run. + +It is also possible to tell U-Boot that it has jumped from a temporary +previous U-Boot binary, with the -j option. That binary is automatically +removed by the U-Boot that gets the -j option. This allows you to write +tests which emulate the action of chain-loading U-Boot, typically used in +a situation where a second 'updatable' U-Boot is stored on your board. It +is very risky to overwrite or upgrade the only U-Boot on a board, since a +power or other failure will brick the board and require return to the +manufacturer in the case of a consumer device. + + +Supported Drivers +----------------- + +U-Boot sandbox supports these emulations: + +- Block devices +- Chrome OS EC +- GPIO +- Host filesystem (access files on the host from within U-Boot) +- Keyboard (Chrome OS) +- LCD +- 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 +device are supported. + +Also sandbox uses generic board (CONFIG_SYS_GENERIC_BOARD) and supports +driver model (CONFIG_DM) and associated commands.

SPI Emulation @@ -85,7 +244,56 @@ CONFIG_SPI_IDLE_VAL The idle value on the SPI bus

-Tests ------ +Writing Sandbox Drivers +----------------------- + +Generally you should put your driver in a file containing the word 'sandbox' +and put it in the same directory as other drivers of its type. You can then +implement the same hooks as the other drivers. + +To access U-Boot's emulated memory, use map_sysmem() as mentioned above. + +If your driver needs to store configuration or state (such as SPI flash +contents or emulated chip registers), you can use the device tree as +described above. Define handlers for this with the SANDBOX_STATE_IO macro. +See arch/sandbox/include/asm/state.h for documentation. In short you provide +a node name, compatible string and functions to read and write the state. +Since writing the state can expand the device tree, you may need to use +state_setprop() which does this automatically and avoids running out of +space. See existing code for examples. + + +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 + - test/dm/test-dm.sh to run these. + 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 +coverage in U-Boot is limited, as we need to work to improve it. + +Note that many of these tests are implemented as commands which you can +run natively on your board if desired (and enabled). + +It would be useful to have a central script to run all of these.

-So far we have no tests, but when we do these will be documented here. +-- +Simon Glass sjg@chromium.org +Updated 22-Mar-14