(C) Copyright 2000 - 2013

Wolfgang Denk, DENX Software Engineering, wd@denx.de.

SPDX-License-Identifier: GPL-2.0+

Summary:

This directory contains the source code for U-Boot, a boot loader for Embedded boards based on PowerPC, ARM, MIPS and several other processors, which can be installed in a boot ROM and used to initialize and test the hardware or to download and run application code.

The development of U-Boot is closely related to Linux: some parts of the source code originate in the Linux source tree, we have some header files in common, and special provision has been made to support booting of Linux images.

Some attention has been paid to make this software easily configurable and extendable. For instance, all monitor commands are implemented with the same call interface, so that it's very easy to add new commands. Also, instead of permanently adding rarely used code (for instance hardware test utilities) to the monitor, you can load and run it dynamically.

Status:

In general, all boards for which a configuration option exists in the Makefile have been tested to some extent and can be considered "working". In fact, many of them are used in production systems.

In case of problems see the CHANGELOG file to find out who contributed the specific port. In addition, there are various MAINTAINERS files scattered throughout the U-Boot source identifying the people or companies responsible for various boards and subsystems.

Note: As of August, 2010, there is no longer a CHANGELOG file in the actual U-Boot source tree; however, it can be created dynamically from the Git log using:

make CHANGELOG

Where to get help:

In case you have questions about, problems with or contributions for U-Boot, you should send a message to the U-Boot mailing list at u-boot@lists.denx.de. There is also an archive of previous traffic on the mailing list - please search the archive before asking FAQ's. Please see http://lists.denx.de/pipermail/u-boot and http://dir.gmane.org/gmane.comp.boot-loaders.u-boot

Where to get source code:

The U-Boot source code is maintained in the Git repository at git://www.denx.de/git/u-boot.git ; you can browse it online at http://www.denx.de/cgi-bin/gitweb.cgi?p=u-boot.git;a=summary

The "snapshot" links on this page allow you to download tarballs of any version you might be interested in. Official releases are also available for FTP download from the ftp://ftp.denx.de/pub/u-boot/ directory.

Pre-built (and tested) images are available from ftp://ftp.denx.de/pub/u-boot/images/

Where we come from:

• start from 8xxrom sources
• create PPCBoot project (http://sourceforge.net/projects/ppcboot)
• clean up code
• make it easier to add custom boards
• make it possible to add other [PowerPC] CPUs
• extend functions, especially:
  • Provide extended interface to Linux boot loader
  • S-Record download
  • network boot
  • PCMCIA / CompactFlash / ATA disk / SCSI ... boot
• create ARMBoot project (http://sourceforge.net/projects/armboot)
• add other CPU families (starting with ARM)
• create U-Boot project (http://sourceforge.net/projects/u-boot)
• current project page: see http://www.denx.de/wiki/U-Boot

Names and Spelling:

The "official" name of this project is "Das U-Boot". The spelling "U-Boot" shall be used in all written text (documentation, comments in source files etc.). Example:

This is the README file for the U-Boot project.

File names etc. shall be based on the string "u-boot". Examples:

include/asm-ppc/u-boot.h

#include <asm/u-boot.h>

Variable names, preprocessor constants etc. shall be either based on the string "u_boot" or on "U_BOOT". Example:

U_BOOT_VERSION		u_boot_logo
IH_OS_U_BOOT		u_boot_hush_start

Versioning:

Starting with the release in October 2008, the names of the releases were changed from numerical release numbers without deeper meaning into a time stamp based numbering. Regular releases are identified by names consisting of the calendar year and month of the release date. Additional fields (if present) indicate release candidates or bug fix releases in "stable" maintenance trees.

Examples: U-Boot v2009.11 - Release November 2009 U-Boot v2009.11.1 - Release 1 in version November 2009 stable tree U-Boot v2010.09-rc1 - Release candidate 1 for September 2010 release

Directory Hierarchy:

/arch Architecture specific files /arc Files generic to ARC architecture /arm Files generic to ARM architecture /m68k Files generic to m68k architecture /microblaze Files generic to microblaze architecture /mips Files generic to MIPS architecture /nds32 Files generic to NDS32 architecture /nios2 Files generic to Altera NIOS2 architecture /openrisc Files generic to OpenRISC architecture /powerpc Files generic to PowerPC architecture /sandbox Files generic to HW-independent "sandbox" /sh Files generic to SH architecture /x86 Files generic to x86 architecture /api Machine/arch independent API for external apps /board Board dependent files /cmd U-Boot commands functions /common Misc architecture independent functions /configs Board default configuration files /disk Code for disk drive partition handling /doc Documentation (don't expect too much) /drivers Commonly used device drivers /dts Contains Makefile for building internal U-Boot fdt. /examples Example code for standalone applications, etc. /fs Filesystem code (cramfs, ext2, jffs2, etc.) /include Header Files /lib Library routines generic to all architectures /Licenses Various license files /net Networking code /post Power On Self Test /scripts Various build scripts and Makefiles /test Various unit test files /tools Tools to build S-Record or U-Boot images, etc.

Software Configuration:

Configuration is usually done using C preprocessor defines; the rationale behind that is to avoid dead code whenever possible.

There are two classes of configuration variables:

• Configuration OPTIONS: These are selectable by the user and have names beginning with "CONFIG_".

• Configuration SETTINGS: These depend on the hardware etc. and should not be meddled with if you don't know what you're doing; they have names beginning with "CONFIG_SYS_".

Previously, all configuration was done by hand, which involved creating symbolic links and editing configuration files manually. More recently, U-Boot has added the Kbuild infrastructure used by the Linux kernel, allowing you to use the "make menuconfig" command to configure your build.

Selection of Processor Architecture and Board Type:

For all supported boards there are ready-to-use default configurations available; just type "make <board_name>_defconfig".

Example: For a TQM823L module type:

cd u-boot
make TQM823L_defconfig

Note: If you're looking for the default configuration file for a board you're sure used to be there but is now missing, check the file doc/README.scrapyard for a list of no longer supported boards.

Sandbox Environment:

U-Boot can be built natively to run on a Linux host using the 'sandbox' board. This allows feature development which is not board- or architecture- specific to be undertaken on a native platform. The sandbox is also used to run some of U-Boot's tests.

See board/sandbox/README.sandbox for more details.

Board Initialisation Flow:

This is the intended start-up flow for boards. This should apply for both SPL and U-Boot proper (i.e. they both follow the same rules).

Note: "SPL" stands for "Secondary Program Loader," which is explained in more detail later in this file.

At present, SPL mostly uses a separate code path, but the function names and roles of each function are the same. Some boards or architectures may not conform to this. At least most ARM boards which use CONFIG_SPL_FRAMEWORK conform to this.

Execution typically starts with an architecture-specific (and possibly CPU-specific) start.S file, such as:

- arch/arm/cpu/armv7/start.S
- arch/powerpc/cpu/mpc83xx/start.S
- arch/mips/cpu/start.S

and so on. From there, three functions are called; the purpose and limitations of each of these functions are described below.

lowlevel_init(): - purpose: essential init to permit execution to reach board_init_f() - no global_data or BSS - there is no stack (ARMv7 may have one but it will soon be removed) - must not set up SDRAM or use console - must only do the bare minimum to allow execution to continue to board_init_f() - this is almost never needed - return normally from this function

board_init_f(): - purpose: set up the machine ready for running board_init_r(): i.e. SDRAM and serial UART - global_data is available - stack is in SRAM - BSS is not available, so you cannot use global/static variables, only stack variables and global_data

Non-SPL-specific notes:
- dram_init() is called to set up DRAM. If already done in SPL this
	can do nothing

SPL-specific notes:
- you can override the entire board_init_f() function with your own
	version as needed.
- preloader_console_init() can be called here in extremis
- should set up SDRAM, and anything needed to make the UART work
- these is no need to clear BSS, it will be done by crt0.S
- must return normally from this function (don't call board_init_r()
	directly)

Here the BSS is cleared. For SPL, if CONFIG_SPL_STACK_R is defined, then at this point the stack and global_data are relocated to below CONFIG_SPL_STACK_R_ADDR. For non-SPL, U-Boot is relocated to run at the top of memory.

board_init_r(): - purpose: main execution, common code - global_data is available - SDRAM is available - BSS is available, all static/global variables can be used - execution eventually continues to main_loop()

Non-SPL-sp