xref: /openbmc/u-boot/doc/README.generic-board (revision 643ad899)
1#
2# (C) Copyright 2014 Google, Inc
3# Simon Glass <sjg@chromium.org>
4#
5# SPDX-License-Identifier:	GPL-2.0+
6#
7
8DEPRECATION NOTICE FOR arch/<arch>/lib/board.c
9
10For board maintainers: Please submit patches for boards you maintain before
11July 2014, to make them use generic board.
12
13For architecture maintainers: Please submit patches to remove your
14architecture-specific board.c file before October 2014.
15
16
17Background
18----------
19
20U-Boot has traditionally had a board.c file for each architecture. This has
21introduced quite a lot of duplication, with each architecture tending to do
22initialisation slightly differently. To address this, a new 'generic board
23init' feature was introduced a year ago in March 2013 (further motivation is
24provided in the cover letter below).
25
26
27What has changed?
28-----------------
29
30The main change is that the arch/<arch>/lib/board.c file is being removed in
31favour of common/board_f.c (for pre-relocation init) and common/board_r.c
32(for post-relocation init).
33
34Related to this, the global_data and bd_t structures now have a core set of
35fields which are common to all architectures. Architecture-specific fields
36have been moved to separate structures.
37
38
39Supported Arcthitectures
40------------------------
41
42If you are unlucky then your architecture may not support generic board.
43The following architectures are supported now:
44
45   arc
46   arm
47   mips
48   powerpc
49   sandbox
50   x86
51
52If your architecture is not supported, you need to adjust your
53arch/<arch>/config.mk file to include:
54
55   __HAVE_ARCH_GENERIC_BOARD := y
56
57and test it with a suitable board, as follows.
58
59
60Adding Support for your Board
61-----------------------------
62
63To enable generic board for your board, define CONFIG_SYS_GENERIC_BOARD in
64your board config header file.
65
66Test that U-Boot still functions correctly on your board, and fix any
67problems you find. Don't be surprised if there are no problems - generic
68board has had a reasonable amount of testing with common boards.
69
70
71DeadLine
72--------
73
74Please don't take this the wrong way - there is no intent to make your life
75miserable, and we have the greatest respect and admiration for U-Boot users.
76However, with any migration there has to be a period where the old way is
77deprecated and removed. Every patch to the deprecated code introduces a
78potential breakage in the new unused code. Therefore:
79
80Boards or architectures not converted over to general board by the
81end of 2014 may be forcibly changed over (potentially causing run-time
82breakage) or removed.
83
84
85
86Further Background
87------------------
88
89The full text of the original generic board series is reproduced below.
90
91--8<-------------
92
93This series creates a generic board.c implementation which contains
94the essential functions of the major arch/xxx/lib/board.c files.
95
96What is the motivation for this change?
97
981. There is a lot of repeated code in the board.c files. Any change to
99things like setting up the baud rate requires a change in 10 separate
100places.
101
1022. Since there are 10 separate files, adding a new feature which requires
103initialisation is painful since it must be independently added in 10
104places.
105
1063. As time goes by the architectures naturely diverge since there is limited
107pressure to compare features or even CONFIG options against simiilar things
108in other board.c files.
109
1104. New architectures must implement all the features all over again, and
111sometimes in subtley different ways. This places an unfair burden on getting
112a new architecture fully functional and running with U-Boot.
113
1145. While it is a bit of a tricky change, I believe it is worthwhile and
115achievable. There is no requirement that all code be common, only that
116the code that is common should be located in common/board.c rather than
117arch/xxx/lib/board.c.
118
119All the functions of board_init_f() and board_init_r() are broken into
120separate function calls so that they can easily be included or excluded
121for a particular architecture. It also makes it easier to adopt Graeme's
122initcall proposal when it is ready.
123
124http://lists.denx.de/pipermail/u-boot/2012-January/114499.html
125
126This series removes the dependency on generic relocation. So relocation
127happens as one big chunk and is still completely arch-specific. See the
128relocation series for a proposed solution to this for ARM:
129
130http://lists.denx.de/pipermail/u-boot/2011-December/112928.html
131
132or Graeme's recent x86 series v2:
133
134http://lists.denx.de/pipermail/u-boot/2012-January/114467.html
135
136Instead of moving over a whole architecture, this series takes the approach
137of simply enabling generic board support for an architecture. It is then up
138to each board to opt in by defining CONFIG_SYS_GENERIC_BOARD in the board
139config file. If this is not done, then the code will be generated as
140before. This allows both sets of code to co-exist until we are comfortable
141with the generic approach, and enough boards run.
142
143ARM is a relatively large board.c file and one which I can test, therefore
144I think it is a good target for this series. On the other hand, x86 is
145relatively small and simple, but different enough that it introduces a
146few issues to be solved. So I have chosen both ARM and x86 for this series.
147After a suggestion from Wolfgang I have added PPC also. This is the
148largest and most feature-full board, so hopefully we have all bases
149covered in this RFC.
150
151A generic global_data structure is also required. This might upset a few
152people. Here is my basic reasoning: most fields are the same, all
153architectures include and need it, most global_data.h files already have
154#ifdefs to select fields for a particular SOC, so it is hard to
155see why architecures are different in this area. We can perhaps add a
156way to put architecture-specific fields into a separate header file, but
157for now I have judged that to be counter-productive.
158
159Similarly we need a generic bd_info structure, since generic code will
160be accessing it. I have done this in the same way as global_data and the
161same comments apply.
162
163There was dicussion on the list about passing gd_t around as a parameter
164to pre-relocation init functions. I think this makes sense, but it can
165be done as a separate change, and this series does not require it.
166
167While this series needs to stand on its own (as with the link script
168cleanup series and the generic relocation series) the goal is the
169unification of the board init code. So I hope we can address issues with
170this in mind, rather than focusing too narrowly on particular ARM, x86 or
171PPC issues.
172
173I have run-tested ARM on Tegra Seaboard only. To try it out, define
174CONFIG_SYS_GENERIC_BOARD in your board file and rebuild. Most likely on
175x86 and PPC at least it will hang, but if you are lucky it will print
176something first :-)
177
178I have run this though MAKEALL with CONFIG_SYS_GENERIC_BOARD on for all
179ARM, PPC and x86 boards. There are a few failures due to errors in
180the board config, which I have sent patches for. The main issue is
181just the difference between __bss_end and __bss_end__.
182
183Note: the first group of commits are required for this series to build,
184but could be separated out if required. I have included them here for
185convenience.
186
187------------->8--
188
189Simon Glass, sjg@chromium.org
190March 2014
191