Merge branch 'master' of git://git.denx.de/u-boot-net
[platform/kernel/u-boot.git] / doc / SPL / README.omap3
1 Overview of SPL on OMAP3 devices
2 ================================
3
4 Introduction
5 ------------
6
7 This document provides an overview of how SPL functions on OMAP3 (and related
8 such as am35x and am37x) processors.
9
10 Methodology
11 -----------
12
13 On these platforms the ROM supports trying a sequence of boot devices.  Once
14 one has been used successfully to load SPL this information is stored in memory
15 and the location stored in a register.  We will read this to determine where to
16 read U-Boot from in turn.
17
18 Memory Map
19 ----------
20
21 This is an example of a typical setup.  See top-level README for documentation
22 of which CONFIG variables control these values.  For a given board and the
23 amount of DRAM available to it different values may need to be used.
24 Note that the size of the SPL text rodata and data is enforced with a CONFIG
25 option and growing over that size results in a link error.  The SPL stack
26 starts at the top of SRAM (which is configurable) and grows downward.  The
27 space between the top of SRAM and the enforced upper bound on the size of the
28 SPL text, data and rodata is considered the safe stack area.  Details on
29 confirming this behavior are shown below.
30
31 A portion of the system memory map looks as follows:
32 SRAM: 0x40200000 - 0x4020FFFF
33 DDR1: 0x80000000 - 0xBFFFFFFF
34
35 Option 1 (SPL only):
36 0x40200800 - 0x4020BBFF: Area for SPL text, data and rodata
37 0x4020E000 - 0x4020FFFC: Area for the SPL stack.
38 0x80000000 - 0x8007FFFF: Area for the SPL BSS.
39 0x80100000: CONFIG_SYS_TEXT_BASE of U-Boot
40 0x80208000 - 0x80307FFF: malloc() pool available to SPL.
41
42 Option 2 (SPL or X-Loader):
43 0x40200800 - 0x4020BBFF: Area for SPL text, data and rodata
44 0x4020E000 - 0x4020FFFC: Area for the SPL stack.
45 0x80008000: CONFIG_SYS_TEXT_BASE of U-Boot
46 0x87000000 - 0x8707FFFF: Area for the SPL BSS.
47 0x87080000 - 0x870FFFFF: malloc() pool available to SPL.
48
49 For the areas that reside within DDR1 they must not be used prior to s_init()
50 completing.  Note that CONFIG_SYS_TEXT_BASE must be clear of the areas that SPL
51 uses while running.  This is why we have two versions of the memory map that
52 only vary in where the BSS and malloc pool reside.
53
54 Estimating stack usage
55 ----------------------
56
57 With gcc 4.6 (and later) and the use of GNU cflow it is possible to estimate
58 stack usage at various points in run sequence of SPL.  The -fstack-usage option
59 to gcc will produce '.su' files (such as arch/arm/cpu/armv7/syslib.su) that
60 will give stack usage information and cflow can construct program flow.
61
62 Must have gcc 4.6 or later, which supports -fstack-usage
63
64 1) Build normally
65 2) Perform the following shell command to generate a list of C files used in
66 SPL:
67 $ find spl -name '*.su' | sed -e 's:^spl/::' -e 's:[.]su$:.c:' > used-spl.list
68 3) Execute cflow:
69 $ cflow --main=board_init_r `cat used-spl.list` 2>&1 | $PAGER
70
71 cflow will spit out a number of warnings as it does not parse
72 the config files and picks functions based on #ifdef.  Parsing the '.i'
73 files instead introduces another set of headaches.  These warnings are
74 not usually important to understanding the flow, however.