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