block/qcow: Improve error when opening qcow2 files as qcow

[qemu.git] / docs / generic-loader.txt

diff --git a/docs/generic-loader.txt b/docs/generic-loader.txt
index 8fcb5504143120da8100f3b4cd28ac5ea39724f2..a9603a2af7696fe7291197d859688cc9cb8df9a0 100644 (file)
--- a/docs/generic-loader.txt
+++ b/docs/generic-loader.txt
@@ -8,7 +8,7 @@ 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:
 
@@ -36,7 +36,7 @@ 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:
 
@@ -55,25 +55,26 @@ 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. This can be done
-similarly to setting memory values. The syntax is shown below:
+-------------
+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 addr in memory that the file should be loaded. This is
-                  ignored if you are using an ELF (unless force-raw is true).
-                  This is required if you aren't loading an ELF.
+    <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
-                  where the image is stored or in the case of an ELF file to
-                  the value in the header. This option should only be used
-                  for the boot image.
+                  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> - Forces the file to be treated as a raw image. This can be
-                  used to specify the load address of ELF files.
+    <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
@@ -82,3 +83,10 @@ 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.