docs/generic-loader.txt

   1 Copyright (c) 2016 Xilinx Inc.
   2
   3 This work is licensed under the terms of the GNU GPL, version 2 or later.  See
   4 the COPYING file in the top-level directory.
   5
   6
   7 The 'loader' device allows the user to load multiple images or values into
   8 QEMU at startup.
   9
  10 Loading Data into Memory Values
  11 -------------------------------
  12 The loader device allows memory values to be set from the command line. This
  13 can be done by following the syntax below:
  14
  15      -device loader,addr=<addr>,data=<data>,data-len=<data-len>
  16                    [,data-be=<data-be>][,cpu-num=<cpu-num>]
  17
  18     <addr>      - The address to store the data in.
  19     <data>      - The value to be written to the address. The maximum size of
  20                   the data is 8 bytes.
  21     <data-len>  - The length of the data in bytes. This argument must be
  22                   included if the data argument is.
  23     <data-be>   - Set to true if the data to be stored on the guest should be
  24                   written as big endian data. The default is to write little
  25                   endian data.
  26     <cpu-num>   - The number of the CPU's address space where the data should
  27                   be loaded. If not specified the address space of the first
  28                   CPU is used.
  29
  30 All values are parsed using the standard QemuOps parsing. This allows the user
  31 to specify any values in any format supported. By default the values
  32 will be parsed as decimal. To use hex values the user should prefix the number
  33 with a '0x'.
  34
  35 An example of loading value 0x8000000e to address 0xfd1a0104 is:
  36     -device loader,addr=0xfd1a0104,data=0x8000000e,data-len=4
  37
  38 Setting a CPU's Program Counter
  39 -------------------------------
  40 The loader device allows the CPU's PC to be set from the command line. This
  41 can be done by following the syntax below:
  42
  43      -device loader,addr=<addr>,cpu-num=<cpu-num>
  44
  45     <addr>      - The value to use as the CPU's PC.
  46     <cpu-num>   - The number of the CPU whose PC should be set to the
  47                   specified value.
  48
  49 All values are parsed using the standard QemuOps parsing. This allows the user
  50 to specify any values in any format supported. By default the values
  51 will be parsed as decimal. To use hex values the user should prefix the number
  52 with a '0x'.
  53
  54 An example of setting CPU 0's PC to 0x8000 is:
  55     -device loader,addr=0x8000,cpu-num=0
  56
  57 Loading Files
  58 -------------
  59 The loader device also allows files to be loaded into memory. It can load raw
  60 files and ELF executable files.  Raw files are loaded verbatim.  ELF executable
  61 files are loaded by an ELF loader.  The syntax is shown below:
  62
  63     -device loader,file=<file>[,addr=<addr>][,cpu-num=<cpu-num>][,force-raw=<raw>]
  64
  65     <file>      - A file to be loaded into memory
  66     <addr>      - The addr in memory that the file should be loaded. This is
  67                   ignored if you are using an ELF (unless force-raw is true).
  68                   This is required if you aren't loading an ELF.
  69     <cpu-num>   - This specifies the CPU that should be used. This is an
  70                   optional argument and will cause the CPU's PC to be set to
  71                   where the image is stored or in the case of an ELF file to
  72                   the value in the header. This option should only be used
  73                   for the boot image.
  74                   This will also cause the image to be written to the specified
  75                   CPU's address space. If not specified, the default is CPU 0.
  76     <force-raw> - Setting force-raw=on forces the file to be treated as a raw
  77                   image.  This can be used to load ELF files as if they were raw.
  78
  79 All values are parsed using the standard QemuOps parsing. This allows the user
  80 to specify any values in any format supported. By default the values
  81 will be parsed as decimal. To use hex values the user should prefix the number
  82 with a '0x'.
  83
  84 An example of loading an ELF file which CPU0 will boot is shown below:
  85     -device loader,file=./images/boot.elf,cpu-num=0
  86
  87 Restrictions and ToDos
  88 ----------------------
  89  - At the moment it is just assumed that if you specify a cpu-num then you
  90    want to set the PC as well. This might not always be the case. In future
  91    the internal state 'set_pc' (which exists in the generic loader now) should
  92    be exposed to the user so that they can choose if the PC is set or not.