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

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

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