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