summaryrefslogtreecommitdiffstats
path: root/arch/architecture.dox
blob: 94360989cf7d35d6da21f137373fc5b4cf96bae9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
/** @page dev_architecture Integrate a new architecture (ARCH)

@section linker_scripts Rules for the generic Linker Script File

Never include an object file by name directly! Linker Script Files defines the
layout, not the content. Content is defined in objecfiles instead.

Don't rely on the given object file order to create your binary U-Boot v2! This
may work, but is not relyable in all cases (and its a very bad style)!

For the special case some layout contraints exists, use specific section
naming instead. Refer @ref reset_code how to define this specific section.

@section reset_code Bring it up: The Reset Code

The way a CPU wakes up after reset is very specific to its architecture.

For example the ARM architecture starts its reset code at address 0x0000000,
the x86 architecture at 0x000FFFF0, PowerPC at 0x00000100 or 0xFFFFF100.

So for the special reset code on all architectures it must be located at
architecture specific locations within the binary U-Boot image.

All reset code uses section ".text_entry" for its localisation within the
binary U-Boot image. Its up to the linker script file to use this section name
to find the right place in whatever environment and U-Boot sizes.

@code
	.section ".text_entry","ax"
@endcode

@section arch_files List of changes

 - create a new subdirectory in /arch
TODO

*/

/** @page dev_cpu Integrate a new CPU (MACH)

Features required for every CPU:

 - clocksource
 - CPU reset function

@section time_keeping Time keeping

In U-Boot-v2 we are using the clocksource mechanism from the Linux Kernel.
This makes it fairly easy to add timer functionality for a new board or
architecture.

Apart from initialization there is only one function to be registerd:
clocksource_read(). This function returns the current value of a free running
counter. Other functions like udelay() and get_time_ns() are derived from this
function. The only thing you have to implement is a clocksource driver and
to register it at runtime.

@code
static uint64_t mycpu_clocksource_read(void)
{
	TODO
}

static struct clocksource cs = {
	.read	= mycpu_clocksource_read,
	.mask	= 0xffffffff,
	.shift	= 10,
};

....
	init_clock(&cs);
....
@endcode

See arch/arm/mach-imx/clocksource.c for an example. clocksource drivers from
the Linux Kernel can be used nearly 1:1, except for the register accesses.

Note: For clocksources the __lshrdi3 symbol is needed. You can find the
function for your architecture in the Linux Kernel or a libc of your choice.

Note: U-Boot-v2 expects an upward counting counter!

@section reset_function Reset function

TODO

@li @subpage dev_arm_mach
@li @subpage dev_bf_mach
@li @subpage dev_ppc_mach

*/