u-boot README翻译

# SPDX-License-Identifier: GPL-2.0+
#
# (C) Copyright 2000 - 2013
# Wolfgang Denk, DENX Software Engineering, wd@denx.de.

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.

• 这个目录包含了U-Boot的源代码，一个为基于PowerPC,ARM,MIPS和几种其他处理器的嵌入式开发板的Boot引导程序，这个程序可以被安装在Boot ROM中，用来初始化或测试硬件或者用来下载和运行应用程序。

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.

• U-Boot的发展是跟Linux息息相关的：源代码的一些内容来源于Linux源码树，我们有一些通用的头文件，已经为支持引导Linux镜像做了一些准备。

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.

• 我们已经花费了好多精力，使这个程序更容易被配置和扩展。例如，所有的monitor 命令可以使用相同的接口来执行，因此添加新的命令是很容易的事。同时，这个程序没有一直都包含很少使用的一些代码，你可以动态地加载和运行那些很少使用的代码；

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.

• 总的说来，那些在Makefile中存在的配置项在某种程度上已经被测试过，可以认为它们都是有效的。事实上，这些配置好多都在生产系统上使用。

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.

• 如果有什么问题，可以查看CHANGELOG文件，可以找出谁为某个特定的接口做出过贡献。此外，。。。。。省略了，哈哈哈哈。

Where to get help

从哪里获得帮助

Where to get source code

从哪里获得源代码

Where we come from

我们来自哪里

Names and Spelling

名字和拼写

Versioning

版本说明

Directory Hierarchy

目录等级

Software Configuration

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

• 配置通常通过C预处理器定义来完成；使用这种方法的根本原因就是为了尽可能的减少dead代码；

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_".

• 有两类配置变量：

  *配置 OPTIONS：
  这些是由用户自行选择的，有好多名称都是由"CONFIG_"打头；

  *配置 SETTINGS：
  这些取决于硬件。如果你不知道你在做什么的话，最好别乱动这些配置；他们的名称由"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.

• 以前，所有的配置都是手动完成的，需要手动去创建符号链接，编辑配置文件。最近以来，U-boot已经把Linux内核中使用的Kbuild 结构加入进来，允许你使用“make menuconfig”命令来配置你的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.

• 对于所有已经支持的板子，U-boot已经有可以使用的默认配置；只需要键入"make <board_name>_defconfig"就可以进行配置；

例如：对于使用TQM823L模块：
cd u-boot
make TQM823L_defconfig

注意：如果你正在寻找一款板子的默认配置文件，并且你确定过去是存在的，但现在消失了，你需要阅读doc/README文件，那里有当前U-boot不再支持板子的清单；

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 doc/arch/index.rst for more details.

• U-boot能够被创建并在使用了sandbox的Linux主机上运行。这允许可以不满足U-boot运行的板子或架构，而使用sandbox运行U-boot。Sandbox也被用来做一些U-boot的测试。

• 查看doc/arch/index.rst来获得更多细节。

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).

• 这是一个为板子设计好的启动流程。这个流程应当在SPL和U-boot中被正确的使用；

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

• 注意：“SPL”表示“Secondary Program Loader”，这个将在本文中稍后进行详细解释；

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.

• 目前，SPL大多使用一个分离的代码路径,但是函数名称和每个函数的作用都是一样的。有些板子或架构也许不遵守这个规则。但是，至少在大多数使用CONFIG_SPL_FRAMEWORK的ARM开发板上，是遵从这个规则的。

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

• 程序运行通常从某个架构（某个处理器）的start.S文件开始，例如：
  • 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

• lowlevel_init():
• • 目的：必要的初始化来允许执行到board_init_f()
• • 没有全局数据或者BSS
• • 没有堆栈
• • 禁止设置堆栈或者使用控制台
• • 只做一些最小的来执行到board_init_f()
• • 这个总是不是必须的
• • 从这个函数正常返回

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

• board_init_f():
• 目的：设施机器准备好运行board_init_r()，例如SDRAM和串口；
• 可以使用全局数据
• 堆栈在SRAM里
• BSS还不可用，因此你不能使用全局或静态变量，只允许使用堆栈变量和全局数据

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

• Non-SPL-specific notes:
• 调用dram_init()来设置DRAM。如果在SPL中已经完成，就什么也不要做；

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
   - for specific scenarios on certain architectures an early BSS *can*
     be made available (via CONFIG_SPL_EARLY_BSS by moving the clearing
     of BSS prior to entering board_init_f()) but doing so is discouraged.
     Instead it is strongly recommended to architect any code changes
     or additions such to not depend on the availability of BSS during
     board_init_f() as indicated in other sections of this README to
     maintain compatibility and consistency across the entire code base.
   - must return normally from this function (don't call board_init_r()
   	directly)

• SPL-specific notes:
• 你可以忽略掉整个的board_init_f()函数，可以使用你自己的版本，如果有需要；
• 在万不得已的情况下，可以调用preloader_console_init()
• 应当设置 SDRAM，做一些设置让串口工作
• 没有必要清除，清除操作会由crt0.S完成
• 从这个函数必须正常的返回(不要直接调用call board_init_r())

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.

这里，BSS被清除。对于SPL，如果CONFIG_SPL_STACK_R被定义，那么在这个点上，堆栈和全局数据被重定位到CONFIG_SPL_STACK_R_ADDR下。对于non-SPL，U-boot被重定位到内存的顶端运行。

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()

• 目的：主要的执行程序，通用的代码
• 全局数据可以使用
• SDRAM可以使用
• BSS可以使用，所有的静态或全局变量都可以使用
• 执行最终会进入到main_loop()

Non-SPL-specific notes:
   - U-Boot is relocated to the top of memory and is now running from
   	there.

• Non-SPL-specific notes:
• U-Boot被重定位到内存顶端，并从这里开始运行

   SPL-specific notes:
   - stack is optionally in SDRAM, if CONFIG_SPL_STACK_R is defined and
   	CONFIG_SPL_STACK_R_ADDR points into SDRAM
   - preloader_console_init() can be called here - typically this is
   	done by selecting CONFIG_SPL_BOARD_INIT and then supplying a
   	spl_board_init() function containing this call
   - loads U-Boot or (in falcon mode) Linux

• SPL-specific notes：
• 可以在SDRAM中操作堆栈，如果定义了CONFIG_SPL_STACK_R，CONFIG_SPL_STACK_R_ADDR指向SDRAM。
• 在这里可以调用preloader_console_init()——通常这都是由选择CONFIG_SPL_BOARD_INIT，并且提供一个函数spl_board_init()来完成的
• 装在U-Boot或者Linux

Configuration

Configuration depends on the combination of board and CPU type; all
such information is kept in a configuration file
"include/configs/<board_name>.h".

• 配置取决于板子和CPU类型；所有的这些信息都被保存在一个配置文件里——“include/configs/<board_name>.h”

Example: For a TQM823L module, all configuration settings are in
"include/configs/TQM823L.h".

• 例如：对一块TQM823L板子来说，所有的配置设置都在"include/configs/TQM823L.h"文件里；

Many of the options are named exactly as the corresponding Linux
kernel configuration options. The intention is to make it easier to
build a config tool - later.

• 许多操作的命名完全和Linux内核配置操作一致。其目的是为了更容易的创建配置工具。

Board initialization settings

During Initialization u-boot calls a number of board specific functions
to allow the preparation of board specific prerequisites, e.g. pin setup
before drivers are initialized. To enable these callbacks the
following configuration macros have to be defined. Currently this is
architecture specific, so please check arch/your_architecture/lib/board.c
typically in board_init_f() and board_init_r().

Configuration Settings

Low Level (hardware related) configuration options

Freescale QE/FMAN Firmware Support

Freescale Layerscape Management Complex Firmware Support

Freescale Layerscape Debug Server Support

Reproducible builds

Building the Software

Testing of U-Boot Modifications, Ports to New Hardware, etc.

Monitor Commands - Overview

Monitor Commands - Detailed Description

Environment Variables