doc/README.generic-board

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