README

- CONFIG_SYS_SIUMCR:	SIU Module Configuration (11-6)

- CONFIG_SYS_SYPCR:	System Protection Control (11-9)

- CONFIG_SYS_TBSCR:	Time Base Status and Control (11-26)

- CONFIG_SYS_PISCR:	Periodic Interrupt Status and Control (11-31)

- CONFIG_SYS_PLPRCR:	PLL, Low-Power, and Reset Control Register (15-30)

- CONFIG_SYS_SCCR:	System Clock and reset Control Register (15-27)

- CONFIG_SYS_OR_TIMING_SDRAM:
		SDRAM timing

- CONFIG_SYS_MAMR_PTA:
		periodic timer for refresh

- CONFIG_SYS_DER:	Debug Event Register (37-47)

- FLASH_BASE0_PRELIM, FLASH_BASE1_PRELIM, CONFIG_SYS_REMAP_OR_AM,
  CONFIG_SYS_PRELIM_OR_AM, CONFIG_SYS_OR_TIMING_FLASH, CONFIG_SYS_OR0_REMAP,
  CONFIG_SYS_OR0_PRELIM, CONFIG_SYS_BR0_PRELIM, CONFIG_SYS_OR1_REMAP, CONFIG_SYS_OR1_PRELIM,
  CONFIG_SYS_BR1_PRELIM:
		Memory Controller Definitions: BR0/1 and OR0/1 (FLASH)

- SDRAM_BASE2_PRELIM, SDRAM_BASE3_PRELIM, SDRAM_MAX_SIZE,
  CONFIG_SYS_OR_TIMING_SDRAM, CONFIG_SYS_OR2_PRELIM, CONFIG_SYS_BR2_PRELIM,
  CONFIG_SYS_OR3_PRELIM, CONFIG_SYS_BR3_PRELIM:
		Memory Controller Definitions: BR2/3 and OR2/3 (SDRAM)

- CONFIG_SYS_MAMR_PTA, CONFIG_SYS_MPTPR_2BK_4K, CONFIG_SYS_MPTPR_1BK_4K, CONFIG_SYS_MPTPR_2BK_8K,
  CONFIG_SYS_MPTPR_1BK_8K, CONFIG_SYS_MAMR_8COL, CONFIG_SYS_MAMR_9COL:
		Machine Mode Register and Memory Periodic Timer
		Prescaler definitions (SDRAM timing)

- CONFIG_SYS_I2C_UCODE_PATCH, CONFIG_SYS_I2C_DPMEM_OFFSET [0x1FC0]:
		enable I2C microcode relocation patch (MPC8xx);
		define relocation offset in DPRAM [DSP2]

- CONFIG_SYS_SMC_UCODE_PATCH, CONFIG_SYS_SMC_DPMEM_OFFSET [0x1FC0]:
		enable SMC microcode relocation patch (MPC8xx);
		define relocation offset in DPRAM [SMC1]

- CONFIG_SYS_SPI_UCODE_PATCH, CONFIG_SYS_SPI_DPMEM_OFFSET [0x1FC0]:
		enable SPI microcode relocation patch (MPC8xx);
		define relocation offset in DPRAM [SCC4]

- CONFIG_SYS_USE_OSCCLK:
		Use OSCM clock mode on MBX8xx board. Be careful,
		wrong setting might damage your board. Read
		doc/README.MBX before setting this variable!

- CONFIG_SYS_CPM_POST_WORD_ADDR: (MPC8xx, MPC8260 only)
		Offset of the bootmode word in DPRAM used by post
		(Power On Self Tests). This definition overrides
		#define'd default value in commproc.h resp.
		cpm_8260.h.

- CONFIG_SYS_PCI_SLV_MEM_LOCAL, CONFIG_SYS_PCI_SLV_MEM_BUS, CONFIG_SYS_PICMR0_MASK_ATTRIB,
  CONFIG_SYS_PCI_MSTR0_LOCAL, CONFIG_SYS_PCIMSK0_MASK, CONFIG_SYS_PCI_MSTR1_LOCAL,
  CONFIG_SYS_PCIMSK1_MASK, CONFIG_SYS_PCI_MSTR_MEM_LOCAL, CONFIG_SYS_PCI_MSTR_MEM_BUS,
  CONFIG_SYS_CPU_PCI_MEM_START, CONFIG_SYS_PCI_MSTR_MEM_SIZE, CONFIG_SYS_POCMR0_MASK_ATTRIB,
  CONFIG_SYS_PCI_MSTR_MEMIO_LOCAL, CONFIG_SYS_PCI_MSTR_MEMIO_BUS, CPU_PCI_MEMIO_START,
  CONFIG_SYS_PCI_MSTR_MEMIO_SIZE, CONFIG_SYS_POCMR1_MASK_ATTRIB, CONFIG_SYS_PCI_MSTR_IO_LOCAL,
  CONFIG_SYS_PCI_MSTR_IO_BUS, CONFIG_SYS_CPU_PCI_IO_START, CONFIG_SYS_PCI_MSTR_IO_SIZE,
  CONFIG_SYS_POCMR2_MASK_ATTRIB: (MPC826x only)
		Overrides the default PCI memory map in arch/powerpc/cpu/mpc8260/pci.c if set.

- CONFIG_PCI_DISABLE_PCIE:
		Disable PCI-Express on systems where it is supported but not
		required.

- CONFIG_SYS_SRIO:
		Chip has SRIO or not

- CONFIG_SRIO1:
		Board has SRIO 1 port available

- CONFIG_SRIO2:
		Board has SRIO 2 port available

- CONFIG_SYS_SRIOn_MEM_VIRT:
		Virtual Address of SRIO port 'n' memory region

- CONFIG_SYS_SRIOn_MEM_PHYS:
		Physical Address of SRIO port 'n' memory region

- CONFIG_SYS_SRIOn_MEM_SIZE:
		Size of SRIO port 'n' memory region

- CONFIG_SYS_NDFC_16
		Defined to tell the NDFC that the NAND chip is using a
		16 bit bus.

- CONFIG_SYS_NDFC_EBC0_CFG
		Sets the EBC0_CFG register for the NDFC. If not defined
		a default value will be used.

- CONFIG_SPD_EEPROM
		Get DDR timing information from an I2C EEPROM. Common
		with pluggable memory modules such as SODIMMs

  SPD_EEPROM_ADDRESS
		I2C address of the SPD EEPROM

- CONFIG_SYS_SPD_BUS_NUM
		If SPD EEPROM is on an I2C bus other than the first
		one, specify here. Note that the value must resolve
		to something your driver can deal with.

- CONFIG_SYS_DDR_RAW_TIMING
		Get DDR timing information from other than SPD. Common with
		soldered DDR chips onboard without SPD. DDR raw timing
		parameters are extracted from datasheet and hard-coded into
		header files or board specific files.

- CONFIG_FSL_DDR_INTERACTIVE
		Enable interactive DDR debugging. See doc/README.fsl-ddr.

- CONFIG_SYS_83XX_DDR_USES_CS0
		Only for 83xx systems. If specified, then DDR should
		be configured using CS0 and CS1 instead of CS2 and CS3.

- CONFIG_ETHER_ON_FEC[12]
		Define to enable FEC[12] on a 8xx series processor.

- CONFIG_FEC[12]_PHY
		Define to the hardcoded PHY address which corresponds
		to the given FEC; i. e.
			#define CONFIG_FEC1_PHY 4
		means that the PHY with address 4 is connected to FEC1

		When set to -1, means to probe for first available.

- CONFIG_FEC[12]_PHY_NORXERR
		The PHY does not have a RXERR line (RMII only).
		(so program the FEC to ignore it).

- CONFIG_RMII
		Enable RMII mode for all FECs.
		Note that this is a global option, we can't
		have one FEC in standard MII mode and another in RMII mode.

- CONFIG_CRC32_VERIFY
		Add a verify option to the crc32 command.
		The syntax is:

		=> crc32 -v <address> <count> <crc32>

		Where address/count indicate a memory area
		and crc32 is the correct crc32 which the
		area should have.

- CONFIG_LOOPW
		Add the "loopw" memory command. This only takes effect if
		the memory commands are activated globally (CONFIG_CMD_MEM).

- CONFIG_MX_CYCLIC
		Add the "mdc" and "mwc" memory commands. These are cyclic
		"md/mw" commands.
		Examples:

		=> mdc.b 10 4 500
		This command will print 4 bytes (10,11,12,13) each 500 ms.

		=> mwc.l 100 12345678 10
		This command will write 12345678 to address 100 all 10 ms.

		This only takes effect if the memory commands are activated
		globally (CONFIG_CMD_MEM).

- CONFIG_SKIP_LOWLEVEL_INIT
		[ARM, NDS32, MIPS only] If this variable is defined, then certain
		low level initializations (like setting up the memory
		controller) are omitted and/or U-Boot does not
		relocate itself into RAM.

		Normally this variable MUST NOT be defined. The only
		exception is when U-Boot is loaded (to RAM) by some
		other boot loader or by a debugger which performs
		these initializations itself.

- CONFIG_SPL_BUILD
		Modifies the behaviour of start.S when compiling a loader
		that is executed before the actual U-Boot. E.g. when
		compiling a NAND SPL.

- CONFIG_USE_ARCH_MEMCPY
  CONFIG_USE_ARCH_MEMSET
		If these options are used a optimized version of memcpy/memset will
		be used if available. These functions may be faster under some
		conditions but may increase the binary size.

Building the Software:
======================

Building U-Boot has been tested in several native build environments
and in many different cross environments. Of course we cannot support
all possibly existing versions of cross development tools in all
(potentially obsolete) versions. In case of tool chain problems we
recommend to use the ELDK (see http://www.denx.de/wiki/DULG/ELDK)
which is extensively used to build and test U-Boot.

If you are not using a native environment, it is assumed that you
have GNU cross compiling tools available in your path. In this case,
you must set the environment variable CROSS_COMPILE in your shell.
Note that no changes to the Makefile or any other source files are
necessary. For example using the ELDK on a 4xx CPU, please enter:

	$ CROSS_COMPILE=ppc_4xx-
	$ export CROSS_COMPILE

Note: If you wish to generate Windows versions of the utilities in
      the tools directory you can use the MinGW toolchain
      (http://www.mingw.org).  Set your HOST tools to the MinGW
      toolchain and execute 'make tools'.  For example:

       $ make HOSTCC=i586-mingw32msvc-gcc HOSTSTRIP=i586-mingw32msvc-strip tools

      Binaries such as tools/mkimage.exe will be created which can
      be executed on computers running Windows.

U-Boot is intended to be simple to build. After installing the
sources you must configure U-Boot for one specific board type. This
is done by typing:

	make NAME_config

where "NAME_config" is the name of one of the existing configu-
rations; see the main Makefile for supported names.

Note: for some board special configuration names may exist; check if
      additional information is available from the board vendor; for
      instance, the TQM823L systems are available without (standard)
      or with LCD support. You can select such additional "features"
      when choosing the configuration, i. e.

      make TQM823L_config
	- will configure for a plain TQM823L, i. e. no LCD support

      make TQM823L_LCD_config
	- will configure for a TQM823L with U-Boot console on LCD

      etc.


Finally, type "make all", and you should get some working U-Boot
images ready for download to / installation on your system:

- "u-boot.bin" is a raw binary image
- "u-boot" is an image in ELF binary format
- "u-boot.srec" is in Motorola S-Record format

By default the build is performed locally and the objects are saved
in the source directory. One of the two methods can be used to change
this behavior and build U-Boot to some external directory:

1. Add O= to the make command line invocations:

	make O=/tmp/build distclean
	make O=/tmp/build NAME_config
	make O=/tmp/build all

2. Set environment variable BUILD_DIR to point to the desired location:

	export BUILD_DIR=/tmp/build
	make distclean
	make NAME_config
	make all

Note that the command line "O=" setting overrides the BUILD_DIR environment
variable.


Please be aware that the Makefiles assume you are using GNU make, so
for instance on NetBSD you might need to use "gmake" instead of
native "make".


If the system board that you have is not listed, then you will need
to port U-Boot to your hardware platform. To do this, follow these
steps:

1.  Add a new configuration option for your board to the toplevel
    "Makefile" and to the "MAKEALL" script, using the existing
    entries as examples. Note that here and at many other places
    boards and other names are listed in alphabetical sort order. Please
    keep this order.
2.  Create a new directory to hold your board specific code. Add any
    files you need. In your board directory, you will need at least
    the "Makefile", a "<board>.c", "flash.c" and "u-boot.lds".
3.  Create a new configuration file "include/configs/<board>.h" for
    your board
3.  If you're porting U-Boot to a new CPU, then also create a new
    directory to hold your CPU specific code. Add any files you need.
4.  Run "make <board>_config" with your new name.
5.  Type "make", and you should get a working "u-boot.srec" file
    to be installed on your target system.
6.  Debug and solve any problems that might arise.
    [Of course, this last step is much harder than it sounds.]


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

If you have modified U-Boot sources (for instance added a new board
or support for new devices, a new CPU, etc.) you are expected to
provide feedback to the other developers. The feedback normally takes
the form of a "patch", i. e. a context diff against a certain (latest
official or latest in the git repository) version of U-Boot sources.

But before you submit such a patch, please verify that your modifi-
cation did not break existing code. At least make sure that *ALL* of
the supported boards compile WITHOUT ANY compiler warnings. To do so,
just run the "MAKEALL" script, which will configure and build U-Boot
for ALL supported system. Be warned, this will take a while. You can
select which (cross) compiler to use by passing a `CROSS_COMPILE'
environment variable to the script, i. e. to use the ELDK cross tools
you can type

	CROSS_COMPILE=ppc_8xx- MAKEALL

or to build on a native PowerPC system you can type

	CROSS_COMPILE=' ' MAKEALL

When using the MAKEALL script, the default behaviour is to build
U-Boot in the source directory. This location can be changed by
setting the BUILD_DIR environment variable. Also, for each target
built, the MAKEALL script saves two log files (<target>.ERR and
<target>.MAKEALL) in the <source dir>/LOG directory. This default
location can be changed by setting the MAKEALL_LOGDIR environment
variable. For example:

	export BUILD_DIR=/tmp/build
	export MAKEALL_LOGDIR=/tmp/log
	CROSS_COMPILE=ppc_8xx- MAKEALL

With the above settings build objects are saved in the /tmp/build,
log files are saved in the /tmp/log and the source tree remains clean
during the whole build process.


See also "U-Boot Porting Guide" below.


Monitor Commands - Overview:
============================

go	- start application at address 'addr'
run	- run commands in an environment variable
bootm	- boot application image from memory
bootp	- boot image via network using BootP/TFTP protocol
tftpboot- boot image via network using TFTP protocol
	       and env variables "ipaddr" and "serverip"
	       (and eventually "gatewayip")
tftpput - upload a file via network using TFTP protocol
rarpboot- boot image via network using RARP/TFTP protocol
diskboot- boot from IDE devicebootd   - boot default, i.e., run 'bootcmd'
loads	- load S-Record file over serial line
loadb	- load binary file over serial line (kermit mode)
md	- memory display
mm	- memory modify (auto-incrementing)
nm	- memory modify (constant address)
mw	- memory write (fill)
cp	- memory copy
cmp	- memory compare
crc32	- checksum calculation
i2c	- I2C sub-system
sspi	- SPI utility commands
base	- print or set address offset
printenv- print environment variables
setenv	- set environment variables
saveenv - save environment variables to persistent storage
protect - enable or disable FLASH write protection
erase	- erase FLASH memory
flinfo	- print FLASH memory information
bdinfo	- print Board Info structure
iminfo	- print header information for application image
coninfo - print console devices and informations
ide	- IDE sub-system
loop	- infinite loop on address range
loopw	- infinite write loop on address range
mtest	- simple RAM test
icache	- enable or disable instruction cache
dcache	- enable or disable data cache
reset	- Perform RESET of the CPU
echo	- echo args to console
version - print monitor version
help	- print online help
?	- alias for 'help'


Monitor Commands - Detailed Description:
========================================

TODO.

For now: just type "help <command>".


Environment Variables:
======================

U-Boot supports user configuration using Environment Variables which
can be made persistent by saving to Flash memory.

Environment Variables are set using "setenv", printed using
"printenv", and saved to Flash using "saveenv". Using "setenv"
without a value can be used to delete a variable from the
environment. As long as you don't save the environment you are
working with an in-memory copy. In case the Flash area containing the
environment is erased by accident, a default environment is provided.

Some configuration options can be set using Environment Variables.

List of environment variables (most likely not complete):

  baudrate	- see CONFIG_BAUDRATE

  bootdelay	- see CONFIG_BOOTDELAY

  bootcmd	- see CONFIG_BOOTCOMMAND

  bootargs	- Boot arguments when booting an RTOS image

  bootfile	- Name of the image to load with TFTP

  bootm_low	- Memory range available for image processing in the bootm
		  command can be restricted. This variable is given as
		  a hexadecimal number and defines lowest address allowed
		  for use by the bootm command. See also "bootm_size"
		  environment variable. Address defined by "bootm_low" is
		  also the base of the initial memory mapping for the Linux
		  kernel -- see the description of CONFIG_SYS_BOOTMAPSZ and
		  bootm_mapsize.

  bootm_mapsize	- Size of the initial memory mapping for the Linux kernel.
		  This variable is given as a hexadecimal number and it
		  defines the size of the memory region starting at base
		  address bootm_low that is accessible by the Linux kernel
		  during early boot.  If unset, CONFIG_SYS_BOOTMAPSZ is used
		  as the default value if it is defined, and bootm_size is
		  used otherwise.

  bootm_size	- Memory range available for image processing in the bootm
		  command can be restricted. This variable is given as
		  a hexadecimal number and defines the size of the region
		  allowed for use by the bootm command. See also "bootm_low"
		  environment variable.

  updatefile	- Location of the software update file on a TFTP server, used
		  by the automatic software update feature. Please refer to
		  documentation in doc/README.update for more details.

  autoload	- if set to "no" (any string beginning with 'n'),
		  "bootp" will just load perform a lookup of the
		  configuration from the BOOTP server, but not try to
		  load any image using TFTP

  autostart	- if set to "yes", an image loaded using the "bootp",
		  "rarpboot", "tftpboot" or "diskboot" commands will
		  be automatically started (by internally calling
		  "bootm")

		  If set to "no", a standalone image passed to the
		  "bootm" command will be copied to the load address
		  (and eventually uncompressed), but NOT be started.
		  This can be used to load and uncompress arbitrary
		  data.

  fdt_high	- if set this restricts the maximum address that the
		  flattened device tree will be copied into upon boot.
		  If this is set to the special value 0xFFFFFFFF then
		  the fdt will not be copied at all on boot.  For this
		  to work it must reside in writable memory, have
		  sufficient padding on the end of it for u-boot to
		  add the information it needs into it, and the memory
		  must be accessible by the kernel.

  i2cfast	- (PPC405GP|PPC405EP only)
		  if set to 'y' configures Linux I2C driver for fast
		  mode (400kHZ). This environment variable is used in
		  initialization code. So, for changes to be effective
		  it must be saved and board must be reset.

  initrd_high	- restrict positioning of initrd images:
		  If this variable is not set, initrd images will be
		  copied to the highest possible address in RAM; this
		  is usually what you want since it allows for
		  maximum initrd size. If for some reason you want to
		  make sure that the initrd image is loaded below the
		  CONFIG_SYS_BOOTMAPSZ limit, you can set this environment
		  variable to a value of "no" or "off" or "0".
		  Alternatively, you can set it to a maximum upper
		  address to use (U-Boot will still check that it
		  does not overwrite the U-Boot stack and data).

		  For instance, when you have a system with 16 MB
		  RAM, and want to reserve 4 MB from use by Linux,
		  you can do this by adding "mem=12M" to the value of
		  the "bootargs" variable. However, now you must make
		  sure that the initrd image is placed in the first
		  12 MB as well - this can be done with

		  setenv initrd_high 00c00000

		  If you set initrd_high to 0xFFFFFFFF, this is an
		  indication to U-Boot that all addresses are legal
		  for the Linux kernel, including addresses in flash
		  memory. In this case U-Boot will NOT COPY the
		  ramdisk at all. This may be useful to reduce the
		  boot time on your system, but requires that this
		  feature is supported by your Linux kernel.

  ipaddr	- IP address; needed for tftpboot command

  loadaddr	- Default load address for commands like "bootp",
		  "rarpboot", "tftpboot", "loadb" or "diskboot"

  loads_echo	- see CONFIG_LOADS_ECHO

  serverip	- TFTP server IP address; needed for tftpboot command

  bootretry	- see CONFIG_BOOT_RETRY_TIME

  bootdelaykey	- see CONFIG_AUTOBOOT_DELAY_STR

  bootstopkey	- see CONFIG_AUTOBOOT_STOP_STR

  ethprime	- controls which interface is used first.

  ethact	- controls which interface is currently active.
		  For example you can do the following

		  => setenv ethact FEC
		  => ping 192.168.0.1 # traffic sent on FEC
		  => setenv ethact SCC
		  => ping 10.0.0.1 # traffic sent on SCC

  ethrotate	- When set to "no" U-Boot does not go through all
		  available network interfaces.
		  It just stays at the currently selected interface.

  netretry	- When set to "no" each network operation will
		  either succeed or fail without retrying.
		  When set to "once" the network operation will
		  fail when all the available network interfaces
		  are tried once without success.
		  Useful on scripts which control the retry operation
		  themselves.

  npe_ucode	- set load address for the NPE microcode

  tftpsrcport	- If this is set, the value is used for TFTP's
		  UDP source port.

  tftpdstport	- If this is set, the value is used for TFTP's UDP
		  destination port instead of the Well Know Port 69.

  tftpblocksize - Block size to use for TFTP transfers; if not set,
		  we use the TFTP server's default block size

  tftptimeout	- Retransmission timeout for TFTP packets (in milli-
		  seconds, minimum value is 1000 = 1 second). Defines
		  when a packet is considered to be lost so it has to
		  be retransmitted. The default is 5000 = 5 seconds.
		  Lowering this value may make downloads succeed
		  faster in networks with high packet loss rates or
		  with unreliable TFTP servers.

  vlan		- When set to a value < 4095 the traffic over
		  Ethernet is encapsulated/received over 802.1q
		  VLAN tagged frames.

The following image location variables contain the location of images
used in booting. The "Image" column gives the role of the image and is
not an environment variable name. The other columns are environment
variable names. "File Name" gives the name of the file on a TFTP
server, "RAM Address" gives the location in RAM the image will be
loaded to, and "Flash Location" gives the image's address in NOR
flash or offset in NAND flash.

*Note* - these variables don't have to be defined for all boards, some
boards currenlty use other variables for these purposes, and some
boards use these variables for other purposes.

Image               File Name        RAM Address       Flash Location
-----               ---------        -----------       --------------
u-boot              u-boot           u-boot_addr_r     u-boot_addr
Linux kernel        bootfile         kernel_addr_r     kernel_addr
device tree blob    fdtfile          fdt_addr_r        fdt_addr
ramdisk             ramdiskfile      ramdisk_addr_r    ramdisk_addr

The following environment variables may be used and automatically
updated by the network boot commands ("bootp" and "rarpboot"),
depending the information provided by your boot server:

  bootfile	- see above
  dnsip		- IP address of your Domain Name Server
  dnsip2	- IP address of your secondary Domain Name Server
  gatewayip	- IP address of the Gateway (Router) to use
  hostname	- Target hostname
  ipaddr	- see above
  netmask	- Subnet Mask
  rootpath	- Pathname of the root filesystem on the NFS server
  serverip	- see above


There are two special Environment Variables:

  serial#	- contains hardware identification information such
		  as type string and/or serial number
  ethaddr	- Ethernet address

These variables can be set only once (usually during manufacturing of
the board). U-Boot refuses to delete or overwrite these variables
once they have been set once.


Further special Environment Variables:

  ver		- Contains the U-Boot version string as printed
		  with the "version" command. This variable is
		  readonly (see CONFIG_VERSION_VARIABLE).


Please note that changes to some configuration parameters may take
only effect after the next boot (yes, that's just like Windoze :-).


Command Line Parsing:
=====================

There are two different command line parsers available with U-Boot:
the old "simple" one, and the much more powerful "hush" shell:

Old, simple command line parser:
--------------------------------

- supports environment variables (through setenv / saveenv commands)
- several commands on one line, separated by ';'
- variable substitution using "... ${name} ..." syntax
- special characters ('$', ';') can be escaped by prefixing with '\',
  for example:
	setenv bootcmd bootm \${address}
- You can also escape text by enclosing in single apostrophes, for example:
	setenv addip 'setenv bootargs $bootargs ip=$ipaddr:$serverip:$gatewayip:$netmask:$hostname::off'

Hush shell:
-----------

- similar to Bourne shell, with control structures like
  if...then...else...fi, for...do...done; while...do...done,
  until...do...done, ...
- supports environment ("global") variables (through setenv / saveenv
  commands) and local shell variables (through standard shell syntax
  "name=value"); only environment variables can be used with "run"
  command

General rules:
--------------

(1) If a command line (or an environment variable executed by a "run"
    command) contains several commands separated by semicolon, and
    one of these commands fails, then the remaining commands will be
    executed anyway.

(2) If you execute several variables with one call to run (i. e.
    calling run with a list of variables as arguments), any failing
    command will cause "run" to terminate, i. e. the remaining
    variables are not executed.

Note for Redundant Ethernet Interfaces:
=======================================

Some boards come with redundant Ethernet interfaces; U-Boot supports
such configurations and is capable of automatic selection of a
"working" interface when needed. MAC assignment works as follows:

Network interfaces are numbered eth0, eth1, eth2, ... Corresponding
MAC addresses can be stored in the environment as "ethaddr" (=>eth0),
"eth1addr" (=>eth1), "eth2addr", ...

If the network interface stores some valid MAC address (for instance
in SROM), this is used as default address if there is NO correspon-
ding setting in the environment; if the corresponding environment
variable is set, this overrides the settings in the card; that means:

o If the SROM has a valid MAC address, and there is no address in the
  environment, the SROM's address is used.

o If there is no valid address in the SROM, and a definition in the
  environment exists, then the value from the environment variable is
  used.

o If both the SROM and the environment contain a MAC address, and
  both addresses are the same, this MAC address is used.

o If both the SROM and the environment contain a MAC address, and the
  addresses differ, the value from the environment is used and a
  warning is printed.

o If neither SROM nor the environment contain a MAC address, an error
  is raised.

If Ethernet drivers implement the 'write_hwaddr' function, valid MAC addresses
will be programmed into hardware as part of the initialization process.  This
may be skipped by setting the appropriate 'ethmacskip' environment variable.
The naming convention is as follows:
"ethmacskip" (=>eth0), "eth1macskip" (=>eth1) etc.

Image Formats:
==============

U-Boot is capable of booting (and performing other auxiliary operations on)
images in two formats:

New uImage format (FIT)
-----------------------

Flexible and powerful format based on Flattened Image Tree -- FIT (similar
to Flattened Device Tree). It allows the use of images with multiple
components (several kernels, ramdisks, etc.), with contents protected by
SHA1, MD5 or CRC32. More details are found in the doc/uImage.FIT directory.


Old uImage format
-----------------

Old image format is based on binary files which can be basically anything,
preceded by a special header; see the definitions in include/image.h for
details; basically, the header defines the following image properties:

* Target Operating System (Provisions for OpenBSD, NetBSD, FreeBSD,
  4.4BSD, Linux, SVR4, Esix, Solaris, Irix, SCO, Dell, NCR, VxWorks,
  LynxOS, pSOS, QNX, RTEMS, INTEGRITY;
  Currently supported: Linux, NetBSD, VxWorks, QNX, RTEMS, LynxOS,
  INTEGRITY).
* Target CPU Architecture (Provisions for Alpha, ARM, AVR32, Intel x86,
  IA64, MIPS, NDS32, Nios II, PowerPC, IBM S390, SuperH, Sparc, Sparc 64 Bit;
  Currently supported: ARM, AVR32, Intel x86, MIPS, NDS32, Nios II, PowerPC).
* Compression Type (uncompressed, gzip, bzip2)
* Load Address
* Entry Point
* Image Name
* Image Timestamp

The header is marked by a special Magic Number, and both the header
and the data portions of the image are secured against corruption by
CRC32 checksums.


Linux Support:
==============

Although U-Boot should support any OS or standalone application
easily, the main focus has always been on Linux during the design of
U-Boot.

U-Boot includes many features that so far have been part of some
special "boot loader" code within the Linux kernel. Also, any
"initrd" images to be used are no longer part of one big Linux image;
instead, kernel and "initrd" are separate images. This implementation
serves several purposes:

- the same features can be used for other OS or standalone
  applications (for instance: using compressed images to reduce the
  Flash memory footprint)

- it becomes much easier to port new Linux kernel versions because
  lots of low-level, hardware dependent stuff are done by U-Boot

- the same Linux kernel image can now be used with different "initrd"
  images; of course this also means that different kernel images can
  be run with the same "initrd". This makes testing easier (you don't
  have to build a new "zImage.initrd" Linux image when you just
  change a file in your "initrd"). Also, a field-upgrade of the
  software is easier now.


Linux HOWTO:
============

Porting Linux to U-Boot based systems:
---------------------------------------

U-Boot cannot save you from doing all the necessary modifications to
configure the Linux device drivers for use with your target hardware
(no, we don't intend to provide a full virtual machine interface to
Linux :-).

But now you can ignore ALL boot loader code (in arch/powerpc/mbxboot).

Just make sure your machine specific header file (for instance
include/asm-ppc/tqm8xx.h) includes the same definition of the Board
Information structure as we define in include/asm-<arch>/u-boot.h,
and make sure that your definition of IMAP_ADDR uses the same value
as your U-Boot configuration in CONFIG_SYS_IMMR.


Configuring the Linux kernel:
-----------------------------

No specific requirements for U-Boot. Make sure you have some root
device (initial ramdisk, NFS) for your target system.


Building a Linux Image:
-----------------------

With U-Boot, "normal" build targets like "zImage" or "bzImage" are
not used. If you use recent kernel source, a new build target
"uImage" will exist which automatically builds an image usable by
U-Boot. Most older kernels also have support for a "pImage" target,
which was introduced for our predecessor project PPCBoot and uses a
100% compatible format.

Example:

	make TQM850L_config
	make oldconfig
	make dep
	make uImage

The "uImage" build target uses a special tool (in 'tools/mkimage') to
encapsulate a compressed Linux kernel image with header	 information,
CRC32 checksum etc. for use with U-Boot. This is what we are doing:

* build a standard "vmlinux" kernel image (in ELF binary format):

* convert the kernel into a raw binary image:

	${CROSS_COMPILE}-objcopy -O binary \
				 -R .note -R .comment \
				 -S vmlinux linux.bin

* compress the binary image:

	gzip -9 linux.bin

* package compressed binary image for U-Boot:

	mkimage -A ppc -O linux -T kernel -C gzip \
		-a 0 -e 0 -n "Linux Kernel Image" \
		-d linux.bin.gz uImage


The "mkimage" tool can also be used to create ramdisk images for use
with U-Boot, either separated from the Linux kernel image, or
combined into one file. "mkimage" encapsulates the images with a 64
byte header containing information about target architecture,
operating system, image type, compression method, entry points, time
stamp, CRC32 checksums, etc.

"mkimage" can be called in two ways: to verify existing images and
print the header information, or to build new images.

In the first form (with "-l" option) mkimage lists the information
contained in the header of an existing U-Boot image; this includes
checksum verification:

	tools/mkimage -l image
	  -l ==> list image header information

The second form (with "-d" option) is used to build a U-Boot image
from a "data file" which is used as image payload:

	tools/mkimage -A arch -O os -T type -C comp -a addr -e ep \
		      -n name -d data_file image
	  -A ==> set architecture to 'arch'
	  -O ==> set operating system to 'os'
	  -T ==> set image type to 'type'
	  -C ==> set compression type 'comp'
	  -a ==> set load address to 'addr' (hex)
	  -e ==> set entry point to 'ep' (hex)
	  -n ==> set image name to 'name'
	  -d ==> use image data from 'datafile'

Right now, all Linux kernels for PowerPC systems use the same load
address (0x00000000), but the entry point address depends on the
kernel version:

- 2.2.x kernels have the entry point at 0x0000000C,
- 2.3.x and later kernels have the entry point at 0x00000000.

So a typical call to build a U-Boot image would read:

	-> tools/mkimage -n '2.4.4 kernel for TQM850L' \
	> -A ppc -O linux -T kernel -C gzip -a 0 -e 0 \
	> -d /opt/elsk/ppc_8xx/usr/src/linux-2.4.4/arch/powerpc/coffboot/vmlinux.gz \
	> examples/uImage.TQM850L
	Image Name:   2.4.4 kernel for TQM850L
	Created:      Wed Jul 19 02:34:59 2000
	Image Type:   PowerPC Linux Kernel Image (gzip compressed)
	Data Size:    335725 Bytes = 327.86 kB = 0.32 MB
	Load Address: 0x00000000
	Entry Point:  0x00000000

To verify the contents of the image (or check for corruption):

	-> tools/mkimage -l examples/uImage.TQM850L
	Image Name:   2.4.4 kernel for TQM850L
	Created:      Wed Jul 19 02:34:59 2000
	Image Type:   PowerPC Linux Kernel Image (gzip compressed)
	Data Size:    335725 Bytes = 327.86 kB = 0.32 MB
	Load Address: 0x00000000
	Entry Point:  0x00000000

NOTE: for embedded systems where boot time is critical you can trade
speed for memory and install an UNCOMPRESSED image instead: this
needs more space in Flash, but boots much faster since it does not
need to be uncompressed:

	-> gunzip /opt/elsk/ppc_8xx/usr/src/linux-2.4.4/arch/powerpc/coffboot/vmlinux.gz
	-> tools/mkimage -n '2.4.4 kernel for TQM850L' \
	> -A ppc -O linux -T kernel -C none -a 0 -e 0 \
	> -d /opt/elsk/ppc_8xx/usr/src/linux-2.4.4/arch/powerpc/coffboot/vmlinux \
	> examples/uImage.TQM850L-uncompressed
	Image Name:   2.4.4 kernel for TQM850L
	Created:      Wed Jul 19 02:34:59 2000
	Image Type:   PowerPC Linux Kernel Image (uncompressed)
	Data Size:    792160 Bytes = 773.59 kB = 0.76 MB
	Load Address: 0x00000000
	Entry Point:  0x00000000


Similar you can build U-Boot images from a 'ramdisk.image.gz' file
when your kernel is intended to use an initial ramdisk:

	-> tools/mkimage -n 'Simple Ramdisk Image' \
	> -A ppc -O linux -T ramdisk -C gzip \
	> -d /LinuxPPC/images/SIMPLE-ramdisk.image.gz examples/simple-initrd
	Image Name:   Simple Ramdisk Image
	Created:      Wed Jan 12 14:01:50 2000
	Image Type:   PowerPC Linux RAMDisk Image (gzip compressed)
	Data Size:    566530 Bytes = 553.25 kB = 0.54 MB
	Load Address: 0x00000000
	Entry Point:  0x00000000


Installing a Linux Image:
-------------------------

To downloading a U-Boot image over the serial (console) interface,
you must convert the image to S-Record format:

	objcopy -I binary -O srec examples/image examples/image.srec

The 'objcopy' does not understand the information in the U-Boot
image header, so the resulting S-Record file will be relative to
address 0x00000000. To load it to a given address, you need to
specify the target address as 'offset' parameter with the 'loads'
command.

Example: install the image to address 0x40100000 (which on the
TQM8xxL is in the first Flash bank):

	=> erase 40100000 401FFFFF

	.......... done
	Erased 8 sectors

	=> loads 40100000
	## Ready for S-Record download ...
	~>examples/image.srec
	1 2 3 4 5 6 7 8 9 10 11 12 13 ...
	...
	15989 15990 15991 15992
	[file transfer complete]
	[connected]
	## Start Addr = 0x00000000


You can check the success of the download using the 'iminfo' command;
this includes a checksum verification so you can be sure no data
corruption happened:

	=> imi 40100000

	## Checking Image at 40100000 ...
	   Image Name:	 2.2.13 for initrd on TQM850L
	   Image Type:	 PowerPC Linux Kernel Image (gzip compressed)
	   Data Size:	 335725 Bytes = 327 kB = 0 MB
	   Load Address: 00000000
	   Entry Point:	 0000000c
	   Verifying Checksum ... OK


Boot Linux:
-----------

The "bootm" command is used to boot an application that is stored in
memory (RAM or Flash). In case of a Linux kernel image, the contents
of the "bootargs" environment variable is passed to the kernel as
parameters. You can check and modify this variable using the
"printenv" and "setenv" commands: