sandbox: Update and expand the README
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>
This commit is contained in:
Simon Glass
parent
ad0e463954
commit
75b3c3aa84
11
README
11
README
@ -264,6 +264,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:
|
||||
----------------------
|
||||
|
||||
|
||||
@ -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
|
||||
-----------------------
|
||||
|
||||
So far we have no tests, but when we do these will be documented here.
|
||||
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.
|
||||
|
||||
--
|
||||
Simon Glass <sjg@chromium.org>
|
||||
Updated 22-Mar-14
|
||||
|
||||
Loading…
Reference in New Issue
Block a user