SPEAr: Update MAINTAINERS and Documentation
[linux-3.10.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. Call the kernel image.
22
23
24 1. Setup and initialise RAM
25 ---------------------------
26
27 Existing boot loaders:          MANDATORY
28 New boot loaders:               MANDATORY
29
30 The boot loader is expected to find and initialise all RAM that the
31 kernel will use for volatile data storage in the system.  It performs
32 this in a machine dependent manner.  (It may use internal algorithms
33 to automatically locate and size all RAM, or it may use knowledge of
34 the RAM in the machine, or any other method the boot loader designer
35 sees fit.)
36
37
38 2. Initialise one serial port
39 -----------------------------
40
41 Existing boot loaders:          OPTIONAL, RECOMMENDED
42 New boot loaders:               OPTIONAL, RECOMMENDED
43
44 The boot loader should initialise and enable one serial port on the
45 target.  This allows the kernel serial driver to automatically detect
46 which serial port it should use for the kernel console (generally
47 used for debugging purposes, or communication with the target.)
48
49 As an alternative, the boot loader can pass the relevant 'console='
50 option to the kernel via the tagged lists specifying the port, and
51 serial format options as described in
52
53        Documentation/kernel-parameters.txt.
54
55
56 3. Detect the machine type
57 --------------------------
58
59 Existing boot loaders:          OPTIONAL
60 New boot loaders:               MANDATORY
61
62 The boot loader should detect the machine type its running on by some
63 method.  Whether this is a hard coded value or some algorithm that
64 looks at the connected hardware is beyond the scope of this document.
65 The boot loader must ultimately be able to provide a MACH_TYPE_xxx
66 value to the kernel. (see linux/arch/arm/tools/mach-types).
67
68 4. Setup boot data
69 ------------------
70
71 Existing boot loaders:          OPTIONAL, HIGHLY RECOMMENDED
72 New boot loaders:               MANDATORY
73
74 The boot loader must provide either a tagged list or a dtb image for
75 passing configuration data to the kernel.  The physical address of the
76 boot data is passed to the kernel in register r2.
77
78 4a. Setup the kernel tagged list
79 --------------------------------
80
81 The boot loader must create and initialise the kernel tagged list.
82 A valid tagged list starts with ATAG_CORE and ends with ATAG_NONE.
83 The ATAG_CORE tag may or may not be empty.  An empty ATAG_CORE tag
84 has the size field set to '2' (0x00000002).  The ATAG_NONE must set
85 the size field to zero.
86
87 Any number of tags can be placed in the list.  It is undefined
88 whether a repeated tag appends to the information carried by the
89 previous tag, or whether it replaces the information in its
90 entirety; some tags behave as the former, others the latter.
91
92 The boot loader must pass at a minimum the size and location of
93 the system memory, and root filesystem location.  Therefore, the
94 minimum tagged list should look:
95
96         +-----------+
97 base -> | ATAG_CORE |  |
98         +-----------+  |
99         | ATAG_MEM  |  | increasing address
100         +-----------+  |
101         | ATAG_NONE |  |
102         +-----------+  v
103
104 The tagged list should be stored in system RAM.
105
106 The tagged list must be placed in a region of memory where neither
107 the kernel decompressor nor initrd 'bootp' program will overwrite
108 it.  The recommended placement is in the first 16KiB of RAM.
109
110 4b. Setup the device tree
111 -------------------------
112
113 The boot loader must load a device tree image (dtb) into system ram
114 at a 64bit aligned address and initialize it with the boot data.  The
115 dtb format is documented in Documentation/devicetree/booting-without-of.txt.
116 The kernel will look for the dtb magic value of 0xd00dfeed at the dtb
117 physical address to determine if a dtb has been passed instead of a
118 tagged list.
119
120 The boot loader must pass at a minimum the size and location of the
121 system memory, and the root filesystem location.  The dtb must be
122 placed in a region of memory where the kernel decompressor will not
123 overwrite it.  The recommended placement is in the first 16KiB of RAM
124 with the caveat that it may not be located at physical address 0 since
125 the kernel interprets a value of 0 in r2 to mean neither a tagged list
126 nor a dtb were passed.
127
128 5. Calling the kernel image
129 ---------------------------
130
131 Existing boot loaders:          MANDATORY
132 New boot loaders:               MANDATORY
133
134 There are two options for calling the kernel zImage.  If the zImage
135 is stored in flash, and is linked correctly to be run from flash,
136 then it is legal for the boot loader to call the zImage in flash
137 directly.
138
139 The zImage may also be placed in system RAM (at any location) and
140 called there.  Note that the kernel uses 16K of RAM below the image
141 to store page tables.  The recommended placement is 32KiB into RAM.
142
143 In either case, the following conditions must be met:
144
145 - Quiesce all DMA capable devices so that memory does not get
146   corrupted by bogus network packets or disk data. This will save
147   you many hours of debug.
148
149 - CPU register settings
150   r0 = 0,
151   r1 = machine type number discovered in (3) above.
152   r2 = physical address of tagged list in system RAM, or
153        physical address of device tree block (dtb) in system RAM
154
155 - CPU mode
156   All forms of interrupts must be disabled (IRQs and FIQs)
157   The CPU must be in SVC mode.  (A special exception exists for Angel)
158
159 - Caches, MMUs
160   The MMU must be off.
161   Instruction cache may be on or off.
162   Data cache must be off.
163
164 - The boot loader is expected to call the kernel image by jumping
165   directly to the first instruction of the kernel image.
166
167   On CPUs supporting the ARM instruction set, the entry must be
168   made in ARM state, even for a Thumb-2 kernel.
169
170   On CPUs supporting only the Thumb instruction set such as
171   Cortex-M class CPUs, the entry must be made in Thumb state.