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 Background
   9 ----------
  10
  11 U-Boot traditionally had a board.c file for each architecture. This introduced
  12 quite a lot of duplication, with each architecture tending to do
  13 initialisation slightly differently. To address this, a new 'generic board
  14 init' feature was introduced in March 2013 (further motivation is
  15 provided in the cover letter below).
  16
  17 All boards and architectures have moved to this as of mid 2016.
  18
  19
  20 What has changed?
  21 -----------------
  22
  23 The main change is that the arch/<arch>/lib/board.c file is removed in
  24 favour of common/board_f.c (for pre-relocation init) and common/board_r.c
  25 (for post-relocation init).
  26
  27 Related to this, the global_data and bd_t structures now have a core set of
  28 fields which are common to all architectures. Architecture-specific fields
  29 have been moved to separate structures.
  30
  31
  32 Further Background
  33 ------------------
  34
  35 The full text of the original generic board series is reproduced below.
  36
  37 --8<-------------
  38
  39 This series creates a generic board.c implementation which contains
  40 the essential functions of the major arch/xxx/lib/board.c files.
  41
  42 What is the motivation for this change?
  43
  44 1. There is a lot of repeated code in the board.c files. Any change to
  45 things like setting up the baud rate requires a change in 10 separate
  46 places.
  47
  48 2. Since there are 10 separate files, adding a new feature which requires
  49 initialisation is painful since it must be independently added in 10
  50 places.
  51
  52 3. As time goes by the architectures naturally diverge since there is limited
  53 pressure to compare features or even CONFIG options against similar things
  54 in other board.c files.
  55
  56 4. New architectures must implement all the features all over again, and
  57 sometimes in subtle different ways. This places an unfair burden on getting
  58 a new architecture fully functional and running with U-Boot.
  59
  60 5. While it is a bit of a tricky change, I believe it is worthwhile and
  61 achievable. There is no requirement that all code be common, only that
  62 the code that is common should be located in common/board.c rather than
  63 arch/xxx/lib/board.c.
  64
  65 All the functions of board_init_f() and board_init_r() are broken into
  66 separate function calls so that they can easily be included or excluded
  67 for a particular architecture. It also makes it easier to adopt Graeme's
  68 initcall proposal when it is ready.
  69
  70 http://lists.denx.de/pipermail/u-boot/2012-January/114499.html
  71
  72 This series removes the dependency on generic relocation. So relocation
  73 happens as one big chunk and is still completely arch-specific. See the
  74 relocation series for a proposed solution to this for ARM:
  75
  76 http://lists.denx.de/pipermail/u-boot/2011-December/112928.html
  77
  78 or Graeme's recent x86 series v2:
  79
  80 http://lists.denx.de/pipermail/u-boot/2012-January/114467.html
  81
  82 Instead of moving over a whole architecture, this series takes the approach
  83 of simply enabling generic board support for an architecture. It is then up
  84 to each board to opt in by defining CONFIG_SYS_GENERIC_BOARD in the board
  85 config file. If this is not done, then the code will be generated as
  86 before. This allows both sets of code to co-exist until we are comfortable
  87 with the generic approach, and enough boards run.
  88
  89 ARM is a relatively large board.c file and one which I can test, therefore
  90 I think it is a good target for this series. On the other hand, x86 is
  91 relatively small and simple, but different enough that it introduces a
  92 few issues to be solved. So I have chosen both ARM and x86 for this series.
  93 After a suggestion from Wolfgang I have added PPC also. This is the
  94 largest and most feature-full board, so hopefully we have all bases
  95 covered in this RFC.
  96
  97 A generic global_data structure is also required. This might upset a few
  98 people. Here is my basic reasoning: most fields are the same, all
  99 architectures include and need it, most global_data.h files already have
 100 #ifdefs to select fields for a particular SOC, so it is hard to
 101 see why architecures are different in this area. We can perhaps add a
 102 way to put architecture-specific fields into a separate header file, but
 103 for now I have judged that to be counter-productive.
 104
 105 Similarly we need a generic bd_info structure, since generic code will
 106 be accessing it. I have done this in the same way as global_data and the
 107 same comments apply.
 108
 109 There was dicussion on the list about passing gd_t around as a parameter
 110 to pre-relocation init functions. I think this makes sense, but it can
 111 be done as a separate change, and this series does not require it.
 112
 113 While this series needs to stand on its own (as with the link script
 114 cleanup series and the generic relocation series) the goal is the
 115 unification of the board init code. So I hope we can address issues with
 116 this in mind, rather than focusing too narrowly on particular ARM, x86 or
 117 PPC issues.
 118
 119 I have run-tested ARM on Tegra Seaboard only. To try it out, define
 120 CONFIG_SYS_GENERIC_BOARD in your board file and rebuild. Most likely on
 121 x86 and PPC at least it will hang, but if you are lucky it will print
 122 something first :-)
 123
 124 I have run this though MAKEALL with CONFIG_SYS_GENERIC_BOARD on for all
 125 ARM, PPC and x86 boards. There are a few failures due to errors in
 126 the board config, which I have sent patches for. The main issue is
 127 just the difference between __bss_end and __bss_end__.
 128
 129 Note: the first group of commits are required for this series to build,
 130 but could be separated out if required. I have included them here for
 131 convenience.
 132
 133 ------------->8--
 134
 135 Simon Glass, sjg@chromium.org
 136 March 2014
 137 Updated after final removal, May 2016