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>

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>
Simon Glass
1 parent ad0e463954
Showing 2 changed files with 226 additions and 7 deletions Side-by-side Diff
README
board/sandbox/sandbox/README.sandbox
@@ -264,6 +264,17 @@
 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:
 ----------------------
  
 /*
- * Copyright (c) 2011 The Chromium OS Authors.
+ * Copyright (c) 2014 The Chromium OS Authors.
  *
  * SPDX-License-Identifier:	GPL-2.0+
  */
  
  
@@ -26,11 +26,170 @@
  
 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,8 +244,57 @@
 	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
...	...	@@ -264,6 +264,17 @@
264	264	directory according to the instructions in cogent/README.
265	265
266	266
	267	+Sandbox Environment:
	268	+--------------------
	269	+
	270	+U-Boot can be built natively to run on a Linux host using the 'sandbox'
	271	+board. This allows feature development which is not board- or architecture-
	272	+specific to be undertaken on a native platform. The sandbox is also used to
	273	+run some of U-Boot's tests.
	274	+
	275	+See board/sandbox/sandbox/README.sandbox for more details.
	276	+
	277	+
267	278	Configuration Options:
268	279	----------------------
269	280
1	1	/*
2		- * Copyright (c) 2011 The Chromium OS Authors.
	2	+ * Copyright (c) 2014 The Chromium OS Authors.
3	3	*
4	4	* SPDX-License-Identifier: GPL-2.0+
5	5	*/
6	6
7	7
...	...	@@ -26,11 +26,170 @@
26	26
27	27	Note that standalone/API support is not available at present.
28	28
29		-The serial driver is a very simple implementation which reads and writes to
30		-the console. It does not set the terminal into raw mode, so cursor keys and
31		-history will not work yet.
32	29
	30	+Basic Operation
	31	+---------------
33	32
	33	+To run sandbox U-Boot use something like:
	34	+
	35	+ make sandbox_config all
	36	+ ./u-boot
	37	+
	38	+Note:
	39	+ If you get errors about 'sdl-config: Command not found' you may need to
	40	+ install libsdl1.2-dev or similar to get SDL support. Alternatively you can
	41	+ build sandbox without SDL (i.e. no display/keyboard support) by removing
	42	+ the CONFIG_SANDBOX_SDL line in include/configs/sandbox.h or using:
	43	+
	44	+ make sandbox_config all NO_SDL=1
	45	+ ./u-boot
	46	+
	47	+
	48	+U-Boot will start on your computer, showing a sandbox emulation of the serial
	49	+console:
	50	+
	51	+
	52	+U-Boot 2014.04 (Mar 20 2014 - 19:06:00)
	53	+
	54	+DRAM: 128 MiB
	55	+Using default environment
	56	+
	57	+In: serial
	58	+Out: lcd
	59	+Err: lcd
	60	+=>
	61	+
	62	+You can issue commands as your would normally. If the command you want is
	63	+not supported you can add it to include/configs/sandbox.h.
	64	+
	65	+To exit, type 'reset' or press Ctrl-C.
	66	+
	67	+
	68	+Console / LCD support
	69	+---------------------
	70	+
	71	+Assuming that CONFIG_SANDBOX_SDL is defined when building, you can run the
	72	+sandbox with LCD and keyboard emulation, using something like:
	73	+
	74	+ ./u-boot -d u-boot.dtb -l
	75	+
	76	+This will start U-Boot with a window showing the contents of the LCD. If
	77	+that window has the focus then you will be able to type commands as you
	78	+would on the console. You can adjust the display settings in the device
	79	+tree file - see arch/sandbox/dts/sandbox.dts.
	80	+
	81	+
	82	+Command-line Options
	83	+--------------------
	84	+
	85	+Various options are available, mostly for test purposes. Use -h to see
	86	+available options. Some of these are described below.
	87	+
	88	+The terminal is normally in what is called 'raw-with-sigs' mode. This means
	89	+that you can use arrow keys for command editing and history, but if you
	90	+press Ctrl-C, U-Boot will exit instead of handling this as a keypress.
	91	+
	92	+Other options are 'raw' (so Ctrl-C is handled within U-Boot) and 'cooked'
	93	+(where the terminal is in cooked mode and cursor keys will not work, Ctrl-C
	94	+will exit).
	95	+
	96	+As mentioned above, -l causes the LCD emulation window to be shown.
	97	+
	98	+A device tree binary file can be provided with -d. If you edit the source
	99	+(it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to
	100	+recreate the binary file.
	101	+
	102	+To execute commands directly, use the -c option. You can specify a single
	103	+command, or multiple commands separated by a semicolon, as is normal in
	104	+U-Boot. Be careful with quoting as the shall will normally process and
	105	+swallow quotes. When -c is used, U-Boot exists after the command is complete,
	106	+but you can force it to go to interactive mode instead with -i.
	107	+
	108	+
	109	+Memory Emulation
	110	+----------------
	111	+
	112	+Memory emulation is supported, with the size set by CONFIG_SYS_SDRAM_SIZE.
	113	+The -m option can be used to read memory from a file on start-up and write
	114	+it when shutting down. This allows preserving of memory contents across
	115	+test runs. You can tell U-Boot to remove the memory file after it is read
	116	+(on start-up) with the --rm_memory option.
	117	+
	118	+To access U-Boot's emulated memory within the code, use map_sysmem(). This
	119	+function is used throughout U-Boot to ensure that emulated memory is used
	120	+rather than the U-Boot application memory. This provides memory starting
	121	+at 0 and extending to the size of the emulation.
	122	+
	123	+
	124	+Storing State
	125	+-------------
	126	+
	127	+With sandbox you can write drivers which emulate the operation of drivers on
	128	+real devices. Some of these drivers may want to record state which is
	129	+preserved across U-Boot runs. This is particularly useful for testing. For
	130	+example, the contents of a SPI flash chip should not disappear just because
	131	+U-Boot exits.
	132	+
	133	+State is stored in a device tree file in a simple format which is driver-
	134	+specific. You then use the -s option to specify the state file. Use -r to
	135	+make U-Boot read the state on start-up (otherwise it starts empty) and -w
	136	+to write it on exit (otherwise the stored state is left unchanged and any
	137	+changes U-Boot made will be lost). You can also use -n to tell U-Boot to
	138	+ignore any problems with missing state. This is useful when first running
	139	+since the state file will be empty.
	140	+
	141	+The device tree file has one node for each driver - the driver can store
	142	+whatever properties it likes in there. See 'Writing Sandbox Drivers' below
	143	+for more details on how to get drivers to read and write their state.
	144	+
	145	+
	146	+Running and Booting
	147	+-------------------
	148	+
	149	+Since there is no machine architecture, sandbox U-Boot cannot actually boot
	150	+a kernel, but it does support the bootm command. Filesystems, memory
	151	+commands, hashing, FIT images, verified boot and many other features are
	152	+supported.
	153	+
	154	+When 'bootm' runs a kernel, sandbox will exit, as U-Boot does on a real
	155	+machine. Of course in this case, no kernel is run.
	156	+
	157	+It is also possible to tell U-Boot that it has jumped from a temporary
	158	+previous U-Boot binary, with the -j option. That binary is automatically
	159	+removed by the U-Boot that gets the -j option. This allows you to write
	160	+tests which emulate the action of chain-loading U-Boot, typically used in
	161	+a situation where a second 'updatable' U-Boot is stored on your board. It
	162	+is very risky to overwrite or upgrade the only U-Boot on a board, since a
	163	+power or other failure will brick the board and require return to the
	164	+manufacturer in the case of a consumer device.
	165	+
	166	+
	167	+Supported Drivers
	168	+-----------------
	169	+
	170	+U-Boot sandbox supports these emulations:
	171	+
	172	+- Block devices
	173	+- Chrome OS EC
	174	+- GPIO
	175	+- Host filesystem (access files on the host from within U-Boot)
	176	+- Keyboard (Chrome OS)
	177	+- LCD
	178	+- Serial (for console only)
	179	+- Sound (incomplete - see sandbox_sdl_sound_init() for details)
	180	+- SPI
	181	+- SPI flash
	182	+- TPM (Trusted Platform Module)
	183	+
	184	+Notable omissions are networking and I2C.
	185	+
	186	+A wide range of commands is implemented. Filesystems which use a block
	187	+device are supported.
	188	+
	189	+Also sandbox uses generic board (CONFIG_SYS_GENERIC_BOARD) and supports
	190	+driver model (CONFIG_DM) and associated commands.
	191	+
	192	+
34	193	SPI Emulation
35	194	-------------
36	195
37	196
...	...	@@ -85,8 +244,57 @@
85	244	The idle value on the SPI bus
86	245
87	246
88		-Tests
89		------
	247	+Writing Sandbox Drivers
	248	+-----------------------
90	249
91		-So far we have no tests, but when we do these will be documented here.
	250	+Generally you should put your driver in a file containing the word 'sandbox'
	251	+and put it in the same directory as other drivers of its type. You can then
	252	+implement the same hooks as the other drivers.
	253	+
	254	+To access U-Boot's emulated memory, use map_sysmem() as mentioned above.
	255	+
	256	+If your driver needs to store configuration or state (such as SPI flash
	257	+contents or emulated chip registers), you can use the device tree as
	258	+described above. Define handlers for this with the SANDBOX_STATE_IO macro.
	259	+See arch/sandbox/include/asm/state.h for documentation. In short you provide
	260	+a node name, compatible string and functions to read and write the state.
	261	+Since writing the state can expand the device tree, you may need to use
	262	+state_setprop() which does this automatically and avoids running out of
	263	+space. See existing code for examples.
	264	+
	265	+
	266	+Testing
	267	+-------
	268	+
	269	+U-Boot sandbox can be used to run various tests, mostly in the test/
	270	+directory. These include:
	271	+
	272	+ command_ut
	273	+ - Unit tests for command parsing and handling
	274	+ compression
	275	+ - Unit tests for U-Boot's compression algorithms, useful for
	276	+ security checking. It supports gzip, bzip2, lzma and lzo.
	277	+ driver model
	278	+ - test/dm/test-dm.sh to run these.
	279	+ image
	280	+ - Unit tests for images:
	281	+ test/image/test-imagetools.sh - multi-file images
	282	+ test/image/test-fit.py - FIT images
	283	+ tracing
	284	+ - test/trace/test-trace.sh tests the tracing system (see README.trace)
	285	+ verified boot
	286	+ - See test/vboot/vboot_test.sh for this
	287	+
	288	+If you change or enhance any of the above subsystems, you shold write or
	289	+expand a test and include it with your patch series submission. Test
	290	+coverage in U-Boot is limited, as we need to work to improve it.
	291	+
	292	+Note that many of these tests are implemented as commands which you can
	293	+run natively on your board if desired (and enabled).
	294	+
	295	+It would be useful to have a central script to run all of these.
	296	+
	297	+--
	298	+Simon Glass <sjg@chromium.org>
	299	+Updated 22-Mar-14