doc/README.generic-board - manifest_repos/bootloader - Git at Google

 #
 # (C) Copyright 2014 Google, Inc
 # Simon Glass <sjg@chromium.org>
 #
 # SPDX-License-Identifier:	GPL-2.0+
 #

 DEPRECATION NOTICE FOR arch/<arch>/lib/board.c

 For board maintainers: Please submit patches for boards you maintain before
 July 2014, to make them use generic board.

 For architecture maintainers: Please submit patches to remove your
 architecture-specific board.c file before October 2014.


 Background
 ----------

 U-Boot has traditionally had a board.c file for each architecture. This has
 introduced quite a lot of duplication, with each architecture tending to do
 initialisation slightly differently. To address this, a new 'generic board
 init' feature was introduced a year ago in March 2013 (further motivation is
 provided in the cover letter below).


 What has changed?
 -----------------

 The main change is that the arch/<arch>/lib/board.c file is being removed in
 favour of common/board_f.c (for pre-relocation init) and common/board_r.c
 (for post-relocation init).

 Related to this, the global_data and bd_t structures now have a core set of
 fields which are common to all architectures. Architecture-specific fields
 have been moved to separate structures.


 Supported Architectures
 ------------------------

 If you are unlucky then your architecture may not support generic board.
 The following architectures are supported now:

    arc
    arm
    avr32
    blackfin
    m68k
    microblaze
    mips
    nios2
    powerpc
    sandbox
    x86

 If your architecture is not supported, you need to select
 HAVE_GENERIC_BOARD in arch/Kconfig
 and test it with a suitable board, as follows.


 Adding Support for your Board
 -----------------------------

 To enable generic board for your board, define CONFIG_SYS_GENERIC_BOARD in
 your board config header file.

 Test that U-Boot still functions correctly on your board, and fix any
 problems you find. Don't be surprised if there are no problems - generic
 board has had a reasonable amount of testing with common boards.


 DeadLine
 --------

 Please don't take this the wrong way - there is no intent to make your life
 miserable, and we have the greatest respect and admiration for U-Boot users.
 However, with any migration there has to be a period where the old way is
 deprecated and removed. Every patch to the deprecated code introduces a
 potential breakage in the new unused code. Therefore:

 Boards or architectures not converted over to general board by the
 end of 2014 may be forcibly changed over (potentially causing run-time
 breakage) or removed.


 Further Background
 ------------------

 The full text of the original generic board series is reproduced below.

 --8<-------------

 This series creates a generic board.c implementation which contains
 the essential functions of the major arch/xxx/lib/board.c files.

 What is the motivation for this change?

 1. There is a lot of repeated code in the board.c files. Any change to
 things like setting up the baud rate requires a change in 10 separate
 places.

 2. Since there are 10 separate files, adding a new feature which requires
 initialisation is painful since it must be independently added in 10
 places.

 3. As time goes by the architectures naturally diverge since there is limited
 pressure to compare features or even CONFIG options against similar things
 in other board.c files.

 4. New architectures must implement all the features all over again, and
 sometimes in subtle different ways. This places an unfair burden on getting
 a new architecture fully functional and running with U-Boot.

 5. While it is a bit of a tricky change, I believe it is worthwhile and
 achievable. There is no requirement that all code be common, only that
 the code that is common should be located in common/board.c rather than
 arch/xxx/lib/board.c.

 All the functions of board_init_f() and board_init_r() are broken into
 separate function calls so that they can easily be included or excluded
 for a particular architecture. It also makes it easier to adopt Graeme's
 initcall proposal when it is ready.

 http://lists.denx.de/pipermail/u-boot/2012-January/114499.html

 This series removes the dependency on generic relocation. So relocation
 happens as one big chunk and is still completely arch-specific. See the
 relocation series for a proposed solution to this for ARM:

 http://lists.denx.de/pipermail/u-boot/2011-December/112928.html

 or Graeme's recent x86 series v2:

 http://lists.denx.de/pipermail/u-boot/2012-January/114467.html

 Instead of moving over a whole architecture, this series takes the approach
 of simply enabling generic board support for an architecture. It is then up
 to each board to opt in by defining CONFIG_SYS_GENERIC_BOARD in the board
 config file. If this is not done, then the code will be generated as
 before. This allows both sets of code to co-exist until we are comfortable
 with the generic approach, and enough boards run.

 ARM is a relatively large board.c file and one which I can test, therefore
 I think it is a good target for this series. On the other hand, x86 is
 relatively small and simple, but different enough that it introduces a
 few issues to be solved. So I have chosen both ARM and x86 for this series.
 After a suggestion from Wolfgang I have added PPC also. This is the
 largest and most feature-full board, so hopefully we have all bases
 covered in this RFC.

 A generic global_data structure is also required. This might upset a few
 people. Here is my basic reasoning: most fields are the same, all
 architectures include and need it, most global_data.h files already have
 #ifdefs to select fields for a particular SOC, so it is hard to
 see why architecures are different in this area. We can perhaps add a
 way to put architecture-specific fields into a separate header file, but
 for now I have judged that to be counter-productive.

 Similarly we need a generic bd_info structure, since generic code will
 be accessing it. I have done this in the same way as global_data and the
 same comments apply.

 There was dicussion on the list about passing gd_t around as a parameter
 to pre-relocation init functions. I think this makes sense, but it can
 be done as a separate change, and this series does not require it.

 While this series needs to stand on its own (as with the link script
 cleanup series and the generic relocation series) the goal is the
 unification of the board init code. So I hope we can address issues with
 this in mind, rather than focusing too narrowly on particular ARM, x86 or
 PPC issues.

 I have run-tested ARM on Tegra Seaboard only. To try it out, define
 CONFIG_SYS_GENERIC_BOARD in your board file and rebuild. Most likely on
 x86 and PPC at least it will hang, but if you are lucky it will print
 something first :-)

 I have run this though MAKEALL with CONFIG_SYS_GENERIC_BOARD on for all
 ARM, PPC and x86 boards. There are a few failures due to errors in
 the board config, which I have sent patches for. The main issue is
 just the difference between __bss_end and __bss_end__.

 Note: the first group of commits are required for this series to build,
 but could be separated out if required. I have included them here for
 convenience.

 ------------->8--

 Simon Glass, sjg@chromium.org
 March 2014
	#
	# (C) Copyright 2014 Google, Inc
	# Simon Glass <sjg@chromium.org>
	#
	# SPDX-License-Identifier: GPL-2.0+
	#

	DEPRECATION NOTICE FOR arch/<arch>/lib/board.c

	For board maintainers: Please submit patches for boards you maintain before
	July 2014, to make them use generic board.

	For architecture maintainers: Please submit patches to remove your
	architecture-specific board.c file before October 2014.


	Background
	----------

	U-Boot has traditionally had a board.c file for each architecture. This has
	introduced quite a lot of duplication, with each architecture tending to do
	initialisation slightly differently. To address this, a new 'generic board
	init' feature was introduced a year ago in March 2013 (further motivation is
	provided in the cover letter below).


	What has changed?
	-----------------

	The main change is that the arch/<arch>/lib/board.c file is being removed in
	favour of common/board_f.c (for pre-relocation init) and common/board_r.c
	(for post-relocation init).

	Related to this, the global_data and bd_t structures now have a core set of
	fields which are common to all architectures. Architecture-specific fields
	have been moved to separate structures.


	Supported Architectures
	------------------------

	If you are unlucky then your architecture may not support generic board.
	The following architectures are supported now:

	arc
	arm
	avr32
	blackfin
	m68k
	microblaze
	mips
	nios2
	powerpc
	sandbox
	x86

	If your architecture is not supported, you need to select
	HAVE_GENERIC_BOARD in arch/Kconfig
	and test it with a suitable board, as follows.


	Adding Support for your Board
	-----------------------------

	To enable generic board for your board, define CONFIG_SYS_GENERIC_BOARD in
	your board config header file.

	Test that U-Boot still functions correctly on your board, and fix any
	problems you find. Don't be surprised if there are no problems - generic
	board has had a reasonable amount of testing with common boards.


	DeadLine
	--------

	Please don't take this the wrong way - there is no intent to make your life
	miserable, and we have the greatest respect and admiration for U-Boot users.
	However, with any migration there has to be a period where the old way is
	deprecated and removed. Every patch to the deprecated code introduces a
	potential breakage in the new unused code. Therefore:

	Boards or architectures not converted over to general board by the
	end of 2014 may be forcibly changed over (potentially causing run-time
	breakage) or removed.



	Further Background
	------------------

	The full text of the original generic board series is reproduced below.

	--8<-------------

	This series creates a generic board.c implementation which contains
	the essential functions of the major arch/xxx/lib/board.c files.

	What is the motivation for this change?

	1. There is a lot of repeated code in the board.c files. Any change to
	things like setting up the baud rate requires a change in 10 separate
	places.

	2. Since there are 10 separate files, adding a new feature which requires
	initialisation is painful since it must be independently added in 10
	places.

	3. As time goes by the architectures naturally diverge since there is limited
	pressure to compare features or even CONFIG options against similar things
	in other board.c files.

	4. New architectures must implement all the features all over again, and
	sometimes in subtle different ways. This places an unfair burden on getting
	a new architecture fully functional and running with U-Boot.

	5. While it is a bit of a tricky change, I believe it is worthwhile and
	achievable. There is no requirement that all code be common, only that
	the code that is common should be located in common/board.c rather than
	arch/xxx/lib/board.c.

	All the functions of board_init_f() and board_init_r() are broken into
	separate function calls so that they can easily be included or excluded
	for a particular architecture. It also makes it easier to adopt Graeme's
	initcall proposal when it is ready.

	http://lists.denx.de/pipermail/u-boot/2012-January/114499.html

	This series removes the dependency on generic relocation. So relocation
	happens as one big chunk and is still completely arch-specific. See the
	relocation series for a proposed solution to this for ARM:

	http://lists.denx.de/pipermail/u-boot/2011-December/112928.html

	or Graeme's recent x86 series v2:

	http://lists.denx.de/pipermail/u-boot/2012-January/114467.html

	Instead of moving over a whole architecture, this series takes the approach
	of simply enabling generic board support for an architecture. It is then up
	to each board to opt in by defining CONFIG_SYS_GENERIC_BOARD in the board
	config file. If this is not done, then the code will be generated as
	before. This allows both sets of code to co-exist until we are comfortable
	with the generic approach, and enough boards run.

	ARM is a relatively large board.c file and one which I can test, therefore
	I think it is a good target for this series. On the other hand, x86 is
	relatively small and simple, but different enough that it introduces a
	few issues to be solved. So I have chosen both ARM and x86 for this series.
	After a suggestion from Wolfgang I have added PPC also. This is the
	largest and most feature-full board, so hopefully we have all bases
	covered in this RFC.

	A generic global_data structure is also required. This might upset a few
	people. Here is my basic reasoning: most fields are the same, all
	architectures include and need it, most global_data.h files already have
	#ifdefs to select fields for a particular SOC, so it is hard to
	see why architecures are different in this area. We can perhaps add a
	way to put architecture-specific fields into a separate header file, but
	for now I have judged that to be counter-productive.

	Similarly we need a generic bd_info structure, since generic code will
	be accessing it. I have done this in the same way as global_data and the
	same comments apply.

	There was dicussion on the list about passing gd_t around as a parameter
	to pre-relocation init functions. I think this makes sense, but it can
	be done as a separate change, and this series does not require it.

	While this series needs to stand on its own (as with the link script
	cleanup series and the generic relocation series) the goal is the
	unification of the board init code. So I hope we can address issues with
	this in mind, rather than focusing too narrowly on particular ARM, x86 or
	PPC issues.

	I have run-tested ARM on Tegra Seaboard only. To try it out, define
	CONFIG_SYS_GENERIC_BOARD in your board file and rebuild. Most likely on
	x86 and PPC at least it will hang, but if you are lucky it will print
	something first :-)

	I have run this though MAKEALL with CONFIG_SYS_GENERIC_BOARD on for all
	ARM, PPC and x86 boards. There are a few failures due to errors in
	the board config, which I have sent patches for. The main issue is
	just the difference between __bss_end and __bss_end__.

	Note: the first group of commits are required for this series to build,
	but could be separated out if required. I have included them here for
	convenience.

	------------->8--

	Simon Glass, sjg@chromium.org
	March 2014