xref: /openbmc/u-boot/doc/README.generic-board (revision 21299d3a)
1# SPDX-License-Identifier: GPL-2.0+
2#
3# (C) Copyright 2014 Google, Inc
4# Simon Glass <sjg@chromium.org>
5
6Background
7----------
8
9U-Boot traditionally had a board.c file for each architecture. This introduced
10quite a lot of duplication, with each architecture tending to do
11initialisation slightly differently. To address this, a new 'generic board
12init' feature was introduced in March 2013 (further motivation is
13provided in the cover letter below).
14
15All boards and architectures have moved to this as of mid 2016.
16
17
18What has changed?
19-----------------
20
21The main change is that the arch/<arch>/lib/board.c file is removed in
22favour of common/board_f.c (for pre-relocation init) and common/board_r.c
23(for post-relocation init).
24
25Related to this, the global_data and bd_t structures now have a core set of
26fields which are common to all architectures. Architecture-specific fields
27have been moved to separate structures.
28
29
30Further Background
31------------------
32
33The full text of the original generic board series is reproduced below.
34
35--8<-------------
36
37This series creates a generic board.c implementation which contains
38the essential functions of the major arch/xxx/lib/board.c files.
39
40What is the motivation for this change?
41
421. There is a lot of repeated code in the board.c files. Any change to
43things like setting up the baud rate requires a change in 10 separate
44places.
45
462. Since there are 10 separate files, adding a new feature which requires
47initialisation is painful since it must be independently added in 10
48places.
49
503. As time goes by the architectures naturally diverge since there is limited
51pressure to compare features or even CONFIG options against similar things
52in other board.c files.
53
544. New architectures must implement all the features all over again, and
55sometimes in subtle different ways. This places an unfair burden on getting
56a new architecture fully functional and running with U-Boot.
57
585. While it is a bit of a tricky change, I believe it is worthwhile and
59achievable. There is no requirement that all code be common, only that
60the code that is common should be located in common/board.c rather than
61arch/xxx/lib/board.c.
62
63All the functions of board_init_f() and board_init_r() are broken into
64separate function calls so that they can easily be included or excluded
65for a particular architecture. It also makes it easier to adopt Graeme's
66initcall proposal when it is ready.
67
68http://lists.denx.de/pipermail/u-boot/2012-January/114499.html
69
70This series removes the dependency on generic relocation. So relocation
71happens as one big chunk and is still completely arch-specific. See the
72relocation series for a proposed solution to this for ARM:
73
74http://lists.denx.de/pipermail/u-boot/2011-December/112928.html
75
76or Graeme's recent x86 series v2:
77
78http://lists.denx.de/pipermail/u-boot/2012-January/114467.html
79
80Instead of moving over a whole architecture, this series takes the approach
81of simply enabling generic board support for an architecture. It is then up
82to each board to opt in by defining CONFIG_SYS_GENERIC_BOARD in the board
83config file. If this is not done, then the code will be generated as
84before. This allows both sets of code to co-exist until we are comfortable
85with the generic approach, and enough boards run.
86
87ARM is a relatively large board.c file and one which I can test, therefore
88I think it is a good target for this series. On the other hand, x86 is
89relatively small and simple, but different enough that it introduces a
90few issues to be solved. So I have chosen both ARM and x86 for this series.
91After a suggestion from Wolfgang I have added PPC also. This is the
92largest and most feature-full board, so hopefully we have all bases
93covered in this RFC.
94
95A generic global_data structure is also required. This might upset a few
96people. Here is my basic reasoning: most fields are the same, all
97architectures include and need it, most global_data.h files already have
98#ifdefs to select fields for a particular SOC, so it is hard to
99see why architecures are different in this area. We can perhaps add a
100way to put architecture-specific fields into a separate header file, but
101for now I have judged that to be counter-productive.
102
103Similarly we need a generic bd_info structure, since generic code will
104be accessing it. I have done this in the same way as global_data and the
105same comments apply.
106
107There was dicussion on the list about passing gd_t around as a parameter
108to pre-relocation init functions. I think this makes sense, but it can
109be done as a separate change, and this series does not require it.
110
111While this series needs to stand on its own (as with the link script
112cleanup series and the generic relocation series) the goal is the
113unification of the board init code. So I hope we can address issues with
114this in mind, rather than focusing too narrowly on particular ARM, x86 or
115PPC issues.
116
117I have run-tested ARM on Tegra Seaboard only. To try it out, define
118CONFIG_SYS_GENERIC_BOARD in your board file and rebuild. Most likely on
119x86 and PPC at least it will hang, but if you are lucky it will print
120something first :-)
121
122I have run this though MAKEALL with CONFIG_SYS_GENERIC_BOARD on for all
123ARM, PPC and x86 boards. There are a few failures due to errors in
124the board config, which I have sent patches for. The main issue is
125just the difference between __bss_end and __bss_end__.
126
127Note: the first group of commits are required for this series to build,
128but could be separated out if required. I have included them here for
129convenience.
130
131------------->8--
132
133Simon Glass, sjg@chromium.org
134March 2014
135Updated after final removal, May 2016
136