[mirror_qemu.git] / docs / generic-loader.txt

Copyright (c) 2016 Xilinx Inc.

This work is licensed under the terms of the GNU GPL, version 2 or later.  See
the COPYING file in the top-level directory.


The 'loader' device allows the user to load multiple images or values into
QEMU at startup.

Loading Data into Memory Values
-------------------------------
The loader device allows memory values to be set from the command line. This
can be done by following the syntax below:

     -device loader,addr=<addr>,data=<data>,data-len=<data-len>
                   [,data-be=<data-be>][,cpu-num=<cpu-num>]

    <addr>      - The address to store the data in.
    <data>      - The value to be written to the address. The maximum size of
                  the data is 8 bytes.
    <data-len>  - The length of the data in bytes. This argument must be
                  included if the data argument is.
    <data-be>   - Set to true if the data to be stored on the guest should be
                  written as big endian data. The default is to write little
                  endian data.
    <cpu-num>   - The number of the CPU's address space where the data should
                  be loaded. If not specified the address space of the first
                  CPU is used.

All values are parsed using the standard QemuOps parsing. This allows the user
to specify any values in any format supported. By default the values
will be parsed as decimal. To use hex values the user should prefix the number
with a '0x'.

An example of loading value 0x8000000e to address 0xfd1a0104 is:
    -device loader,addr=0xfd1a0104,data=0x8000000e,data-len=4

Setting a CPU's Program Counter
-------------------------------
The loader device allows the CPU's PC to be set from the command line. This
can be done by following the syntax below:

     -device loader,addr=<addr>,cpu-num=<cpu-num>

    <addr>      - The value to use as the CPU's PC.
    <cpu-num>   - The number of the CPU whose PC should be set to the
                  specified value.

All values are parsed using the standard QemuOps parsing. This allows the user
to specify any values in any format supported. By default the values
will be parsed as decimal. To use hex values the user should prefix the number
with a '0x'.

An example of setting CPU 0's PC to 0x8000 is:
    -device loader,addr=0x8000,cpu-num=0

Loading Files
-------------
The loader device also allows files to be loaded into memory. It can load ELF,
U-Boot, and Intel HEX executable formats as well as raw images.  The syntax is
shown below:

    -device loader,file=<file>[,addr=<addr>][,cpu-num=<cpu-num>][,force-raw=<raw>]

    <file>      - A file to be loaded into memory
    <addr>      - The memory address where the file should be loaded. This is
                  required for raw images and ignored for non-raw files.
    <cpu-num>   - This specifies the CPU that should be used. This is an
                  optional argument and will cause the CPU's PC to be set to
                  the memory address where the raw file is loaded or the entry
                  point specified in the executable format header. This option
                  should only be used for the boot image.
                  This will also cause the image to be written to the specified
                  CPU's address space. If not specified, the default is CPU 0.
    <force-raw> - Setting force-raw=on forces the file to be treated as a raw
                  image.  This can be used to load supported executable formats
                  as if they were raw.

All values are parsed using the standard QemuOps parsing. This allows the user
to specify any values in any format supported. By default the values
will be parsed as decimal. To use hex values the user should prefix the number
with a '0x'.

An example of loading an ELF file which CPU0 will boot is shown below:
    -device loader,file=./images/boot.elf,cpu-num=0

Restrictions and ToDos
----------------------
 - At the moment it is just assumed that if you specify a cpu-num then you
   want to set the PC as well. This might not always be the case. In future
   the internal state 'set_pc' (which exists in the generic loader now) should
   be exposed to the user so that they can choose if the PC is set or not.
Commit	Line	Data
03bf1953 AF	1	Copyright (c) 2016 Xilinx Inc.
	2
	3	This work is licensed under the terms of the GNU GPL, version 2 or later. See
	4	the COPYING file in the top-level directory.
	5
	6
	7	The 'loader' device allows the user to load multiple images or values into
	8	QEMU at startup.
	9
	10	Loading Data into Memory Values
bcf48274	11	-------------------------------
03bf1953 AF	12	The loader device allows memory values to be set from the command line. This
	13	can be done by following the syntax below:
	14
	15	-device loader,addr=<addr>,data=<data>,data-len=<data-len>
	16	[,data-be=<data-be>][,cpu-num=<cpu-num>]
	17
	18	<addr> - The address to store the data in.
	19	<data> - The value to be written to the address. The maximum size of
	20	the data is 8 bytes.
	21	<data-len> - The length of the data in bytes. This argument must be
	22	included if the data argument is.
	23	<data-be> - Set to true if the data to be stored on the guest should be
	24	written as big endian data. The default is to write little
	25	endian data.
	26	<cpu-num> - The number of the CPU's address space where the data should
	27	be loaded. If not specified the address space of the first
	28	CPU is used.
	29
	30	All values are parsed using the standard QemuOps parsing. This allows the user
	31	to specify any values in any format supported. By default the values
	32	will be parsed as decimal. To use hex values the user should prefix the number
	33	with a '0x'.
	34
	35	An example of loading value 0x8000000e to address 0xfd1a0104 is:
	36	-device loader,addr=0xfd1a0104,data=0x8000000e,data-len=4
	37
	38	Setting a CPU's Program Counter
bcf48274	39	-------------------------------
03bf1953 AF	40	The loader device allows the CPU's PC to be set from the command line. This
	41	can be done by following the syntax below:
	42
	43	-device loader,addr=<addr>,cpu-num=<cpu-num>
	44
	45	<addr> - The value to use as the CPU's PC.
	46	<cpu-num> - The number of the CPU whose PC should be set to the
	47	specified value.
	48
	49	All values are parsed using the standard QemuOps parsing. This allows the user
	50	to specify any values in any format supported. By default the values
	51	will be parsed as decimal. To use hex values the user should prefix the number
	52	with a '0x'.
	53
	54	An example of setting CPU 0's PC to 0x8000 is:
	55	-device loader,addr=0x8000,cpu-num=0
	56
	57	Loading Files
bcf48274	58	-------------
67c791f6 SH	59	The loader device also allows files to be loaded into memory. It can load ELF,
	60	U-Boot, and Intel HEX executable formats as well as raw images. The syntax is
	61	shown below:
03bf1953 AF	62
	63	-device loader,file=<file>[,addr=<addr>][,cpu-num=<cpu-num>][,force-raw=<raw>]
	64
	65	<file> - A file to be loaded into memory
67c791f6 SH	66	<addr> - The memory address where the file should be loaded. This is
67c791f6 SH	67	required for raw images and ignored for non-raw files.
03bf1953 AF	68	<cpu-num> - This specifies the CPU that should be used. This is an
03bf1953 AF	69	optional argument and will cause the CPU's PC to be set to
67c791f6 SH	70	the memory address where the raw file is loaded or the entry
	71	point specified in the executable format header. This option
	72	should only be used for the boot image.
03bf1953 AF	73	This will also cause the image to be written to the specified
03bf1953 AF	74	CPU's address space. If not specified, the default is CPU 0.
bcf48274	75	<force-raw> - Setting force-raw=on forces the file to be treated as a raw
67c791f6 SH	76	image. This can be used to load supported executable formats
67c791f6 SH	77	as if they were raw.
03bf1953 AF	78
	79	All values are parsed using the standard QemuOps parsing. This allows the user
	80	to specify any values in any format supported. By default the values
	81	will be parsed as decimal. To use hex values the user should prefix the number
	82	with a '0x'.
	83
	84	An example of loading an ELF file which CPU0 will boot is shown below:
	85	-device loader,file=./images/boot.elf,cpu-num=0
bcf48274 AF	86
	87	Restrictions and ToDos
	88	----------------------
	89	- At the moment it is just assumed that if you specify a cpu-num then you
	90	want to set the PC as well. This might not always be the case. In future
	91	the internal state 'set_pc' (which exists in the generic loader now) should
	92	be exposed to the user so that they can choose if the PC is set or not.