Add a generic loader

If the caller didn't specify an architecture for the ELF machine the load_elf() function will auto detect it based on the ELF file.

Signed-off-by Alistair Francis <[email protected]>

---
V9:
- Update documentation
V8:
- Move into load_elf64/load_elf32
V7:
- Fix typo

 include/hw/elf_ops.h | 5 +++++
 include/hw/loader.h  | 3 +++
 2 files changed, 8 insertions(+)

include/hw/elf_ops.h +5 -0

index f510e7e..db70c11 100644
@@ -280,6 +280,11 @@ static int glue(load_elf, SZ)(const char *name, int fd,
         glue(bswap_ehdr, SZ)(&ehdr);
     }
 
+    if (elf_machine < 1) {
+        /* The caller didn't specify an ARCH, we can figure it out */
+        elf_machine = ehdr.e_machine;
+    }
+
     switch (elf_machine) {
         case EM_PPC64:
             if (ehdr.e_machine != EM_PPC64) {

include/hw/loader.h +0 -0

index 4879b63..fd540fc 100644

Quoted 40 lines · Alistair Francis

If the caller didn't specify an architecture for the ELF machine the load_elf() function will auto detect it based on the ELF file.

Signed-off-by Alistair Francis <[email protected]>

---
V9:
- Update documentation
V8:
- Move into load_elf64/load_elf32
V7:
- Fix typo

 include/hw/elf_ops.h | 5 +++++
 include/hw/loader.h  | 3 +++
 2 files changed, 8 insertions(+)

include/hw/elf_ops.h +5 -0

index f510e7e..db70c11 100644
@@ -280,6 +280,11 @@ static int glue(load_elf, SZ)(const char *name, int fd,
         glue(bswap_ehdr, SZ)(&ehdr);
     }
 
+    if (elf_machine < 1) {
+        /* The caller didn't specify an ARCH, we can figure it out */
+        elf_machine = ehdr.e_machine;
+    }
+
     switch (elf_machine) {
         case EM_PPC64:
             if (ehdr.e_machine != EM_PPC64) {

include/hw/loader.h +0 -0

index 4879b63..fd540fc 100644
@@ -68,6 +68,9 @@ const char *load_elf_strerror(int error);
  * load will fail if the target ELF does not match. Some architectures
  * have some architecture-specific behaviours that come into effect when
  * their particular values for @elf_machine are set.

include/hw/loader.h const char *load_elf_strerror(int error); · line 74

Quoted 4 lines

include/hw/loader.h +3 -0

+ * If no @elf_machine is provided the machine will default to the value
+ * in the ELFs header and no checks will be carried out against the
+ * machine type.
  */

The argument is mandatory, you can't not provide it. Should we make this "if @elf_machine is EM_NONE then the machine type will be read from the ELF header" ? (EM_NONE is 0).

thanks
-- PMM

Prevously the specified MemoryRegion was ignored during the rom register reset. This patch uses the rom MemoryRegion is avaliable.

Signed-off-by Alistair Francis <[email protected]>

---

When loading ROMs allow the caller to specify an AddressSpace to use for the load.

Signed-off-by Alistair Francis <[email protected]>

---
V9:
- Fixup the ROM ordering
- Don't allow address space and memory region to be specified
V8:
- Introduce an RFC version of AddressSpace loading support

 hw/core/loader.c     | 39 ++++++++++++++++++++++++++++-----------
 include/hw/elf_ops.h |  2 +-
 include/hw/loader.h  | 10 ++++++----
 3 files changed, 35 insertions(+), 16 deletions(-)

hw/core/loader.c +2 -4

index 6b61f29..a024133 100644
@@ -777,6 +777,7 @@ struct Rom {
 
     uint8_t *data;
     MemoryRegion *mr;
+    AddressSpace *as;
     int isrom;
     char *fw_dir;
     char *fw_file;

@@ -796,12 +797,15 @@ static void rom_insert(Rom *rom)
         hw_error ("ROM images must be loaded at startup\n");
     }
 
-    /* list is ordered by load address */
+    /* List is ordered by load address in the same address space */
     QTAILQ_FOREACH(item, &roms, next) {
-        if (rom->addr >= item->addr)
-            continue;
-        QTAILQ_INSERT_BEFORE(item, rom, next);

hw/core/loader.c +1 -1

 }

@@ -833,16 +837,25 @@ static void *rom_set_mr(Rom *rom, Object *owner, const char *name)
 
 int rom_add_file(const char *file, const char *fw_dir,
                  hwaddr addr, int32_t bootindex,
-                 bool option_rom, MemoryRegion *mr)
+                 bool option_rom, MemoryRegion *mr,

hw/core/loader.c +9 -3

+        /* We haven't allocated anything so we don't need any cleanup */
+        return -1;
+    }
+
     rom = g_malloc0(sizeof(*rom));
     rom->name = g_strdup(file);
     rom->path = qemu_find_file(QEMU_FILE_TYPE_BIOS, rom->name);
+    rom->as = as;
     if (rom->path == NULL) {
         rom->path = g_strdup(file);
     }

@@ -969,7 +982,7 @@ MemoryRegion *rom_add_blob(const char *name, const void *blob, size_t len,
  * memory ownership of "data", so we don't have to allocate and copy the buffer.
  */
 int rom_add_elf_program(const char *name, void *data, size_t datasize,
-                        size_t romsize, hwaddr addr)
+                        size_t romsize, hwaddr addr, AddressSpace *as)
 {
     Rom *rom;
 

@@ -979,18 +992,19 @@ int rom_add_elf_program(const char *name, void *data, size_t datasize,
     rom->datasize = datasize;
     rom->romsize  = romsize;
     rom->data     = data;
+    rom->as       = as;
     rom_insert(rom);
     return 0;
 }
 
 int rom_add_vga(const char *file)
 {
-    return rom_add_file(file, "vgaroms", 0, -1, true, NULL);
+    return rom_add_file(file, "vgaroms", 0, -1, true, NULL, NULL);
 }
 
 int rom_add_option(const char *file, int32_t bootindex)
 {
-    return rom_add_file(file, "genroms", 0, bootindex, true, NULL);
+    return rom_add_file(file, "genroms", 0, bootindex, true, NULL, NULL);
 }
 
 static void rom_reset(void *unused)

Quoted 47 lines · Alistair Francis

When loading ROMs allow the caller to specify an AddressSpace to use for the load.

Signed-off-by Alistair Francis <[email protected]>

---
V9:
- Fixup the ROM ordering
- Don't allow address space and memory region to be specified
V8:
- Introduce an RFC version of AddressSpace loading support

 hw/core/loader.c     | 39 ++++++++++++++++++++++++++++-----------
 include/hw/elf_ops.h |  2 +-
 include/hw/loader.h  | 10 ++++++----
 3 files changed, 35 insertions(+), 16 deletions(-)

hw/core/loader.c +9 -5

index 6b61f29..a024133 100644
@@ -777,6 +777,7 @@ struct Rom {
 
     uint8_t *data;
     MemoryRegion *mr;
+    AddressSpace *as;
     int isrom;
     char *fw_dir;
     char *fw_file;

@@ -796,12 +797,15 @@ static void rom_insert(Rom *rom)
         hw_error ("ROM images must be loaded at startup\n");
     }
 
-    /* list is ordered by load address */
+    /* List is ordered by load address in the same address space */
     QTAILQ_FOREACH(item, &roms, next) {
-        if (rom->addr >= item->addr)
-            continue;
-        QTAILQ_INSERT_BEFORE(item, rom, next);
-        return;
+        if (rom->addr >= item->addr && rom->as == item->as) {
+            QTAILQ_INSERT_AFTER(&roms, item, rom, next);
+            return;
+        } else if (rom->addr <= item->addr && rom->as == item->as) {
+            QTAILQ_INSERT_BEFORE(item, rom, next);
+            return;
+        }
     }

hw/core/loader.c static void rom_insert(Rom *rom) · line 810

Quoted 1 line

hw/core/loader.c +0 -0

     QTAILQ_INSERT_TAIL(&roms, rom, next);

This seems a somewhat confusing way of writing this. I think you should define a comparison function and then just replace the current "rom->addr >= item->addr" with "rom_order_compare(rom, item) >= 0". Then it's clear what the comparison you're using to define the sorted order is and that the loop will put things in in sorted position.

Quoted 15 lines

hw/core/loader.c +2 -1

 }

@@ -833,16 +837,25 @@ static void *rom_set_mr(Rom *rom, Object *owner, const char *name)
 
 int rom_add_file(const char *file, const char *fw_dir,
                  hwaddr addr, int32_t bootindex,
-                 bool option_rom, MemoryRegion *mr)
+                 bool option_rom, MemoryRegion *mr,
+                 AddressSpace *as)
 {
     MachineClass *mc = MACHINE_GET_CLASS(qdev_get_machine());
     Rom *rom;
     int rc, fd = -1;
     char devpath[100];
 

hw/core/loader.c static void *rom_set_mr(Rom *rom, Object *owner, const char *name) · line 850

Quoted 3 lines

hw/core/loader.c +3 -0

+    if (as && mr) {
+        fprintf(stderr, "Specifying an Address Space and Memory Region is " \
+                "not valid when loading a rom\n");

Some day we'll fix this up to use Errors, but that day need not be today.

Quoted 42 lines

hw/core/loader.c +9 -3

+        /* We haven't allocated anything so we don't need any cleanup */
+        return -1;
+    }
+
     rom = g_malloc0(sizeof(*rom));
     rom->name = g_strdup(file);
     rom->path = qemu_find_file(QEMU_FILE_TYPE_BIOS, rom->name);
+    rom->as = as;
     if (rom->path == NULL) {
         rom->path = g_strdup(file);
     }

@@ -969,7 +982,7 @@ MemoryRegion *rom_add_blob(const char *name, const void *blob, size_t len,
  * memory ownership of "data", so we don't have to allocate and copy the buffer.
  */
 int rom_add_elf_program(const char *name, void *data, size_t datasize,
-                        size_t romsize, hwaddr addr)
+                        size_t romsize, hwaddr addr, AddressSpace *as)
 {
     Rom *rom;
 

@@ -979,18 +992,19 @@ int rom_add_elf_program(const char *name, void *data, size_t datasize,
     rom->datasize = datasize;
     rom->romsize  = romsize;
     rom->data     = data;
+    rom->as       = as;
     rom_insert(rom);
     return 0;
 }
 
 int rom_add_vga(const char *file)
 {
-    return rom_add_file(file, "vgaroms", 0, -1, true, NULL);
+    return rom_add_file(file, "vgaroms", 0, -1, true, NULL, NULL);
 }
 
 int rom_add_option(const char *file, int32_t bootindex)
 {
-    return rom_add_file(file, "genroms", 0, bootindex, true, NULL);
+    return rom_add_file(file, "genroms", 0, bootindex, true, NULL, NULL);
 }
 

hw/core/loader.c static void rom_reset(void *unused) · line 1026

Quoted 8 lines

hw/core/loader.c +2 -1

 static void rom_reset(void *unused)

@@ -1008,7 +1022,8 @@ static void rom_reset(void *unused)
             void *host = memory_region_get_ram_ptr(rom->mr);
             memcpy(host, rom->data, rom->datasize);
         } else {
-            cpu_physical_memory_write_rom(&address_space_memory,
+            cpu_physical_memory_write_rom(rom->as ? rom->as :
+                                                    &address_space_memory,

Should we just make rom->as be &address_space_memory if the caller doesn't provide one rather than having it be NULL and then special casing what NULL means? (This will also avoid potentially odd effects with some of the ROMs in the list having &address_space_memory for an explicitly specified AS and some having NULL for the same AS but implicitly specified, which is otherwise a pain to deal with in comparisons.)

thanks
-- PMM

Add a new function load_elf_as() that allows the caller to specify an AddressSpace to use when loading the ELF. The original load_elf() function doesn't have any change in functionality.

Signed-off-by Alistair Francis <[email protected]>

---
V8:
- Introduce an RFC version of AddressSpace support

 hw/core/loader.c     | 16 ++++++++++++++--
 include/hw/elf_ops.h |  5 +++--
 include/hw/loader.h  | 16 +++++++++++++++-
 3 files changed, 32 insertions(+), 5 deletions(-)

hw/core/loader.c +14 -2

index a024133..0f69894 100644
@@ -417,6 +417,18 @@ int load_elf(const char *filename, uint64_t (*translate_fn)(void *, uint64_t),
              uint64_t *highaddr, int big_endian, int elf_machine,
              int clear_lsb, int data_swab)
 {
+    return load_elf_as(filename, translate_fn, translate_opaque, pentry,
+                       lowaddr, highaddr, big_endian, elf_machine, clear_lsb,
+                       data_swab, NULL);
+}
+
+/* return < 0 if error, otherwise the number of bytes loaded in memory */
+int load_elf_as(const char *filename,
+                uint64_t (*translate_fn)(void *, uint64_t),
+                void *translate_opaque, uint64_t *pentry, uint64_t *lowaddr,
+                uint64_t *highaddr, int big_endian, int elf_machine,
+                int clear_lsb, int data_swab, AddressSpace *as)
+{
     int fd, data_order, target_data_order, must_swab, ret = ELF_LOAD_FAILED;
     uint8_t e_ident[EI_NIDENT];
 

@@ -455,11 +467,11 @@ int load_elf(const char *filename, uint64_t (*translate_fn)(void *, uint64_t),
     if (e_ident[EI_CLASS] == ELFCLASS64) {
         ret = load_elf64(filename, fd, translate_fn, translate_opaque, must_swab,
                          pentry, lowaddr, highaddr, elf_machine, clear_lsb,
-                         data_swab);
+                         data_swab, as);
     } else {
         ret = load_elf32(filename, fd, translate_fn, translate_opaque, must_swab,
                          pentry, lowaddr, highaddr, elf_machine, clear_lsb,
-                         data_swab);
+                         data_swab, as);
     }
 
  fail:

include/hw/elf_ops.h +3 -2

index 1339677..3b8c9e9 100644
@@ -263,7 +263,8 @@ static int glue(load_elf, SZ)(const char *name, int fd,
                               void *translate_opaque,
                               int must_swab, uint64_t *pentry,
                               uint64_t *lowaddr, uint64_t *highaddr,
-                              int elf_machine, int clear_lsb, int data_swab)
+                              int elf_machine, int clear_lsb, int data_swab,
+                              AddressSpace *as)
 {
     struct elfhdr ehdr;
     struct elf_phdr *phdr = NULL, *ph;

@@ -405,7 +406,7 @@ static int glue(load_elf, SZ)(const char *name, int fd,
             snprintf(label, sizeof(label), "phdr #%d: %s", i, name);
 
             /* rom_add_elf_program() seize the ownership of 'data' */
-            rom_add_elf_program(label, data, file_size, mem_size, addr, NULL);
+            rom_add_elf_program(label, data, file_size, mem_size, addr, as);
 
             total_size += mem_size;
             if (addr < low)

include/hw/loader.h +1 -1

index a701423..36a16cc 100644
@@ -45,7 +45,7 @@ int load_image_gzipped(const char *filename, hwaddr addr, uint64_t max_sz);
 #define ELF_LOAD_WRONG_ENDIAN -4
 const char *load_elf_strerror(int error);
 
-/** load_elf:
+/** load_elf_as:
  * @filename: Path of ELF file
  * @translate_fn: optional function to translate load addresses
  * @translate_opaque: opaque data passed to @translate_fn

include/hw/loader.h +0 -0

  *
  * Load an ELF file's contents to the emulated system's address space.
  * Clients may optionally specify a callback to perform address

@@ -73,6 +75,16 @@ const char *load_elf_strerror(int error);
  * machine type.

include/hw/loader.h +2 -0

+ */
+
 int load_elf(const char *filename, uint64_t (*translate_fn)(void *, uint64_t),
              void *translate_opaque, uint64_t *pentry, uint64_t *lowaddr,
              uint64_t *highaddr, int big_endian, int elf_machine,

Add a new function load_uimage_as() that allows the caller to specify an AddressSpace to use when loading the uImage. The original load_uimage() function doesn't have any change in functionality.

Signed-off-by Alistair Francis <[email protected]>

---

 hw/core/loader.c    | 17 +++++++++++++----
 include/hw/loader.h |  6 ++++++
 2 files changed, 19 insertions(+), 4 deletions(-)

hw/core/loader.c +13 -4

index 0f69894..861dbc2 100644
@@ -581,7 +581,7 @@ static ssize_t gunzip(void *dst, size_t dstlen, uint8_t *src,
 static int load_uboot_image(const char *filename, hwaddr *ep, hwaddr *loadaddr,
                             int *is_linux, uint8_t image_type,
                             uint64_t (*translate_fn)(void *, uint64_t),
-                            void *translate_opaque)
+                            void *translate_opaque, AddressSpace *as)
 {
     int fd;
     int size;

@@ -682,7 +682,7 @@ static int load_uboot_image(const char *filename, hwaddr *ep, hwaddr *loadaddr,
         hdr->ih_size = bytes;
     }
 
-    rom_add_blob_fixed(filename, data, hdr->ih_size, address);
+    rom_add_blob_fixed_as(filename, data, hdr->ih_size, address, as);
 
     ret = hdr->ih_size;
 

@@ -698,14 +698,23 @@ int load_uimage(const char *filename, hwaddr *ep, hwaddr *loadaddr,
                 void *translate_opaque)
 {
     return load_uboot_image(filename, ep, loadaddr, is_linux, IH_TYPE_KERNEL,
-                            translate_fn, translate_opaque);
+                            translate_fn, translate_opaque, NULL);
+}
+
+int load_uimage_as(const char *filename, hwaddr *ep, hwaddr *loadaddr,
+                   int *is_linux,
+                   uint64_t (*translate_fn)(void *, uint64_t),
+                   void *translate_opaque, AddressSpace *as)
+{
+    return load_uboot_image(filename, ep, loadaddr, is_linux, IH_TYPE_KERNEL,
+                            translate_fn, translate_opaque, as);
 }
 
 /* Load a ramdisk.  */
 int load_ramdisk(const char *filename, hwaddr addr, uint64_t max_sz)
 {
     return load_uboot_image(filename, NULL, &addr, NULL, IH_TYPE_RAMDISK,
-                            NULL, NULL);
+                            NULL, NULL, NULL);
 }
 
 /* Load a gzip-compressed kernel to a dynamically allocated buffer. */

include/hw/loader.h +0 -0

index 36a16cc..ede98f6 100644

Add a new function load_image_targphys_as() that allows the caller to specify an AddressSpace to use when loading a targphys. The original load_image_targphys() function doesn't have any change in functionality.

Signed-off-by Alistair Francis <[email protected]>

---

 hw/core/loader.c    | 10 ++++++++--
 include/hw/loader.h |  5 +++++
 2 files changed, 13 insertions(+), 2 deletions(-)

hw/core/loader.c +8 -2

index 861dbc2..31a2d4a 100644
@@ -133,10 +133,16 @@ ssize_t read_targphys(const char *name,
     return did;
 }
 
-/* return the size or -1 if error */
 int load_image_targphys(const char *filename,
                         hwaddr addr, uint64_t max_sz)
 {
+    return load_image_targphys_as(filename, addr, max_sz, NULL);
+}
+
+/* return the size or -1 if error */
+int load_image_targphys_as(const char *filename,
+                           hwaddr addr, uint64_t max_sz, AddressSpace *as)
+{
     int size;
 
     size = get_image_size(filename);

@@ -144,7 +150,7 @@ int load_image_targphys(const char *filename,
         return -1;
     }
     if (size > 0) {
-        rom_add_file_fixed(filename, addr, -1);
+        rom_add_file_fixed_as(filename, addr, -1, as);
     }
     return size;
 }

include/hw/loader.h +0 -0

index ede98f6..1a9053f 100644

Quoted 48 lines · Alistair Francis

Add a new function load_image_targphys_as() that allows the caller to specify an AddressSpace to use when loading a targphys. The original load_image_targphys() function doesn't have any change in functionality.

Signed-off-by Alistair Francis <[email protected]>

---

 hw/core/loader.c    | 10 ++++++++--
 include/hw/loader.h |  5 +++++
 2 files changed, 13 insertions(+), 2 deletions(-)

hw/core/loader.c +8 -2

index 861dbc2..31a2d4a 100644
@@ -133,10 +133,16 @@ ssize_t read_targphys(const char *name,
     return did;
 }
 
-/* return the size or -1 if error */
 int load_image_targphys(const char *filename,
                         hwaddr addr, uint64_t max_sz)
 {
+    return load_image_targphys_as(filename, addr, max_sz, NULL);
+}
+
+/* return the size or -1 if error */
+int load_image_targphys_as(const char *filename,
+                           hwaddr addr, uint64_t max_sz, AddressSpace *as)
+{
     int size;
 
     size = get_image_size(filename);

@@ -144,7 +150,7 @@ int load_image_targphys(const char *filename,
         return -1;
     }
     if (size > 0) {
-        rom_add_file_fixed(filename, addr, -1);
+        rom_add_file_fixed_as(filename, addr, -1, as);
     }
     return size;
 }

include/hw/loader.h +0 -0

index ede98f6..1a9053f 100644
@@ -16,6 +16,9 @@ int load_image(const char *filename, uint8_t *addr); /* deprecated */

include/hw/loader.h int load_image(const char *filename, uint8_t *addr); /* deprecated */ · line 21

Quoted 6 lines

include/hw/loader.h +3 -0

 ssize_t load_image_size(const char *filename, void *addr, size_t size);
 int load_image_targphys(const char *filename, hwaddr,
                         uint64_t max_sz);
+int load_image_targphys_as(const char *filename,
+                           hwaddr addr, uint64_t max_sz, AddressSpace *as);
+

Again, code changes are fine but could we have a doc comment?

thanks
-- PMM

Signed-off-by Alistair Francis <[email protected]>

---
V9:
- Clarify the image loading options
V8:
- Improve documentation
V6:
- Fixup documentation
V4:
- Re-write to be more comprehensive

 docs/generic-loader.txt | 63 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 docs/generic-loader.txt

docs/generic-loader.txt new file +53 -0

new file mode 100644
index 0000000..16c11ee
@@ -0,0 +1,63 @@
+Copyright (c) 2016 Xilinx Inc.
+
+This work is licensed under the terms of the GNU GPL, version 2 or later.  See
+the COPYING file in the top-level directory.
+
+
+The 'loader' device allows the user to load multiple images or values into
+QEMU at startup.
+
+Loading Memory Values
+---------------------
+The loader device allows memory values to be set from the command line. This
+can be done by following the syntax below:
+
+    -device loader,addr=<addr>,data=<data>,data-len=<len>
+    -device loader,addr=<addr>,cpu-num=<cpu-num>
+
+    <addr>      - The address to store the data or the value to use as the
+                  CPU's PC.
+    <data>      - The value to be written to the address. The maximum size of
+                  the data is 8 bytes.
+    <data-len>  - The length of the data in bytes. This argument must be
+                  included if the data argument is.
+    <data-be>   - Set to true if the data to be stored on the guest should be
+                  written as big endian data. The default is to write little
+                  endian data.
+    <cpu-num>   - This will cause the CPU to be reset and the PC to be set to
+                  the value of addr.
+
+For all values both hex and decimal values are allowed. 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:
+    -device loader,addr=0xfd1a0104,data=0x8000000e,data-len=4
+
+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:
+
+    -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.
+    <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.
+                  This will also cause the image to be written to the specified

Quoted 74 lines · Alistair Francis

Signed-off-by Alistair Francis <[email protected]>

---
V9:
- Clarify the image loading options
V8:
- Improve documentation
V6:
- Fixup documentation
V4:
- Re-write to be more comprehensive

 docs/generic-loader.txt | 63 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 docs/generic-loader.txt

docs/generic-loader.txt new file +53 -0

new file mode 100644
index 0000000..16c11ee
@@ -0,0 +1,63 @@
+Copyright (c) 2016 Xilinx Inc.
+
+This work is licensed under the terms of the GNU GPL, version 2 or later.  See
+the COPYING file in the top-level directory.
+
+
+The 'loader' device allows the user to load multiple images or values into
+QEMU at startup.
+
+Loading Memory Values
+---------------------
+The loader device allows memory values to be set from the command line. This
+can be done by following the syntax below:
+
+    -device loader,addr=<addr>,data=<data>,data-len=<len>
+    -device loader,addr=<addr>,cpu-num=<cpu-num>
+
+    <addr>      - The address to store the data or the value to use as the
+                  CPU's PC.
+    <data>      - The value to be written to the address. The maximum size of
+                  the data is 8 bytes.
+    <data-len>  - The length of the data in bytes. This argument must be
+                  included if the data argument is.
+    <data-be>   - Set to true if the data to be stored on the guest should be
+                  written as big endian data. The default is to write little
+                  endian data.
+    <cpu-num>   - This will cause the CPU to be reset and the PC to be set to
+                  the value of addr.
+
+For all values both hex and decimal values are allowed. 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:
+    -device loader,addr=0xfd1a0104,data=0x8000000e,data-len=4
+
+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:
+
+    -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.
+    <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.
+                  This will also cause the image to be written to the specified

docs/generic-loader.txt line 63

Quoted 10 lines

docs/generic-loader.txt new file +10 -0

+                  CPUs address space.
+    <force-raw> - Forces the file to be treated as a raw image. This can be
+                  used to specify the load address of ELF files.
+
+For all values both hex and decimal values are allowed. 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:
+    -device loader,file=./images/boot.elf,cpu-num=0

With this interface, you can specify a file to be loaded to CPU 2's address space (via file=whatever,cpu-num=2) but you can't specify a data value to be loaded to CPU 2's address space (because addr=a,data=x,data-len=y,cpu-num=2 isn't valid). I think we could usefully make that syntax do that.

This is probably most clearly documented by completely splitting
-device loader,addr=<addr>,cpu-num=<cpu-num>
(set the PC)

from
-device loader,addr=<addr>,data=<data>,data-len=<data-len>[,data-be=<data-be>][,cpu-num=<cpu-num>]
(load raw data values)

in the documentation in the same way that loader,file is split.

(I have a feeling we've been circling around on this option syntax over the last few revisions so apologies if I've been inconsistent.)

You also can't specify a file to be loaded which doesn't set the CPU PC, but I'm not sure how important that is. We can always add it later with a no-set-pc option flag if we need it I guess.

thanks
-- PMM