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