Documentation/arm/booting.rst

   1 =================
   2 Booting ARM Linux
   3 =================
   4
   5 Author: Russell King
   6
   7 Date  : 18 May 2002
   8
   9 The following documentation is relevant to 2.4.18-rmk6 and beyond.
  10
  11 In order to boot ARM Linux, you require a boot loader, which is a small
  12 program that runs before the main kernel.  The boot loader is expected
  13 to initialise various devices, and eventually call the Linux kernel,
  14 passing information to the kernel.
  15
  16 Essentially, the boot loader should provide (as a minimum) the
  17 following:
  18
  19 1. Setup and initialise the RAM.
  20 2. Initialise one serial port.
  21 3. Detect the machine type.
  22 4. Setup the kernel tagged list.
  23 5. Load initramfs.
  24 6. Call the kernel image.
  25
  26
  27 1. Setup and initialise RAM
  28 ---------------------------
  29
  30 Existing boot loaders:
  31         MANDATORY
  32 New boot loaders:
  33         MANDATORY
  34
  35 The boot loader is expected to find and initialise all RAM that the
  36 kernel will use for volatile data storage in the system.  It performs
  37 this in a machine dependent manner.  (It may use internal algorithms
  38 to automatically locate and size all RAM, or it may use knowledge of
  39 the RAM in the machine, or any other method the boot loader designer
  40 sees fit.)
  41
  42
  43 2. Initialise one serial port
  44 -----------------------------
  45
  46 Existing boot loaders:
  47         OPTIONAL, RECOMMENDED
  48 New boot loaders:
  49         OPTIONAL, RECOMMENDED
  50
  51 The boot loader should initialise and enable one serial port on the
  52 target.  This allows the kernel serial driver to automatically detect
  53 which serial port it should use for the kernel console (generally
  54 used for debugging purposes, or communication with the target.)
  55
  56 As an alternative, the boot loader can pass the relevant 'console='
  57 option to the kernel via the tagged lists specifying the port, and
  58 serial format options as described in
  59
  60        Documentation/admin-guide/kernel-parameters.rst.
  61
  62
  63 3. Detect the machine type
  64 --------------------------
  65
  66 Existing boot loaders:
  67         OPTIONAL
  68 New boot loaders:
  69         MANDATORY except for DT-only platforms
  70
  71 The boot loader should detect the machine type its running on by some
  72 method.  Whether this is a hard coded value or some algorithm that
  73 looks at the connected hardware is beyond the scope of this document.
  74 The boot loader must ultimately be able to provide a MACH_TYPE_xxx
  75 value to the kernel. (see linux/arch/arm/tools/mach-types).  This
  76 should be passed to the kernel in register r1.
  77
  78 For DT-only platforms, the machine type will be determined by device
  79 tree.  set the machine type to all ones (~0).  This is not strictly
  80 necessary, but assures that it will not match any existing types.
  81
  82 4. Setup boot data
  83 ------------------
  84
  85 Existing boot loaders:
  86         OPTIONAL, HIGHLY RECOMMENDED
  87 New boot loaders:
  88         MANDATORY
  89
  90 The boot loader must provide either a tagged list or a dtb image for
  91 passing configuration data to the kernel.  The physical address of the
  92 boot data is passed to the kernel in register r2.
  93
  94 4a. Setup the kernel tagged list
  95 --------------------------------
  96
  97 The boot loader must create and initialise the kernel tagged list.
  98 A valid tagged list starts with ATAG_CORE and ends with ATAG_NONE.
  99 The ATAG_CORE tag may or may not be empty.  An empty ATAG_CORE tag
 100 has the size field set to '2' (0x00000002).  The ATAG_NONE must set
 101 the size field to zero.
 102
 103 Any number of tags can be placed in the list.  It is undefined
 104 whether a repeated tag appends to the information carried by the
 105 previous tag, or whether it replaces the information in its
 106 entirety; some tags behave as the former, others the latter.
 107
 108 The boot loader must pass at a minimum the size and location of
 109 the system memory, and root filesystem location.  Therefore, the
 110 minimum tagged list should look::
 111
 112                 +-----------+
 113   base ->       | ATAG_CORE |  |
 114                 +-----------+  |
 115                 | ATAG_MEM  |  | increasing address
 116                 +-----------+  |
 117                 | ATAG_NONE |  |
 118                 +-----------+  v
 119
 120 The tagged list should be stored in system RAM.
 121
 122 The tagged list must be placed in a region of memory where neither
 123 the kernel decompressor nor initrd 'bootp' program will overwrite
 124 it.  The recommended placement is in the first 16KiB of RAM.
 125
 126 4b. Setup the device tree
 127 -------------------------
 128
 129 The boot loader must load a device tree image (dtb) into system ram
 130 at a 64bit aligned address and initialize it with the boot data.  The
 131 dtb format is documented in Documentation/devicetree/booting-without-of.txt.
 132 The kernel will look for the dtb magic value of 0xd00dfeed at the dtb
 133 physical address to determine if a dtb has been passed instead of a
 134 tagged list.
 135
 136 The boot loader must pass at a minimum the size and location of the
 137 system memory, and the root filesystem location.  The dtb must be
 138 placed in a region of memory where the kernel decompressor will not
 139 overwrite it, while remaining within the region which will be covered
 140 by the kernel's low-memory mapping.
 141
 142 A safe location is just above the 128MiB boundary from start of RAM.
 143
 144 5. Load initramfs.
 145 ------------------
 146
 147 Existing boot loaders:
 148         OPTIONAL
 149 New boot loaders:
 150         OPTIONAL
 151
 152 If an initramfs is in use then, as with the dtb, it must be placed in
 153 a region of memory where the kernel decompressor will not overwrite it
 154 while also with the region which will be covered by the kernel's
 155 low-memory mapping.
 156
 157 A safe location is just above the device tree blob which itself will
 158 be loaded just above the 128MiB boundary from the start of RAM as
 159 recommended above.
 160
 161 6. Calling the kernel image
 162 ---------------------------
 163
 164 Existing boot loaders:
 165         MANDATORY
 166 New boot loaders:
 167         MANDATORY
 168
 169 There are two options for calling the kernel zImage.  If the zImage
 170 is stored in flash, and is linked correctly to be run from flash,
 171 then it is legal for the boot loader to call the zImage in flash
 172 directly.
 173
 174 The zImage may also be placed in system RAM and called there.  The
 175 kernel should be placed in the first 128MiB of RAM.  It is recommended
 176 that it is loaded above 32MiB in order to avoid the need to relocate
 177 prior to decompression, which will make the boot process slightly
 178 faster.
 179
 180 When booting a raw (non-zImage) kernel the constraints are tighter.
 181 In this case the kernel must be loaded at an offset into system equal
 182 to TEXT_OFFSET - PAGE_OFFSET.
 183
 184 In any case, the following conditions must be met:
 185
 186 - Quiesce all DMA capable devices so that memory does not get
 187   corrupted by bogus network packets or disk data. This will save
 188   you many hours of debug.
 189
 190 - CPU register settings
 191
 192   - r0 = 0,
 193   - r1 = machine type number discovered in (3) above.
 194   - r2 = physical address of tagged list in system RAM, or
 195     physical address of device tree block (dtb) in system RAM
 196
 197 - CPU mode
 198
 199   All forms of interrupts must be disabled (IRQs and FIQs)
 200
 201   For CPUs which do not include the ARM virtualization extensions, the
 202   CPU must be in SVC mode.  (A special exception exists for Angel)
 203
 204   CPUs which include support for the virtualization extensions can be
 205   entered in HYP mode in order to enable the kernel to make full use of
 206   these extensions.  This is the recommended boot method for such CPUs,
 207   unless the virtualisations are already in use by a pre-installed
 208   hypervisor.
 209
 210   If the kernel is not entered in HYP mode for any reason, it must be
 211   entered in SVC mode.
 212
 213 - Caches, MMUs
 214
 215   The MMU must be off.
 216
 217   Instruction cache may be on or off.
 218
 219   Data cache must be off.
 220
 221   If the kernel is entered in HYP mode, the above requirements apply to
 222   the HYP mode configuration in addition to the ordinary PL1 (privileged
 223   kernel modes) configuration.  In addition, all traps into the
 224   hypervisor must be disabled, and PL1 access must be granted for all
 225   peripherals and CPU resources for which this is architecturally
 226   possible.  Except for entering in HYP mode, the system configuration
 227   should be such that a kernel which does not include support for the
 228   virtualization extensions can boot correctly without extra help.
 229
 230 - The boot loader is expected to call the kernel image by jumping
 231   directly to the first instruction of the kernel image.
 232
 233   On CPUs supporting the ARM instruction set, the entry must be
 234   made in ARM state, even for a Thumb-2 kernel.
 235
 236   On CPUs supporting only the Thumb instruction set such as
 237   Cortex-M class CPUs, the entry must be made in Thumb state.