Commit 1e812f8eb1 for qemu.org

commit 1e812f8eb17f528d50843d94efce24a158ff1b4e
Author: Peter Maydell <peter.maydell@linaro.org>
Date:   Thu Jan 15 15:26:30 2026 +0000

    docs/system/generic-loader: Clarify behaviour of cpu-num

    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>

diff --git a/docs/system/generic-loader.rst b/docs/system/generic-loader.rst
index 4f9fb005f1..3ac39cfbbe 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.