README.generic-board 6.99 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
#
# (C) Copyright 2014 Google, Inc
# Simon Glass <sjg@chromium.org>
#
# SPDX-License-Identifier:	GPL-2.0+
#

DEPRECATION NOTICE FOR arch/<arch>/lib/board.c

For board maintainers: Please submit patches for boards you maintain before
July 2014, to make them use generic board.

For architecture maintainers: Please submit patches to remove your
architecture-specific board.c file before October 2014.


Background
----------

20
U-Boot has traditionally had a board.c file for each architecture. This has
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
introduced quite a lot of duplication, with each architecture tending to do
initialisation slightly differently. To address this, a new 'generic board
init' feature was introduced a year ago in March 2013 (further motivation is
provided in the cover letter below).


What has changed?
-----------------

The main change is that the arch/<arch>/lib/board.c file is being removed in
favour of common/board_f.c (for pre-relocation init) and common/board_r.c
(for post-relocation init).

Related to this, the global_data and bd_t structures now have a core set of
fields which are common to all architectures. Architecture-specific fields
have been moved to separate structures.


39
Supported Architectures
40 41 42
------------------------

If you are unlucky then your architecture may not support generic board.
43
The following architectures are supported now:
44 45 46

   arc
   arm
47 48 49 50
   avr32
   blackfin
   m68k
   microblaze
51
   mips
52
   nios2
53 54 55 56
   powerpc
   sandbox
   x86

57 58
If your architecture is not supported, you need to select
HAVE_GENERIC_BOARD in arch/Kconfig
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
and test it with a suitable board, as follows.


Adding Support for your Board
-----------------------------

To enable generic board for your board, define CONFIG_SYS_GENERIC_BOARD in
your board config header file.

Test that U-Boot still functions correctly on your board, and fix any
problems you find. Don't be surprised if there are no problems - generic
board has had a reasonable amount of testing with common boards.


DeadLine
--------

Please don't take this the wrong way - there is no intent to make your life
miserable, and we have the greatest respect and admiration for U-Boot users.
However, with any migration there has to be a period where the old way is
deprecated and removed. Every patch to the deprecated code introduces a
potential breakage in the new unused code. Therefore:

Boards or architectures not converted over to general board by the
end of 2014 may be forcibly changed over (potentially causing run-time
breakage) or removed.



Further Background
------------------

The full text of the original generic board series is reproduced below.

--8<-------------

This series creates a generic board.c implementation which contains
the essential functions of the major arch/xxx/lib/board.c files.

What is the motivation for this change?

1. There is a lot of repeated code in the board.c files. Any change to
things like setting up the baud rate requires a change in 10 separate
places.

2. Since there are 10 separate files, adding a new feature which requires
initialisation is painful since it must be independently added in 10
places.

108 109
3. As time goes by the architectures naturally diverge since there is limited
pressure to compare features or even CONFIG options against similar things
110 111 112
in other board.c files.

4. New architectures must implement all the features all over again, and
113
sometimes in subtle different ways. This places an unfair burden on getting
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
a new architecture fully functional and running with U-Boot.

5. While it is a bit of a tricky change, I believe it is worthwhile and
achievable. There is no requirement that all code be common, only that
the code that is common should be located in common/board.c rather than
arch/xxx/lib/board.c.

All the functions of board_init_f() and board_init_r() are broken into
separate function calls so that they can easily be included or excluded
for a particular architecture. It also makes it easier to adopt Graeme's
initcall proposal when it is ready.

http://lists.denx.de/pipermail/u-boot/2012-January/114499.html

This series removes the dependency on generic relocation. So relocation
happens as one big chunk and is still completely arch-specific. See the
relocation series for a proposed solution to this for ARM:

http://lists.denx.de/pipermail/u-boot/2011-December/112928.html

or Graeme's recent x86 series v2:

http://lists.denx.de/pipermail/u-boot/2012-January/114467.html

Instead of moving over a whole architecture, this series takes the approach
of simply enabling generic board support for an architecture. It is then up
to each board to opt in by defining CONFIG_SYS_GENERIC_BOARD in the board
config file. If this is not done, then the code will be generated as
before. This allows both sets of code to co-exist until we are comfortable
with the generic approach, and enough boards run.

ARM is a relatively large board.c file and one which I can test, therefore
I think it is a good target for this series. On the other hand, x86 is
relatively small and simple, but different enough that it introduces a
few issues to be solved. So I have chosen both ARM and x86 for this series.
After a suggestion from Wolfgang I have added PPC also. This is the
largest and most feature-full board, so hopefully we have all bases
covered in this RFC.

A generic global_data structure is also required. This might upset a few
people. Here is my basic reasoning: most fields are the same, all
architectures include and need it, most global_data.h files already have
#ifdefs to select fields for a particular SOC, so it is hard to
see why architecures are different in this area. We can perhaps add a
way to put architecture-specific fields into a separate header file, but
for now I have judged that to be counter-productive.

Similarly we need a generic bd_info structure, since generic code will
be accessing it. I have done this in the same way as global_data and the
same comments apply.

There was dicussion on the list about passing gd_t around as a parameter
to pre-relocation init functions. I think this makes sense, but it can
be done as a separate change, and this series does not require it.

While this series needs to stand on its own (as with the link script
cleanup series and the generic relocation series) the goal is the
unification of the board init code. So I hope we can address issues with
this in mind, rather than focusing too narrowly on particular ARM, x86 or
PPC issues.

I have run-tested ARM on Tegra Seaboard only. To try it out, define
CONFIG_SYS_GENERIC_BOARD in your board file and rebuild. Most likely on
x86 and PPC at least it will hang, but if you are lucky it will print
something first :-)

I have run this though MAKEALL with CONFIG_SYS_GENERIC_BOARD on for all
ARM, PPC and x86 boards. There are a few failures due to errors in
the board config, which I have sent patches for. The main issue is
just the difference between __bss_end and __bss_end__.

Note: the first group of commits are required for this series to build,
but could be separated out if required. I have included them here for
convenience.

------------->8--

Simon Glass, sjg@chromium.org
March 2014