From: "Alex Bennée" <alex.bennee@linaro.org>
To: qemu-devel@nongnu.org
Cc: julien@xen.org, masami.hiramatsu@linaro.org,
andre.przywara@arm.com, stefano.stabellini@linaro.org,
takahiro.akashi@linaro.org, stefano.stabellini@xilinx.com,
"Alex Bennée" <alex.bennee@linaro.org>,
stratos-dev@op-lists.linaro.org
Subject: [RFC PATCH 05/15] docs: move generic-loader documentation into the main manual
Date: Thu, 5 Nov 2020 17:51:43 +0000 [thread overview]
Message-ID: <20201105175153.30489-6-alex.bennee@linaro.org> (raw)
In-Reply-To: <20201105175153.30489-1-alex.bennee@linaro.org>
We might as well surface this useful information in the manual so
users can find it easily. It is a fairly simple conversion to rst with
the only textual fixes being QemuOps to QemuOpts.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
docs/generic-loader.txt | 92 --------------------------
docs/system/generic-loader.rst | 117 +++++++++++++++++++++++++++++++++
docs/system/index.rst | 1 +
3 files changed, 118 insertions(+), 92 deletions(-)
delete mode 100644 docs/generic-loader.txt
create mode 100644 docs/system/generic-loader.rst
diff --git a/docs/generic-loader.txt b/docs/generic-loader.txt
deleted file mode 100644
index a9603a2af7..0000000000
--- a/docs/generic-loader.txt
+++ /dev/null
@@ -1,92 +0,0 @@
-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.
diff --git a/docs/system/generic-loader.rst b/docs/system/generic-loader.rst
new file mode 100644
index 0000000000..59f28d1230
--- /dev/null
+++ b/docs/system/generic-loader.rst
@@ -0,0 +1,117 @@
+..
+ 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.
+
+Generic Loader
+--------------
+
+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 QemuOpts 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 QemuOpts 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.
+
+
diff --git a/docs/system/index.rst b/docs/system/index.rst
index c0f685b818..3cff0ca98f 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -24,6 +24,7 @@ Contents:
usb
ivshmem
linuxboot
+ generic-loader
vnc-security
tls
gdb
--
2.20.1
next prev parent reply other threads:[~2020-11-05 18:01 UTC|newest]
Thread overview: 34+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-11-05 17:51 [RFC PATCH 00/15] Xen guest-loader and arm64 build fixes/enhancements Alex Bennée
2020-11-05 17:51 ` [RFC PATCH 01/15] hw/board: promote fdt from ARM VirtMachineState to MachineState Alex Bennée
2020-11-05 19:27 ` Philippe Mathieu-Daudé
2020-11-05 20:37 ` Alex Bennée
2020-11-05 17:51 ` [RFC PATCH 02/15] hw/riscv: migrate fdt field to generic MachineState Alex Bennée
2020-11-05 19:24 ` Philippe Mathieu-Daudé
2020-11-06 3:15 ` Bin Meng
2020-11-06 10:21 ` Alex Bennée
2020-11-06 11:32 ` Bin Meng
2020-11-05 17:51 ` [RFC PATCH 03/15] device_tree: add qemu_fdt_setprop_string_array helper Alex Bennée
2020-11-05 17:51 ` [RFC PATCH 04/15] hw/core: implement a guest-loader to support static hypervisor guests Alex Bennée
2020-11-05 17:51 ` Alex Bennée [this message]
2020-11-05 17:51 ` [RFC PATCH 06/15] docs: add some documentation for the guest-loader Alex Bennée
2020-11-19 20:06 ` Alistair Francis
2020-11-19 20:58 ` Peter Maydell
2020-11-05 17:51 ` [RFC PATCH 07/15] accel/meson: you only need accelerator stubs for softmmu builds Alex Bennée
2020-11-05 18:18 ` Philippe Mathieu-Daudé
2020-11-05 17:51 ` [RFC PATCH 08/15] meson.build: fix building of Xen support for aarch64 Alex Bennée
2020-11-05 18:20 ` Philippe Mathieu-Daudé
2020-11-05 17:51 ` [RFC PATCH 09/15] meson.build: introduce CONFIG_XEN_HVM flag Alex Bennée
2020-11-05 18:21 ` Philippe Mathieu-Daudé
2020-11-05 18:47 ` Philippe Mathieu-Daudé
2020-11-05 17:51 ` [RFC PATCH 10/15] meson.build: clean-up summary reporting of XEN and it's features Alex Bennée
2020-11-05 19:11 ` Philippe Mathieu-Daudé
2020-11-05 17:51 ` [RFC PATCH 11/15] include/hw/xen.h: drop superfluous struct Alex Bennée
2020-11-05 19:15 ` Philippe Mathieu-Daudé
2020-11-05 17:51 ` [RFC PATCH 12/15] stubs/xen-hw-stub: drop xenstore_store_pv_console_info stub Alex Bennée
2020-11-05 19:20 ` Philippe Mathieu-Daudé
2020-11-06 10:27 ` Alex Bennée
2020-11-05 17:51 ` [RFC PATCH 13/15] accel/stubs: drop unused cpu.h include Alex Bennée
2020-11-05 19:20 ` Philippe Mathieu-Daudé
2020-11-05 17:51 ` [RFC PATCH 14/15] xen: only build HVM support under CONFIG_XEN_HVM Alex Bennée
2020-11-05 17:51 ` [RFC PATCH 15/15] meson.build: build a Xen aware qemu-aarch64-system Alex Bennée
2020-11-05 18:15 ` [RFC PATCH 00/15] Xen guest-loader and arm64 build fixes/enhancements no-reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20201105175153.30489-6-alex.bennee@linaro.org \
--to=alex.bennee@linaro.org \
--cc=andre.przywara@arm.com \
--cc=julien@xen.org \
--cc=masami.hiramatsu@linaro.org \
--cc=qemu-devel@nongnu.org \
--cc=stefano.stabellini@linaro.org \
--cc=stefano.stabellini@xilinx.com \
--cc=stratos-dev@op-lists.linaro.org \
--cc=takahiro.akashi@linaro.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).