AMCC suggested to set the PMU bit to 0 for best performace on the
PPC440 DDR controller. The 440er common DDR setup files (sdram.c &
spd_sdram.c) are changed accordingly. So all 440er boards using
these setup routines will automatically receive this performance
increase.

Please see below some benchmarks done by AMCC to demonstrate this
performance changes:


----------------------------------------
SDRAM0_CFG0[PMU] = 1 (U-Boot default for Bamboo, Yosemite and Yellowstone)
----------------------------------------
Stream benchmark results
-------------------------------------------------------------
This system uses 8 bytes per DOUBLE PRECISION word.
-------------------------------------------------------------
Array size = 2000000, Offset = 0
Total memory required = 45.8 MB.
Each test is run 10 times, but only
the *best* time for each is used.
-------------------------------------------------------------
Your clock granularity/precision appears to be 1 microseconds.
Each test below will take on the order of 112345 microseconds.
   (= 112345 clock ticks)
Increase the size of the arrays if this shows that you are not getting
at least 20 clock ticks per test.
-------------------------------------------------------------
WARNING -- The above is only a rough guideline.
For best results, please be sure you know the precision of your system
timer.
-------------------------------------------------------------
Function      Rate (MB/s)   RMS time     Min time     Max time
Copy:         256.7683       0.1248       0.1246       0.1250
Scale:        246.0157       0.1302       0.1301       0.1302
Add:          255.0316       0.1883       0.1882       0.1885
Triad:        253.1245       0.1897       0.1896       0.1899


TTCP Benchmark Results
ttcp-t: socket
ttcp-t: connect
ttcp-t: buflen=8192, nbuf=2048, align=16384/0, port=5000  tcp  ->
localhost
ttcp-t: 16777216 bytes in 0.28 real seconds = 454.29 Mbit/sec +++
ttcp-t: 2048 I/O calls, msec/call = 0.14, calls/sec = 7268.57
ttcp-t: 0.0user 0.1sys 0:00real 60% 0i+0d 0maxrss 0+2pf 3+1506csw

----------------------------------------
SDRAM0_CFG0[PMU] = 0 (Suggested modification)
Setting PMU = 0 provides a noticeable performance improvement *2% to
5% improvement in memory performance.
*Improves the Mbit/sec for TTCP benchmark by almost 76%.
----------------------------------------
Stream benchmark results
-------------------------------------------------------------
This system uses 8 bytes per DOUBLE PRECISION word.
-------------------------------------------------------------
Array size = 2000000, Offset = 0
Total memory required = 45.8 MB.
Each test is run 10 times, but only
the *best* time for each is used.
-------------------------------------------------------------
Your clock granularity/precision appears to be 1 microseconds.
Each test below will take on the order of 120066 microseconds.
   (= 120066 clock ticks)
Increase the size of the arrays if this shows that you are not getting
at least 20 clock ticks per test.
-------------------------------------------------------------
WARNING -- The above is only a rough guideline.
For best results, please be sure you know the precision of your system
timer.
-------------------------------------------------------------
Function      Rate (MB/s)   RMS time     Min time     Max time
Copy:         262.5167       0.1221       0.1219       0.1223
Scale:        258.4856       0.1238       0.1238       0.1240
Add:          262.5404       0.1829       0.1828       0.1831
Triad:        266.8594       0.1800       0.1799       0.1802

TTCP Benchmark Results
ttcp-t: socket
ttcp-t: connect
ttcp-t: buflen=8192, nbuf=2048, align=16384/0, port=5000  tcp  ->
localhost
ttcp-t: 16777216 bytes in 0.16 real seconds = 804.06 Mbit/sec +++
ttcp-t: 2048 I/O calls, msec/call = 0.08, calls/sec = 12864.89
ttcp-t: 0.0user 0.0sys 0:00real 46% 0i+0d 0maxrss 0+2pf 120+1csw


2006-07-28, Stefan Roese <sr@denx.de>

---------------------------------------------------------------------
Cleanup of AMCC eval boards (Walnut/Sycamore, Bubinga, Ebony, Ocotea)
---------------------------------------------------------------------

Changes to all AMCC eval boards:
--------------------------------

o Changed u-boot image size to 256 kBytes instead of 512 kBytes on most
  boards.

o Use 115200 baud as default console baudrate.

o Added config option to use redundant environment in flash. This is also
  the default setting. Option for environment in nvram is still available
  for backward compatibility.

o Merged board specific flash drivers to common flash driver:
  board/amcc/common/flash.c


Sycamore/Walnut (one port supporting both eval boards):
-------------------------------------------------------

o Cleanup to allow easier "cloning" for different (custom) boards:

  o Moved EBC configuration from board specific asm-file "init.S"
    using defines in board configuration file. No board specific
    asm file needed anymore.


August 01 2005, Stefan Roese <sr@denx.de>

Synopsys' DesignWare(r) ARC(r) Processors are a family of 32-bit CPUs
that SoC designers can optimize for a wide range of uses, from deeply embedded
to high-performance host applications.

More information on ARC cores avaialble here:
http://www.synopsys.com/IP/ProcessorIP/ARCProcessors/Pages/default.aspx

Designers can differentiate their products by using patented configuration
technology to tailor each ARC processor instance to meet specific performance,
power and area requirements.

The DesignWare ARC processors are also extendable, allowing designers to add
their own custom instructions that dramatically increase performance.

Synopsys' ARC processors have been used by over 170 customers worldwide who
collectively ship more than 1 billion ARC-based chips annually.

All DesignWare ARC processors utilize a 16-/32-bit ISA that provides excellent
performance and code density for embedded and host SoC applications.

The RISC microprocessors are synthesizable and can be implemented in any foundry
or process, and are supported by a complete suite of development tools.

The ARC GNU toolchain with support for all ARC Processors can be downloaded
from here (available pre-built toolchains as well):

https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain/releases

Subject: Re: [PATCH][CFT] bring ARM memory layout in line with the documented behaviour
From: "Anders Larsen" <alarsen@rea.de>
Date: Thu, 18 Sep 2003 14:15:21 +0200
To: Wolfgang Denk <wd@denx.de>

...
>I still see  references  to  _armboot_start,  _armboot_end_data,  and
>_armboot_end - which role do these play now? Can we get rid of them?
>
>How are they (should they be) set in your memory map above?

_armboot_start contains the value of CONFIG_SYS_TEXT_BASE (0xA07E0000); it seems
CONFIG_SYS_TEXT_BASE and _armboot_start are both used for the same purpose in
different parts of the (ARM) code.
Furthermore, the startup code (cpu/<arm>/start.S) internally uses
another variable (_TEXT_BASE) with the same content as _armboot_start.
I agree that this mess should be cleaned up.

DSP side awareness for Freescale heterogeneous multicore chips based on
StarCore and Power Architecture
===============================================================
powerpc/mpc85xx code ve APIs and function to get the number,
configuration and frequencies of all PowerPC cores and devices
connected to them, but it didnt have the similar code ofr HEterogeneous
SC3900/DSP cores and such devices like CPRI, MAPLE, MAPLE-ULB etc.

Code for DSP side awareness provides such functionality for Freescale
Heterogeneous SoCs which are chasis-2 compliant like B4860 and B4420

As part of this feature, following changes have been made:
==========================================================

1. Changed files:
=================
- arch/powerpc/cpu/mpc85xx/cpu.c

Code added in this file to print the DSP cores and other device's(CPRI,
MAPLE etc) frequencies

- arch/powerpc/cpu/mpc85xx/speed.c

Added Defines and code to extract the frequncy information for all
required cores and devices from RCW and System frequency

- arch/powerpc/cpu/mpc8xxx/cpu.c

Added API to get the number of SC cores in running system and Their BIT
MASK, similar to the code written for PowerPC

- arch/powerpc/include/asm/config_mpc85xx.h

Added top level CONFIG to identify presence of HETEROGENUOUS clusters
in the system and CONFIGS for SC3900/DSP components

- arch/powerpc/include/asm/processor.h
- include/common.h

Added newly added Functions Declaration

- include/e500.h

Global structure updated for dsp cores and other components

2. CONFIGs ADDED
================

CONFIG_HETROGENOUS_CLUSTERS	- Define for checking the presence of
				  DSP/SC3900 core clusters

CONFIG_SYS_FSL_NUM_CC_PLLS	- Define for number of PLLs

Though there are only 4 PLLs in B4, but in sequence of PLLs from PLL1 -
PLL5, PLL3 is Reserved(as mentioned in RM), so this define contains the
value as 5 not 4, to iterate over all PLLs while coding

CONFIG_SYS_MAPLE		- Define for MAPLE Baseband Accelerator
CONFIG_SYS_CPRI			- Define for CPRI Interface
CONFIG_PPC_CLUSTER_START	- Start index of ppc clusters
CONFIG_DSP_CLUSTER_START	- Start index of dsp clusters

Following are the defines for PLL's index that provide the Clocking to
CPRI, ULB and ETVE components

CONFIG_SYS_CPRI_CLK		- Define PLL index for CPRI clock
CONFIG_SYS_ULB_CLK		- Define PLL index for ULB clock
CONFIG_SYS_ETVPE_CLK		- Define PLL index for ETVPE clock

3. Changes in MPC85xx_SYS_INFO Global structure
===============================================

DSP cores and other device's components have been added in this structure.

freq_processor_dsp[CONFIG_MAX_DSP_CPUS]	- Array to contain the DSP core's frequencies
freq_cpri				- To store CPRI frequency
freq_maple				- To store MAPLE frequency
freq_maple_ulb				- To store MAPLE-ULB frequency
freq_maple_etvpe			- To store MAPLE-eTVPE frequency

4. U-BOOT LOGS
==============
4.1 B4860QDS board
    Boot from NOR flash

U-Boot 2014.07-00222-g70587a8-dirty (Aug 07 2014 - 13:15:47)

CPU0:  B4860E, Version: 2.0, (0x86880020)
Core:  e6500, Version: 2.0, (0x80400020) Clock Configuration:
       CPU0:1600 MHz, CPU1:1600 MHz, CPU2:1600 MHz, CPU3:1600 MHz,
       DSP CPU0:1200 MHz, DSP CPU1:1200 MHz, DSP CPU2:1200 MHz, DSP CPU3:1200 MHz,
       DSP CPU4:1200 MHz, DSP CPU5:1200 MHz,
       CCB:666.667 MHz,
       DDR:933.333 MHz (1866.667 MT/s data rate) (Asynchronous), IFC:166.667 MHz
       CPRI:600  MHz
       MAPLE:600  MHz, MAPLE-ULB:800  MHz, MAPLE-eTVPE:1000 MHz
       FMAN1: 666.667 MHz
       QMAN:  333.333 MHz

CPUn	 -  PowerPC core
DSP CPUn -  SC3900 core

Shaveta Leekha(shaveta@freescale.com)
Created August 7, 2014
===========================================

JFFS2 options and usage.
-----------------------

JFFS2 in U-Boot is a read only implementation of the file system in
Linux with the same name. To use JFFS2 define CONFIG_CMD_JFFS2.

The module adds three new commands.
fsload  - load binary file from a file system image
fsinfo  - print information about file systems
ls      - list files in a directory
chpart  - change active partition

If you do now need the commands, you can enable the filesystem separately
with CONFIG_FS_JFFS2 and call the jffs2 functions yourself.

If you boot from a partition which is mounted writable, and you
update your boot environment by replacing single files on that
partition, you should also define CONFIG_SYS_JFFS2_SORT_FRAGMENTS. Scanning
the JFFS2 filesystem takes *much* longer with this feature, though.
Sorting is done while inserting into the fragment list, which is
more or less a bubble sort. That algorithm is known to be O(n^2),
thus you should really consider if you can avoid it!


There only one way for JFFS2 to find the disk. It uses the flash_info
structure to find the start of a JFFS2 disk (called partition in the code)
and you can change where the partition is with two defines.

CONFIG_SYS_JFFS2_FIRST_BANK
	defined the first flash bank to use

CONFIG_SYS_JFFS2_FIRST_SECTOR
	defines the first sector to use
---

TODO.

	Remove the assumption that JFFS can dereference a pointer
	into the disk. The current code do not work with memory holes
	or hardware with a sliding window (PCMCIA).

JFFS2 NAND support:

To enable, use the following #define in the board configuration file:

#define CONFIG_JFFS2_NAND

Configuration of partitions is similar to how this is done in  U-Boot
for  JFFS2  on top NOR flash.

Status LED
========================================

This README describes the status LED API.

The API is defined by the include file include/status_led.h

The first step is to enable CONFIG_LED_STATUS in menuconfig:
> Device Drivers > LED Support.

If the LED support is only for specific board, enable
CONFIG_LED_STATUS_BOARD_SPECIFIC in the menuconfig.

Status LEDS 0 to 5 are enabled by the following configurations at menuconfig:
CONFIG_STATUS_LED0, CONFIG_STATUS_LED1, ... CONFIG_STATUS_LED5

The following should be configured for each of the enabled LEDs:
CONFIG_STATUS_LED_BIT<n>
CONFIG_STATUS_LED_STATE<n>
CONFIG_STATUS_LED_FREQ<n>
Where <n> is an integer 1 through 5 (empty for 0).

CONFIG_STATUS_LED_BIT is passed into the __led_* functions to identify which LED
is being acted on. As such, the value choose must be unique with with respect to
the other CONFIG_STATUS_LED_BIT's. Mapping the value to a physical LED is the
reponsiblity of the __led_* function.

CONFIG_STATUS_LED_STATE is the initial state of the LED. It should be set to one
of these values: CONFIG_LED_STATUS_OFF or CONFIG_LED_STATUS_ON.

CONFIG_STATUS_LED_FREQ determines the LED blink frequency.
Values range from 2 to 10.

Some other LED macros
---------------------

CONFIG_STATUS_LED_BOOT is the LED to light when the board is booting.
This must be a valid LED number (0-5).

CONFIG_STATUS_LED_RED is the red LED. It is used to signal errors. This must be
a valid LED number (0-5). Other similar color LED's macros are
CONFIG_STATUS_LED_GREEN, CONFIG_STATUS_LED_YELLOW and CONFIG_STATUS_LED_BLUE.

General LED functions
---------------------
The following functions should be defined:

__led_init is called once to initialize the LED to CONFIG_STATUS_LED_STATE.
One time start up code should be placed here.

__led_set is called to change the state of the LED.

__led_toggle is called to toggle the current state of the LED.

Colour LED
========================================

Colour LED's are at present only used by ARM.

The functions names explain their purpose.

coloured_LED_init
red_LED_on
red_LED_off
green_LED_on
green_LED_off
yellow_LED_on
yellow_LED_off
blue_LED_on
blue_LED_off

These are weakly defined in arch/arm/lib/board.c to noops. Where applicable, define
these functions in the board specific source.

TBD : Describe older board dependent macros similar to what is done for

TBD : Describe general support via asm/status_led.h

LED display internal API
=======================================

This README describes the LED display API.

The API is defined by the include file include/led-display.h

The first step in to define CONFIG_CMD_DISPLAY in the board config file.
Then you need to provide the following functions to access LED display:

void display_set(int cmd);

This function should control the state of the LED display. Argument is
an ORed combination of the following values:
 DISPLAY_CLEAR	-- clear the display
 DISPLAY_HOME	-- set the position to the beginning of display

int display_putc(char c);

This function should display it's parameter on the LED display in the
current position. Returns the displayed character on success or -1 in
case of failure.

With this functions defined 'display' command will display it's
arguments on the LED display (or clear the display if called without
arguments).

N1213 is a configurable hard/soft core of NDS32's N12 CPU family.

Features
========

CPU Core
 - 16-/32-bit mixable instruction format.
 - 32 general-purpose 32-bit registers.
 - 8-stage pipeline.
 - Dynamic branch prediction.
 - 32/64/128/256 BTB.
 - Return address stack (RAS).
 - Vector interrupts for internal/external.
   interrupt controller with 6 hardware interrupt signals.
 - 3 HW-level nested interruptions.
 - User and super-user mode support.
 - Memory-mapped I/O.
 - Address space up to 4GB.

Memory Management Unit
 - TLB
   - 4/8-entry fully associative iTLB/dTLB.
   - 32/64/128-entry 4-way set-associati.ve main TLB.
   - TLB locking support
 - Optional hardware page table walker.
 - Two groups of page size support.
  - 4KB & 1MB.
  - 8KB & 1MB.

Memory Subsystem
 - I & D cache.
   - Virtually indexed and physically tagged.
   - Cache size: 8KB/16KB/32KB/64KB.
   - Cache line size: 16B/32B.
   - Set associativity: 2-way, 4-way or direct-mapped.
   - Cache locking support.
 - I & D local memory (LM).
   - Size: 4KB to 1MB.
   - Bank numbers: 1 or 2.
   - Optional 1D/2D DMA engine.
   - Internal or external to CPU core.

Bus Interface
 - Synchronous/Asynchronous AHB bus: 0, 1 or 2 ports.
 - Synchronous High speed memory port.
   (HSMP): 0, 1 or 2 ports.

Debug
 - JTAG debug interface.
 - Embedded debug module (EDM).
 - Optional embedded program tracer interface.

Miscellaneous
 - Programmable data endian control.
 - Performance monitoring mechanism.

NDS32 is a new high-performance 32-bit RISC microprocessor core.

http://www.andestech.com/

AndeStar ISA
============
AndeStar is a patent-pending 16-bit/32-bit mixed-length instruction set to
achieve optimal system performance, code density, and power efficiency.

It contains the following features:
 - Intermixable 32-bit and 16-bit instruction sets without the need for
   mode switch.
 - 16-bit instructions as a frequently used subset of 32-bit instructions.
 - RISC-style register-based instruction set.
 - 32 32-bit General Purpose Registers (GPR).
 - Upto 1024 User Special Registers (USR) for existing and extension
   instructions.
 - Rich load/store instructions for...
   - Single memory access with base address update.
   - Multiple aligned and unaligned memory accesses for memory copy and stack
     operations.
   - Data prefetch to improve data cache performance.
   - Non-bus locking synchronization instructions.
 - PC relative jump and PC read instructions for efficient position independent
   code.
 - Multiply-add and multiple-sub with 64-bit accumulator.
 - Instruction for efficient power management.
 - Bi-endian support.
 - Three instruction extension space for application acceleration:
   - Performance extension.
   - Andes future extensions (for floating-point, multimedia, etc.)
   - Customer extensions.

AndesCore CPU
=============
Andes Technology has 4 families of CPU cores: N12, N10, N9, N8.

For details about N12 CPU family, please check doc/README.N1213.

The NDS32 ports of u-boot, the Linux kernel, the GNU toolchain and
other associated software are actively supported by Andes Technology Corporation.

In U-Boot, we implemented the networked console via the standard
"devices" mechanism, which means that you can switch between the
serial and network input/output devices by adjusting the 'stdin' and
'stdout' environment variables. To switch to the networked console,
set either of these variables to "nc". Input and output can be
switched independently.

CONFIG_NETCONSOLE_BUFFER_SIZE - Override the default buffer size

We use an environment variable 'ncip' to set the IP address and the
port of the destination. The format is <ip_addr>:<port>. If <port> is
omitted, the value of 6666 is used. If the env var doesn't exist, the
broadcast address and port 6666 are used. If it is set to an IP
address of 0 (or 0.0.0.0) then no messages are sent to the network.
The source / listening port can be configured separately by setting
the 'ncinport' environment variable and the destination port can be
configured by setting the 'ncoutport' environment variable.

For example, if your server IP is 192.168.1.1, you could use:

	=> setenv nc 'setenv stdout nc;setenv stdin nc'
	=> setenv ncip 192.168.1.1
	=> saveenv
	=> run nc


On the host side, please use this script to access the console:

	tools/netconsole <ip> [port]

The script uses netcat to talk to the board over UDP.  It requires you to
specify the target IP address (or host name, assuming DNS is working). The
script can be interrupted by pressing ^T (CTRL-T).

Be aware that in some distributives (Fedora Core 5 at least)
usage of nc has been changed and -l and -p options are considered
as mutually exclusive. If nc complains about options provided,
you can just remove the -p option from the script.

It turns out that 'netcat' cannot be used to listen to broadcast
packets. We developed our own tool 'ncb' (see tools directory) that
listens to broadcast packets on a given port and dumps them to the
standard output.  It will be built when compiling for a board which
has CONFIG_NETCONSOLE defined.  If the netconsole script can find it
in PATH or in the same directory, it will be used instead.

For Linux, the network-based console needs special configuration.
Minimally, the host IP address needs to be specified. This can be
done either via the kernel command line, or by passing parameters
while loading the netconsole.o module (when used in a loadable module
configuration). Please refer to Documentation/networking/logging.txt
file for the original Ingo Molnar's documentation on how to pass
parameters to the loadable module.

The format of the kernel command line parameter (for the static
configuration) is as follows:

  netconsole=[src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr]

where

  src-port	source for UDP packets
		(defaults to 6665)
  src-ip	source IP to use
		(defaults to the interface's address)
  dev		network interface
		(defaults to eth0)
  tgt-port	port for logging agent
		(defaults to 6666)
  tgt-ip	IP address for logging agent
		(this is the required parameter)
  tgt-macaddr	ethernet MAC address for logging agent
		(defaults to broadcast)

Examples:

  netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc

or

  netconsole=@/,@192.168.3.1/

Please note that for the Linux networked console to work, the
ethernet interface has to be up by the time the netconsole driver is
initialized. This means that in case of static kernel configuration,
the respective Ethernet interface has to be brought up using the "IP
Autoconfiguration" kernel feature, which is usually done by defaults
in the ELDK-NFS-based environment.

To browse the Linux network console output, use the 'netcat' tool invoked
as follows:

	nc -u -l -p 6666

Note that unlike the U-Boot implementation the Linux netconsole is
unidirectional, i. e. you have console output only in Linux.

Open Firmware Flat Tree and usage.
----------------------------------

As part of the ongoing cleanup of the Linux PPC trees, the preferred
way to pass bootloader and board setup information is the open
firmware flat tree.

Please take a look at the following email discussion for some
background.

  http://ozlabs.org/pipermail/linuxppc-dev/2005-August/019408.html
  http://ozlabs.org/pipermail/linuxppc-dev/2005-August/019362.html

The generated tree is part static and part dynamic.

There is a static part which is compiled in with DTC and a dynamic
part which is programmatically appended.

You'll need a fairly recent DTC tool, which is available by git at

  rsync://ozlabs.org/dtc/dtc.git

The xxd binary dumper is needed too which I got from

  ftp://ftp.uni-erlangen.de/pub/utilities/etc/xxd-1.10.tar.gz


Pantelis Antoniou, 13 Oct 2005

Power-On-Self-Test support in U-Boot
------------------------------------

This project is to support Power-On-Self-Test (POST) in U-Boot.

1. High-level requirements

The key requirements for this project are as follows:

1) The project shall develop a flexible framework for implementing
   and running Power-On-Self-Test in U-Boot. This framework shall
   possess the following features:

   o) Extensibility

      The framework shall allow adding/removing/replacing POST tests.
      Also, standalone POST tests shall be supported.

   o) Configurability

      The framework shall allow run-time configuration of the lists
      of tests running on normal/power-fail booting.

   o) Controllability

      The framework shall support manual running of the POST tests.

2) The results of tests shall be saved so that it will be possible to
   retrieve them from Linux.

3) The following POST tests shall be developed for MPC823E-based
   boards:

   o) CPU test
   o) Cache test
   o) Memory test
   o) Ethernet test
   o) Serial channels test
   o) Watchdog timer test
   o) RTC test
   o) I2C test
   o) SPI test
   o) USB test

4) The LWMON board shall be used for reference.

2. Design

This section details the key points of the design for the project.
The whole project can be divided into two independent tasks:
enhancing U-Boot/Linux to provide a common framework for running POST
tests and developing such tests for particular hardware.

2.1. Hardware-independent POST layer

A new optional module will be added to U-Boot, which will run POST
tests and collect their results at boot time. Also, U-Boot will
support running POST tests manually at any time by executing a
special command from the system console.

The list of available POST tests will be configured at U-Boot build
time. The POST layer will allow the developer to add any custom POST
tests. All POST tests will be divided into the following groups:

  1) Tests running on power-on booting only

     This group will contain those tests that run only once on
     power-on reset (e.g. watchdog test)

  2) Tests running on normal booting only

     This group will contain those tests that do not take much
     time and can be run on the regular basis (e.g. CPU test)

  3) Tests running in special "slow test mode" only

     This group will contain POST tests that consume much time
     and cannot be run regularly (e.g. strong memory test, I2C test)

  4) Manually executed tests

     This group will contain those tests that can be run manually.

If necessary, some tests may belong to several groups simultaneously.
For example, SDRAM test may run in both normal and "slow test" mode.
In normal mode, SDRAM test may perform a fast superficial memory test
only, while running in slow test mode it may perform a full memory
check-up.

Also, all tests will be discriminated by the moment they run at.
Specifically, the following groups will be singled out:

  1) Tests running before relocating to RAM

     These tests will run immediately after initializing RAM
     as to enable modifying it without taking care of its
     contents. Basically, this group will contain memory tests
     only.

  2) Tests running after relocating to RAM

     These tests will run immediately before entering the main
     loop as to guarantee full hardware initialization.

The POST layer will also distinguish a special group of tests that
may cause system rebooting (e.g. watchdog test). For such tests, the
layer will automatically detect rebooting and will notify the test
about it.

2.1.1. POST layer interfaces

This section details the interfaces between the POST layer and the
rest of U-Boot.

The following flags will be defined:

#define POST_POWERON		0x01	/* test runs on power-on booting */
#define POST_NORMAL		0x02	/* test runs on normal booting */
#define POST_SLOWTEST		0x04	/* test is slow, enabled by key press */
#define POST_POWERTEST		0x08	/* test runs after watchdog reset */
#define POST_ROM		0x100	/* test runs in ROM */
#define POST_RAM		0x200	/* test runs in RAM */
#define POST_MANUAL		0x400	/* test can be executed manually */
#define POST_REBOOT		0x800	/* test may cause rebooting */
#define POST_PREREL             0x1000  /* test runs before relocation */

The POST layer will export the following interface routines:

  o) int post_run(bd_t *bd, char *name, int flags);

     This routine will run the test (or the group of tests) specified
     by the name and flag arguments. More specifically, if the name
     argument is not NULL, the test with this name will be performed,
     otherwise all tests running in ROM/RAM (depending on the flag
     argument) will be executed. This routine will be called at least
     twice with name set to NULL, once from board_init_f() and once
     from board_init_r(). The flags argument will also specify the
     mode the test is executed in (power-on, normal, power-fail,
     manual).

  o) void post_reloc(ulong offset);

     This routine will be called from board_init_r() and will
     relocate the POST test table.

  o) int post_info(char *name);

     This routine will print the list of all POST tests that can be
     executed manually if name is NULL, and the description of a
     particular test if name is not NULL.

  o) int post_log(char *format, ...);

     This routine will be called from POST tests to log their
     results. Basically, this routine will print the results to
     stderr. The format of the arguments and the return value
     will be identical to the printf() routine.

Also, the following board-specific routines will be called from the
U-Boot common code:

  o) int board_power_mode(void)

     This routine will return the mode the system is running in
     (POST_POWERON, POST_NORMAL or POST_SHUTDOWN).

  o) void board_poweroff(void)

     This routine will turn off the power supply of the board. It
     will be called on power-fail booting after running all POST
     tests.

  o) int post_hotkeys_pressed(gd_t *gd)

     This routine will scan the keyboard to detect if a magic key
     combination has been pressed, or otherwise detect if the
     power-on long-running tests shall be executed or not ("normal"
     versus "slow" test mode).

The list of available POST tests be kept in the post_tests array
filled at U-Boot build time. The format of entry in this array will
be as follows:

struct post_test {
    char *name;
    char *cmd;
    char *desc;
    int flags;
    int (*test)(bd_t *bd, int flags);
};

  o) name

     This field will contain a short name of the test, which will be
     used in logs and on listing POST tests (e.g. CPU test).

  o) cmd

     This field will keep a name for identifying the test on manual
     testing (e.g. cpu). For more information, refer to section
     "Command line interface".

  o) desc

     This field will contain a detailed description of the test,
     which will be printed on user request. For more information, see
     section "Command line interface".

  o) flags

     This field will contain a combination of the bit flags described
     above, which will specify the mode the test is running in
     (power-on, normal, power-fail or manual mode), the moment it
     should be run at (before or after relocating to RAM), whether it
     can cause system rebooting or not.

  o) test

     This field will contain a pointer to the routine that will
     perform the test, which will take 2 arguments. The first
     argument will be a pointer to the board info structure, while
     the second will be a combination of bit flags specifying the
     mode the test is running in (POST_POWERON, POST_NORMAL,
     POST_SLOWTEST, POST_MANUAL) and whether the last execution of
     the test caused system rebooting (POST_REBOOT). The routine will
     return 0 on successful execution of the test, and 1 if the test
     failed.

The lists of the POST tests that should be run at power-on/normal/
power-fail booting will be kept in the environment. Namely, the
following environment variables will be used: post_poweron,
powet_normal, post_slowtest.

2.1.2. Test results

The results of tests will be collected by the POST layer. The POST
log will have the following format:

...
--------------------------------------------
START <name>
<test-specific output>
[PASSED|FAILED]
--------------------------------------------
...

Basically, the results of tests will be printed to stderr. This
feature may be enhanced in future to spool the log to a serial line,
save it in non-volatile RAM (NVRAM), transfer it to a dedicated
storage server and etc.

2.1.3. Integration issues

All POST-related code will be #ifdef'ed with the CONFIG_POST macro.
This macro will be defined in the config_<board>.h file for those
boards that need POST. The CONFIG_POST macro will contain the list of
POST tests for the board. The macro will have the format of array
composed of post_test structures:

#define CONFIG_POST \
	{
		"On-board peripherals test", "board", \
		"  This test performs full check-up of the " \
		"on-board hardware.", \
		POST_RAM | POST_SLOWTEST, \
		&board_post_test \
	}

A new file, post.h, will be created in the include/ directory. This
file will contain common POST declarations and will define a set of
macros that will be reused for defining CONFIG_POST. As an example,
the following macro may be defined:

#define POST_CACHE \
	{
		"Cache test", "cache", \
		"  This test verifies the CPU cache operation.", \
		POST_RAM | POST_NORMAL, \
		&cache_post_test \
	}

A new subdirectory will be created in the U-Boot root directory. It
will contain the source code of the POST layer and most of POST
tests. Each POST test in this directory will be placed into a
separate file (it will be needed for building standalone tests). Some
POST tests (mainly those for testing peripheral devices) will be
located in the source files of the drivers for those devices. This
way will be used only if the test subtantially uses the driver.

2.1.4. Standalone tests

The POST framework will allow to develop and run standalone tests. A
user-space library will be developed to provide the POST interface
functions to standalone tests.

2.1.5. Command line interface

A new command, diag, will be added to U-Boot. This command will be
used for listing all available hardware tests, getting detailed
descriptions of them and running these tests.

More specifically, being run without any arguments, this command will
print the list of all available hardware tests:

=> diag
Available hardware tests:
  cache             - cache test
  cpu               - CPU test
  enet              - SCC/FCC ethernet test
Use 'diag [<test1> [<test2>]] ... ' to get more info.
Use 'diag run [<test1> [<test2>]] ... ' to run tests.
=>

If the first argument to the diag command is not 'run', detailed
descriptions of the specified tests will be printed:

=> diag cpu cache
cpu - CPU test
  This test verifies the arithmetic logic unit of CPU.
cache - cache test
  This test verifies the CPU cache operation.
=>

If the first argument to diag is 'run', the specified tests will be
executed. If no tests are specified, all available tests will be
executed.

It will be prohibited to execute tests running in ROM manually. The
'diag' command will not display such tests and/or run them.

2.1.6. Power failure handling

The Linux kernel will be modified to detect power failures and
automatically reboot the system in such cases. It will be assumed
that the power failure causes a system interrupt.

To perform correct system shutdown, the kernel will register a
handler of the power-fail IRQ on booting. Being called, the handler
will run /sbin/reboot using the call_usermodehelper() routine.
/sbin/reboot will automatically bring the system down in a secure
way. This feature will be configured in/out from the kernel
configuration file.

The POST layer of U-Boot will check whether the system runs in
power-fail mode. If it does, the system will be powered off after
executing all hardware tests.

2.1.7. Hazardous tests

Some tests may cause system rebooting during their execution. For
some tests, this will indicate a failure, while for the Watchdog
test, this means successful operation of the timer.

In order to support such tests, the following scheme will be
implemented. All the tests that may cause system rebooting will have
the POST_REBOOT bit flag set in the flag field of the correspondent
post_test structure. Before starting tests marked with this bit flag,
the POST layer will store an identification number of the test in a
location in IMMR. On booting, the POST layer will check the value of
this variable and if it is set will skip over the tests preceding the
failed one. On second execution of the failed test, the POST_REBOOT
bit flag will be set in the flag argument to the test routine. This
will allow to detect system rebooting on the previous iteration. For
example, the watchdog timer test may have the following
declaration/body:

...
#define POST_WATCHDOG \
	{
		"Watchdog timer test", "watchdog", \
		"  This test checks the watchdog timer.", \
		POST_RAM | POST_POWERON | POST_REBOOT, \
		&watchdog_post_test \
	}
...

...
int watchdog_post_test(bd_t *bd, int flags)
{
	unsigned long start_time;

	if (flags & POST_REBOOT) {
		/* Test passed */
		return 0;
	} else {
		/* disable interrupts */
		disable_interrupts();
		/* 10-second delay */
		...
		/* if we've reached this, the watchdog timer does not work */
		enable_interrupts();
		return 1;
	}
}
...

2.2. Hardware-specific details

This project will also develop a set of POST tests for MPC8xx- based
systems. This section provides technical details of how it will be
done.

2.2.1. Generic PPC tests

The following generic POST tests will be developed:

  o) CPU test

     This test will check the arithmetic logic unit (ALU) of CPU. The
     test will take several milliseconds and will run on normal
     booting.

  o) Cache test

     This test will verify the CPU cache (L1 cache). The test will
     run on normal booting.

  o) Memory test

     This test will examine RAM and check it for errors. The test
     will always run on booting. On normal booting, only a limited
     amount of RAM will be checked. On power-fail booting a fool
     memory check-up will be performed.

2.2.1.1. CPU test

This test will verify the following ALU instructions:

  o) Condition register istructions

     This group will contain: mtcrf, mfcr, mcrxr, crand, crandc,
     cror, crorc, crxor, crnand, crnor, creqv, mcrf.

     The mtcrf/mfcr instructions will be tested by loading different
     values into the condition register (mtcrf), moving its value to
     a general-purpose register (mfcr) and comparing this value with
     the expected one. The mcrxr instruction will be tested by
     loading a fixed value into the XER register (mtspr), moving XER
     value to the condition register (mcrxr), moving it to a
     general-purpose register (mfcr) and comparing the value of this
     register with the expected one. The rest of instructions will be
     tested by loading a fixed value into the condition register
     (mtcrf), executing each instruction several times to modify all
     4-bit condition fields, moving the value of the conditional
     register to a general-purpose register (mfcr) and comparing it
     with the expected one.

  o) Integer compare instructions

     This group will contain: cmp, cmpi, cmpl, cmpli.

     To verify these instructions the test will run them with
     different combinations of operands, read the condition register
     value and compare it with the expected one. More specifically,
     the test will contain a pre-built table containing the
     description of each test case: the instruction, the values of
     the operands, the condition field to save the result in and the
     expected result.

  o) Arithmetic instructions

     This group will contain: add, addc, adde, addme, addze, subf,
     subfc, subfe, subme, subze, mullw, mulhw, mulhwu, divw, divwu,
     extsb, extsh.

     The test will contain a pre-built table of instructions,
     operands, expected results and expected states of the condition
     register. For each table entry, the test will cyclically use
     different sets of operand registers and result registers. For
     example, for instructions that use 3 registers on the first
     iteration r0/r1 will be used as operands and r2 for result. On
     the second iteration, r1/r2 will be used as operands and r3 as
     for result and so on. This will enable to verify all
     general-purpose registers.

  o) Logic instructions

     This group will contain: and, andc, andi, andis, or, orc, ori,
     oris, xor, xori, xoris, nand, nor, neg, eqv, cntlzw.

     The test scheme will be identical to that from the previous
     point.

  o) Shift instructions

     This group will contain: slw, srw, sraw, srawi, rlwinm, rlwnm,
     rlwimi

     The test scheme will be identical to that from the previous
     point.

  o) Branch instructions

     This group will contain: b, bl, bc.

     The first 2 instructions (b, bl) will be verified by jumping to
     a fixed address and checking whether control was transferred to
     that very point. For the bl instruction the value of the link
     register will be checked as well (using mfspr). To verify the bc
     instruction various combinations of the BI/BO fields, the CTR
     and the condition register values will be checked. The list of
     such combinations will be pre-built and linked in U-Boot at
     build time.

  o) Load/store instructions

     This group will contain: lbz(x)(u), lhz(x)(u), lha(x)(u),
     lwz(x)(u), stb(x)(u), sth(x)(u), stw(x)(u).

     All operations will be performed on a 16-byte array. The array
     will be 4-byte aligned. The base register will point to offset
     8. The immediate offset (index register) will range in [-8 ...
     +7]. The test cases will be composed so that they will not cause
     alignment exceptions. The test will contain a pre-built table
     describing all test cases. For store instructions, the table
     entry will contain: the instruction opcode, the value of the
     index register and the value of the source register. After
     executing the instruction, the test will verify the contents of
     the array and the value of the base register (it must change for
     "store with update" instructions). For load instructions, the
     table entry will contain: the instruction opcode, the array
     contents, the value of the index register and the expected value
     of the destination register. After executing the instruction,
     the test will verify the value of the destination register and
     the value of the base register (it must change for "load with
     update" instructions).

  o) Load/store multiple/string instructions


The CPU test will run in RAM in order to allow run-time modification
of the code to reduce the memory footprint.

2.2.1.2 Special-Purpose Registers Tests

TBD.

2.2.1.3. Cache test

To verify the data cache operation the following test scenarios will
be used:

  1) Basic test #1

    - turn on the data cache
    - switch the data cache to write-back or write-through mode
    - invalidate the data cache
    - write the negative pattern to a cached area
    - read the area

    The negative pattern must be read at the last step

  2) Basic test #2

    - turn on the data cache
    - switch the data cache to write-back or write-through mode
    - invalidate the data cache
    - write the zero pattern to a cached area
    - turn off the data cache
    - write the negative pattern to the area
    - turn on the data cache
    - read the area

    The negative pattern must be read at the last step

  3) Write-through mode test

    - turn on the data cache
    - switch the data cache to write-through mode
    - invalidate the data cache
    - write the zero pattern to a cached area
    - flush the data cache
    - write the negative pattern to the area
    - turn off the data cache
    - read the area

    The negative pattern must be read at the last step

  4) Write-back mode test

    - turn on the data cache
    - switch the data cache to write-back mode
    - invalidate the data cache
    - write the negative pattern to a cached area
    - flush the data cache
    - write the zero pattern to the area
    - invalidate the data cache
    - read the area

    The negative pattern must be read at the last step

To verify the instruction cache operation the following test
scenarios will be used:

  1) Basic test #1

    - turn on the instruction cache
    - unlock the entire instruction cache
    - invalidate the instruction cache
    - lock a branch instruction in the instruction cache
    - replace the branch instruction with "nop"
    - jump to the branch instruction
    - check that the branch instruction was executed

  2) Basic test #2

    - turn on the instruction cache
    - unlock the entire instruction cache
    - invalidate the instruction cache
    - jump to a branch instruction
    - check that the branch instruction was executed
    - replace the branch instruction with "nop"
    - invalidate the instruction cache
    - jump to the branch instruction
    - check that the "nop" instruction was executed

The CPU test will run in RAM in order to allow run-time modification
of the code.

2.2.1.4. Memory test

The memory test will verify RAM using sequential writes and reads
to/from RAM. Specifically, there will be several test cases that will
use different patterns to verify RAM. Each test case will first fill
a region of RAM with one pattern and then read the region back and
compare its contents with the pattern. The following patterns will be
used:

 1) zero pattern (0x00000000)
 2) negative pattern (0xffffffff)
 3) checkerboard pattern (0x55555555, 0xaaaaaaaa)
 4) bit-flip pattern ((1 << (offset % 32)), ~(1 << (offset % 32)))
 5) address pattern (offset, ~offset)

Patterns #1, #2 will help to find unstable bits. Patterns #3, #4 will
be used to detect adherent bits, i.e. bits whose state may randomly
change if adjacent bits are modified. The last pattern will be used
to detect far-located errors, i.e. situations when writing to one
location modifies an area located far from it. Also, usage of the
last pattern will help to detect memory controller misconfigurations
when RAM represents a cyclically repeated portion of a smaller size.

Being run in normal mode, the test will verify only small 4Kb regions
of RAM around each 1Mb boundary. For example, for 64Mb RAM the
following areas will be verified: 0x00000000-0x00000800,
0x000ff800-0x00100800, 0x001ff800-0x00200800, ..., 0x03fff800-
0x04000000. If the test is run in power-fail mode, it will verify the
whole RAM.

The memory test will run in ROM before relocating U-Boot to RAM in
order to allow RAM modification without saving its contents.

2.2.2. Common tests

This section describes tests that are not based on any hardware
peculiarities and use common U-Boot interfaces only. These tests do
not need any modifications for porting them to another board/CPU.

2.2.2.1. I2C test

For verifying the I2C bus, a full I2C bus scanning will be performed
using the i2c_probe() routine. If a board defines
CONFIG_SYS_POST_I2C_ADDRS the I2C test will pass if all devices
listed in CONFIG_SYS_POST_I2C_ADDRS are found, and no additional
devices are detected.  If CONFIG_SYS_POST_I2C_ADDRS is not defined
the test will pass if any I2C device is found.

The CONFIG_SYS_POST_I2C_IGNORES define can be used to list I2C
devices which may or may not be present when using
CONFIG_SYS_POST_I2C_ADDRS.  The I2C POST test will pass regardless
if the devices in CONFIG_SYS_POST_I2C_IGNORES are found or not.
This is useful in cases when I2C devices are optional (eg on a
daughtercard that may or may not be present) or not critical
to board operation.

2.2.2.2. Watchdog timer test

To test the watchdog timer the scheme mentioned above (refer to
section "Hazardous tests") will be used. Namely, this test will be
marked with the POST_REBOOT bit flag. On the first iteration, the
test routine will make a 10-second delay. If the system does not
reboot during this delay, the watchdog timer is not operational and
the test fails. If the system reboots, on the second iteration the
POST_REBOOT bit will be set in the flag argument to the test routine.
The test routine will check this bit and report a success if it is
set.

2.2.2.3. RTC test

The RTC test will use the rtc_get()/rtc_set() routines. The following
features will be verified:

  o) Time uniformity

     This will be verified by reading RTC in polling within a short
     period of time (5-10 seconds).

  o) Passing month boundaries

     This will be checked by setting RTC to a second before a month
     boundary and reading it after its passing the boundary. The test
     will be performed for both leap- and nonleap-years.

2.2.3. MPC8xx peripherals tests

This project will develop a set of tests verifying the peripheral
units of MPC8xx processors. Namely, the following controllers of the
MPC8xx communication processor module (CPM) will be tested:

  o) Serial Management Controllers (SMC)

  o) Serial Communication Controllers (SCC)

2.2.3.1. Ethernet tests (SCC)

The internal (local) loopback mode will be used to test SCC. To do
that the controllers will be configured accordingly and several
packets will be transmitted. These tests may be enhanced in future to
use external loopback for testing. That will need appropriate
reconfiguration of the physical interface chip.

The test routines for the SCC ethernet tests will be located in
arch/powerpc/cpu/mpc8xx/scc.c.

2.2.3.2. UART tests (SMC/SCC)

To perform these tests the internal (local) loopback mode will be
used. The SMC/SCC controllers will be configured to connect the
transmitter output to the receiver input. After that, several bytes
will be transmitted. These tests may be enhanced to make to perform
"external" loopback test using a loopback cable. In this case, the
test will be executed manually.

The test routine for the SMC/SCC UART tests will be located in
arch/powerpc/cpu/mpc8xx/serial.c.

2.2.3.3. USB test

TBD

2.2.3.4. SPI test

TBD

To use SNTP support, add define CONFIG_CMD_SNTP to the
configuration file of the board.

The "sntp" command gets network time from NTP time server and
syncronize RTC of the board. This command needs the command line
parameter of server's IP address or environment variable
"ntpserverip". The network time is sent as UTC. So if you want to
set local time to RTC, set the offset in second from UTC to the
environment variable "time offset".

If the DHCP server provides time server's IP or time offset, you
don't need to set the above environment variables yourself.

Current limitations of SNTP support:
1. The roundtrip time is ignored.
2. Only the 1st NTP server IP, in the option ntp-servers of DHCP, will
   be used.

Generic SPL framework
=====================

Overview
--------

To unify all existing implementations for a secondary program loader (SPL)
and to allow simply adding of new implementations this generic SPL framework
has been created. With this framework almost all source files for a board
can be reused. No code duplication or symlinking is necessary anymore.


How it works
------------

The object files for SPL are built separately and placed in the "spl" directory.
The final binaries which are generated are u-boot-spl, u-boot-spl.bin and
u-boot-spl.map.

A config option named CONFIG_SPL_BUILD is enabled by Kconfig for SPL.
Source files can therefore be compiled for SPL with different settings.

For example:

ifeq ($(CONFIG_SPL_BUILD),y)
obj-y += board_spl.o
else
obj-y += board.o
endif

obj-$(CONFIG_SPL_BUILD) += foo.o

#ifdef CONFIG_SPL_BUILD
	foo();
#endif


The building of SPL images can be enabled by CONFIG_SPL option in Kconfig.

Because SPL images normally have a different text base, one has to be
configured by defining CONFIG_SPL_TEXT_BASE. The linker script has to be
defined with CONFIG_SPL_LDSCRIPT.

To support generic U-Boot libraries and drivers in the SPL binary one can
optionally define CONFIG_SPL_XXX_SUPPORT. Currently following options
are supported:

CONFIG_SPL_LIBCOMMON_SUPPORT (common/libcommon.o)
CONFIG_SPL_LIBDISK_SUPPORT (disk/libdisk.o)
CONFIG_SPL_I2C_SUPPORT (drivers/i2c/libi2c.o)
CONFIG_SPL_GPIO_SUPPORT (drivers/gpio/libgpio.o)
CONFIG_SPL_MMC_SUPPORT (drivers/mmc/libmmc.o)
CONFIG_SPL_SERIAL_SUPPORT (drivers/serial/libserial.o)
CONFIG_SPL_SPI_FLASH_SUPPORT (drivers/mtd/spi/libspi_flash.o)
CONFIG_SPL_SPI_SUPPORT (drivers/spi/libspi.o)
CONFIG_SPL_FAT_SUPPORT (fs/fat/libfat.o)
CONFIG_SPL_EXT_SUPPORT
CONFIG_SPL_LIBGENERIC_SUPPORT (lib/libgeneric.o)
CONFIG_SPL_POWER_SUPPORT (drivers/power/libpower.o)
CONFIG_SPL_NAND_SUPPORT (drivers/mtd/nand/raw/libnand.o)
CONFIG_SPL_DRIVERS_MISC_SUPPORT (drivers/misc)
CONFIG_SPL_DMA_SUPPORT (drivers/dma/libdma.o)
CONFIG_SPL_POST_MEM_SUPPORT (post/drivers/memory.o)
CONFIG_SPL_NAND_LOAD (drivers/mtd/nand/raw/nand_spl_load.o)
CONFIG_SPL_SPI_LOAD (drivers/mtd/spi/spi_spl_load.o)
CONFIG_SPL_RAM_DEVICE (common/spl/spl.c)
CONFIG_SPL_WATCHDOG_SUPPORT (drivers/watchdog/libwatchdog.o)


Debugging
---------

When building SPL with DEBUG set you may also need to set CONFIG_PANIC_HANG
as in most cases do_reset is not defined within SPL.


Estimating stack usage
----------------------

With gcc 4.6 (and later) and the use of GNU cflow it is possible to estimate
stack usage at various points in run sequence of SPL.  The -fstack-usage option
to gcc will produce '.su' files (such as arch/arm/cpu/armv7/syslib.su) that
will give stack usage information and cflow can construct program flow.

Must have gcc 4.6 or later, which supports -fstack-usage

1) Build normally
2) Perform the following shell command to generate a list of C files used in
SPL:
$ find spl -name '*.su' | sed -e 's:^spl/::' -e 's:[.]su$:.c:' > used-spl.list
3) Execute cflow:
$ cflow --main=board_init_r `cat used-spl.list` 2>&1 | $PAGER

cflow will spit out a number of warnings as it does not parse
the config files and picks functions based on #ifdef.  Parsing the '.i'
files instead introduces another set of headaches.  These warnings are
not usually important to understanding the flow, however.

Generic TPL framework
=====================

Overview
--------

TPL---Third Program Loader.

Due to the SPL on some boards(powerpc mpc85xx) has a size limit and cannot
be compatible with all the external device(e.g. DDR). So add a tertiary
program loader (TPL) to enable a loader stub loaded by the code from the
SPL. It loads the final uboot image into DDR, then jump to it to begin
execution. Now, only the powerpc mpc85xx has this requirement and will
implemente it.

Keep consistent with SPL, with this framework almost all source files for a
board can be reused. No code duplication or symlinking is necessary anymore.

How it works
------------

There has been a directory $(srctree)/spl which contains only a Makefile. The
Makefile is shared by SPL and TPL.

The object files are built separately for SPL/TPL and placed in the
directory spl/tpl. The final binaries which are generated are
u-boot-{spl|tpl}, u-boot-{spl|tpl}.bin and u-boot-{spl|tpl}.map.

During the TPL build a variable named CONFIG_TPL_BUILD is exported in the
make environment and also appended to CPPFLAGS with -DCONFIG_TPL_BUILD.

The SPL options are shared by SPL and TPL, the board config file should
determine which SPL options to choose based on whether CONFIG_TPL_BUILD
is set. Source files can be compiled for TPL with options choosed in the
board config file.

For example:

spl/Makefile:
LIBS-$(CONFIG_SPL_LIBCOMMON_SUPPORT) += common/libcommon.o

CONFIG_SPL_LIBCOMMON_SUPPORT is defined in board config file:
#ifdef CONFIG_TPL_BUILD
#define CONFIG_SPL_LIBCOMMON_SUPPORT
#endif

U-Boot has networking support for VLANs (802.1q), and CDP (Cisco
Discovery Protocol).

You control the sending/receiving of VLAN tagged packets with the
"vlan" environmental variable. When not present no tagging is
performed.

CDP is used mainly to discover your device VLAN(s) when connected to
a Cisco switch.

Note: In order to enable CDP support a small change is needed in the
networking driver. You have to enable reception of the
01:00:0c:cc:cc:cc MAC address which is a multicast address.

Various defines control CDP; see the README section.

This file contains API information of the initialization code written for
Vitesse cross-point devices, VSC3316 and VSC3308 for board B4860QDS

Author: Shaveta Leekha <shaveta@freescale.com>

About Device:
=============
VSC 3316/3308 is a low-power, low-cost asynchronous crosspoint switch capable of data rates upto 11.5Gbps.

VSC3316 has 16 input and 16 output ports whereas VSC3308 has 8 input and 8 output ports. Programming of these devices are performed by two-wire or four-wire serial interface.

Initialization:
===============
On reset, VSC devices are in low-power state with all inputs, outputs and connections in an off state.
First thing required is to program it to interface with either two-wire or four-wire interface.
In our case the interface is two-wire I2C serial interface. So the value in Interface mode register at address 79.h to be written is 0x02 for two-wire interface. Also for crosspoint connections to be activated, 01.h value need to be written in 75.h (core configuration register).

API Overview:
=============

	vsc_if_enable(u8 vsc_addr):
	--------------------------
		This API programs VSC to interface with either two-wire or four-wire interface. In our case the interface is two-wire I2C serial interface. So the value in Interface mode register at address 79.h to be written is 0x02 for two-wire interface.
	Parameters:
		vsc_addr - Address of the VSC device on board.


	vsc3316_config(u8 vsc_addr, int con_arr[][2], u8 num_con):
	---------------------------------------------------------
	This API configures the VSC3316 device for required connections. Connection through the VSC device requires the inputs and outputs to be properly configured.
	Connection registers are on page 00. It Configures the selected input and output correctly and join them to make a connection. It also program Input state register, Global input ISE, Global input LOS, Global core control, Output mode register and core control registers etc.
	vsc3308_config(u8 vsc_addr, int con_arr[][2], u8 num_con) does the essential configurations for VSC3308.

	Parameters:
		vsc_addr - Address of the VSC device on board.
		con_arr - connection array
		num_con - number of connections to be configured

	vsc_wp_config(u8 vsc_addr):
	--------------------------
		For crosspoint connections to be activated, 01.h value need to be written in 75.h (core configuration register), which is done by this API.
	Parameters:
		vsc_addr - Address of the VSC device on board.

Andes Technology SoC AG101P
===========================

AG101P is the mainline SoC produced by Andes Technology using N1213 CPU core
with FPU and DDR contoller support.
AG101P has integrated both AHB and APB bus and many periphals for application
and product development.

ADP-AG101P
=========

ADP-AG101P is the SoC with AG101 hardcore CPU.

Configurations
==============

CONFIG_MEM_REMAP:
	Doing memory remap is essential for preparing some non-OS or RTOS
	applications.

CONFIG_SKIP_LOWLEVEL_INIT:
	If you want to boot this system from SPI ROM and bypass e-bios (the
	other boot loader on ROM). You should undefine CONFIG_SKIP_LOWLEVEL_INIT
	in "include/configs/adp-ag101p.h".

Build and boot steps
====================

build:
1. Prepare the toolchains and make sure the $PATH to toolchains is correct.
2. Use `make adp-ag101p_defconfig` in u-boot root to build the image.

Burn u-boot to SPI ROM:
====================

This section will be added later.

Android Fastboot
~~~~~~~~~~~~~~~~

Overview
========
The protocol that is used over USB is described in
README.android-fastboot-protocol in same directory.

The current implementation is a minimal support of the erase command,the
"oem format" command and flash command;it only supports eMMC devices.

Client installation
===================
The counterpart to this gadget is the fastboot client which can
be found in Android's platform/system/core repository in the fastboot
folder. It runs on Windows, Linux and even OSX. Linux user are lucky since
they only need libusb.
Windows users need to bring some time until they have Android SDK (currently
http://dl.google.com/android/installer_r12-windows.exe) installed. You
need to install ADB package which contains the required glue libraries for
accessing USB. Also you need "Google USB driver package" and "SDK platform
tools". Once installed the usb driver is placed in your SDK folder under
extras\google\usb_driver. The android_winusb.inf needs a line like

   %SingleBootLoaderInterface% = USB_Install, USB\VID_0451&PID_D022

either in the [Google.NTx86] section for 32bit Windows or [Google.NTamd64]
for 64bit Windows. VID and PID should match whatever the fastboot is
advertising.

Board specific
==============
The fastboot gadget relies on the USB download gadget, so the following
options must be configured:

CONFIG_USB_GADGET_DOWNLOAD
CONFIG_USB_GADGET_VENDOR_NUM
CONFIG_USB_GADGET_PRODUCT_NUM
CONFIG_USB_GADGET_MANUFACTURER

NOTE: The CONFIG_USB_GADGET_VENDOR_NUM must be one of the numbers supported by
the fastboot client. The list of vendor IDs supported can be found in the
fastboot client source code (fastboot.c) mentioned above.

The fastboot function is enabled by defining CONFIG_USB_FUNCTION_FASTBOOT,
CONFIG_CMD_FASTBOOT and CONFIG_ANDROID_BOOT_IMAGE.

The fastboot protocol requires a large memory buffer for downloads. This
buffer should be as large as possible for a platform. The location of the
buffer and size are set with CONFIG_FASTBOOT_BUF_ADDR and
CONFIG_FASTBOOT_BUF_SIZE.

Fastboot partition aliases can also be defined for devices where GPT
limitations prevent user-friendly partition names such as "boot", "system"
and "cache".  Or, where the actual partition name doesn't match a standard
partition name used commonly with fastboot.  Current implentation checks
aliases when accessing partitions by name (flash_write and erase functions).
To define a partition alias add an environment variable similar to:
fastboot_partition_alias_<alias partition name>=<actual partition name>
Example: fastboot_partition_alias_boot=LNX

Partition Names
===============
The Fastboot implementation in U-boot allows to write images into disk
partitions (currently on eMMC). Target partitions are referred on the host
computer by their names.

For GPT/EFI the respective partition name is used.

For MBR the partitions are referred by generic names according to the
following schema:

  <device type> <device index letter> <partition index>

Example: hda3, sdb1, usbda1

The device type is as follows:

  * IDE, ATAPI and SATA disks: hd
  * SCSI disks: sd
  * USB media: usbd
  * MMC and SD cards: mmcsd
  * Disk on chip: docd
  * other: xx

The device index starts from 'a' and refers to the interface (e.g. USB
controller, SD/MMC controller) or disk index. The partition index starts
from 1 and describes the partition number on the particular device.

Writing Partition Table
=======================
Fastboot also allows to write the partition table to the media. This can be
done by writing the respective partition table image to a special target
"gpt" or "mbr". These names can be customized by defining the following
configuration options:

CONFIG_FASTBOOT_GPT_NAME
CONFIG_FASTBOOT_MBR_NAME

In Action
=========
Enter into fastboot by executing the fastboot command in u-boot and you
should see:
|GADGET DRIVER: usb_dnl_fastboot

On the client side you can fetch the bootloader version for instance:
|>fastboot getvar bootloader-version
|bootloader-version: U-Boot 2014.04-00005-gd24cabc
|finished. total time: 0.000s

or initiate a reboot:
|>fastboot reboot

and once the client comes back, the board should reset.

You can also specify a kernel image to boot. You have to either specify
the an image in Android format _or_ pass a binary kernel and let the
fastboot client wrap the Android suite around it. On OMAP for instance you
take zImage kernel and pass it to the fastboot client:

|>fastboot -b 0x80000000 -c "console=ttyO2 earlyprintk root=/dev/ram0
|	mem=128M" boot zImage
|creating boot image...
|creating boot image - 1847296 bytes
|downloading 'boot.img'...
|OKAY [  2.766s]
|booting...
|OKAY [ -0.000s]
|finished. total time: 2.766s

and on the gadget side you should see:
|Starting download of 1847296 bytes
|........................................................
|downloading of 1847296 bytes finished
|Booting kernel..
|## Booting Android Image at 0x81000000 ...
|Kernel load addr 0x80008000 size 1801 KiB
|Kernel command line: console=ttyO2 earlyprintk root=/dev/ram0 mem=128M
|   Loading Kernel Image ... OK
|OK
|
|Starting kernel ...

FastBoot  Version  0.4
----------------------

The fastboot protocol is a mechanism for communicating with bootloaders
over USB.  It is designed to be very straightforward to implement, to
allow it to be used across a wide range of devices and from hosts running
Linux, Windows, or OSX.


Basic Requirements
------------------

* Two bulk endpoints (in, out) are required
* Max packet size must be 64 bytes for full-speed and 512 bytes for
  high-speed USB
* The protocol is entirely host-driven and synchronous (unlike the
  multi-channel, bi-directional, asynchronous ADB protocol)


Transport and Framing
---------------------

1. Host sends a command, which is an ascii string in a single
   packet no greater than 64 bytes.

2. Client response with a single packet no greater than 64 bytes.
   The first four bytes of the response are "OKAY", "FAIL", "DATA",
   or "INFO".  Additional bytes may contain an (ascii) informative
   message.

   a. INFO -> the remaining 60 bytes are an informative message
      (providing progress or diagnostic messages).  They should
      be displayed and then step #2 repeats

   b. FAIL -> the requested command failed.  The remaining 60 bytes
      of the response (if present) provide a textual failure message
      to present to the user.  Stop.

   c. OKAY -> the requested command completed successfully.  Go to #5

   d. DATA -> the requested command is ready for the data phase.
      A DATA response packet will be 12 bytes long, in the form of
      DATA00000000 where the 8 digit hexidecimal number represents
      the total data size to transfer.

3. Data phase.  Depending on the command, the host or client will
   send the indicated amount of data.  Short packets are always
   acceptable and zero-length packets are ignored.  This phase continues
   until the client has sent or received the number of bytes indicated
   in the "DATA" response above.

4. Client responds with a single packet no greater than 64 bytes.
   The first four bytes of the response are "OKAY", "FAIL", or "INFO".
   Similar to #2:

   a. INFO -> display the remaining 60 bytes and return to #4

   b. FAIL -> display the remaining 60 bytes (if present) as a failure
      reason and consider the command failed.  Stop.

   c. OKAY -> success.  Go to #5

5. Success.  Stop.


Example Session
---------------

Host:    "getvar:version"        request version variable

Client:  "OKAY0.4"               return version "0.4"

Host:    "getvar:nonexistant"    request some undefined variable

Client:  "OKAY"                  return value ""

Host:    "download:00001234"     request to send 0x1234 bytes of data

Client:  "DATA00001234"          ready to accept data

Host:    < 0x1234 bytes >        send data

Client:  "OKAY"                  success

Host:    "flash:bootloader"      request to flash the data to the bootloader

Client:  "INFOerasing flash"     indicate status / progress
         "INFOwriting flash"
         "OKAY"                  indicate success

Host:    "powerdown"             send a command

Client:  "FAILunknown command"   indicate failure


Command Reference
-----------------

* Command parameters are indicated by printf-style escape sequences.

* Commands are ascii strings and sent without the quotes (which are
  for illustration only here) and without a trailing 0 byte.

* Commands that begin with a lowercase letter are reserved for this
  specification.  OEM-specific commands should not begin with a
  lowercase letter, to prevent incompatibilities with future specs.

 "getvar:%s"           Read a config/version variable from the bootloader.
                       The variable contents will be returned after the
                       OKAY response.

 "download:%08x"       Write data to memory which will be later used
                       by "boot", "ramdisk", "flash", etc.  The client
                       will reply with "DATA%08x" if it has enough
                       space in RAM or "FAIL" if not.  The size of
                       the download is remembered.

  "verify:%08x"        Send a digital signature to verify the downloaded
                       data.  Required if the bootloader is "secure"
                       otherwise "flash" and "boot" will be ignored.

  "flash:%s"           Write the previously downloaded image to the
                       named partition (if possible).

  "erase:%s"           Erase the indicated partition (clear to 0xFFs)

  "boot"               The previously downloaded data is a boot.img
                       and should be booted according to the normal
                       procedure for a boot.img

  "continue"           Continue booting as normal (if possible)

  "reboot"             Reboot the device.

  "reboot-bootloader"  Reboot back into the bootloader.
                       Useful for upgrade processes that require upgrading
                       the bootloader and then upgrading other partitions
                       using the new bootloader.

  "powerdown"          Power off the device.



Client Variables
----------------

The "getvar:%s" command is used to read client variables which
represent various information about the device and the software
on it.

The various currently defined names are:

  version             Version of FastBoot protocol supported.
                      It should be "0.3" for this document.

  version-bootloader  Version string for the Bootloader.

  version-baseband    Version string of the Baseband Software

  product             Name of the product

  serialno            Product serial number

  secure              If the value is "yes", this is a secure
                      bootloader requiring a signature before
                      it will install or boot images.

Names starting with a lowercase character are reserved by this
specification.  OEM-specific names should not start with lowercase
characters.

Disabling I-cache:
- Set CONFIG_SYS_ICACHE_OFF

Disabling D-cache:
- Set CONFIG_SYS_DCACHE_OFF

Enabling I-cache:
- Make sure CONFIG_SYS_ICACHE_OFF is not set and call icache_enable().

Enabling D-cache:
- Make sure CONFIG_SYS_DCACHE_OFF is not set and call dcache_enable().

Enabling Caches at System Startup:
- Implement enable_caches() for your platform and enable the I-cache and
  D-cache from this function. This function is called immediately
  after relocation.

Guidelines for Working with D-cache:

Memory to Peripheral DMA:
- Flush the buffer after the MPU writes the data and before the DMA is
  initiated.

Peripheral to Memory DMA:
- Invalidate the buffer before starting the DMA. In case there are any dirty
  lines from the DMA buffer in the cache, subsequent cache-line replacements
  may corrupt the buffer in memory while the DMA is still going on. Cache-line
  replacement can happen if the CPU tries to bring some other memory locations
  into the cache while the DMA is going on.
- Invalidate the buffer after the DMA is complete and before the MPU reads
  it. This may be needed in addition to the invalidation before the DMA
  mentioned above, because in some processors memory contents can spontaneously
  come to the cache due to speculative memory access by the CPU. If this
  happens with the DMA buffer while DMA is going on we have a coherency problem.

Buffer Requirements:
- Any buffer that is invalidated(that is, typically the peripheral to
  memory DMA buffer) should be aligned to cache-line boundary both at
  at the beginning and at the end of the buffer.
- If the buffer is not cache-line aligned invalidation will be restricted
  to the aligned part. That is, one cache-line at the respective boundary
  may be left out while doing invalidation.
- A suitable buffer can be alloced on the stack using the
  ALLOC_CACHE_ALIGN_BUFFER macro.

Cleanup Before Linux:
- cleanup_before_linux() should flush the D-cache, invalidate I-cache, and
  disable MMU and caches.
- The following sequence is advisable while disabling d-cache:
  1. dcache_disable() - flushes and disables d-cache
  2. invalidate_dcache_all() - invalid any entry that came to the cache
	in the short period after the cache was flushed but before the
	cache got disabled.

To make relocation on arm working, the following changes are done:

At arch level: add linker flag -pie

	This causes the linker to generate fixup tables .rel.dyn and .dynsym,
	which must be applied to the relocated image before transferring
	control to it.

	These fixups are described in the ARM ELF documentation as type 23
	(program-base-relative) and 2 (symbol-relative)

At cpu level: modify linker file and add a relocation and fixup loop

	the linker file must be modified to include the .rel.dyn and .dynsym
	tables in the binary image, and to provide symbols for the relocation
	code to access these tables

	The relocation and fixup loop must be executed after executing
	board_init_f at initial location and before executing board_init_r
	at final location.

At board level:

	dram_init(): bd pointer is now at this point not accessible, so only
	detect the real dramsize, and store it in gd->ram_size. Bst detected
	with get_ram_size().

TODO:	move also dram initialization there on boards where it is possible.

	Setup of the the bd_t dram bank info is done in the new function
	dram_init_banksize() called after bd is accessible.

At lib level:

	Board.c code is adapted from ppc code

* WARNING ** WARNING ** WARNING ** WARNING ** WARNING ** WARNING ** WARNING *

Boards which are not fixed to support relocation will be REMOVED!

-----------------------------------------------------------------------------

For boards which boot from spl, it is possible to save one copy
if CONFIG_SYS_TEXT_BASE == relocation address! This prevents that uboot code
is copied again in relocate_code().

example for the tx25 board booting from NAND Flash:

a) cpu starts
b) it copies the first page in nand to internal ram
   (spl code)
c) end executes this code
d) this initialize CPU, RAM, ... and copy itself to RAM
   (this bin must fit in one page, so board_init_f()
    don;t fit in it ... )
e) there it copy u-boot to CONFIG_SYS_NAND_U_BOOT_DST and
   starts this image @ CONFIG_SYS_NAND_U_BOOT_START
f) u-boot code steps through board_init_f() and calculates
   the relocation address and copy itself to it

If CONFIG_SYS_TEXT_BASE == relocation address, the copying of u-boot
in f) could be saved.

-----------------------------------------------------------------------------

TODO

- fill in bd_t infos (check)
- adapt all boards

- maybe adapt CONFIG_SYS_TEXT_BASE (this must be checked from board maintainers)
  This *must* be done for boards, which boot from NOR flash

  on other boards if CONFIG_SYS_TEXT_BASE = relocation baseaddr, this saves
  one copying from u-boot code.

- new function dram_init_banksize() is actual board specific. Maybe
  we make a weak default function in arch/arm/lib/board.c ?

-----------------------------------------------------------------------------

Relocation with SPL (example for the tx25 booting from NAND Flash):

- cpu copies the first page from NAND to 0xbb000000 (IMX_NFC_BASE)
  and start with code execution on this address.

- The First page contains u-boot code from drivers/mtd/nand/raw/mxc_nand_spl.c
  which inits the dram, cpu registers, reloacte itself to CONFIG_SPL_TEXT_BASE	and loads
  the "real" u-boot to CONFIG_SYS_NAND_U_BOOT_DST and starts execution
  @CONFIG_SYS_NAND_U_BOOT_START

- This u-boot does no RAM init, nor CPU register setup. Just look
  where it has to copy and relocate itself to this address. If
  relocate address = CONFIG_SYS_TEXT_BASE (not the same, as the
  CONFIG_SPL_TEXT_BASE from the spl code), then there is no need
  to copy, just go on with bss clear and jump to board_init_r.

-----------------------------------------------------------------------------

How ELF relocations 23 and 2 work.

TBC

-------------------------------------------------------------------------------------

Debugging u-boot in RAM:
(example on the qong board)

-----------------

a) start debugger

arm-linux-gdb u-boot

[hs@pollux u-boot]$ arm-linux-gdb u-boot
GNU gdb Red Hat Linux (6.7-2rh)
Copyright (C) 2007 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=i686-pc-linux-gnu --target=arm-linux".
The target architecture is set automatically (currently arm)
..
(gdb)

-----------------

b) connect to target

target remote bdi10:2001

(gdb) target remote bdi10:2001
Remote debugging using bdi10:2001
0x8ff17f10 in ?? ()
(gdb)

-----------------

c) discard symbol-file

(gdb) symbol-file
Discard symbol table from `/home/hs/celf/u-boot/u-boot'? (y or n) y
No symbol file now.
(gdb)

-----------------

d) load new symbol table:

(gdb) add-symbol-file u-boot 0x8ff08000
add symbol table from file "u-boot" at
	.text_addr = 0x8ff08000
(y or n) y
Reading symbols from /home/hs/celf/u-boot/u-boot...done.
(gdb) c
Continuing.
^C
Program received signal SIGSTOP, Stopped (signal).
0x8ff17f18 in serial_getc () at serial_mxc.c:192
192		while (__REG(UART_PHYS + UTS) & UTS_RXEMPTY);
(gdb)

add-symbol-file u-boot 0x8ff08000
		       ^^^^^^^^^^
		       get this address from u-boot bdinfo command
		       or get it from gd->relocaddr in gdb

 => bdinfo
rch_number = XXXXXXXXXX
boot_params = XXXXXXXXXX
DRAM bank   = XXXXXXXXXX
-> start    = XXXXXXXXXX
-> size     = XXXXXXXXXX
ethaddr     = XXXXXXXXXX
ip_addr     = XXXXXXXXXX
baudrate    = XXXXXXXXXX
TLB addr    = XXXXXXXXXX
relocaddr   = 0x8ff08000
	      ^^^^^^^^^^
reloc off   = XXXXXXXXXX
irq_sp	    = XXXXXXXXXX
sp start    = XXXXXXXXXX
FB base     = XXXXXXXXXX

or interrupt execution by any means and re-load the symbols at the location
specified by gd->relocaddr -- this is only valid after board_init_f.

(gdb) set $s = gd->relocaddr
(gdb) symbol-file
(gdb) add-symbol-file u-boot $s

Now you can use gdb as usual :-)

U-Boot for arm64

Summary
=======
The initial arm64 U-Boot port was developed before hardware was available,
so the first supported platforms were the Foundation and Fast Model for ARMv8.
These days U-Boot runs on a variety of 64-bit capable ARM hardware, from
embedded development boards to servers.

Notes
=====

1. U-Boot can run at any exception level it is entered in, it is
   recommened to enter it in EL3 if U-Boot takes some responsibilities of a
   classical firmware (like initial hardware setup, CPU errata workarounds
   or SMP bringup). U-Boot can be entered in EL2 when its main purpose is
   that of a boot loader. It can drop to lower exception levels before
   entering the OS.

2. U-Boot for arm64 is compiled with AArch64-gcc. AArch64-gcc
   use rela relocation format, a tool(tools/relocate-rela) by Scott Wood
   is used to encode the initial addend of rela to u-boot.bin. After running,
   the U-Boot will be relocated to destination again.

3. Earlier Linux kernel versions required the FDT to be placed at a
   2 MB boundary and within the same 512 MB section as the kernel image,
   resulting in fdt_high to be defined specially.
   Since kernel version 4.2 Linux is more relaxed about the DT location, so it
   can be placed anywhere in memory.
   Please reference linux/Documentation/arm64/booting.txt for detail.

4. Spin-table is used to wake up secondary processors. One location
   (or per processor location) is defined to hold the kernel entry point
   for secondary processors. It must be ensured that the location is
   accessible and zero immediately after secondary processor
   enter slave_cpu branch execution in start.S. The location address
   is encoded in cpu node of DTS. Linux kernel store the entry point
   of secondary processors to it and send event to wakeup secondary
   processors.
   Please reference linux/Documentation/arm64/booting.txt for detail.

5. Generic board is supported.

6. CONFIG_ARM64 instead of CONFIG_ARMV8 is used to distinguish aarch64 and
   aarch32 specific codes.


Contributors
============
   Tom Rini            <trini@ti.com>
   Scott Wood          <scottwood@freescale.com>
   York Sun            <yorksun@freescale.com>
   Simon Glass         <sjg@chromium.org>
   Sharma Bhupesh      <bhupesh.sharma@freescale.com>
   Rob Herring         <robherring2@gmail.com>
   Sergey Temerkhanov  <s.temerkhanov@gmail.com>

The trusted boot framework on Marvell Armada 38x
================================================

Contents:

1. Overview of the trusted boot
2. Terminology
3. Boot image layout
4. The secured header
5. The secured boot flow
6. Usage example
7. Work to be done
8. Bibliography

1. Overview of the trusted boot
-------------------------------

The Armada's trusted boot framework enables the SoC to cryptographically verify
a specially prepared boot image. This can be used to establish a chain of trust
from the boot firmware all the way to the OS.

To achieve this, the Armada SoC requires a specially prepared boot image, which
contains the relevant cryptographic data, as well as other information
pertaining to the boot process. Furthermore, a eFuse structure (a
one-time-writeable memory) need to be configured in the correct way.

Roughly, the secure boot process works as follows:

* Load the header block of the boot image, extract a special "root" public RSA
  key from it, and verify its SHA-256 hash against a SHA-256 stored in a eFuse
  field.
* Load an array of code signing public RSA keys from the header block, and
  verify its RSA signature (contained in the header block as well) using the
  "root" RSA key.
* Choose a code signing key, and use it to verify the header block (excluding
  the key array).
* Verify the binary image's signature (contained in the header block) using the
  code signing key.
* If all checks pass successfully, boot the image.

The chain of trust is thus as follows:

* The SHA-256 value in the eFuse field verifies the "root" public key.
* The "root" public key verifies the code signing key array.
* The selected code signing key verifies the header block and the binary image.

In the special case of building a boot image containing U-Boot as the binary
image, which employs this trusted boot framework, the following tasks need to
be addressed:

1. Creation of the needed cryptographic key material.
2. Creation of a conforming boot image containing the U-Boot image as binary
   image.
3. Burning the necessary eFuse values.

(1) will be addressed later, (2) will be taken care of by U-Boot's build
system (some user configuration is required, though), and for (3) the necessary
data (essentially a series of U-Boot commands to be entered at the U-Boot
command prompt) will be created by the build system as well.

The documentation of the trusted boot mode is contained in part 1, chapter
7.2.5 in the functional specification [1], and in application note [2].

2. Terminology
--------------

	           CSK - Code Signing Key(s): An array of RSA key pairs, which
                         are used to sign and verify the secured header and the
                         boot loader image.
	           KAK - Key Authentication Key: A RSA key pair, which is used
                         to sign and verify the array of CSKs.
	  Header block - The first part of the boot image, which contains the
			 image's headers (also known as "headers block", "boot
			 header", and "image header")
                 eFuse - A one-time-writeable memory.
               BootROM - The Armada's built-in boot firmware, which is
                         responsible for verifying and starting secure images.
	    Boot image - The complete image the SoC's boot firmware loads
			 (contains the header block and the binary image)
	   Main header - The header in the header block containing information
			 and data pertaining to the boot process (used for both
			 the regular and secured boot processes)
	  Binary image - The binary code payload of the boot image; in this
			 case the U-Boot's code (also known as "source image",
			 or just "image")
	Secured header - The specialized header in the header block that
			 contains information and data pertaining to the
			 trusted boot (also known as "security header")
     Secured boot mode - A special boot mode of the Armada SoC in which secured
                         images are verified (non-secure images won't boot);
                         the mode is activated by setting a eFuse field.
    Trusted debug mode - A special mode for the trusted boot that allows
			 debugging of devices employing the trusted boot
			 framework in a secure manner (untested in the current
			 implementation).
Trusted boot framework - The ARMADA SoC's implementation of a secure verified
                         boot process.

3. Boot image layout
--------------------

+-- Boot image --------------------------------------------+
|                                                          |
| +-- Header block --------------------------------------+ |
| | Main header                                          | |
| +------------------------------------------------------+ |
| | Secured header                                       | |
| +------------------------------------------------------+ |
| | BIN header(s)                                        | |
| +------------------------------------------------------+ |
| | REG header(s)                                        | |
| +------------------------------------------------------+ |
| | Padding                                              | |
| +------------------------------------------------------+ |
|                                                          |
| +------------------------------------------------------+ |
| | Binary image + checksum                              | |
| +------------------------------------------------------+ |
+----------------------------------------------------------+

4. The secured header
---------------------

For the trusted boot framework, a additional header is added to the boot image.
The following data are relevant for the secure boot:

		   KAK: The KAK is contained in the secured header in the form
		        of a RSA-2048 public key in DER format with a length of
			524 bytes.
Header block signature: The RSA signature of the header block (excluding the
                        CSK array), created using the selected CSK.
Binary image signature: The RSA signature of the binary image, created using
                        the selected CSK.
             CSK array: The array of the 16 CSKs as RSA-2048 public keys in DER
	                format with a length of 8384 = 16 * 524 bytes.
   CSK block signature: The RSA signature of the CSK array, created using the
                        KAK.

NOTE: The JTAG delay, Box ID, and Flash ID header fields do play a role in the
trusted boot process to enable and configure secure debugging, but they were
not tested in the current implementation of the trusted boot in U-Boot.

5. The secured boot flow
------------------------

The steps in the boot flow that are relevant for the trusted boot framework
proceed as follows:

1) Check if trusted boot is enabled, and perform regular boot if it is not.
2) Load the secured header, and verify its checksum.
3) Select the lowest valid CSK from CSK0 to CSK15.
4) Verify the SHA-256 hash of the KAK embedded in the secured header.
5) Verify the RSA signature of the CSK block from the secured header with the
   KAK.
6) Verify the header block signature (which excludes the CSK block) from the
   secured header with the selected CSK.
7) Load the binary image to the main memory and verify its checksum.
8) Verify the binary image's RSA signature from the secured header with the
   selected CSK.
9) Continue the boot process as in the case of the regular boot.

NOTE: All RSA signatures are verified according to the PKCS #1 v2.1 standard
described in [3].

NOTE: The Box ID and Flash ID are checked after step 6, and the trusted debug
mode may be entered there, but since this mode is untested in the current
implementation, it is not described further.

6. Usage example
----------------

### Create key material

To employ the trusted boot framework, cryptographic key material needs to be
created. In the current implementation, two keys are needed to build a valid
secured boot image: The KAK private key and a CSK private key (both have to be
2048 bit RSA keys in PEM format). Note that the usage of more than one CSK is
currently not supported.

NOTE: Since the public key can be generated from the private key, it is
sufficient to store the private key for each key pair.

OpenSSL can be used to generate the needed files kwb_kak.key and kwb_csk.key
(the names of these files have to be configured, see the next section on
kwbimage.cfg settings):

openssl genrsa -out kwb_kak.key 2048
openssl genrsa -out kwb_csk.key 2048

The generated files have to be placed in the U-Boot root directory.

Alternatively, instead of copying the files, symlinks to the private keys can
be placed in the U-Boot root directory.

WARNING: Knowledge of the KAK or CSK private key would enable an attacker to
generate secured boot images containing arbitrary code. Hence, the private keys
should be carefully guarded.

### Create/Modifiy kwbimage.cfg

The Kirkwook architecture in U-Boot employs a special board-specific
configuration file (kwbimage.cfg), which controls various boot image settings
that are interpreted by the BootROM, such as the boot medium. The support the
trusted boot framework, several new options were added to faciliate
configuration of the secured boot.

The configuration file's layout has been retained, only the following new
options were added:

		KAK - The name of the KAK RSA private key file in the U-Boot
                      root directory, without the trailing extension of ".key".
		CSK - The name of the (active) CSK RSA private key file in the
		      U-Boot root directory, without the trailing extension of
		      ".key".
	     BOX_ID - The BoxID to be used for trusted debugging (a integer
	              value).
	   FLASH_ID - The FlashID to be used for trusted debugging (a integer
	              value).
	 JTAG_DELAY - The JTAG delay to be used for trusted debugging (a
	              integer value).
          CSK_INDEX - The index of the active CSK (a integer value).
SEC_SPECIALIZED_IMG - Flag to indicate whether to include the BoxID and FlashID
		      in the image (that is, whether to use the trusted debug
		      mode or not); no parameters.
       SEC_BOOT_DEV - The boot device from which the trusted boot is allowed to
		      proceed, identified via a numeric ID. The tested values
		      are 0x34 = NOR flash, 0x31 = SDIO/MMC card; for
		      additional ID values, consult the documentation in [1].
      SEC_FUSE_DUMP - Dump the "fuse prog" commands necessary for writing the
		      correct eFuse values to a text file in the U-Boot root
		      directory. The parameter is the architecture for which to
		      dump the commands (currently only "a38x" is supported).

The parameter values may be hardcoded into the file, but it is also possible to
employ a dynamic approach of creating a Autoconf-like kwbimage.cfg.in, then
reading configuration values from Kconfig options or from the board config
file, and generating the actual kwbimage.cfg from this template using Makefile
mechanisms (see board/gdsys/a38x/Makefile as an example for this approach).

### Set config options

To enable the generation of trusted boot images, the corresponding support
needs to be activated, and a index for the active CSK needs to be selected as
well.

Furthermore, eFuse writing support has to be activated in order to burn the
eFuse structure's values (this option is just needed for programming the eFuse
structure; production boot images may disable it).

ARM architecture
 -> [*] Build image for trusted boot
    (0)   Index of active CSK
 -> [*] Enable eFuse support
    [ ]   Fake eFuse access (dry run)

### Build and test boot image

The creation of the boot image is done via the usual invocation of make (with a
suitably set CROSS_COMPILE environment variable, of course). The resulting boot
image u-boot-spl.kwb can then be tested, if so desired. The hdrparser from [5]
can be used for this purpose. To build the tool, invoke make in the
'tools/marvell/doimage_mv' directory of [5], which builds a stand-alone
hdrparser executable. A test can be conducted by calling hdrparser with the
produced boot image and the following (mandatory) parameters:

./hdrparser -k 0 -t u-boot-spl.kwb

Here we assume that the CSK index is 0 and the boot image file resides in the
same directory (adapt accordingly if needed). The tool should report that all
checksums are valid ("GOOD"), that all signature verifications succeed
("PASSED"), and, finally, that the overall test was successful
("T E S T   S U C C E E D E D" in the last line of output).

### Burn eFuse structure

+----------------------------------------------------------+
| WARNING: Burning the eFuse structure is a irreversible   |
| operation! Should wrong or corrupted values be used, the |
| board won't boot anymore, and recovery is likely         |
| impossible!                                              |
+----------------------------------------------------------+

After the build process has finished, and the SEC_FUSE_DUMP option was set in
the kwbimage.cfg was set, a text file kwb_fuses_a38x.txt should be present in
the U-Boot top-level directory. It contains all the necessary commands to set
the eFuse structure to the values needed for the used KAK digest, as well as
the CSK index, Flash ID and Box ID that were selected in kwbimage.cfg.

Sequentially executing the commands in this file at the U-Boot command prompt
will write these values to the eFuse structure.

If the SEC_FUSE_DUMP option was not set, the commands needed to burn the fuses
have to be crafted by hand. The needed fuse lines can be looked up in [1]; a
rough overview of the process is:

* Burn the KAK public key hash. The hash itself can be found in the file
  pub_kak_hash.txt in the U-Boot top-level directory; be careful to account for
  the endianness!
* Burn the CSK selection, BoxID, and FlashID
* Enable trusted boot by burning the corresponding fuse (WARNING: this must be
  the last fuse line written!)
* Lock the unused fuse lines

The command to employ is the "fuse prog" command previously enabled by setting
the corresponding configuration option.

For the trusted boot, the fuse prog command has a special syntax, since the
ARMADA SoC demands that whole fuse lines (64 bit values) have to be written as
a whole. The fuse prog command itself allows lists of 32 bit words to be
written at a time, but this is translated to a series of single 32 bit write
operations to the fuse line, where the individual 32 bit words are identified
by a "word" counter that is increased for each write.

To work around this restriction, we interpret each line to have three "words"
(0-2): The first and second words are the values to be written to the fuse
line, and the third is a lock flag, which is supposed to lock the fuse line
when set to 1. Writes to the first and second words are memoized between
function calls, and the fuse line is only really written and locked (on writing
the third word) if both words were previously set, so that "incomplete" writes
are prevented. An exception to this is a single write to the third word (index
2) without previously writing neither the first nor the second word, which
locks the fuse line without setting any value; this is needed to lock the
unused fuse lines.

As an example, to write the value 0011223344556677 to fuse line 10, we would
use the following command:

fuse prog -y 10 0 00112233 44556677 1

Here 10 is the fuse line number, 0 is the index of the first word to be
written, 00112233 and 44556677 are the values to be written to the fuse line
(first and second word) and the trailing 1 is the value for the third word
responsible for locking the line.

A "lock-only" command would look like this:

fuse prog -y 11 2 1

Here 11 is the fuse number, 2 is the index of the first word to be written
(notice that we only write to word 2 here; the third word for fuse line
locking), and the 1 is the value for the word we are writing to.

WARNING: According to application note [4], the VHV pin of the SoC must be
connected to a 1.8V source during eFuse programming, but *must* be disconnected
for normal operation. The AN [4] describes a software-controlled circuit (based
on a N-channel or P-channel FET and a free GPIO pin of the SoC) to achieve
this, but a jumper-based circuit should suffice as well. Regardless of the
chosen circuit, the issue needs to be addressed accordingly!

7. Work to be done
------------------

* Add the ability to populate more than one CSK
* Test secure debug
* Test on Armada XP

8. Bibliography
---------------

[1] ARMADA(R) 38x Family High-Performance Single/Dual CPU System on Chip
    Functional Specification; MV-S109094-00, Rev. C; August 2, 2015,
    Preliminary
[2] AN-383: ARMADA(R) 38x Families Secure Boot Mode Support; MV-S302501-00
    Rev.  A; March 11, 2015, Preliminary
[3] Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography
    Specifications Version 2.1; February 2003;
    https://www.ietf.org/rfc/rfc3447.txt
[4] AN-389: ARMADA(R) VHV Power; MV-S302545-00 Rev. B; January 28, 2016,
    Released
[5] Marvell Armada 38x U-Boot support; November 25, 2015;
    https://github.com/MarvellEmbeddedProcessors/u-boot-marvell

2017-01-05, Mario Six <mario.six@gdsys.cc>

Atmel AT91 Evaluation kits

Index
  - I. Board mapping & boot media
  - II. NAND partition table
  - III. watchdog support

I. Board mapping & boot media
------------------------------------------------------------------------------
AT91SAM9260EK, AT91SAM9G20EK & AT91SAM9XEEK
------------------------------------------------------------------------------

Memory map
	0x20000000 - 23FFFFFF	SDRAM (64 MB)
	0xC0000000 - Cxxxxxxx	Atmel Dataflash card (J13)
	0xD0000000 - D07FFFFF	Soldered Atmel Dataflash (AT45DB642)

Environment variables

	U-Boot environment variables can be stored at different places:
		- Dataflash on SPI chip select 1 (default)
		- Dataflash on SPI chip select 0 (dataflash card)
		- Nand flash.

	You can choose your storage location at config step (here for at91sam9260ek) :
		make at91sam9260ek_nandflash_config	- use nand flash
		make at91sam9260ek_dataflash_cs0_config	- use data flash (spi cs0)
		make at91sam9260ek_dataflash_cs1_config	- use data flash (spi cs1)


------------------------------------------------------------------------------
AT91SAM9261EK, AT91SAM9G10EK
------------------------------------------------------------------------------

Memory map
	0x20000000 - 23FFFFFF	SDRAM (64 MB)
	0xC0000000 - C07FFFFF	Soldered Atmel Dataflash (AT45DB642)
	0xD0000000 - Dxxxxxxx	Atmel Dataflash card (J22)

Environment variables

	U-Boot environment variables can be stored at different places:
		- Dataflash on SPI chip select 0 (default)
		- Dataflash on SPI chip select 3 (dataflash card)
		- Nand flash.

	You can choose your storage location at config step (here for at91sam9260ek) :
		make at91sam9261ek_nandflash_config	- use nand flash
		make at91sam9261ek_dataflash_cs0_config	- use data flash (spi cs0)
		make at91sam9261ek_dataflash_cs3_config	- use data flash (spi cs3)


------------------------------------------------------------------------------
AT91SAM9263EK
------------------------------------------------------------------------------

Memory map
	0x20000000 - 23FFFFFF	SDRAM (64 MB)
	0xC0000000 - Cxxxxxxx	Atmel Dataflash card (J9)

Environment variables

	U-Boot environment variables can be stored at different places:
		- Dataflash on SPI chip select 0 (dataflash card)
		- Nand flash.
		- Nor flash (not populate by default)

	You can choose your storage location at config step (here for at91sam9260ek) :
		make at91sam9263ek_nandflash_config	- use nand flash
		make at91sam9263ek_dataflash_cs0_config	- use data flash (spi cs0)
		make at91sam9263ek_norflash_config	- use nor flash

	You can choose to boot directly from U-Boot at config step
		make at91sam9263ek_norflash_boot_config	- boot from nor flash


------------------------------------------------------------------------------
AT91SAM9M10G45EK
------------------------------------------------------------------------------

Memory map
	0x70000000 - 77FFFFFF	SDRAM (128 MB)

Environment variables

	U-Boot environment variables can be stored at different places:
		- Nand flash.

	You can choose your storage location at config step (here for at91sam9m10g45ek) :
		make at91sam9m10g45ek_nandflash_config		- use nand flash


------------------------------------------------------------------------------
AT91SAM9RLEK
------------------------------------------------------------------------------

Memory map
	0x20000000 - 23FFFFFF	SDRAM (64 MB)
	0xC0000000 - C07FFFFF   Soldered Atmel Dataflash (AT45DB642)

Environment variables

	U-Boot environment variables can be stored at different places:
		- Dataflash on SPI chip select 0
		- Nand flash.

	You can choose your storage location at config step (here for at91sam9rlek) :
		make at91sam9rlek_nandflash_config	- use nand flash


------------------------------------------------------------------------------
AT91SAM9N12EK, AT91SAM9X5EK
------------------------------------------------------------------------------

Memory map
	0x20000000 - 27FFFFFF	SDRAM (128 MB)

Environment variables

	U-Boot environment variables can be stored at different places:
		- Nand flash.
		- SD/MMC card
		- Serialflash/Dataflash on SPI chip select 0

	You can choose your storage location at config step (here for at91sam9x5ek) :
		make at91sam9x5ek_dataflash_config	- use data flash
		make at91sam9x5ek_mmc_config		- use sd/mmc card
		make at91sam9x5ek_nandflash_config	- use nand flash
		make at91sam9x5ek_spiflash_config	- use serial flash


------------------------------------------------------------------------------
SAMA5D3XEK
------------------------------------------------------------------------------

Memory map
	0x20000000 - 3FFFFFFF	SDRAM (512 MB)

Environment variables

	U-Boot environment variables can be stored at different places:
		- Nand flash.
		- SD/MMC card
		- Serialflash on SPI chip select 0

	You can choose your storage location at config step (here for sama5d3xek) :
		make sama5d3xek_mmc_config		- use SD/MMC card
		make sama5d3xek_nandflash_config	- use nand flash
		make sama5d3xek_serialflash_config	- use serial flash


II. NAND partition table

	All the board support boot from NAND flash will use the following NAND
	partition table

		0x00000000 - 0x0003FFFF	bootstrap	(256 KiB)
		0x00040000 - 0x000BFFFF u-boot		(512 KiB)
		0x000C0000 - 0x000FFFFF env		(256 KiB)
		0x00100000 - 0x0013FFFF env_redundant	(256 KiB)
		0x00140000 - 0x0017FFFF spare		(256 KiB)
		0x00180000 - 0x001FFFFF dtb		(512 KiB)
		0x00200000 - 0x007FFFFF kernel		(6 MiB)
		0x00800000 - 0xxxxxxxxx rootfs		(All left)

III. Watchdog support

	For security reasons, the at91 watchdog is running at boot time and,
	if deactivated, cannot be used anymore.
	If you want to use the watchdog, you will need to keep it running in
	your code (make sure not to disable it in AT91Bootstrap for instance).

	In the U-Boot configuration, the AT91 watchdog support is enabled using
	the CONFIG_AT91SAM9_WATCHDOG and CONFIG_HW_WATCHDOG options.

How to use SD/MMC cards with Atmel SoCs having MCI hardware
-----------------------------------------------------------
2010-08-16 Reinhard Meyer <reinhard.meyer@emk-elektronik.de>

This is a new approach to use Atmel MCI hardware with the
general MMC framework. Therefore it benefits from that
framework's abilities to handle SDHC Cards and the ability
to write blocks.

- AT91SAM9XE512 (tested, will definitely work with XE128 and XE256)
- AT91SAM9260 (not tested, but MCI is to AT91SAM9XE)
- AT91SAM9G20 (not tested, should work)

It should work with all other ATMEL devices that have MCI.

The generic driver does NOT assign port pins to the MCI block
nor does it start the MCI clock. This has to be handled in a
board/SoC specific manner before the driver is initialized:

example: this is added to at91sam9260_devices.c:

#if defined(CONFIG_GENERIC_ATMEL_MCI)
void at91_mci_hw_init(void)
{
	at91_set_a_periph(AT91_PIO_PORTA, 8, PUP);	/* MCCK */
#if defined(CONFIG_ATMEL_MCI_PORTB)
	at91_set_b_periph(AT91_PIO_PORTA, 1, PUP);	/* MCCDB */
	at91_set_b_periph(AT91_PIO_PORTA, 0, PUP);	/* MCDB0 */
	at91_set_b_periph(AT91_PIO_PORTA, 5, PUP);	/* MCDB1 */
	at91_set_b_periph(AT91_PIO_PORTA, 4, PUP);	/* MCDB2 */
	at91_set_b_periph(AT91_PIO_PORTA, 3, PUP);	/* MCDB3 */
#else
	at91_set_a_periph(AT91_PIO_PORTA, 7, PUP);	/* MCCDA */
	at91_set_a_periph(AT91_PIO_PORTA, 6, PUP);	/* MCDA0 */
	at91_set_a_periph(AT91_PIO_PORTA, 9, PUP);	/* MCDA1 */
	at91_set_a_periph(AT91_PIO_PORTA, 10, PUP);	/* MCDA2 */
	at91_set_a_periph(AT91_PIO_PORTA, 11, PUP);	/* MCDA3 */
#endif
}
#endif

the board specific file need added:
...
#ifdef CONFIG_GENERIC_ATMEL_MCI
# include <mmc.h>
#endif
...
#ifdef CONFIG_GENERIC_ATMEL_MCI
/* this is a weak define that we are overriding */
int board_mmc_init(bd_t *bd)
{
	/* Enable clock */
	at91_sys_write(AT91_PMC_PCER, 1 << AT91SAM9260_ID_MCI);
	at91_mci_hw_init();

	/* This calls the atmel_mci_init in gen_atmel_mci.c */
	return atmel_mci_init((void *)AT91_BASE_MCI);
}

/* this is a weak define that we are overriding */
int board_mmc_getcd(struct mmc *mmc)
{
	return !at91_get_gpio_value(CONFIG_SYS_MMC_CD_PIN);
}

#endif

and the board definition files needs:

/* SD/MMC card */
#define CONFIG_GENERIC_ATMEL_MCI	1
#define CONFIG_ATMEL_MCI_PORTB		1	/* Atmel XE-EK uses port B */
#define CONFIG_SYS_MMC_CD_PIN		AT91_PIN_PC9
#define CONFIG_CMD_MMC			1

How to enable PMECC(Programmable Multibit ECC) for nand on Atmel SoCs
-----------------------------------------------------------
2012-08-22 Josh Wu <josh.wu@atmel.com>

The Programmable Multibit ECC (PMECC) controller is a programmable binary
BCH(Bose, Chaudhuri and Hocquenghem) encoder and decoder. This controller
can be used to support both SLC and MLC NAND Flash devices. It supports to
generate ECC to correct 2, 4, 8, 12 or 24 bits of error per sector (512 or
1024 bytes) of data.

Following Atmel AT91 products support PMECC.
- AT91SAM9X25, X35, G25, G15, G35 (tested)
- AT91SAM9N12 (not tested, Should work)

As soon as your nand flash software ECC works, you can enable PMECC.

To use PMECC in this driver, the user needs to set:
	1. the PMECC correction error bits capability: CONFIG_PMECC_CAP.
	   It can be 2, 4, 8, 12 or 24.
	2. The PMECC sector size: CONFIG_PMECC_SECTOR_SIZE.
	   It only can be 512 or 1024.

Take 'configs/at91sam9x5ek_nandflash_defconfig' as an example, the board
configuration file has the following entries:

	CONFIG_PMECC_CAP=2
	CONFIG_PMECC_SECTOR_SIZE=512
	CONFIG_SPL_GENERATE_ATMEL_PMECC_HEADER=y

How to enable PMECC header for direct programmable boot.bin
-----------------------------------------------------------
2014-05-19 Andreas Bießmann <andreas@biessmann.org>

The usual way to program SPL into NAND flash is to use the SAM-BA Atmel tool.
This however is often not usable when doing field updates. To be able to
program a SPL binary into NAND flash we need to add the PMECC header to the
binary before. Chapter '12.4.4.1 NAND Flash Boot: NAND Flash Detection' in
sama5d3 SoC spec (as of 03. April 2014) defines how this PMECC header has to
look like. In order to do so we have a new image type added to mkimage to
generate this PMECC header and integrated this into the build process of SPL.

To enable the generation of atmel PMECC header for SPL one needs to define
CONFIG_SPL_GENERATE_ATMEL_PMECC_HEADER. The required parameters are taken from
board configuration and compiled into the host tools atmel_pmecc_params. This
tool will be called in build process to parametrize mkimage for atmelimage
type. The mkimage tool has intentionally _not_ compiled in those parameters.

The mkimage image type atmelimage also set the 6'th interrupt vector to the
correct value. This feature can also be used to setup a boot.bin for MMC boot.

/*
 * (C) Copyright 2001
 * Dave Ellis, SIXNET, dge@sixnetio.com
 *
 * SPDX-License-Identifier:	GPL-2.0+
 */

Using autoboot configuration options
====================================

The basic autoboot configuration options are documented in the main
U-Boot README. See it for details. They are:

  bootdelay
  bootcmd
  CONFIG_BOOTDELAY
  CONFIG_BOOTCOMMAND

Some additional options that make autoboot safer in a production
product are documented here.

Why use them?
-------------

The basic autoboot feature allows a system to automatically boot to
the real application (such as Linux) without a user having to enter
any commands. If any key is pressed before the boot delay time
expires, U-Boot stops the autoboot process, gives a U-Boot prompt
and waits forever for a command. That's a good thing if you pressed a
key because you wanted to get the prompt.

It's not so good if the key press was a stray character on the
console serial port, say because a user who knows nothing about
U-Boot pressed a key before the system had time to boot. It's even
worse on an embedded product that doesn't have a console during
normal use. The modem plugged into that console port sends a
character at the wrong time and the system hangs, with no clue as to
why it isn't working.

You might want the system to autoboot to recover after an external
configuration program stops autoboot. If the configuration program
dies or loses its connection (modems can disconnect at the worst
time) U-Boot will patiently wait forever for it to finish.

These additional configuration options can help provide a system that
boots when it should, but still allows access to U-Boot.

What they do
------------

  CONFIG_BOOT_RETRY_TIME
  CONFIG_BOOT_RETRY_MIN

  "bootretry" environment variable

	These options determine what happens after autoboot is
	stopped and U-Boot is waiting for commands.

	CONFIG_BOOT_RETRY_TIME must be defined to enable the boot
	retry feature. If the environment variable "bootretry" is
	found then its value is used, otherwise the retry timeout is
	CONFIG_BOOT_RETRY_TIME. CONFIG_BOOT_RETRY_MIN is optional and
	defaults to CONFIG_BOOT_RETRY_TIME. All times are in seconds.

	If the retry timeout is negative, the U-Boot command prompt
	never times out. Otherwise it is forced to be at least
	CONFIG_BOOT_RETRY_MIN seconds. If no valid U-Boot command is
	entered before the specified time the boot delay sequence is
	restarted. Each command that U-Boot executes restarts the
	timeout.

	If CONFIG_BOOT_RETRY_TIME < 0 the feature is there, but
	doesn't do anything unless the environment variable
	"bootretry" is >= 0.

  CONFIG_AUTOBOOT_KEYED
  CONFIG_AUTOBOOT_KEYED_CTRLC
  CONFIG_AUTOBOOT_PROMPT
  CONFIG_AUTOBOOT_DELAY_STR
  CONFIG_AUTOBOOT_STOP_STR

  "bootdelaykey"  environment variable
  "bootstopkey"	  environment variable

	These options give more control over stopping autoboot. When
	they are used a specific character or string is required to
	stop or delay autoboot.

	Define CONFIG_AUTOBOOT_KEYED (no value required) to enable
	this group of options.	CONFIG_AUTOBOOT_DELAY_STR,
	CONFIG_AUTOBOOT_STOP_STR or both should be specified (or
	specified by the corresponding environment variable),
	otherwise there is no way to stop autoboot.

	CONFIG_AUTOBOOT_PROMPT is displayed before the boot delay
	selected by CONFIG_BOOTDELAY starts. If it is not defined
	there is no output indicating that autoboot is in progress.

	Note that CONFIG_AUTOBOOT_PROMPT is used as the (only)
	argument to a printf() call, so it may contain '%' format
	specifications, provided that it also includes, sepearated by
	commas exactly like in a printf statement, the required
	arguments. It is the responsibility of the user to select only
	such arguments that are valid in the given context. A
	reasonable prompt could be defined as

		#define CONFIG_AUTOBOOT_PROMPT \
			"autoboot in %d seconds\n",bootdelay

	If CONFIG_AUTOBOOT_DELAY_STR or "bootdelaykey" is specified
	and this string is received from console input before
	autoboot starts booting, U-Boot gives a command prompt. The
	U-Boot prompt will time out if CONFIG_BOOT_RETRY_TIME is
	used, otherwise it never times out.

	If CONFIG_AUTOBOOT_STOP_STR or "bootstopkey" is specified and
	this string is received from console input before autoboot
	starts booting, U-Boot gives a command prompt. The U-Boot
	prompt never times out, even if CONFIG_BOOT_RETRY_TIME is
	used.

	The string recognition is not very sophisticated. If a
	partial match is detected, the first non-matching character
	is checked to see if starts a new match. There is no check
	for a shorter partial match, so it's best if the first
	character of a key string does not appear in the rest of the
	string.

	The CONFIG_AUTOBOOT_KEYED_CTRLC #define allows for the boot
	sequence to be interrupted by ctrl-c, in addition to the
	"bootdelaykey" and "bootstopkey". Setting this variable
	provides an escape sequence from the limited "password"
	strings.

  CONFIG_RESET_TO_RETRY

	(Only effective when CONFIG_BOOT_RETRY_TIME is also set)
	After the countdown timed out, the board will be reset to restart
	again.

Overview
--------
The B4860QDS is a Freescale reference board that hosts the B4860 SoC (and variants).

B4860 Overview
-------------
The B4860 QorIQ Qonverge device is a Freescale high-end, multicore SoC based on
StarCore and Power Architecture® cores. It targets the broadband wireless
infrastructure and builds upon the proven success of the existing multicore
DSPs and Power CPUs. It is designed to bolster the rapidly changing and
expanding wireless markets, such as 3GLTE (FDD and TDD), LTE-Advanced, and UMTS.

The B4860 is a highly-integrated StarCore and Power Architecture processor that
contains:
. Six fully-programmable StarCore SC3900 FVP subsystems, divided into three
clusters-each core runs up to 1.2 GHz, with an architecture highly optimized for
wireless base station applications
. Four dual-thread e6500 Power Architecture processors organized in one cluster-each
core runs up to 1.8 GHz
. Two DDR3/3L controllers for high-speed, industry-standard memory interface each
runs at up to 1866.67 MHz
. MAPLE-B3 hardware acceleration-for forward error correction schemes including
Turbo or Viterbi decoding, Turbo encoding and rate matching, MIMO MMSE
equalization scheme, matrix operations, CRC insertion and check, DFT/iDFT and
FFT/iFFT calculations, PUSCH/PDSCH acceleration, and UMTS chip rate
acceleration
. CoreNet fabric that fully supports coherency using MESI protocol between the
  e6500 cores, SC3900 FVP cores, memories and external interfaces.
  CoreNet fabric interconnect runs at 667 MHz and supports coherent and
  non-coherent out of order transactions with prioritization and bandwidth
  allocation amongst CoreNet endpoints.
. Data Path Acceleration Architecture, which includes the following:
. Frame Manager (FMan), which supports in-line packet parsing and general
  classification to enable policing and QoS-based packet distribution
. Queue Manager (QMan) and Buffer Manager (BMan), which allow offloading
  of queue management, task management, load distribution, flow ordering, buffer
  management, and allocation tasks from the cores
. Security engine (SEC 5.3)-crypto-acceleration for protocols such as IPsec,
  SSL, and 802.16
. RapidIO manager (RMAN) - Support SRIO types 8, 9, 10, and 11 (inbound and
  outbound). Supports types 5, 6 (outbound only)
. Large internal cache memory with snooping and stashing capabilities for
  bandwidth saving and high utilization of processor elements. The 9856-Kbyte
  internal memory space includes the following:
. 32 Kbyte L1 ICache per e6500/SC3900 core
. 32 Kbyte L1 DCache per e6500/SC3900 core
. 2048 Kbyte unified L2 cache for each SC3900 FVP cluster
. 2048 Kbyte unified L2 cache for the e6500 cluster
. Two 512 Kbyte shared L3 CoreNet platform caches (CPC)
. Sixteen 10-GHz SerDes lanes serving:
. Two Serial RapidIO interfaces.
	- Each supports up to 4 lanes and a total of up to 8 lanes
. Up to 8-lanes Common Public Radio Interface (CPRI) controller for glue-less
  antenna connection
. Two 10-Gbit Ethernet controllers (10GEC)
. Six 1G/2.5-Gbit Ethernet controllers for network communications
. PCI Express controller
. Debug (Aurora)
. Two OCeaN DMAs
. Various system peripherals
. 182 32-bit timers

B4860QDS Overview
------------------
- DDRC1: Ten separate DDR3 parts of 16-bit to support 72-bit (ECC) at 1866MT/s, ECC, 4 GB
  of memory in two ranks of 2 GB.
- DDRC2: Five separate DDR3 parts of 16-bit to support 72-bit (ECC) at 1866MT/s, ECC, 2 GB
  of memory. Single rank.
- SerDes 1 multiplexing: Two Vitesse (transmit and receive path) cross-point 16x16 switch
  VSC3316
- SerDes 2 multiplexing: Two Vitesse (transmit and receive path) cross-point 8x8 switch VSC3308
- USB 2.0 ULPI PHY USB3315 by SMSC supports USB port in host mode.
  B4860 UART port is available over USB-to-UART translator USB2SER or over RS232 flat cable.
- A Vitesse dual SGMII phy VSC8662 links the B4860 SGMII lines to 2xRJ-45 copper connectors
  for Stand-alone mode and to the 1000Base-X over AMC MicroTCA connector ports 0 and 2 for
  AMC mode.
- The B4860 configuration may be loaded from nine bits coded reset configuration reset source. The
  RCW source is set by appropriate DIP-switches:
- 16-bit NOR Flash / PROMJet
- QIXIS 8-bit NOR Flash Emulator
- 8-bit NAND Flash
- 24-bit SPI Flash
- Long address I2C EEPROM
- Available debug interfaces are:
	- On-board eCWTAP controller with ETH and USB I/F
	- JTAG/COP 16-pin header for any external TAP controller
	- External JTAG source over AMC to support B2B configuration
	- 70-pin Aurora debug connector
- QIXIS (FPGA) logic:
	- 2 KB internal memory space including
- IDT840NT4 clock synthesizer provides B4860 essential clocks : SYSCLK, DDRCLK1,2 and
  RTCCLK.
- Two 8T49N222A SerDes ref clock devices support two SerDes port clock frequency - total four
  refclk, including CPRI clock scheme.

B4420 Personality
--------------------

B4420 Personality
--------------------
B4420 is a reduced personality of B4860 with less core/clusters(both SC3900 and e6500), less DDR
controllers, less serdes lanes, less SGMII interfaces and reduced target frequencies.

Key differences between B4860 and B4420
----------------------------------------

B4420 has:
1. Less e6500 cores: 1 cluster with 2 e6500 cores
2. Less SC3900 cores/clusters: 1 cluster with 2 SC3900 cores per cluster.
3. Single DDRC
4. 2X 4 lane serdes
5. 3 SGMII interfaces
6. no sRIO
7. no 10G

B4860QDS Default Settings
-------------------------

Switch Settings
----------------

SW1	OFF [0]	OFF [0]	OFF [0]	OFF [0]	OFF [0]	OFF [0]	OFF [0]	OFF [0]
SW2	ON	ON	ON	ON	ON	ON	OFF	OFF
SW3	OFF	OFF	OFF	ON	OFF	OFF	ON	OFF
SW5	OFF	OFF	OFF	OFF	OFF	OFF	ON	ON

Note: PCIe slots modes: All the PCIe devices work as Root Complex.
Note: Boot location: NOR flash.

SysClk/Core(e6500)/CCB/DDR/FMan/DDRCLK/StarCore/CPRI-Maple/eTVPE-Maple/ULB-Maple
66MHz/1.6GHz/667MHz/1.6GHz data rate/667MHz/133MHz/1200MHz/500MHz/800MHz/667MHz

a) NAND boot
	SW1 [1.1] = 0
	SW2 [1.1] = 1
	SW3 [1:4] = 0001
b) NOR boot
	SW1 [1.1] = 1
	SW2 [1.1] = 0
	SW3 [1:4] = 1000.

B4420QDS Default Settings
-------------------------

Switch Settings
----------------
SW1	OFF[0]	OFF [0]	OFF [0]	OFF [0]	OFF [0]	OFF [0]	OFF [0]	OFF [0]
SW2	ON	OFF	ON	OFF	ON	ON	OFF	OFF
SW3	OFF	OFF	OFF	ON	OFF	OFF	ON	OFF
SW5	OFF	OFF	OFF	OFF	OFF	OFF	ON	ON

Note: PCIe slots modes: All the PCIe devices work as Root Complex.
Note: Boot location: NOR flash.

SysClk/Core(e6500)/CCB/DDR/FMan/DDRCLK/StarCore/CPRI-Maple/eTVPE-Maple/ULB-Maple
66MHz/1.6GHz/667MHz/1.6GHz data rate/667MHz/133MHz/1200MHz/500MHz/800MHz/667MHz

a) NAND boot
	SW1 [1.1] = 0
	SW2 [1.1] = 1
	SW3 [1:4] = 0001
b) NOR boot
	SW1 [1.1] = 1
	SW2 [1.1] = 0
	SW3 [1:4] = 1000.

Memory map on B4860QDS
----------------------
The addresses in brackets are physical addresses.

Start Address	End Address	Description	Size
0xF_FFDF_1000 	0xF_FFFF_FFFF	Free		2 MB
0xF_FFDF_0000 	0xF_FFDF_0FFF	IFC - FPGA 	4 KB
0xF_FF81_0000 	0xF_FFDE_FFFF	Free		5 MB
0xF_FF80_0000	0xF_FF80_FFFF	IFC NAND Flash	64 KB
0xF_FF00_0000	0xF_FF7F_FFFF	Free		8 MB
0xF_FE00_0000 	0xF_FEFF_FFFF	CCSRBAR		16 MB
0xF_F801_0000 	0xF_FDFF_FFFF	Free		95 MB
0xF_F800_0000	0xF_F800_FFFF	PCIe I/O Space 	64 KB
0xF_F600_0000 	0xF_F7FF_FFFF	QMAN s/w portal	32 MB
0xF_F400_0000 	0xF_F5FF_FFFF	BMAN s/w portal	32 MB
0xF_F000_0000 	0xF_F3FF_FFFF	Free		64 MB
0xF_E800_0000 	0xF_EFFF_FFFF	IFC  NOR Flash 	128 MB
0xF_E000_0000	0xF_E7FF_FFFF	Promjet		128 MB
0xF_A0C0_0000 	0xF_DFFF_FFFF	Free		1012 MB
0xF_A000_0000 	0xF_A0BF_FFFF	MAPLE0/1/2	12 MB
0xF_0040_0000 	0xF_9FFF_FFFF	Free		12 GB
0xF_0000_0000 	0xF_01FF_FFFF	DCSR		32 MB
0xC_4000_0000 	0xE_FFFF_FFFF	Free		11 GB
0xC_3000_0000 	0xC_3FFF_FFFF	sRIO-2 I/O 	256 MB
0xC_2000_0000 	0xC_2FFF_FFFF	sRIO-1 I/O  	256 MB
0xC_0000_0000	0xC_1FFF_FFFF	PCIe Mem Space 	512 MB
0x1_0000_0000 	0xB_FFFF_FFFF	Free		44 GB
0x0_8000_0000 	0x0_FFFF_FFFF	DDRC1		2 GB
0x0_0000_0000 	0x0_7FFF_FFFF	DDRC2	  	2 GB

Memory map on B4420QDS
----------------------
The addresses in brackets are physical addresses.

Start Address	End Address	Description	Size
0xF_FFDF_1000 	0xF_FFFF_FFFF	Free		2 MB
0xF_FFDF_0000 	0xF_FFDF_0FFF	IFC - FPGA 	4 KB
0xF_FF81_0000 	0xF_FFDE_FFFF	Free		5 MB
0xF_FF80_0000	0xF_FF80_FFFF	IFC NAND Flash	64 KB
0xF_FF00_0000	0xF_FF7F_FFFF	Free		8 MB
0xF_FE00_0000 	0xF_FEFF_FFFF	CCSRBAR		16 MB
0xF_F801_0000 	0xF_FDFF_FFFF	Free		95 MB
0xF_F800_0000	0xF_F800_FFFF	PCIe I/O Space 	64 KB
0xF_F600_0000 	0xF_F7FF_FFFF	QMAN s/w portal	32 MB
0xF_F400_0000 	0xF_F5FF_FFFF	BMAN s/w portal	32 MB
0xF_F000_0000 	0xF_F3FF_FFFF	Free		64 MB
0xF_E800_0000 	0xF_EFFF_FFFF	IFC  NOR Flash 	128 MB
0xF_E000_0000	0xF_E7FF_FFFF	Promjet		128 MB
0xF_A0C0_0000 	0xF_DFFF_FFFF	Free		1012 MB
0xF_A000_0000 	0xF_A0BF_FFFF	MAPLE0/1/2	12 MB
0xF_0040_0000 	0xF_9FFF_FFFF	Free		12 GB
0xF_0000_0000 	0xF_01FF_FFFF	DCSR		32 MB
0xC_4000_0000 	0xE_FFFF_FFFF	Free		11 GB
0xC_3000_0000 	0xC_3FFF_FFFF	sRIO-2 I/O 	256 MB
0xC_2000_0000 	0xC_2FFF_FFFF	sRIO-1 I/O  	256 MB
0xC_0000_0000	0xC_1FFF_FFFF	PCIe Mem Space 	512 MB
0x1_0000_0000 	0xB_FFFF_FFFF	Free		44 GB
0x0_0000_0000 	0x0_FFFF_FFFF	DDRC1		4 GB


NOR Flash memory Map on B4860 and B4420QDS
------------------------------------------
 Start		 End		Definition			Size
0xEFF40000	0xEFFFFFFF	U-Boot (current bank)		768KB
0xEFF20000	0xEFF3FFFF	U-Boot env (current bank)	128KB
0xEFF00000	0xEFF1FFFF	FMAN Ucode (current bank)	128KB
0xEF300000	0xEFEFFFFF	rootfs (alternate bank)		12MB
0xEE800000	0xEE8FFFFF	device tree (alternate bank)	1MB
0xEE020000	0xEE6FFFFF	Linux.uImage (alternate bank)	6MB+896KB
0xEE000000	0xEE01FFFF	RCW (alternate bank)		128KB
0xEDF40000	0xEDFFFFFF	U-Boot (alternate bank)		768KB
0xEDF20000	0xEDF3FFFF	U-Boot env (alternate bank)	128KB
0xEDF00000	0xEDF1FFFF	FMAN ucode (alternate bank)	128KB
0xED300000	0xEDEFFFFF	rootfs (current bank)		12MB
0xEC800000	0xEC8FFFFF	device tree (current bank)	1MB
0xEC020000	0xEC6FFFFF	Linux.uImage (current bank)	6MB+896KB
0xEC000000	0xEC01FFFF	RCW (current bank)		128KB

Various Software configurations/environment variables/commands
--------------------------------------------------------------
The below commands apply to both B4860QDS and B4420QDS.

1. U-Boot environment variable hwconfig
   The default hwconfig is:
	hwconfig=fsl_ddr:ctlr_intlv=null,bank_intlv=cs0_cs1;usb1:
					dr_mode=host,phy_type=ulpi
   Note: For USB gadget set "dr_mode=peripheral"

2. FMAN Ucode versions
   fsl_fman_ucode_B4860_106_3_6.bin

3. Switching to alternate bank
   Commands for switching to alternate bank.

	1. To change from vbank0 to vbank2
		=> qixis_reset altbank (it will boot using vbank2)

	2.To change from vbank2 to vbank0
		=> qixis reset (it will boot using vbank0)

4. To change personality of board
   For changing personality from B4860 to B4420
	1)Boot from vbank0
	2)Flash vbank2 with b4420 rcw and U-Boot
	3)Give following commands to uboot prompt
	   => mw.b ffdf0040 0x30;
	   => mw.b ffdf0010 0x00;
	   => mw.b ffdf0062 0x02;
	   => mw.b ffdf0050 0x02;
	   => mw.b ffdf0010 0x30;
	   => reset

   Note: Power off cycle will lead to default switch settings.
   Note: 0xffdf0000 is the address of the QIXIS FPGA.

5. Switching between NOR and NAND boot(RCW src changed from NOR <-> NAND)

   To change from NOR to NAND boot give following command on uboot prompt
	=> mw.b ffdf0040 0x30
	=> mw.b ffdf0010 0x00
	=> mw.b 0xffdf0050 0x08
	=> mw.b 0xffdf0060 0x82
	=> mw.b ffdf0061 0x00
	=> mw.b ffdf0010 0x30
	=> reset

   To change from NAND to NOR boot give following command on uboot prompt:
	=> mw.b ffdf0040 0x30
	=> mw.b ffdf0010 0x00
	=> mw.b 0xffdf0050 0x00(for vbank0) or (mw.b 0xffdf0050 0x02 for vbank2)
	=> mw.b 0xffdf0060 0x12
	=> mw.b ffdf0061 0x01
	=> mw.b ffdf0010 0x30
	=> reset

   Note: Power off cycle will lead to default switch settings.
   Note: 0xffdf0000 is the address of the QIXIS FPGA.

6.  Ethernet interfaces for B4860QDS
   Serdes protocosl tested:
   0x2a, 0x8d (serdes1, serdes2) [DEFAULT]
   0x2a, 0xb2 (serdes1, serdes2)

   When using [DEFAULT] RCW, which including 2 * 1G SGMII on board and 2 * 1G
   SGMII on SGMII riser card.
   Under U-Boot these network interfaces are recognized as:
   FM1@DTSEC3, FM1@DTSEC4, FM1@DTSEC5 and FM1@DTSEC6.

   On Linux the interfaces are renamed as:
	. eth2 -> fm1-gb2
	. eth3 -> fm1-gb3
	. eth4 -> fm1-gb4
	. eth5 -> fm1-gb5

7. RCW and Ethernet interfaces for B4420QDS
   Serdes protocosl tested:
   0x18, 0x9e (serdes1, serdes2)

   Under U-Boot these network interfaces are recognized as:
   FM1@DTSEC3, FM1@DTSEC4 and  e1000#0.

   On Linux the interfaces are renamed as:
	. eth2 -> fm1-gb2
	. eth3 -> fm1-gb3

NAND boot with 2 Stage boot loader
----------------------------------
PBL initialise the internal SRAM and copy SPL(160KB) in SRAM.
SPL further initialise DDR using SPD and environment variables and copy
U-Boot(768 KB) from flash to DDR.
Finally SPL transer control to U-Boot for futher booting.

SPL has following features:
 - Executes within 256K
 - No relocation required

 Run time view of SPL framework during  boot :-
 -----------------------------------------------
 Area        | Address                         |
-----------------------------------------------
 Secure boot | 0xFFFC0000 (32KB)               |
 headers     |                                 |
 -----------------------------------------------
 GD, BD      | 0xFFFC8000 (4KB)                |
 -----------------------------------------------
 ENV         | 0xFFFC9000 (8KB)                |
 -----------------------------------------------
 HEAP        | 0xFFFCB000 (30KB)               |
 -----------------------------------------------
 STACK       | 0xFFFD8000 (22KB)               |
 -----------------------------------------------
 U-Boot SPL  | 0xFFFD8000 (160KB)              |
 -----------------------------------------------

NAND Flash memory Map on B4860 and B4420QDS
------------------------------------------
 Start		 End		Definition			Size
0x000000	0x0FFFFF	U-Boot                          1MB
0x140000	0x15FFFF	U-Boot env                      128KB
0x1A0000	0x1BFFFF	FMAN Ucode                      128KB

Summary
=======

This document describes how to use U-Boot on the Broadcom 7445 SoC, as
a third stage bootloader loaded by Broadcom's BOLT bootloader.

BOLT loads U-Boot as a generic ELF binary.  Some U-Boot features such
as networking are not yet available but other important features are,
including:

   - ext4 file system traversal

   - support for loading FIT images

   - advanced scripting

   - support for FIT-provided DTBs instead of relying on the
     BOLT-provided DTB

A customized version of this port has been used in production.  The
same approach may work on other BCM7xxx boards, with some
configuration adjustments and memory layout experimentation.

Build
=====

make bcm7445_defconfig
make
${CROSS_COMPILE}strip u-boot

Run
===

Flash the u-boot binary into board storage, then invoke it from BOLT.
For example:

BOLT> boot -bsu -elf flash0.u-boot1

This port assumes that I-cache and D-cache are already enabled when
U-Boot is entered.

Flattened Image Tree Support
============================

What follows is an example FIT image source file.  Build it with:

mkimage -f image.its image.itb

Booting the resulting image.itb was tested on BOLT v1.20, with the
following kernels:

https://github.com/Broadcom/stblinux-3.14
https://github.com/Broadcom/stblinux-4.1
https://github.com/Broadcom/stblinux-4.9

and with a generic ARMv7 root file system.

image.its:
/dts-v1/;
/ {
	description = "BCM7445 FIT";
	images {
		kernel@1 {
			description = "Linux kernel";
			/*
			 * This kernel image output format can be
			 * generated with:
			 *
			 * make vmlinux
			 * ${CROSS_COMPILE}objcopy -O binary -S vmlinux vmlinux.bin
			 * gzip -9 vmlinux.bin
			 *
			 * For stblinux-3.14, the specific Broadcom
			 * board type should be configured in the
			 * kernel, for example CONFIG_BCM7445D0=y.
			 */
			data = /incbin/("<vmlinux.bin.gz>");
			type = "kernel";
			arch = "arm";
			os = "linux";
			compression = "gzip";
			load = <0x8000>;
			entry = <0x8000>;
			hash@1 {
				algo = "sha256";
			};
		};
		ramdisk@1 {
			description = "Initramfs root file system";
			data = /incbin/("<initramfs.cpio.gz>");
			type = "ramdisk";
			arch = "arm";
			os = "linux";
			compression = "gzip";
			/*
			 * Set the environment variable initrd_high to
			 * 0xffffffff, and set "load" and "entry" here
			 * to 0x0 to keep initramfs in-place and to
			 * accommodate stblinux bmem/CMA reservations.
			 */
			load = <0x0>;
			entry = <0x0>;
			hash@1 {
				algo = "sha256";
			};
		};
		fdt@1 {
			description = "Device tree dumped from BOLT";
			/*
			 * This DTB should be similar to the
			 * BOLT-generated device tree, after BOLT has
			 * done its runtime modifications to it.  For
			 * example, it can be dumped from within
			 * U-Boot (at ${fdtcontroladdr}), after BOLT
			 * has loaded U-Boot.  The result can be added
			 * to the Linux source tree as a .dts file.
			 *
			 * To support modifications to the device tree
			 * in-place in U-Boot, add to Linux's
			 * arch/arm/boot/dts/Makefile:
			 *
			 * DTC_FLAGS ?= -p 4096
			 *
			 * This will leave some padding in the DTB and
			 * thus reserve room for node additions.
			 *
			 * Also, set the environment variable fdt_high
			 * to 0xffffffff to keep the DTB in-place and
			 * to accommodate stblinux bmem/CMA
			 * reservations.
			 */
			data = /incbin/("<bolt-<version>.dtb");
			type = "flat_dt";
			arch = "arm";
			compression = "none";
			hash@1 {
				algo = "sha256";
			};
		};
	};
	configurations {
		default = "conf@bcm7445";
		conf@bcm7445 {
			description = "BCM7445 configuration";
			kernel = "kernel@1";
			ramdisk = "ramdisk@1";
			fdt = "fdt@1";
		};
	};
};

BEDBUG Support for U-Boot
--------------------------

These changes implement the bedbug (emBEDded deBUGger) debugger in U-Boot.
A specific implementation is made for the AMCC 405 processor but other flavors
can be easily implemented.

#####################
### Modifications ###
#####################

./common/Makefile
	Included cmd_bedbug.c and bedbug.c in the Makefile.

./common/command.c
	Added bedbug commands to command table.

./common/board.c
	Added call to initialize debugger on startup.

./arch/powerpc/cpu/ppc4xx/Makefile
	Added bedbug_405.c to the Makefile.

./arch/powerpc/cpu/ppc4xx/start.S
	Added code to handle the debug exception (0x2000) on the 405.
	Also added code to handle critical exceptions since the debug
	is treated as critical on the 405.

./arch/powerpc/cpu/ppc4xx/traps.c
	Added more detailed output for the program exception to tell
	if it is an illegal instruction, privileged instruction or
	a trap. Also added debug trap handler.

./include/ppc_asm.tmpl
	Added code to handle critical exceptions

#################
### New Stuff ###
#################

./include/bedbug/ppc.h
./include/bedbug/regs.h
./include/bedbug/bedbug.h
./include/bedbug/elf.h		[obsoleted by new include/elf.h]
./include/bedbug/tables.h
./include/cmd_bedbug.h
./common/cmd_bedbug.c
./common/bedbug.c
	Bedbug library includes code for assembling and disassembling
	PowerPC instructions to/from memory as well as handling
	hardware breakpoints and stepping through code.  These
	routines are common to all PowerPC processors.

./arch/powerpc/cpu/ppc4xx/bedbug_405.c
	AMCC  PPC405 specific debugger routines.


Bedbug support for the MPC860
-----------------------------

Changes:

	common/cmd_bedbug.c
		Added call to initialize 860 debugger.

	arch/powerpc/cpu/mpc8xx/Makefile
		Added new file "bedbug_860.c" to the makefile

	arch/powerpc/cpu/mpc8xx/start.S
		Added handler for InstructionBreakpoint (0xfd00)

	arch/powerpc/cpu/mpc8xx/traps.c
		Added new routine DebugException()

New Files:

	arch/powerpc/cpu/mpc8xx/bedbug_860.c
		CPU-specific routines for 860 debug registers.

This patch rewrites the miiphybb ( Bit-banged MII bus driver ) in order to
support an arbitrary number of mii buses. This feature is useful when your
board uses different mii buses for different phys and all (or a part) of these
buses are implemented via bit-banging mode.

The driver requires that the following macros should be defined into the board
configuration file:

CONFIG_BITBANGMII	- Enable the miiphybb driver
CONFIG_BITBANGMII_MULTI - Enable the multi bus support

If the CONFIG_BITBANGMII_MULTI is not defined, the board's config file needs
to define at least the following macros:

MII_INIT      - Generic code to enable the MII bus (optional)
MDIO_DECLARE  - Declaration needed to access to the MDIO pin (optional)
MDIO_ACTIVE   - Activate the MDIO pin as out pin
MDIO_TRISTATE - Activate the MDIO pin as input/tristate pin
MDIO_READ     - Read the MDIO pin
MDIO(v)       - Write v on the MDIO pin
MDC_DECLARE   - Declaration needed to access to the MDC pin (optional)
MDC(v)	      - Write v on the MDC pin

The previous macros make the driver compatible with the previous version
(that didn't support the multi-bus).

When the CONFIG_BITBANGMII_MULTI is also defined, the board code needs to fill
the bb_miiphy_buses[] array with a record for each required bus and declare
the bb_miiphy_buses_num variable with the number of mii buses.
The record (struct bb_miiphy_bus) has the following fields/callbacks (see
miiphy.h for details):

char name[]	       - The symbolic name that must be equal to the MII bus
			 registered name
int (*init)()	       - Initialization function called at startup time (just
			 before the Ethernet initialization)
int (*mdio_active)()   - Activate the MDIO pin as output
int (*mdio_tristate)() - Activate the MDIO pin as input/tristate pin
int (*set_mdio)()      - Write the MDIO pin
int (*get_mdio)()      - Read the MDIO pin
int (*set_mdc)()       - Write the MDC pin
int (*delay)()	       - Delay function
void *priv	       - Private data used by board specific code

The board code will look like:

struct bb_miiphy_bus bb_miiphy_buses[] = {
 { .name = "miibus#1", .init = b1_init, .mdio_active = b1_mdio_active, ... },
 { .name = "miibus#2", .init = b2_init, .mdio_active = b2_mdio_active, ... },
 ...
};
int bb_miiphy_buses_num = sizeof(bb_miiphy_buses) /
			  sizeof(bb_miiphy_buses[0]);

2009 Industrie Dial Face S.p.A.
     Luigi 'Comio' Mantellini <luigi.mantellini@idf-hit.com>

Notes for the Blackfin architecture port of Das U-Boot

 =========
 ! ABOUT !
 =========

<marketing blurb>
Blackfin Processors embody a new breed of 16/32-bit embedded processor, ideally
suited for products where a convergence of capabilities are necessary -
multi-format audio, video, voice and image processing; multi-mode baseband and
packet processing; control processing; and real-time security.  The Blackfin's
unique combination of software flexibility and scalability has gained it
widespread adoption in convergent applications.
</marketing blurb>

The Blackfin processor is wholly developed by Analog Devices Inc.

 ===========
 ! SUPPORT !
 ===========

All open source code for the Blackfin processors are being handled via our
collaborative website:
http://blackfin.uclinux.org/

In particular, bug reports, feature requests, help etc... for Das U-Boot are
handled in the Das U-Boot sub project:
http://blackfin.uclinux.org/gf/project/u-boot

This website is backed both by an open source community as well as a dedicated
team from Analog Devices Inc.

 =============
 ! TOOLCHAIN !
 =============

To compile the Blackfin aspects, you'll need the GNU toolchain configured for
the Blackfin processor.  You can obtain such a cross-compiler here:
http://blackfin.uclinux.org/gf/project/toolchain

 =================
 ! DOCUMENTATION !
 =================

For Blackfin specific documentation, you can visit our dedicated doc wiki:
http://docs.blackfin.uclinux.org/doku.php?id=bootloaders:u-boot

/*
 * (C) Copyright 2011-2012 Pali Rohár <pali.rohar@gmail.com>
 *
 * SPDX-License-Identifier:	GPL-2.0+
 */

ANSI terminal bootmenu command

The "bootmenu" command uses U-Boot menu interfaces and provides
a simple mechanism for creating menus with different boot items.
The cursor keys "Up" and "Down" are used for navigation through
the items. Current active menu item is highlighted and can be
selected using the "Enter" key. The selection of the highlighted
menu entry invokes an U-Boot command (or a list of commands)
associated with this menu entry.

The "bootmenu" command interprets ANSI escape sequencies, so
an ANSI terminal is required for proper menu rendering and item
selection.

The assembling of the menu is done via a set of environment variables
"bootmenu_<num>" and "bootmenu_delay", i.e.:

  bootmenu_delay=<delay>
  bootmenu_<num>="<title>=<commands>"

  <delay> is the autoboot delay in seconds, after which the first
  menu entry will be selected automatically

  <num> is the boot menu entry number, starting from zero

  <title> is the text of the menu entry shown on the console
  or on the boot screen

  <commands> are commands which will be executed when a menu
  entry is selected

  (title and commands are separated by first appearance of '='
   character in the environment variable)

First (optional) argument of the "bootmenu" command is a delay specifier
and it overrides the delay value defined by "bootmenu_delay" environment
variable. If the environment variable "bootmenu_delay" is not set or if
the argument of the "bootmenu" command is not specified, the default delay
will be CONFIG_BOOTDELAY. If delay is 0, no menu entries will be shown on
the console (or on the screen) and the command of the first menu entry will
be called immediately. If delay is less then 0, bootmenu will be shown and
autoboot will be disabled.

Bootmenu always adds menu entry "U-Boot console" at the end of all menu
entries specified by environment variables. When selecting this entry
the bootmenu terminates and the usual U-Boot command prompt is presented
to the user.

Example environment:

  setenv bootmenu_0 Boot 1. kernel=bootm 0x82000000  # Set first menu entry
  setenv bootmenu_1 Boot 2. kernel=bootm 0x83000000  # Set second menu entry
  setenv bootmenu_2 Reset board=reset                # Set third menu entry
  setenv bootmenu_3 U-Boot boot order=boot           # Set fourth menu entry
  bootmenu 20        # Run bootmenu with autoboot delay 20s


The above example will be rendered as below
(without decorating rectangle):

┌──────────────────────────────────────────┐
│                                          │
│  *** U-Boot Boot Menu ***                │
│                                          │
│     Boot 1. kernel                       │
│     Boot 2. kernel                       │
│     Reset board                          │
│     U-Boot boot order                    │
│     U-Boot console                       │
│                                          │
│  Hit any key to stop autoboot: 20        │
│  Press UP/DOWN to move, ENTER to select  │
│                                          │
└──────────────────────────────────────────┘

Selected menu entry will be highlighted - it will have inverted
background and text colors.

To enable the "bootmenu" command add following definitions to the
board config file:

  #define CONFIG_CMD_BOOTMENU
  #define CONFIG_MENU

To run the bootmenu at startup add these additional definitions:

  #define CONFIG_AUTOBOOT_KEYED
  #define CONFIG_BOOTDELAY 30
  #define CONFIG_MENU_SHOW

When you intend to use the bootmenu on color frame buffer console,
make sure to additionally define CONFIG_CFB_CONSOLE_ANSI in the
board config file.

MIPS Boston Development Board

---------
  About
---------

The MIPS Boston development board is built around an FPGA & 3 PCIe controllers,
one of which is connected to an Intel EG20T Platform Controller Hub which
provides most connectivity to the board. It is used during the development &
testing of both new CPUs and the software support for them. It is essentially
the successor of the older MIPS Malta board.

--------
  QEMU
--------

U-Boot can be run on a currently out-of-tree branch of QEMU with support for
the Boston board added. This QEMU code can currently be found in the "boston"
branch of git://git.linux-mips.org/pub/scm/paul/qemu.git and used like so:

  $ git clone git://git.linux-mips.org/pub/scm/paul/qemu.git -b boston
  $ cd qemu
  $ ./configure --target-list=mips64el-softmmu
  $ make
  $ ./mips64el-softmmu/qemu-system-mips64el -M boston -m 2G \
      -bios u-boot.bin -serial stdio

Please note that QEMU will default to emulating the I6400 CPU which implements
the MIPS64r6 ISA, and at the time of writing doesn't implement any earlier CPUs
with support for the CPS features the Boston board relies upon. You will
therefore need to configure U-Boot to build for MIPSr6 in order to obtain a
binary that will work in QEMU.

-------------
  Toolchain
-------------

If building for MIPSr6 then you will need a toolchain including GCC 5.x or
newer, or the Codescape toolchain available for download from Imagination
Technologies:

  http://codescape-mips-sdk.imgtec.com/components/toolchain/2015.06-05/

The "IMG GNU Linux Toolchain" is capable of building for all current MIPS ISAs,
architecture revisions & both endiannesses.

--------
  TODO
--------

  - AHCI support
  - CPU driver
  - Exception handling (+UHI?)
  - Flash support
  - IOCU support
  - L2 cache support
  - More general LCD display driver
  - Multi-arch-variant multi-endian fat binary

/*
 * (C) Copyright 2008-2009
 * BuS Elektronik GmbH & Co. KG <www.bus-elektronik.de>
 * Jens Scharsig <esw@bus-elektronik.de>
 *
 * SPDX-License-Identifier:	GPL-2.0+
 */

U-Boot vcxk video controller driver
======================================

By defining CONFIG_VIDEO_VCXK this driver can be used with VC2K, VC4K and
VC8K devices on following boards:

board           | ARCH          | Vendor
-----------------------------------------------------------------------
EB+CPU5282-T1   | MCF5282       | BuS Elektronik GmbH & Co. KG
EB+MCF-EVB123   | MCF5282       | BuS Elektronik GmbH & Co. KG
EB+CPUx9K2      | AT91RM9200    | BuS Elektronik GmbH & Co. KG
ZLSA            | AT91RM9200    | Ruf Telematik AG

Driver configuration
--------------------

The driver needs some defines to describe the target hardware:

CONFIG_SYS_VCXK_BASE

	base address of VCxK hardware memory

CONFIG_SYS_VCXK_DEFAULT_LINEALIGN

	defines the physical alignment of a pixel row

CONFIG_SYS_VCXK_DOUBLEBUFFERED

	some boards that use vcxk prevent read from framebuffer memory.
	define this option to enable double buffering (needs 16KiB RAM)

CONFIG_SYS_VCXK_<xxxx>_PIN

	defines the number of the I/O line PIN in the port
	valid values for <xxxx> are:

		ACKNOWLEDGE
			describes the acknowledge line from vcxk hardware

		ENABLE
			describes the enable line to vcxk hardware

		INVERT
			describes the invert line to vcxk hardware

		RESET
			describes the reset line to vcxk hardware

		REQUEST
			describes the request line to vcxk hardware

CONFIG_SYS_VCXK_<xxxx>_PORT

	defines the I/O port which is connected with the line
	for valid values for <xxxx> see CONFIG_SYS_VCXK_<xxxx>_PIN

CONFIG_SYS_VCXK_<xxxx>_DDR

	defines the register which configures the direction
	for valid values for <xxxx> see CONFIG_SYS_VCXK_<xxxx>_PIN

The common CFI driver provides this weak default implementation for
flash_cmd_reset():

static void __flash_cmd_reset(flash_info_t *info)
{
	/*
	 * We do not yet know what kind of commandset to use, so we issue
	 * the reset command in both Intel and AMD variants, in the hope
	 * that AMD flash roms ignore the Intel command.
	 */
	flash_write_cmd(info, 0, 0, AMD_CMD_RESET);
	udelay(1);
	flash_write_cmd(info, 0, 0, FLASH_CMD_RESET);
}
void flash_cmd_reset(flash_info_t *info)
	__attribute__((weak,alias("__flash_cmd_reset")));

Some flash chips seem to have trouble with this reset sequence.
In this case, board-specific code can override this weak default
version with a board-specific function.

At the time of writing, there are two boards that define their own
routine for this.

First, the digsy_mtc board equipped with the M29W128GH from Numonyx
needs this version to function properly:

void flash_cmd_reset(flash_info_t *info)
{
	flash_write_cmd(info, 0, 0, AMD_CMD_RESET);
}

In addition, the t3corp board defines the routine thusly:

void flash_cmd_reset(flash_info_t *info)
{
	/*
	 * FLASH at address CONFIG_SYS_FLASH_BASE is a Spansion chip and
	 * needs the Spansion type reset commands. The other flash chip
	 * is located behind a FPGA (Xilinx DS617) and needs the Intel type
	 * reset command.
	 */
	if (info->start[0] == CONFIG_SYS_FLASH_BASE)
		flash_write_cmd(info, 0, 0, AMD_CMD_RESET);
	else
		flash_write_cmd(info, 0, 0, FLASH_CMD_RESET);
}

see also:
http://www.mail-archive.com/u-boot@lists.denx.de/msg24368.html


Config Option

  CONFIG_SYS_MAX_FLASH_SECT: Number of sectors available on Flash device

  CONFIG_SYS_FLASH_CFI_WIDTH: Data-width of the flash device

  CONFIG_CMD_FLASH: Enables Flash command library

  CONFIG_FLASH_CFI_DRIVER: Enables CFI Flash driver

  CONFIG_FLASH_CFI_MTD: Enables MTD frame work for NOR Flash devices

Running U-Boot from coreboot on Chromebooks
===========================================

U-Boot can be used as a secondary boot loader in a few situations such as from
UEFI and coreboot (see README.x86). Recent Chromebooks use coreboot even on
ARM platforms to start up the machine.

This document aims to provide a guide to booting U-Boot on a Chromebook. It
is only a starting point, and there are many guides on the interwebs. But
placing this information in the U-Boot tree should make it easier to find for
those who use U-Boot habitually.

Most of these platforms are supported by U-Boot natively, but it is risky to
replace the ROM unless you have a servo board and cable to restore it with.


For all of these the standard U-Boot build instructions apply. For example on
ARM:

   sudo apt install gcc-arm-linux-gnueabi
   mkdir b
   make O=b/nyan_big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all

You can obtain the vbutil_kernel utility here:

   https://drive.google.com/open?id=0B7WYZbZ9zd-3dHlVVXo4VXE2T0U


Snow (Samsung ARM Chromebook)
-----------------------------

See here:

https://www.chromium.org/chromium-os/firmware-porting-guide/using-nv-u-boot-on-the-samsung-arm-chromebook


Nyan-big
--------

Compiled based on information here:
https://lists.denx.de/pipermail/u-boot/2015-March/209530.html
https://git.collabora.com/cgit/user/tomeu/u-boot.git/commit/?h=nyan-big
https://lists.denx.de/pipermail/u-boot/2017-May/289491.html
https://github.com/chromeos-nvidia-androidtv/gnu-linux-on-acer-chromebook-13#copy-data-to-the-sd-card

1. Patch U-Boot

Open include/configs/tegra124-common.h

Change:

#define CONFIG_SYS_TEXT_BASE	0x80110000

to:

#define CONFIG_SYS_TEXT_BASE	0x81000100


2. Build U-Boot

   mkdir b
   make -j8 O=b/nyan-big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all


3. Select a .its file

Select something from doc/chromium which matches your board, or create your
own.

Note that the device tree node is required, even though it is not actually
used by U-Boot. This is because the Chromebook expects to pass it to the
kernel, and crashes if it is not present.


4. Build and sign an image

   ./b/nyan-big/tools/mkimage -f doc/chromium/nyan-big.its u-boot-chromium.fit
   echo test >dummy.txt
   vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \
	--signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \
	--version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
	--bootloader dummy.txt --pack u-boot.kpart


5. Prepare an SD card

   DISK=/dev/sdc   # Replace with your actual SD card device
   sudo cgpt create $DISK
   sudo cgpt add -b 34 -s 32768 -P 1 -S 1 -t kernel $DISK
   sudo cgpt add -b 32802 -s 2000000 -t rootfs $DISK
   sudo gdisk $DISK   # Enter command 'w' to write a protective MBR to the disk


6. Write U-Boot to the SD card

   sudo dd if=u-boot.kpart of=/dev/sdc1; sync


7. Start it up

Reboot the device in dev mode. Make sure that you have USB booting enabled. To
do this, login as root (via Ctrl-Alt-forward_arrow) and type
'enable_dev_usb_boot'. You only need to do this once.

Reboot the device with the SD card inserted. Press Clrl-U at the developer
mode screen. It should show something like the following on the display:

   U-Boot 2017.07-00637-g242eb42-dirty (May 22 2017 - 06:14:21 -0600)

   Model: Acer Chromebook 13 CB5-311
   Board: Google/NVIDIA Nyan-big, ID: 1

   Net:   No ethernet found.
   Hit any key to stop autoboot:  0
   Tegra124 (Nyan-big) #


8. Known problems

On the serial console the word MMC is chopped at the start of the line:

C:   sdhci@700b0000: 2, sdhci@700b0400: 1, sdhci@700b0600: 0

This is likely due to some problem with change-over of the serial driver
during relocation (or perhaps updating the clock setup in board_init()).


9. Notes

To check that you copied the u-boot.its file correctly, use these commands.
You should see that the data at 0x100 in u-boot-chromium.fit is the first few
bytes of U-Boot:

   hd u-boot-chromium.fit |head -20
   ...
   00000100  b8 00 00 ea 14 f0 9f e5  14 f0 9f e5 14 f0 9f e5  |................|

   hd b/nyan-big/u-boot.bin |head
   00000000  b8 00 00 ea 14 f0 9f e5  14 f0 9f e5 14 f0 9f e5  |................|


The 'data' property of the FIT is set up to start at offset 0x100 bytes into
the file. The change to CONFIG_SYS_TEXT_BASE is also an offset of 0x100 bytes
from the load address. If this changes, you either need to modify U-Boot to be
fully relocatable, or expect it to hang.


chromebook_jerry
----------------

The instruction are similar to those for Nyan with changes as noted below:

1. Patch U-Boot

Open include/configs/rk3288_common.h

Change:

#define CONFIG_SYS_TEXT_BASE		0x00100000

to:

#define CONFIG_SYS_TEXT_BASE		0x02000100



2. Build U-Boot

   mkdir b
   make -j8 O=b/chromebook_jerry CROSS_COMPILE=arm-linux-gnueabi- \
	chromebook_jerry_defconfig all


3. See above

4. Build and sign an image

   ./b/chromebook_jerry/tools/mkimage -f doc/chromium/chromebook_jerry.its \
	u-boot-chromium.fit
   echo test >dummy.txt
   vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \
	--signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \
	--version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
	--bootloader dummy.txt --pack u-boot.kpart


5. See above

6. See above

7. Start it up

Reboot the device in dev mode. Make sure that you have USB booting enabled. To
do this, login as root (via Ctrl-Alt-forward_arrow) and type
'enable_dev_usb_boot'. You only need to do this once.

Reboot the device with the SD card inserted. Press Clrl-U at the developer
mode screen. It should show something like the following on the display:

   U-Boot 2017.05-00649-g72acdbf-dirty (May 29 2017 - 14:57:05 -0600)

   Model: Google Jerry
   Net:   Net Initialization Skipped
   No ethernet found.
   Hit any key to stop autoboot:  0


8. Known problems

None as yet.


9. Notes

None as yet.


Other notes
===========

flashrom
--------

   Used to make a backup of your firmware, or to replace it.

   See: https://www.chromium.org/chromium-os/packages/cros-flashrom


coreboot
--------

Coreboot itself is not designed to actually boot an OS. Instead, a program
called Depthcharge is used. This originally came out of U-Boot and was then
heavily hacked and modified such that is is almost unrecognisable. It does
include a very small part of the U-Boot command-line interface but is not
usable as a general-purpose boot loader.

In addition, it has a very unusual design in that it does not do device init
itself, but instead relies on coreboot. This is similar to (in U-Boot) having
a SPI driver with an empty probe() method, relying on whatever was set up
beforehand. It can be quite hard to figure out between these two code bases
what settings are actually used. When chain-loading into U-Boot we must be
careful to reinit anything that U-Boot expects. If not, some peripherals (or
the whole machine) may not work. This makes the process of chainloading more
complicated than it could be on some platforms.

Finally, it supports only a subset of the U-Boot's FIT format. In particular
it uses a fixed address to load the FIT and does not support load/exec
addresses. This means that U-Boot must be able to boot from whatever
address Depthcharge happens to use (it is the CONFIG_KERNEL_START setting
in Depthcharge). In practice this means that the data in the kernel@1 FIT node
(see above) must start at the same address as U-Boot's CONFIG_SYS_TEXT_BASE.

The biggest problem when trying to compile U-Boot with clang is that
almost all archs rely on storing gd in a global register and clang user
manual states: "clang does not support global register variables; this
is unlikely to be implemented soon because it requires additional LLVM
backend support."

Since version 3.4 the ARM backend can be instructed to leave r9 alone.
Global registers themselves are not supported so some inline assembly is
used to get its value. This does lead to larger code then strictly
necessary, but at least works.

NOTE: target compilation only work for _some_ ARM boards at the moment.
Also Aarch64 is not supported: Most notably boards which aren't using
the generic board will fail to compile, but since those are expected
to be converted this will solve itself. Boards which reassign gd in c
will also fail to compile, but there is in no strict reason to do so
in the ARM world, since crt0.S takes care of this. These assignments
can be avoided by changing the init calls but this is not in mainline yet.

NOTE: without the -mllvm -arm-use-movt=0 flags U-Boot will compile
fine, but llvm might hardcode addresses in movw / movt pairs, which
cannot be relocated and U-Boot will fail at runtime.

Debian (based)
--------------
Binary packages can be installed as usual, e.g.:
sudo apt-get install clang

Note that we still use binutils for some tools so we must continue to set
CROSS_COMPILE. To compile U-Boot with clang on linux without IAS use e.g.:
make HOSTCC=clang rpi_2_defconfig
make HOSTCC=clang CROSS_COMPILE=arm-linux-gnueabi- CC=clang -j8

It can also be used to compile sandbox:
make HOSTCC=clang sandbox_defconfig
make HOSTCC=clang CC=clang -j8

FreeBSD 11 (Current):
--------------------
Since llvm 3.4 is currently in the base system, the integrated as is
incapable of building U-Boot. Therefore gas from devel/arm-gnueabi-binutils
is used instead. It needs a symlinks to be picked up correctly though:

ln -s /usr/local/bin/arm-gnueabi-freebsd-as /usr/bin/arm-freebsd-eabi-as

# The following commands compile U-Boot using the clang xdev toolchain.
# NOTE: CROSS_COMPILE and target differ on purpose!
export CROSS_COMPILE=arm-gnueabi-freebsd-
gmake rpi_2_defconfig
gmake CC="clang -target arm-freebsd-eabi --sysroot /usr/arm-freebsd" -j8

Given that U-Boot will default to gcc, above commands can be
simplified with a simple wrapper script, listed below.

/usr/local/bin/arm-gnueabi-freebsd-gcc
---
#!/bin/sh

exec clang -target arm-freebsd-eabi --sysroot /usr/arm-freebsd "$@"

Commands are added to U-Boot by creating a new command structure.
This is done by first including command.h, then using the U_BOOT_CMD() macro
to fill in a cmd_tbl_t struct.

U_BOOT_CMD(name,maxargs,repeatable,command,"usage","help")

name:	 is the name of the commad. THIS IS NOT a string.
maxargs: the maximum number of arguments this function takes
repeatable: either 0 or 1 to indicate if autorepeat is allowed
command: Function pointer (*cmd)(struct cmd_tbl_s *, int, int, char *[]);
usage:	 Short description. This is a string
help:	 Long description. This is a string


**** Behind the scene ******

The structure created is named with a special prefix and placed by
the linker in a special section using the linker lists mechanism
(see include/linker_lists.h)

This makes it possible for the final link to extract all commands
compiled into any object code and construct a static array so the
command array can be iterated over using the linker lists macros.

The linker lists feature ensures that the linker does not discard
these symbols when linking full U-Boot even though they are not
referenced in the source code as such.

If a new board is defined do not forget to define the command section
by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these
3 lines:

	.u_boot_list : {
		KEEP(*(SORT(.u_boot_list*)));
	}

A slow day today so here is a revised itest command with provisional
support for comparing strings as well :-))

Now table driven to allow the operators
-eq, -ne, -lt, -gt, -le, -ge, ==, !=, <>, <, >, <=, >=

Uses the expected command modifier for integer compares of width 1, 2 or
4 bytes of .b, .w, .l and the new modifer of .s for a string compare.
String comparison is over the length of the shorter, this hopefully
avoids missing terminators when using an indirect pointer.

eg.
if itest.l *40000 == 12345678 then; ....
if itest.w *40000 != 1234 then; ....
if itest.b *40000 >= 12 then; ....
if itest.s *40000 -eq hello then; ....

The spl command is used to export a boot parameter image to RAM. Later
it may implement more functions connected to the SPL.

SUBCOMMAND EXPORT
To execute the command everything has to be in place as if bootm should be
used. (kernel image, initrd-image, fdt-image etc.)

export has two subcommands:
	atags: exports the ATAGS
	fdt: exports the FDT

Call is:
spl export <fdt|atags> [kernel_addr] [initrd_addr] [fdt_addr if fdt]


TYPICAL CALL

on OMAP3:
nandecc hw
nand read 0x82000000 0x280000 0x400000 	/* Read kernel image from NAND*/
spl export atags 			/* export ATAGS */
nand erase 0x680000 0x20000		/* erase - one page */
nand write 0x80000100 0x680000 0x20000	/* write the image - one page */

call with FDT:
nandecc hw
nand read 0x82000000 0x280000 0x400000 	/* Read kernel image from NAND*/
tftpboot 0x80000100 devkit8000.dtb /* Read fdt */
spl export fdt 0x82000000 - 0x80000100	/* export FDT */
nand erase 0x680000 0x20000		/* erase - one page */
nand write <adress shown by spl export> 0x680000 0x20000

/*
 * (C) Copyright 2000
 * Paolo Scaffardi, AIRVENT SAM s.p.a - RIMINI(ITALY), arsenio@tin.it
 *
 * SPDX-License-Identifier:	GPL-2.0+
 */

U-Boot console handling
========================

HOW THE CONSOLE WORKS?
----------------------

At system startup U-Boot initializes a serial console. When U-Boot
relocates itself to RAM, all console drivers are initialized (they
will register all detected console devices to the system for further
use).

If not defined in the environment, the first input device is assigned
to the 'stdin' file, the first output one to 'stdout' and 'stderr'.

You can use the command "coninfo" to see all registered console
devices and their flags. You can assign a standard file (stdin,
stdout or stderr) to any device you see in that list simply by
assigning its name to the corresponding environment variable. For
example:

    setenv stdin serial		<- To use the serial input
    setenv stdout video		<- To use the video console

Do a simple "saveenv" to save the console settings in the environment
and get them working on the next startup, too.

HOW CAN I USE STANDARD FILE INTO THE SOURCES?
---------------------------------------------

You can use the following functions to access the console:

* STDOUT:
    putc	(to put a char to stdout)
    puts	(to put a string to stdout)
    printf	(to format and put a string to stdout)

* STDIN:
    tstc	(to test for the presence of a char in stdin)
    getc	(to get a char from stdin)

* STDERR:
    eputc	(to put a char to stderr)
    eputs	(to put a string to stderr)
    eprintf	(to format and put a string to stderr)

* FILE (can be 'stdin', 'stdout', 'stderr'):
    fputc	(like putc but redirected to a file)
    fputs	(like puts but redirected to a file)
    fprintf	(like printf but redirected to a file)
    ftstc	(like tstc but redirected to a file)
    fgetc	(like getc but redirected to a file)

Remember that all FILE-related functions CANNOT be used before
U-Boot relocation (done in 'board_init_r' in arch/*/lib/board.c).

HOW CAN I USE STANDARD FILE INTO APPLICATIONS?
----------------------------------------------

Use the 'bd_mon_fnc' field of the bd_t structure passed to the
application to do everything you want with the console.

But REMEMBER that that will work only if you have not overwritten any
U-Boot code while loading (or uncompressing) the image of your
application.

For example, you won't get the console stuff running in the Linux
kernel because the kernel overwrites U-Boot before running. Only
some parameters like the framebuffer descriptors are passed to the
kernel in the high memory area to let the applications (the kernel)
use the framebuffers initialized by U-Boot.

SUPPORTED DRIVERS
-----------------

Working drivers:

    serial	(architecture dependent serial stuff)
    video	(mpc8xx video controller)

Work in progress:

    wl_kbd	(Wireless 4PPM keyboard)

Waiting for volounteers:

    lcd	(mpc8xx lcd controller; to )

TESTED CONFIGURATIONS
---------------------

The driver has been tested with the following configurations (see
CREDITS for other contact informations):

- MPC823FADS with AD7176 on a PAL TV (YCbYCr)	- arsenio@tin.it

Summary
=======

This README is about U-Boot support for TI's ARM 926EJS based family of SoCs.
These SOCs are used for cameras, video security and surveillance, DVR's, etc.
DaVinci SOC's comprise of DM644x, DM646x, DM35x and DM36x series of SOC's
Additionally there are some SOCs meant for the audio market which though have
an OMAP part number are very similar to the DaVinci series of SOC's
Additionally, some family members contain a TI DSP and/or graphics
co processors along with a host of other peripherals.

Currently the following boards are supported:

* TI DaVinci DM644x EVM

* TI DaVinci DM646x EVM

* TI DaVinci DM355 EVM

* TI DaVinci DM365 EVM

* TI DA830 EVM

* TI DA850 EVM

* DM355 based Leopard board

* DM644x based schmoogie board

* DM644x based sffsdr board

* DM644x based sonata board

Build
=====

* TI DaVinci DM644x EVM:

make davinci_dvevm_config
make

* TI DaVinci DM646x EVM:

make davinci_dm6467evm_config
make

* TI DaVinci DM355 EVM:

make davinci_dm355evm_config
make

* TI DaVinci DM365 EVM:

make davinci_dm365evm_config
make

* TI DA830 EVM:

make da830evm_config
make

* TI DA850 EVM:

make da850evm_config
make

* DM355 based Leopard board:

make davinci_dm355leopard_config
make

* DM644x based schmoogie board:

make davinci_schmoogie_config
make

* DM644x based sffsdr board:

make davinci_sffsdr_config
make

* DM644x based sonata board:

make davinci_sonata_config
make

Bootloaders
===============

The DaVinci SOC's use 2 bootloaders. The low level initialization
is done by a UBL(user boot loader). The UBL is written to a NAND/NOR/SPI flash
by a programmer. During initial bootup, the ROM Bootloader reads the UBL
from a storage device and loads it into the IRAM. The UBL then loads the U-Boot
into the RAM.
The programmers and UBL are always released as part of any standard TI
software release associated with an SOC.

Alternative boot method (DA850 EVM only):
For the DA850 EVM an SPL (secondary program loader, see doc/README.SPL)
is provided to load U-Boot directly from SPI flash. In this case, the
SPL does the low level initialization that is otherwise done by the SPL.
To build U-Boot with this SPL, do
make da850evm_config
make u-boot.ais
and program the resulting u-boot.ais file to the SPI flash of the DA850 EVM.

Environment Variables
=====================

The DA850 EVM allows the user to specify the maximum cpu clock allowed by the
silicon, in Hz, via an environment variable "maxcpuclk".

The maximum clock rate allowed depends on the silicon populated on the EVM.
Please make sure you understand the restrictions placed on this clock in the
device specific datasheet before setting up this variable. This information is
passed to the Linux kernel using the ATAG_REVISION atag.

If "maxcpuclk" is not defined, the configuration CONFIG_DA850_EVM_MAX_CPU_CLK
is used to obtain this information.

Links
=====

1) TI DaVinci DM355 EVM:
http://focus.ti.com/docs/prod/folders/print/tms320dm355.html
http://www.spectrumdigital.com/product_info.php?cPath=103&products_id=203&osCsid=c499af6087317f11b3da19b4e8f1af32

2) TI DaVinci DM365 EVM:
http://focus.ti.com/docs/prod/folders/print/tms320dm365.html?247SEM=
http://support.spectrumdigital.com/boards/evmdm365/revc/

3) DaVinci DM355 based leopard board
http://designsomething.org/leopardboard/default.aspx
http://www.spectrumdigital.com/product_info.php?cPath=103&products_id=192&osCsid=67c20335668ffc57cb35727106eb24b1

4) TI DaVinci DM6467 EVM:
http://focus.ti.com/docs/prod/folders/print/tms320dm6467.html
http://support.spectrumdigital.com/boards/evmdm6467/revf/

5) TI DaVinci DM6446 EVM:
http://focus.ti.com/docs/prod/folders/print/tms320dm6446.html
http://www.spectrumdigital.com/product_info.php?cPath=103&products_id=222

6) TI DA830 EVM
http://focus.ti.com/apps/docs/gencontent.tsp?appId=1&contentId=52385
http://www.spectrumdigital.com/product_info.php?cPath=37&products_id=214

7) TI DA850 EVM
http://focus.ti.com/docs/prod/folders/print/omap-l138.html
http://www.logicpd.com/products/development-kits/zoom-omap-l138-evm-development-kit

Davinci special defines
=======================

CONFIG_SYS_DV_NOR_BOOT_CFG:	AM18xx based boards, booting in NOR Boot mode
				need a "NOR Boot Configuration Word" stored
				in the NOR Flash. This define adds this.
				More Info about this, see:
				spraba5a.pdf chapter 3.1

With this approach, we don't need the UBL any more on DaVinci boards.
A "make boardname" will compile a u-boot.ubl, with UBL Header, which is
needed for the RBL to find the "UBL", which actually is a  UBL-compatible
header, nand spl code and u-boot code.


As the RBL uses another read function as the "standard" u-boot,
we need a command, which switches between this two read/write
functions, so we can write the UBL header and the spl
code in a format, which the RBL can read. This is realize
(at the moment in board specific code) in the u-boot command
nandrbl

nandrbl without arguments returns actual mode (rbl or uboot).
with nandrbl mode (mode = "rbl" or "uboot") you can switch
between the two NAND read/write modes.


To set up mkimage you need a config file for mkimage, example:
board/ait/cam_enc_4xx/ublimage.cfg

For information about the configuration please see:
doc/README.ublimage

Example for the cam_enc_4xx board:
On the cam_enc_4xx board we have a NAND flash with blocksize = 0x20000 and
pagesize = 0x800, so the u-boot.ubl image (which you get with:
"make cam_enc_4xx") looks like this:

00000000  00 ed ac a1 20 00 00 00  06 00 00 00 05 00 00 00  |.... ...........|
00000010  00 00 00 00 20 00 00 00  ff ff ff ff ff ff ff ff  |.... ...........|
00000020  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
*
00000800  14 00 00 ea 14 f0 9f e5  10 f0 9f e5 0c f0 9f e5  |................|
00000810  08 f0 9f e5 04 f0 9f e5  00 f0 9f e5 04 f0 1f e5  |................|
00000820  00 01 00 00 78 56 34 12  78 56 34 12 78 56 34 12  |....xV4.xV4.xV4.|
[...]
*
00001fe0  00 00 00 00 00 00 00 00  ff ff ff ff ff ff ff ff  |................|
00001ff0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
*
00003800  14 00 00 ea 14 f0 9f e5  14 f0 9f e5 14 f0 9f e5  |................|
00003810  14 f0 9f e5 14 f0 9f e5  14 f0 9f e5 14 f0 9f e5  |................|
00003820  80 01 08 81 e0 01 08 81  40 02 08 81 a0 02 08 81  |........@.......|

In the first "page" of the image, we have the UBL Header, needed for
the RBL to find the spl code.

The spl code starts in the second "page" of the image, with a size
defined by:

#define CONFIG_SYS_NROF_PAGES_NAND_SPL	6

After the spl code, there comes the "real" u-boot code
@ (6 + 1) * pagesize = 0x3800

------------------------------------------------------------------------
Setting up spl code:

/*
 * RBL searches from Block n (n = 1..24)
 * so we can define, how many UBL Headers
 * we write before the real spl code
 */
#define CONFIG_SYS_NROF_UBL_HEADER	5
#define CONFIG_SYS_NROF_PAGES_NAND_SPL	6

#define CONFIG_SYS_NAND_U_BOOT_OFFS	((CONFIG_SYS_NROF_UBL_HEADER * \
					CONFIG_SYS_NAND_BLOCK_SIZE) + \
					(CONFIG_SYS_NROF_PAGES_NAND_SPL) * \
					CONFIG_SYS_NAND_PAGE_SIZE)
------------------------------------------------------------------------

Burning into NAND:

step 1:
The RBL searches from Block n ( n = 1..24) on page 0 for valid UBL
Headers, so you have to burn the UBL header page from the u-boot.ubl
image to the blocks, you want to have the UBL header.
!! Don;t forget to switch to rbl nand read/write functions with
   "nandrbl rbl"

step 2:
You need to setup in the ublimage.cfg, where the RBL can find the spl
code, and how big it is.

!! RBL always starts reading from page 0 !!

For the AIT board, we have:
PAGES		6
START_BLOCK	5

So we need to copy the spl code to block 5 page 0
!! Don;t forget to switch to rbl nand read/write functions with
   "nandrbl rbl"

step 3:
You need to copy the u-boot image to the block/page
where the spl code reads it (CONFIG_SYS_NAND_U_BOOT_OFFS)
!! Don;t forget to switch to rbl nand read/write functions with
   "nandrbl uboot", which is default.

On the cam_enc_4xx board it is:
#define CONFIG_SYS_NAND_U_BOOT_OFFS	(0xc0000)

-> this results in following NAND usage on the cam_enc_4xx board:

addr

20000		possible UBL Header
40000		possible UBL Header
60000		possible UBL Header
80000		possilbe UBL Header
a0000		spl code
c0000		u-boot code

The above steps are executeed through the following environment vars:
(using 80000 as address for the UBL header)

pagesz=800
uboot=/tftpboot/cam_enc_4xx/u-boot.ubl
load=tftp 80000000 ${uboot}
writeheader nandrbl rbl;nand erase 80000 ${pagesz};nand write 80000000 80000 ${pagesz};nandrbl uboot
writenand_spl nandrbl rbl;nand erase a0000 3000;nand write 80000800 a0000 3000;nandrbl uboot
writeuboot nandrbl uboot;nand erase c0000 5d000;nand write 80003800 c0000 5d000
update=run load writeheader writenand_spl writeuboot

If you do a "run load update" u-boot, spl + ubl header
are magically updated ;-)

Note:
- There seem to be a bug in the RBL code (at least on my HW),
  In the UBL block, I can set the page to values != 0, so it
  is possible to burn step 1 and step 2 in one step into the
  flash, but the RBL ignores the page settings, so I have to
  burn the UBL Header to a page 0 and the spl code to
  a page 0 ... :-(
- If we make the nand read/write functions in the RBL equal to
  the functions in u-boot (as I have no RBL code, it is only
  possible in u-boot), we could burn the complete image in
  one step ... that would be nice ...

#
#  Copyright (C) 2015
#
#  Lukasz Majewski <l.majewski@majess.pl>
#
#
# SPDX-License-Identifier:	GPL-2.0+

Device Firmware Upgrade (DFU) - extension to use TFTP
=====================================================

Why?
----

* Update TFTP (CONFIG_UPDATE_TFTP) only supports writing
code to NAND memory via TFTP.
* DFU supports writing data to the variety of mediums (NAND,
eMMC, SD, partitions, RAM, etc) via USB.

Combination of both solves their shortcomings!


Overview
--------

This document briefly describes how to use DFU for
upgrading firmware (e.g. kernel, u-boot, rootfs, etc.)
via TFTP protocol.

By using Ethernet (TFTP protocol to be precise) it is
possible to overcome the major problem of USB based DFU -
the relatively low transfer speed for large files.
This was caused by DFU standard, which imposed utilization
of only EP0 for transfer. By using Ethernet we can circumvent
this shortcoming.

Beagle Bone Black rev. C (BBB) powered by TI's am335x CPU has
been used as a demo board.

To utilize this feature, one needs to first enable support
for USB based DFU (CONFIG_DFU_*) and DFU TFTP update
(CONFIG_DFU_TFTP) described in ./doc/README.update.

The "dfu" command has been extended to support transfer via TFTP - one
needs to type for example "dfu tftp 0 mmc 0"

This feature does not depend on "fitupd" command enabled.

As of this writing (SHA1:8d77576371381ade83de475bb639949b44941e8c v2015.10-rc2)
the update.c code is not enabled (CONFIG_UPDATE_TFTP) by any board in the
contemporary u-boot tree.


Environment variables
---------------------

The "dfu tftp" command can be used in the "preboot" environment variable
(when it is enabled by defining CONFIG_PREBOOT).
This is the preferable way of using this command in the early boot stage
as opposed to legacy update_tftp() function invocation.


Beagle Bone Black (BBB) setup
-----------------------------

1. Setup tftp env variables:
   *  select desired eth device - 'ethact' variable ["ethact=cpsw"]
      (use "bdinfo" to check current setting)
   *  setup "serverip" and "ipaddr" variables
   *  set "loadaddr" as a fixed buffer where incoming data is placed
      ["loadaddr=0x81000000"]

#########
# BONUS #
#########
It is possible to use USB interface to emulate ETH connection by setting
"ethact=usb_ether". In this way one can have very fast DFU transfer via USB.

For 33MiB test image the transfer rate was 1MiB/s for ETH over USB and 200KiB/s
for pure DFU USB transfer.

2. Setup update_tftp variables:
   *  set "updatefile" - the file name to be downloaded via TFTP (stored on
      the HOST at e.g. /srv/tftp)

3. If required, to update firmware on boot, put the "dfu tftp 0 mmc 0" in the
    "preboot" env variable. Otherwise use this command from u-boot prompt.

4. Inspect "dfu" specific variables:
   * "dfu_alt_info" - information about available DFU entities
   * "dfu_bufsiz"   - variable to set buffer size [in bytes] - when it is not
		    possible to set large enough default buffer (8 MiB @ BBB)



FIT image format for download
-----------------------------

To create FIT image for download one should follow the update tftp README file
(./doc/README.update) with one notable difference:

The original snippet of ./doc/uImage.FIT/update_uboot.its

	images {
		update@1 {
			description = "U-Boot binary";

should look like

	images {
		u-boot.bin@1 {
			description = "U-Boot binary";

where "u-boot.bin" is the DFU entity name to be stored.



To do
-----

* Extend dfu-util command to support TFTP based transfers
* Upload support (via TFTP)

If you are experiencing hangups/data-aborts when trying to display a BMP image,
the following might be relevant to your situation...

Some architectures cannot handle unaligned memory accesses, and an attempt to
perform one will lead to a data abort. On such architectures it is necessary to
make sure all data is properly aligned, and in many situations simply choosing
a 32 bit aligned address is enough to ensure proper alignment. This is not
always the case when dealing with data that has an internal layout such as a
BMP image:

BMP images have a header that starts with 2 byte-size fields followed by mostly
32 bit fields. The packed struct that represents this header can be seen below:

typedef struct bmp_header {
	/* Header */
	char signature[2];
	__u32	file_size;
	__u32	reserved;
	__u32	data_offset;
	... etc
} __attribute__ ((packed)) bmp_header_t;

When placed in an aligned address such as 0x80a00000, char signature offsets
the __u32 fields into unaligned addresses (in our example 0x80a00002,
0x80a00006, and so on...). When these fields are accessed by U-Boot, a 32 bit
access is generated at a non-32-bit-aligned address, causing a data abort.
The proper alignment for BMP images is therefore: 32-bit-aligned-address + 2.

/*
 * (C) Copyright 2014 Red Hat Inc.
 * Copyright (c) 2014-2015, NVIDIA CORPORATION.  All rights reserved.
 * Copyright (C) 2015 K. Merker <merker@debian.org>
 *
 * SPDX-License-Identifier:     GPL-2.0+
 */

Generic Distro Configuration Concept
====================================

Linux distributions are faced with supporting a variety of boot mechanisms,
environments or bootloaders (PC BIOS, EFI, U-Boot, Barebox, ...). This makes
life complicated. Worse, bootloaders such as U-Boot have a configurable set
of features, and each board chooses to enable a different set of features.
Hence, distros typically need to have board-specific knowledge in order to
set up a bootable system.

This document defines a common set of U-Boot features that are required for
a distro to support the board in a generic fashion. Any board wishing to
allow distros to install and boot in an out-of-the-box fashion should enable
all these features. Linux distros can then create a single set of boot
support/install logic that targets these features. This will allow distros
to install on many boards without the need for board-specific logic.

In fact, some of these features can be implemented by any bootloader, thus
decoupling distro install/boot logic from any knowledge of the bootloader.

This model assumes that boards will load boot configuration files from a
regular storage mechanism (eMMC, SD card, USB Disk, SATA disk, etc.) with
a standard partitioning scheme (MBR, GPT). Boards that cannot support this
storage model are outside the scope of this document, and may still need
board-specific installer/boot-configuration support in a distro.

To some extent, this model assumes that a board has a separate boot flash
that contains U-Boot, and that the user has somehow installed U-Boot to this
flash before running the distro installer. Even on boards that do not conform
to this aspect of the model, the extent of the board-specific support in the
distro installer logic would be to install a board-specific U-Boot package to
the boot partition during installation. This distro-supplied U-Boot can still
implement the same features as on any other board, and hence the distro's boot
configuration file generation logic can still be board-agnostic.

Locating Bootable Disks
-----------------------

Typical desktop/server PCs search all (or a user-defined subset of) attached
storage devices for a bootable partition, then load the bootloader or boot
configuration files from there. A U-Boot board port that enables the features
mentioned in this document will search for boot configuration files in the
same way.

Thus, distros do not need to manipulate any kind of bootloader-specific
configuration data to indicate which storage device the system should boot
from.

Distros simply need to install the boot configuration files (see next
section) in an ext2/3/4 or FAT partition, mark the partition bootable (via
the MBR bootable flag, or GPT legacy_bios_bootable attribute), and U-Boot (or
any other bootloader) will find those boot files and execute them. This is
conceptually identical to creating a grub2 configuration file on a desktop
PC.

Note that in the absence of any partition that is explicitly marked bootable,
U-Boot falls back to searching the first valid partition of a disk for boot
configuration files. Other bootloaders are recommended to do the same, since
I believe that partition table bootable flags aren't so commonly used outside
the realm of x86 PCs.

U-Boot can also search for boot configuration files from a TFTP server.

Boot Configuration Files
------------------------

The standard format for boot configuration files is that of extlinux.conf, as
handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly
as specified at:

http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/

... with the exceptions that the BootLoaderSpec document:

* Prescribes a separate configuration per boot menu option, whereas U-Boot
  lumps all options into a single extlinux.conf file. Hence, U-Boot searches
  for /extlinux/extlinux.conf then /boot/extlinux/extlinux.conf on disk, or
  pxelinux.cfg/default over the network.

* Does not document the fdtdir option, which automatically selects the DTB to
  pass to the kernel.

One example extlinux.conf generated by the Fedora installer is:

------------------------------------------------------------
# extlinux.conf generated by anaconda

ui menu.c32

menu autoboot Welcome to Fedora. Automatic boot in # second{,s}. Press a key for options.
menu title Fedora Boot Options.
menu hidden

timeout 50
#totaltimeout 9000

default Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)

label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl) 22 (Rawhide)
	kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl
	append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf
	fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl
	initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl.img

label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)
	kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
	append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf
	fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
	initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae.img

label Fedora-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc (0-rescue-8f6ba7b039524e0eb957d2c9203f04bc)
	kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc
	initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img
	append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8
	fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae
------------------------------------------------------------

Another hand-crafted network boot configuration file is:

------------------------------------------------------------
TIMEOUT 100

MENU TITLE TFTP boot options

LABEL jetson-tk1-emmc
        MENU LABEL ../zImage root on Jetson TK1 eMMC
        LINUX ../zImage
        FDTDIR ../
        APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=80a5a8e9-c744-491a-93c1-4f4194fd690b

LABEL venice2-emmc
        MENU LABEL ../zImage root on Venice2 eMMC
        LINUX ../zImage
        FDTDIR ../
        APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=5f71e06f-be08-48ed-b1ef-ee4800cc860f

LABEL sdcard
        MENU LABEL ../zImage, root on 2GB sdcard
        LINUX ../zImage
        FDTDIR ../
        APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=b2f82cda-2535-4779-b467-094a210fbae7

LABEL fedora-installer-fk
        MENU LABEL Fedora installer w/ Fedora kernel
        LINUX fedora-installer/vmlinuz
        INITRD fedora-installer/initrd.img.orig
        FDTDIR fedora-installer/dtb
        APPEND loglevel=8 ip=dhcp inst.repo=http://10.0.0.2/mirrors/fedora/linux/development/rawhide/armhfp/os/ rd.shell cma=64M
------------------------------------------------------------

U-Boot Implementation
=====================

Enabling the distro options
---------------------------

In your board's defconfig, enable the DISTRO_DEFAULTS option by adding
a line with "CONFIG_DISTRO_DEFAULTS=y". If you want to enable this
from Kconfig itself, for e.g. all boards using a specific SoC then
add a "default y if ARCH_FOO" to the DISTRO_DEFAULTS section of
the Kconfig file in the root of the u-boot sources.

In your board configuration file, include the following:

------------------------------------------------------------
#ifndef CONFIG_SPL_BUILD
#include <config_distro_defaults.h>
#include <config_distro_bootcmd.h>
#endif
------------------------------------------------------------

The first of those headers primarily enables a core set of U-Boot features,
such as support for MBR and GPT partitions, ext* and FAT filesystems, booting
raw zImage and initrd (rather than FIT- or uImage-wrapped files), etc. Network
boot support is also enabled here, which is useful in order to boot distro
installers given that distros do not commonly distribute bootable install
media for non-PC targets at present.

Finally, a few options that are mostly relevant only when using U-Boot-
specific boot.scr scripts are enabled. This enables distros to generate a
U-Boot-specific boot.scr script rather than extlinux.conf as the boot
configuration file. While doing so is fully supported, and
<config_distro_defaults.h> exposes enough parameterization to boot.scr to
allow for board-agnostic boot.scr content, this document recommends that
distros generate extlinux.conf rather than boot.scr. extlinux.conf is intended
to work across multiple bootloaders, whereas boot.scr will only work with
U-Boot. TODO: document the contract between U-Boot and boot.scr re: which
environment variables a generic boot.scr may rely upon.

The second of those headers sets up the default environment so that $bootcmd
is defined in a way that searches attached disks for boot configuration files,
and executes them if found.

Required Environment Variables
------------------------------

The U-Boot "syslinux" and "pxe boot" commands require a number of environment
variables be set. Default values for these variables are often hard-coded into
CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that
the user doesn't have to configure them.

fdt_addr:

  Mandatory for any system that provides the DTB in HW (e.g. ROM) and wishes
  to pass that DTB to Linux, rather than loading a DTB from the boot
  filesystem. Prohibited for any other system.

  If specified a DTB to boot the system must be available at the given
  address.

fdt_addr_r:

  Mandatory. The location in RAM where the DTB will be loaded or copied to when
  processing the fdtdir/devicetreedir or fdt/devicetree options in
  extlinux.conf.

  This is mandatory even when fdt_addr is provided, since extlinux.conf must
  always be able to provide a DTB which overrides any copy provided by the HW.

  A size of 1MB for the FDT/DTB seems reasonable.

ramdisk_addr_r:

  Mandatory. The location in RAM where the initial ramdisk will be loaded to
  when processing the initrd option in extlinux.conf.

  It is recommended that this location be highest in RAM out of fdt_addr_,
  kernel_addr_r, and ramdisk_addr_r, so that the RAM disk can vary in size
  and use any available RAM.

kernel_addr_r:

  Mandatory. The location in RAM where the kernel will be loaded to when
  processing the kernel option in the extlinux.conf.

  The kernel should be located within the first 128M of RAM in order for the
  kernel CONFIG_AUTO_ZRELADDR option to work, which is likely enabled on any
  distro kernel. Since the kernel will decompress itself to 0x8000 after the
  start of RAM, kernel_addr_r should not overlap that area, or the kernel will
  have to copy itself somewhere else first before decompression.

  A size of 16MB for the kernel is likely adequate.

pxefile_addr_r:

  Mandatory. The location in RAM where extlinux.conf will be loaded to prior
  to processing.

  A size of 1MB for extlinux.conf is more than adequate.

scriptaddr:

  Mandatory, if the boot script is boot.scr rather than extlinux.conf. The
  location in RAM where boot.scr will be loaded to prior to execution.

  A size of 1MB for extlinux.conf is more than adequate.

For suggestions on memory locations for ARM systems, you must follow the
guidelines specified in Documentation/arm/Booting in the Linux kernel tree.

For a commented example of setting these values, please see the definition of
MEM_LAYOUT_ENV_SETTINGS in include/configs/tegra124-common.h.

Boot Target Configuration
-------------------------

<config_distro_bootcmd.h> defines $bootcmd and many helper command variables
that automatically search attached disks for boot configuration files and
execute them. Boards must provide configure <config_distro_bootcmd.h> so that
it supports the correct set of possible boot device types. To provide this
configuration, simply define macro BOOT_TARGET_DEVICES prior to including
<config_distro_bootcmd.h>. For example:

------------------------------------------------------------
#ifndef CONFIG_SPL_BUILD
#define BOOT_TARGET_DEVICES(func) \
        func(MMC, mmc, 1) \
        func(MMC, mmc, 0) \
        func(USB, usb, 0) \
        func(PXE, pxe, na) \
        func(DHCP, dhcp, na)
#include <config_distro_bootcmd.h>
#endif
------------------------------------------------------------

Each entry in the macro defines a single boot device (e.g. a specific eMMC
device or SD card) or type of boot device (e.g. USB disk). The parameters to
the func macro (passed in by the internal implementation of the header) are:

- Upper-case disk type (MMC, SATA, SCSI, IDE, USB, DHCP, PXE).
- Lower-case disk type (same options as above).
- ID of the specific disk (MMC only) or ignored for other types.

User Configuration
==================

Once the user has installed U-Boot, it is expected that the environment will
be reset to the default values in order to enable $bootcmd and friends, as set
up by <config_distro_bootcmd.h>. After this, various environment variables may
be altered to influence the boot process:

boot_targets:

  The list of boot locations searched.

  Example: mmc0, mmc1, usb, pxe

  Entries may be removed or re-ordered in this list to affect the boot order.

boot_prefixes:

  For disk-based booting, the list of directories within a partition that are
  searched for boot configuration files (extlinux.conf, boot.scr).

  Example: / /boot/

  Entries may be removed or re-ordered in this list to affect the set of
  directories which are searched.

boot_scripts:

  The name of U-Boot style boot.scr files that $bootcmd searches for.

  Example: boot.scr.uimg boot.scr

  (Typically we expect extlinux.conf to be used, but execution of boot.scr is
  maintained for backwards-compatibility.)

  Entries may be removed or re-ordered in this list to affect the set of
  filenames which are supported.

scan_dev_for_extlinux:

  If you want to disable extlinux.conf on all disks, set the value to something
  innocuous, e.g. setenv scan_dev_for_extlinux true.

scan_dev_for_scripts:

  If you want to disable boot.scr on all disks, set the value to something
  innocuous, e.g. setenv scan_dev_for_scripts true.

boot_net_usb_start:

  If you want to prevent USB enumeration by distro boot commands which execute
  network operations, set the value to something innocuous, e.g. setenv
  boot_net_usb_start true. This would be useful if you know your Ethernet
  device is not attached to USB, and you wish to increase boot speed by
  avoiding unnecessary actions.

boot_net_pci_enum:

  If you want to prevent PCI enumeration by distro boot commands which execute
  network operations, set the value to something innocuous, e.g. setenv
  boot_net_pci_enum true. This would be useful if you know your Ethernet
  device is not attached to PCI, and you wish to increase boot speed by
  avoiding unnecessary actions.

Interactively booting from a specific device at the u-boot prompt
=================================================================

For interactively booting from a user-selected device at the u-boot command
prompt, the environment provides predefined bootcmd_<target> variables for
every target defined in boot_targets, which can be run be the user.

If the target is a storage device, the format of the target is always
<device type><device number>, e.g. mmc0.  Specifying the device number is
mandatory for storage devices, even if only support for a single instance
of the storage device is actually implemented.

For network targets (dhcp, pxe), only the device type gets specified;
they do not have a device number.

Examples:

 - run bootcmd_usb0
   boots from the first USB mass storage device

 - run bootcmd_mmc1
   boots from the second MMC device

 - run bootcmd_pxe
   boots by tftp using a pxelinux.cfg

The list of possible targets consists of:

- network targets
  * dhcp
  * pxe

- storage targets (to which a device number must be appended)
  * mmc
  * sata
  * scsi
  * ide
  * usb

Other *boot* variables than the ones defined above are only for internal use
of the boot environment and are not guaranteed to exist or work in the same
way in future u-boot versions.  In particular the <device type>_boot
variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation
detail and must not be used as a public interface.