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