[people/ms/u-boot.git] / doc / README.semihosting

/*
 * Copyright 2014 Broadcom Corporation.
 *
 * SPDX-License-Identifier:	GPL-2.0+
 */

Semihosting is ARM's way of having a real or virtual target communicate
with a host or host debugger for basic operations such as file I/O,
console I/O, etc. Please see
http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0471c/Bgbjjgij.html for more information.

For developing on armv8 virtual fastmodel platforms, semihosting is a
valuable tool since it allows access to image/configuration files before
eMMC or other NV media are available.

There are two main ARM virtual Fixed Virtual Platform (FVP) models,
Versatile Express (VE) FVP and BASE FVP (See
http://www.arm.com/products/tools/models/fast-models/foundation-model.php)
The initial vexpress64 u-boot board created here runs on the VE virtual
platform using the license-free Foundation_v8 simulator. Fortunately,
the Foundation_v8 simulator also supports the BASE_FVP model which
companies can purchase licenses for and contain much more functionality.
So we can, in u-boot, run either model by either using the VE FVP (default),
or turning on CONFIG_BASE_FVP for the more full featured model.

Rather than create a new armv8 board similar to armltd/vexpress64, add
semihosting calls to the existing one, enabled with CONFIG_SEMIHOSTING
and CONFIG_BASE_FVP both set. Also reuse the existing board config file
vexpress_aemv8a.h but differentiate the two models by the presence or
absence of CONFIG_BASE_FVP. This change is tested and works on both the
Foundation and Base fastmodel simulators.

The level of semihosting support is minimal, restricted to just what it
takes to load images to memory. If more semihosting functionality is
required, such as file seek, outputting strings, reading characters, etc,
then it can be easily added later.

We require that the board include file define these env variables:
- kernel_name		e.g. "uImage"
- kernel_addr_r		e.g. "0x80000000"
- initrd_name		e.g. "ramdisk.img"
- initrd_addr_r		e.g. "0x88000000"
- fdt_name		e.g. "devtree.dtb"
- fdt_addr_r		e.g. "0x83000000"

Optionally, "fdt_high" and "initrd_high" can be specified as per
their rules for allowing or preventing copying of these images.

For the "fdt chosen" startup macro, this code will then define:
- initrd_end (based on retrieving initrd_addr_r plus actual initrd_size)

We will then load the kernel, initrd, and fdt into the specified
locations in memory in a similar way that the ATF fastmodel code
uses semihosting calls to load other boot stages and u-boot itself.
Commit	Line	Data
261d2760 DR	1	/*
	2	* Copyright 2014 Broadcom Corporation.
	3	*
	4	* SPDX-License-Identifier: GPL-2.0+
	5	*/
	6
	7	Semihosting is ARM's way of having a real or virtual target communicate
	8	with a host or host debugger for basic operations such as file I/O,
	9	console I/O, etc. Please see
	10	http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0471c/Bgbjjgij.html for more information.
	11
	12	For developing on armv8 virtual fastmodel platforms, semihosting is a
	13	valuable tool since it allows access to image/configuration files before
	14	eMMC or other NV media are available.
	15
	16	There are two main ARM virtual Fixed Virtual Platform (FVP) models,
	17	Versatile Express (VE) FVP and BASE FVP (See
	18	http://www.arm.com/products/tools/models/fast-models/foundation-model.php)
	19	The initial vexpress64 u-boot board created here runs on the VE virtual
	20	platform using the license-free Foundation_v8 simulator. Fortunately,
	21	the Foundation_v8 simulator also supports the BASE_FVP model which
	22	companies can purchase licenses for and contain much more functionality.
	23	So we can, in u-boot, run either model by either using the VE FVP (default),
	24	or turning on CONFIG_BASE_FVP for the more full featured model.
	25
	26	Rather than create a new armv8 board similar to armltd/vexpress64, add
	27	semihosting calls to the existing one, enabled with CONFIG_SEMIHOSTING
	28	and CONFIG_BASE_FVP both set. Also reuse the existing board config file
	29	vexpress_aemv8a.h but differentiate the two models by the presence or
	30	absence of CONFIG_BASE_FVP. This change is tested and works on both the
	31	Foundation and Base fastmodel simulators.
	32
	33	The level of semihosting support is minimal, restricted to just what it
	34	takes to load images to memory. If more semihosting functionality is
	35	required, such as file seek, outputting strings, reading characters, etc,
	36	then it can be easily added later.
	37
	38	We require that the board include file define these env variables:
	39	- kernel_name e.g. "uImage"
	40	- kernel_addr_r e.g. "0x80000000"
	41	- initrd_name e.g. "ramdisk.img"
	42	- initrd_addr_r e.g. "0x88000000"
	43	- fdt_name e.g. "devtree.dtb"
	44	- fdt_addr_r e.g. "0x83000000"
	45
	46	Optionally, "fdt_high" and "initrd_high" can be specified as per
	47	their rules for allowing or preventing copying of these images.
	48
	49	For the "fdt chosen" startup macro, this code will then define:
	50	- initrd_end (based on retrieving initrd_addr_r plus actual initrd_size)
	51
	52	We will then load the kernel, initrd, and fdt into the specified
	53	locations in memory in a similar way that the ATF fastmodel code
	54	uses semihosting calls to load other boot stages and u-boot itself.