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