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 4f9fb005f1d88b999c3105b3fb9cc5dc952302f6..3ac39cfbbe251bc11ba51f13aae893c25157a87c 100644 (file)
--- 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.