[PATCH 0/3] generic-loader: improve docs

[PATCH 0/3] generic-loader: improve docs

[Peter Maydell]

This patchset makes some minor improvements to the generic-loader
docs. The main thing I wanted to do is the first patch, which
makes it clearer that if you don't specify cpu-num when loading
a file then the PC won't be set to the entry point.

The second patch is because I noticed a typo ("QemuOps") and then
realised that rather than fixing the typo we should instead
rephrase to not mention that implementation detail.

The third patch moves a TODO out of the user-facing docs.

thanks
-- PMM

Peter Maydell (3):
  docs/system/generic-loader: Clarify behaviour of cpu-num
  docs/system/generic-loader: Don't mention QemuOpts implementation
    detail
  docs/system/generic-loader: move TODO to source code

 docs/system/generic-loader.rst | 56 ++++++++++++++++------------------
 hw/core/generic-loader.c       | 18 +++++++++++
 2 files changed, 44 insertions(+), 30 deletions(-)

-- 
2.43.0

[PATCH 1/3] docs/system/generic-loader: Clarify behaviour of cpu-num

[Peter Maydell]

The cpu-num suboption to the generic loader has two effects when
it is used with -device loader,file=<file>:
 * it specifies which CPU to load the data through
 * it specifies which CPU gets its PC set to the file's entry point

Our documentation is not very clear about what happens if you don't
pass this suboption.  The default is that we pick the first CPU to
load the data, but we don't set the PC for any CPU, so the "If not
specified, the default is CPU 0" is confusing: it applies for loading
but not for the PC setting.

Clarify the text to make it clearer that the option has two effects
and the default behaviour is different for the two effects.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/system/generic-loader.rst | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/docs/system/generic-loader.rst b/docs/system/generic-loader.rst
index 4f9fb005f1d..3ac39cfbbe2 100644
--- a/docs/system/generic-loader.rst
+++ b/docs/system/generic-loader.rst
@@ -87,12 +87,17 @@ shown below:
 
 ``<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.
+  optional argument with two effects:
+
+  * this CPU's address space is used to load the data
+  * this CPU's PC will be set to the address where the raw file is loaded
+    or the entry point specified in the executable format header
+
+  If this option is not specified, then the data will be loaded via
+  the address space of the first CPU, and no CPU will have its PC set.
+
+  Since it sets the starting PC, this option should only be used for the boot
+  image.
 
 ``<force-raw>``
   Setting 'force-raw=on' forces the file to be treated as a raw image.
-- 
2.43.0

Re: [PATCH 1/3] docs/system/generic-loader: Clarify behaviour of cpu-num

[Alex Bennée]

Peter Maydell <peter.maydell@linaro.org> writes:

> The cpu-num suboption to the generic loader has two effects when
> it is used with -device loader,file=<file>:
>  * it specifies which CPU to load the data through
>  * it specifies which CPU gets its PC set to the file's entry point
>
> Our documentation is not very clear about what happens if you don't
> pass this suboption.  The default is that we pick the first CPU to
> load the data, but we don't set the PC for any CPU, so the "If not
> specified, the default is CPU 0" is confusing: it applies for loading
> but not for the PC setting.
>
> Clarify the text to make it clearer that the option has two effects
> and the default behaviour is different for the two effects.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

[PATCH 2/3] docs/system/generic-loader: Don't mention QemuOpts implementation detail

[Peter Maydell]

We currently say "All values are parsed using the standard QemuOpts
parsing".  This doesn't tell the user anything useful because we
don't mention QemuOpts anywhere else in the docs.  What we're really
trying to tell the user is what we mention afterwards: that the
values are decimal, and you need an 0x prefix for hex.  How we
achieve it is an implementation detail the user doesn't need to know.

Drop the explicit mention of QemuOpts; this in passing removes a typo
"QemuOps" that we made in one place. Put the informative note
more closely associated with the <addr> suboption which is the
one that users might most reasonably assume to default to hex.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/system/generic-loader.rst | 25 ++++++++++++-------------
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/docs/system/generic-loader.rst b/docs/system/generic-loader.rst
index 3ac39cfbbe2..d5416711e93 100644
--- a/docs/system/generic-loader.rst
+++ b/docs/system/generic-loader.rst
@@ -21,6 +21,10 @@ can be done by following the syntax below::
 ``<addr>``
   The address to store the data in.
 
+  Note that as usual with QEMU numeric option values, the default is to
+  treat the argument as decimal.  To specify a value in hex, prefix it
+  with '0x'.
+
 ``<data>``
   The value to be written to the address. The maximum size of the data
   is 8 bytes.
@@ -37,10 +41,6 @@ can be done by following the syntax below::
   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::
 
@@ -57,14 +57,13 @@ can be done by following the syntax below::
 ``<addr>``
   The value to use as the CPU's PC.
 
+  Note that as usual with QEMU numeric option values, the default is to
+  treat the argument as decimal.  To specify a value in hex, prefix it
+  with '0x'.
+
 ``<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
@@ -85,6 +84,10 @@ shown below:
   The memory address where the file should be loaded. This is required
   for raw images and ignored for non-raw files.
 
+  Note that as usual with QEMU numeric option values, the default is to
+  treat the argument as decimal.  To specify a value in hex, prefix it
+  with '0x'.
+
 ``<cpu-num>``
   This specifies the CPU that should be used. This is an
   optional argument with two effects:
@@ -104,10 +107,6 @@ shown below:
   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::
 
-- 
2.43.0

Re: [PATCH 2/3] docs/system/generic-loader: Don't mention QemuOpts implementation detail

[Alex Bennée]

Peter Maydell <peter.maydell@linaro.org> writes:

> We currently say "All values are parsed using the standard QemuOpts
> parsing".  This doesn't tell the user anything useful because we
> don't mention QemuOpts anywhere else in the docs.  What we're really
> trying to tell the user is what we mention afterwards: that the
> values are decimal, and you need an 0x prefix for hex.  How we
> achieve it is an implementation detail the user doesn't need to know.
>
> Drop the explicit mention of QemuOpts; this in passing removes a typo
> "QemuOps" that we made in one place. Put the informative note
> more closely associated with the <addr> suboption which is the
> one that users might most reasonably assume to default to hex.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/system/generic-loader.rst | 25 ++++++++++++-------------
>  1 file changed, 12 insertions(+), 13 deletions(-)
>
> diff --git a/docs/system/generic-loader.rst b/docs/system/generic-loader.rst
> index 3ac39cfbbe2..d5416711e93 100644
> --- a/docs/system/generic-loader.rst
> +++ b/docs/system/generic-loader.rst
> @@ -21,6 +21,10 @@ can be done by following the syntax below::
>  ``<addr>``
>    The address to store the data in.
>  
> +  Note that as usual with QEMU numeric option values, the default is to
> +  treat the argument as decimal.  To specify a value in hex, prefix it
> +  with '0x'.
> +
>  ``<data>``
>    The value to be written to the address. The maximum size of the data
>    is 8 bytes.
> @@ -37,10 +41,6 @@ can be done by following the syntax below::
>    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::
>  
> @@ -57,14 +57,13 @@ can be done by following the syntax below::
>  ``<addr>``
>    The value to use as the CPU's PC.
>  
> +  Note that as usual with QEMU numeric option values, the default is to
> +  treat the argument as decimal.  To specify a value in hex, prefix it
> +  with '0x'.
> +
>  ``<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
> @@ -85,6 +84,10 @@ shown below:
>    The memory address where the file should be loaded. This is required
>    for raw images and ignored for non-raw files.
>  
> +  Note that as usual with QEMU numeric option values, the default is to
> +  treat the argument as decimal.  To specify a value in hex, prefix it
> +  with '0x'.
> +
>  ``<cpu-num>``
>    This specifies the CPU that should be used. This is an
>    optional argument with two effects:
> @@ -104,10 +107,6 @@ shown below:
>    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::

This isn't wrong but I wonder if there is a way to avoid so much
repetition? Is there a way to have common footnotes we could apply
anywhere we are discussing QEMU's numeric parsing?

Anyway:

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [PATCH 2/3] docs/system/generic-loader: Don't mention QemuOpts implementation detail

[Peter Maydell]

On Tue, 25 Nov 2025 at 14:56, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> Peter Maydell <peter.maydell@linaro.org> writes:
> > @@ -85,6 +84,10 @@ shown below:
> >    The memory address where the file should be loaded. This is required
> >    for raw images and ignored for non-raw files.
> >
> > +  Note that as usual with QEMU numeric option values, the default is to
> > +  treat the argument as decimal.  To specify a value in hex, prefix it
> > +  with '0x'.
> > +
> >  ``<cpu-num>``
> >    This specifies the CPU that should be used. This is an
> >    optional argument with two effects:
> > @@ -104,10 +107,6 @@ shown below:
> >    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::
>
> This isn't wrong but I wonder if there is a way to avoid so much
> repetition? Is there a way to have common footnotes we could apply
> anywhere we are discussing QEMU's numeric parsing?

Mmm, I wasn't thrilled by the repetition, but at least this
way the info is in the user's face where they'll see it
when they're looking at how to set the address, rather than
tucked away at the bottom or behind a footnote link where
they might not read it.

In a lot of cases it's not something we need to mention at
all -- nobody expects the argument to "-smp" to be hex,
for instance :-)

-- PMM

[PATCH 3/3] docs/system/generic-loader: move TODO to source code

[Peter Maydell]

Currently we have a "Restrictions and ToDos" section at the bottom of
the document which notes that there's no way to specify a CPU to load
a file through that doesn't also set that CPU's PC.  This is written
as a developer-facing note.  Move this to a TODO comment in the
source code, and provide a shorter user-facing statement of the
current restriction under the specific sub-option that it applies to.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/system/generic-loader.rst | 14 +++-----------
 hw/core/generic-loader.c       | 18 ++++++++++++++++++
 2 files changed, 21 insertions(+), 11 deletions(-)

diff --git a/docs/system/generic-loader.rst b/docs/system/generic-loader.rst
index d5416711e93..0df9b66976a 100644
--- a/docs/system/generic-loader.rst
+++ b/docs/system/generic-loader.rst
@@ -99,6 +99,9 @@ shown below:
   If this option is not specified, then the data will be loaded via
   the address space of the first CPU, and no CPU will have its PC set.
 
+  Note that there is currently no way to specify the address space to
+  load the data without also causing that CPU's PC to be set.
+
   Since it sets the starting PC, this option should only be used for the boot
   image.
 
@@ -111,14 +114,3 @@ shown below:
 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/hw/core/generic-loader.c b/hw/core/generic-loader.c
index 433efb73872..508c090872a 100644
--- a/hw/core/generic-loader.c
+++ b/hw/core/generic-loader.c
@@ -30,6 +30,24 @@
  * separate backend.
  */
 
+/*
+ * TODO: currently the "load a file" functionality provides no way
+ * for the user to specify which CPU address space to load the data
+ * into without also causing that CPU's PC to be set to the start
+ * address of the file.
+ *
+ * We could fix this by having a new suboption set-pc (default: true)
+ * so the user can say
+ *  -device loader,file=<file>,cpu-num=<cpu-num>
+ * for the current "use this address space and set the PC" behaviour
+ * or
+ *  -device loader,file=<file>,cpu-num=<cpu-num>,set-pc=off
+ * to just pick the address space and not set the PC.
+ *
+ * Using set-pc without file= should be handled as an error; otherwise
+ * it can feed through to what we set s->set_pc to.
+ */
+
 #include "qemu/osdep.h"
 #include "system/dma.h"
 #include "system/reset.h"
-- 
2.43.0

Re: [PATCH 3/3] docs/system/generic-loader: move TODO to source code

[Alex Bennée]

Peter Maydell <peter.maydell@linaro.org> writes:

> Currently we have a "Restrictions and ToDos" section at the bottom of
> the document which notes that there's no way to specify a CPU to load
> a file through that doesn't also set that CPU's PC.  This is written
> as a developer-facing note.  Move this to a TODO comment in the
> source code, and provide a shorter user-facing statement of the
> current restriction under the specific sub-option that it applies to.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro