docs/system/generic-loader.rst

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