[deliverable/linux.git] / Documentation / arm / Booting

			Booting ARM Linux
			=================

Author:	Russell King
Date  : 18 May 2002

The following documentation is relevant to 2.4.18-rmk6 and beyond.

In order to boot ARM Linux, you require a boot loader, which is a small
program that runs before the main kernel.  The boot loader is expected
to initialise various devices, and eventually call the Linux kernel,
passing information to the kernel.

Essentially, the boot loader should provide (as a minimum) the
following:

1. Setup and initialise the RAM.
2. Initialise one serial port.
3. Detect the machine type.
4. Setup the kernel tagged list.
5. Call the kernel image.


1. Setup and initialise RAM
---------------------------

Existing boot loaders:		MANDATORY
New boot loaders:		MANDATORY

The boot loader is expected to find and initialise all RAM that the
kernel will use for volatile data storage in the system.  It performs
this in a machine dependent manner.  (It may use internal algorithms
to automatically locate and size all RAM, or it may use knowledge of
the RAM in the machine, or any other method the boot loader designer
sees fit.)


2. Initialise one serial port
-----------------------------

Existing boot loaders:		OPTIONAL, RECOMMENDED
New boot loaders:		OPTIONAL, RECOMMENDED

The boot loader should initialise and enable one serial port on the
target.  This allows the kernel serial driver to automatically detect
which serial port it should use for the kernel console (generally
used for debugging purposes, or communication with the target.)

As an alternative, the boot loader can pass the relevant 'console='
option to the kernel via the tagged lists specifying the port, and
serial format options as described in

       Documentation/kernel-parameters.txt.


3. Detect the machine type
--------------------------

Existing boot loaders:		OPTIONAL
New boot loaders:		MANDATORY

The boot loader should detect the machine type its running on by some
method.  Whether this is a hard coded value or some algorithm that
looks at the connected hardware is beyond the scope of this document.
The boot loader must ultimately be able to provide a MACH_TYPE_xxx
value to the kernel. (see linux/arch/arm/tools/mach-types).

4. Setup boot data
------------------

Existing boot loaders:		OPTIONAL, HIGHLY RECOMMENDED
New boot loaders:		MANDATORY

The boot loader must provide either a tagged list or a dtb image for
passing configuration data to the kernel.  The physical address of the
boot data is passed to the kernel in register r2.

4a. Setup the kernel tagged list
--------------------------------

The boot loader must create and initialise the kernel tagged list.
A valid tagged list starts with ATAG_CORE and ends with ATAG_NONE.
The ATAG_CORE tag may or may not be empty.  An empty ATAG_CORE tag
has the size field set to '2' (0x00000002).  The ATAG_NONE must set
the size field to zero.

Any number of tags can be placed in the list.  It is undefined
whether a repeated tag appends to the information carried by the
previous tag, or whether it replaces the information in its
entirety; some tags behave as the former, others the latter.

The boot loader must pass at a minimum the size and location of
the system memory, and root filesystem location.  Therefore, the
minimum tagged list should look:

	+-----------+
base ->	| ATAG_CORE |  |
	+-----------+  |
	| ATAG_MEM  |  | increasing address
	+-----------+  |
	| ATAG_NONE |  |
	+-----------+  v

The tagged list should be stored in system RAM.

The tagged list must be placed in a region of memory where neither
the kernel decompressor nor initrd 'bootp' program will overwrite
it.  The recommended placement is in the first 16KiB of RAM.

4b. Setup the device tree
-------------------------

The boot loader must load a device tree image (dtb) into system ram
at a 64bit aligned address and initialize it with the boot data.  The
dtb format is documented in Documentation/devicetree/booting-without-of.txt.
The kernel will look for the dtb magic value of 0xd00dfeed at the dtb
physical address to determine if a dtb has been passed instead of a
tagged list.

The boot loader must pass at a minimum the size and location of the
system memory, and the root filesystem location.  The dtb must be
placed in a region of memory where the kernel decompressor will not
overwrite it.  The recommended placement is in the first 16KiB of RAM
with the caveat that it may not be located at physical address 0 since
the kernel interprets a value of 0 in r2 to mean neither a tagged list
nor a dtb were passed.

5. Calling the kernel image
---------------------------

Existing boot loaders:		MANDATORY
New boot loaders:		MANDATORY

There are two options for calling the kernel zImage.  If the zImage
is stored in flash, and is linked correctly to be run from flash,
then it is legal for the boot loader to call the zImage in flash
directly.

The zImage may also be placed in system RAM (at any location) and
called there.  Note that the kernel uses 16K of RAM below the image
to store page tables.  The recommended placement is 32KiB into RAM.

In either case, the following conditions must be met:

- Quiesce all DMA capable devices so that memory does not get
  corrupted by bogus network packets or disk data. This will save
  you many hours of debug.

- CPU register settings
  r0 = 0,
  r1 = machine type number discovered in (3) above.
  r2 = physical address of tagged list in system RAM, or
       physical address of device tree block (dtb) in system RAM

- CPU mode
  All forms of interrupts must be disabled (IRQs and FIQs)

  For CPUs which do not include the ARM virtualization extensions, the
  CPU must be in SVC mode.  (A special exception exists for Angel)

  CPUs which include support for the virtualization extensions can be
  entered in HYP mode in order to enable the kernel to make full use of
  these extensions.  This is the recommended boot method for such CPUs,
  unless the virtualisations are already in use by a pre-installed
  hypervisor.

  If the kernel is not entered in HYP mode for any reason, it must be
  entered in SVC mode.

- Caches, MMUs
  The MMU must be off.
  Instruction cache may be on or off.
  Data cache must be off.

  If the kernel is entered in HYP mode, the above requirements apply to
  the HYP mode configuration in addition to the ordinary PL1 (privileged
  kernel modes) configuration.  In addition, all traps into the
  hypervisor must be disabled, and PL1 access must be granted for all
  peripherals and CPU resources for which this is architecturally
  possible.  Except for entering in HYP mode, the system configuration
  should be such that a kernel which does not include support for the
  virtualization extensions can boot correctly without extra help.

- The boot loader is expected to call the kernel image by jumping
  directly to the first instruction of the kernel image.

  On CPUs supporting the ARM instruction set, the entry must be
  made in ARM state, even for a Thumb-2 kernel.

  On CPUs supporting only the Thumb instruction set such as
  Cortex-M class CPUs, the entry must be made in Thumb state.
Commit	Line	Data
1da177e4 LT	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
ede338f4 GL	68	4. Setup boot data
ede338f4 GL	69	------------------
1da177e4 LT	70
	71	Existing boot loaders: OPTIONAL, HIGHLY RECOMMENDED
	72	New boot loaders: MANDATORY
	73
ede338f4 GL	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
1da177e4 LT	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
ede338f4 GL	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
1da177e4 LT	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
13fce806	145	- Quiesce all DMA capable devices so that memory does not get
1da177e4 LT	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.
ede338f4 GL	152	r2 = physical address of tagged list in system RAM, or
ede338f4 GL	153	physical address of device tree block (dtb) in system RAM
1da177e4 LT	154
	155	- CPU mode
	156	All forms of interrupts must be disabled (IRQs and FIQs)
6a6d55c3 DM	157
	158	For CPUs which do not include the ARM virtualization extensions, the
	159	CPU must be in SVC mode. (A special exception exists for Angel)
	160
	161	CPUs which include support for the virtualization extensions can be
	162	entered in HYP mode in order to enable the kernel to make full use of
	163	these extensions. This is the recommended boot method for such CPUs,
	164	unless the virtualisations are already in use by a pre-installed
	165	hypervisor.
	166
	167	If the kernel is not entered in HYP mode for any reason, it must be
	168	entered in SVC mode.
1da177e4 LT	169
	170	- Caches, MMUs
	171	The MMU must be off.
	172	Instruction cache may be on or off.
	173	Data cache must be off.
	174
6a6d55c3 DM	175	If the kernel is entered in HYP mode, the above requirements apply to
	176	the HYP mode configuration in addition to the ordinary PL1 (privileged
	177	kernel modes) configuration. In addition, all traps into the
	178	hypervisor must be disabled, and PL1 access must be granted for all
	179	peripherals and CPU resources for which this is architecturally
	180	possible. Except for entering in HYP mode, the system configuration
	181	should be such that a kernel which does not include support for the
	182	virtualization extensions can boot correctly without extra help.
	183
1da177e4 LT	184	- The boot loader is expected to call the kernel image by jumping
	185	directly to the first instruction of the kernel image.
	186
540b5738 DM	187	On CPUs supporting the ARM instruction set, the entry must be
	188	made in ARM state, even for a Thumb-2 kernel.
	189
	190	On CPUs supporting only the Thumb instruction set such as
	191	Cortex-M class CPUs, the entry must be made in Thumb state.