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