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.

AX25 is Andes CPU IP to adopt RISC-V architecture.

Features
========

CPU Core
 - 5-stage in-order execution pipeline
 - Hardware Multiplier
	 - radix-2/radix-4/radix-16/radix-256/fast
 - Hardware Divider
 - Optional branch prediction
 - Machine mode and optional user mode
 - Optional performance monitoring

ISA
 - RV64I base integer instructions
 - RVC for 16-bit compressed instructions
 - RVM for multiplication and division instructions

Memory subsystem
 - I & D local memory
   - Size: 4KB to 16MB
 - Memory subsyetem soft-error protection
   - Protection scheme: parity-checking or error-checking-and-correction (ECC)
   - Automatic hardware error correction

Bus
 - Interface Protocol
   - Synchronous AHB (32-bit/64-bit data-width), or
   - Synchronous AXI4 (64-bit data-width)

Power management
 - Wait for interrupt (WFI) mode

Debug
 - Configurable number of breakpoints: 2/4/8
 - External Debug Module
   - AHB slave port
 - External JTAG debug transport module

Platform Level Interrupt Controller (PLIC)
 - AHB slave port
 - Configurable number of interrupts: 1-1023
 - Configurable number of interrupt priorities: 3/7/15/63/127/255
 - Configurable number of targets:  1-16
 - Preempted interrupt priority stack

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 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_FS_FAT (fs/fat/libfat.o)
CONFIG_SPL_FS_EXT4
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 AE350
===========================

AE350 is the mainline SoC produced by Andes Technology using AX25 CPU core
base on RISC-V architecture.

AE350 has integrated both AHB and APB bus and many periphals for application
and product development.

AX25-AE350
=========

AX25-AE350 is the SoC with AE350 hardcore CPU.

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

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/ax25-ae350.h".

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

build:
1. Prepare the toolchains and make sure the $PATH to toolchains is correct.
2. Use `make ae350_rv[32|64]_defconfig` in u-boot root to build the image for 32 or 64 bit.

Verification
====================

Target
====================
1. startup
2. relocation
3. timer driver
4. uart driver
5. mac driver
6. mmc driver
7. spi driver

Steps
====================
1. Define CONFIG_SKIP_LOWLEVEL_INIT to build u-boot which is loaded via gdb from ram.
2. Undefine CONFIG_SKIP_LOWLEVEL_INIT to build u-boot which is booted from spi rom.
3. Ping a server by mac driver
4. Scan sd card and copy u-boot image which is booted from flash to ram by sd driver.
5. Burn this u-boot image to spi rom by spi driver
6. Re-boot u-boot from spi flash with power off and power on.

Messages of U-Boot boot on AE350 board
======================================
U-Boot 2018.01-rc2-00033-g824f89a (Dec 21 2017 - 16:51:26 +0800)

DRAM:  1 GiB
MMC:   mmc@f0e00000: 0
SF: Detected mx25u1635e with page size 256 Bytes, erase size 4 KiB, total 2 MiB
In:    serial@f0300000
Out:   serial@f0300000
Err:   serial@f0300000
Net:
Warning: mac@e0100000 (eth0) using random MAC address - be:dd:d7:e4:e8:10
eth0: mac@e0100000

RISC-V # version
U-Boot 2018.01-rc2-00033-gb265b91-dirty (Dec 22 2017 - 13:54:21 +0800)

riscv32-unknown-linux-gnu-gcc (GCC) 7.2.0
GNU ld (GNU Binutils) 2.29

RISC-V # setenv ipaddr 10.0.4.200 ;
RISC-V # setenv serverip 10.0.4.97 ;
RISC-V # ping 10.0.4.97 ;
Using mac@e0100000 device
host 10.0.4.97 is alive

RISC-V # mmc rescan
RISC-V # fatls mmc 0:1
   318907   u-boot-ae350-64.bin
     1252   hello_world_ae350_32.bin
   328787   u-boot-ae350-32.bin

3 file(s), 0 dir(s)

RISC-V # sf probe 0:0 50000000 0
SF: Detected mx25u1635e with page size 256 Bytes, erase size 4 KiB, total 2 MiB

RISC-V # sf test 0x100000 0x1000
SPI flash test:
0 erase: 36 ticks, 111 KiB/s 0.888 Mbps
1 check: 29 ticks, 137 KiB/s 1.096 Mbps
2 write: 40 ticks, 100 KiB/s 0.800 Mbps
3 read: 20 ticks, 200 KiB/s 1.600 Mbps
Test passed
0 erase: 36 ticks, 111 KiB/s 0.888 Mbps
1 check: 29 ticks, 137 KiB/s 1.096 Mbps
2 write: 40 ticks, 100 KiB/s 0.800 Mbps
3 read: 20 ticks, 200 KiB/s 1.600 Mbps

RISC-V # fatload mmc 0:1 0x600000 u-boot-ae350-32.bin
reading u-boot-ae350-32.bin
328787 bytes read in 324 ms (990.2 KiB/s)

RISC-V # sf erase 0x0 0x51000
SF: 331776 bytes @ 0x0 Erased: OK

RISC-V # sf write 0x600000 0x0 0x50453
device 0 offset 0x0, size 0x50453
SF: 328787 bytes @ 0x0 Written: OK

RISC-V # crc32 0x600000 0x50453
crc32 for 00600000 ... 00650452 ==> 692dc44a

RISC-V # crc32 0x80000000 0x50453
crc32 for 80000000 ... 80050452 ==> 692dc44a
RISC-V #

*** power-off and power-on, this U-Boot is booted from spi flash 	***

U-Boot 2018.01-rc2-00032-gf67dd47-dirty (Dec 21 2017 - 13:56:03 +0800)

DRAM:  1 GiB
MMC:   mmc@f0e00000: 0
SF: Detected mx25u1635e with page size 256 Bytes, erase size 4 KiB, total 2 MiB
In:    serial@f0300000
Out:   serial@f0300000
Err:   serial@f0300000
Net:
Warning: mac@e0100000 (eth0) using random MAC address - ee:4c:58:29:32:f5
eth0: mac@e0100000
RISC-V #


Boot bbl and riscv-linux via U-Boot on QEMU
===========================================
1. Build riscv-linux
2. Build bbl and riscv-linux with --with-payload
3. Prepare ae350.dtb
4. Creating OS-kernel images
	./mkimage -A riscv -O linux -T kernel -C none -a 0x0000 -e 0x0000 -d bbl.bin bootmImage-bbl.bin
	Image Name:
	Created:      Tue Mar 13 10:06:42 2018
	Image Type:   RISC-V Linux Kernel Image (uncompressed)
	Data Size:    17901204 Bytes = 17481.64 KiB = 17.07 MiB
	Load Address: 00000000
	Entry Point:  00000000

4. Copy bootmImage-bbl.bin and ae350.dtb to qemu sd card image
5. Message of booting riscv-linux from bbl via u-boot on qemu

U-Boot 2018.03-rc4-00031-g2631273 (Mar 13 2018 - 15:02:55 +0800)

DRAM:  1 GiB
main-loop: WARNING: I/O thread spun for 1000 iterations
MMC:   mmc@f0e00000: 0
Loading Environment from SPI Flash... *** Warning - spi_flash_probe_bus_cs() failed, using default environment

Failed (-22)
In:    serial@f0300000
Out:   serial@f0300000
Err:   serial@f0300000
Net:
Warning: mac@e0100000 (eth0) using random MAC address - 02:00:00:00:00:00
eth0: mac@e0100000
RISC-V # mmc rescan
RISC-V # mmc part

Partition Map for MMC device 0  --   Partition Type: DOS

Part    Start Sector    Num Sectors     UUID            Type
RISC-V # fatls mmc 0:0
 17901268   bootmImage-bbl.bin
     1954   ae2xx.dtb

2 file(s), 0 dir(s)

RISC-V # fatload mmc 0:0 0x00600000 bootmImage-bbl.bin
17901268 bytes read in 4642 ms (3.7 MiB/s)
RISC-V # fatload mmc 0:0 0x2000000 ae350.dtb
1954 bytes read in 1 ms (1.9 MiB/s)
RISC-V # setenv bootm_size 0x2000000
RISC-V # setenv fdt_high 0x1f00000
RISC-V # bootm 0x00600000 - 0x2000000
## Booting kernel from Legacy Image at 00600000 ...
   Image Name:
   Image Type:   RISC-V Linux Kernel Image (uncompressed)
   Data Size:    17901204 Bytes = 17.1 MiB
   Load Address: 00000000
   Entry Point:  00000000
   Verifying Checksum ... OK
## Flattened Device Tree blob at 02000000
   Booting using the fdt blob at 0x2000000
   Loading Kernel Image ... OK
   Loading Device Tree to 0000000001efc000, end 0000000001eff7a1 ... OK
[    0.000000] OF: fdt: Ignoring memory range 0x0 - 0x200000
[    0.000000] Linux version 4.14.0-00046-gf3e439f-dirty (rick@atcsqa06) (gcc version 7.1.1 20170509 (GCC)) #1 Tue Jan 9 16:34:25 CST 2018
[    0.000000] bootconsole [early0] enabled
[    0.000000] Initial ramdisk at: 0xffffffe000016a98 (12267008 bytes)
[    0.000000] Zone ranges:
[    0.000000]   DMA      [mem 0x0000000000200000-0x000000007fffffff]
[    0.000000]   Normal   empty
[    0.000000] Movable zone start for each node
[    0.000000] Early memory node ranges
[    0.000000]   node   0: [mem 0x0000000000200000-0x000000007fffffff]
[    0.000000] Initmem setup node 0 [mem 0x0000000000200000-0x000000007fffffff]
[    0.000000] elf_hwcap is 0x112d
[    0.000000] random: fast init done
[    0.000000] Built 1 zonelists, mobility grouping on.  Total pages: 516615
[    0.000000] Kernel command line: console=ttyS0,38400n8 earlyprintk=uart8250-32bit,0xf0300000 debug loglevel=7
[    0.000000] PID hash table entries: 4096 (order: 3, 32768 bytes)
[    0.000000] Dentry cache hash table entries: 262144 (order: 9, 2097152 bytes)
[    0.000000] Inode-cache hash table entries: 131072 (order: 8, 1048576 bytes)
[    0.000000] Sorting __ex_table...
[    0.000000] Memory: 2047832K/2095104K available (1856K kernel code, 204K rwdata, 532K rodata, 12076K init, 756K bss, 47272K reserved, 0K cma-reserved)
[    0.000000] SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=1, Nodes=1
[    0.000000] NR_IRQS: 0, nr_irqs: 0, preallocated irqs: 0
[    0.000000] riscv,cpu_intc,0: 64 local interrupts mapped
[    0.000000] riscv,plic0,e4000000: mapped 31 interrupts to 1/2 handlers
[    0.000000] clocksource: riscv_clocksource: mask: 0xffffffffffffffff max_cycles: 0x24e6a1710, max_idle_ns: 440795202120 ns
[    0.000000] Calibrating delay loop (skipped), value calculated using timer frequency.. 20.00 BogoMIPS (lpj=40000)
[    0.000000] pid_max: default: 32768 minimum: 301
[    0.004000] Mount-cache hash table entries: 4096 (order: 3, 32768 bytes)
[    0.004000] Mountpoint-cache hash table entries: 4096 (order: 3, 32768 bytes)
[    0.056000] devtmpfs: initialized
[    0.060000] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 7645041785100000 ns
[    0.064000] futex hash table entries: 256 (order: 0, 6144 bytes)
[    0.068000] NET: Registered protocol family 16
[    0.080000] vgaarb: loaded
[    0.084000] clocksource: Switched to clocksource riscv_clocksource
[    0.088000] NET: Registered protocol family 2
[    0.092000] TCP established hash table entries: 16384 (order: 5, 131072 bytes)
[    0.096000] TCP bind hash table entries: 16384 (order: 5, 131072 bytes)
[    0.096000] TCP: Hash tables configured (established 16384 bind 16384)
[    0.100000] UDP hash table entries: 1024 (order: 3, 32768 bytes)
[    0.100000] UDP-Lite hash table entries: 1024 (order: 3, 32768 bytes)
[    0.104000] NET: Registered protocol family 1
[    0.616000] Unpacking initramfs...
[    1.220000] workingset: timestamp_bits=62 max_order=19 bucket_order=0
[    1.244000] io scheduler noop registered
[    1.244000] io scheduler cfq registered (default)
[    1.244000] io scheduler mq-deadline registered
[    1.248000] io scheduler kyber registered
[    1.360000] Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
[    1.368000] console [ttyS0] disabled
[    1.372000] f0300000.serial: ttyS0 at MMIO 0xf0300020 (irq = 10, base_baud = 1228800) is a 16550A
[    1.392000] console [ttyS0] enabled
[    1.392000] ftmac100: Loading version 0.2 ...
[    1.396000] ftmac100 e0100000.mac eth0: irq 8, mapped at ffffffd002005000
[    1.400000] ftmac100 e0100000.mac eth0: generated random MAC address 6e:ac:c3:92:36:c0
[    1.404000] IR NEC protocol handler initialized
[    1.404000] IR RC5(x/sz) protocol handler initialized
[    1.404000] IR RC6 protocol handler initialized
[    1.404000] IR JVC protocol handler initialized
[    1.408000] IR Sony protocol handler initialized
[    1.408000] IR SANYO protocol handler initialized
[    1.408000] IR Sharp protocol handler initialized
[    1.408000] IR MCE Keyboard/mouse protocol handler initialized
[    1.412000] IR XMP protocol handler initialized
[    1.456000] ftsdc010 f0e00000.mmc: mmc0 - using hw SDIO IRQ
[    1.464000] bootconsole [early0] uses init memory and must be disabled even before the real one is ready
[    1.464000] bootconsole [early0] disabled
[    1.508000] Freeing unused kernel memory: 12076K
[    1.512000] This architecture does not have kernel memory protection.
[    1.520000] mmc0: new SD card at address 4567
[    1.524000] mmcblk0: mmc0:4567 QEMU! 20.0 MiB
[    1.844000]  mmcblk0:
Wed Dec  1 10:00:00 CST 2010
/ #



TODO
==================================================
Boot bbl and riscv-linux via U-Boot on AE350 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 and UDP is described in the
``README.android-fastboot-protocol`` file in the same directory.

The current implementation supports the following standard commands:

- ``boot``
- ``continue``
- ``download``
- ``erase`` (if enabled)
- ``flash`` (if enabled)
- ``getvar``
- ``reboot``
- ``reboot-bootloader``
- ``set_active`` (only a stub implementation which always succeeds)

The following OEM commands are supported (if enabled):

- oem format - this executes ``gpt write mmc %x $partitions``

Support for both eMMC and NAND devices is included.

Client installation
===================

The counterpart to this 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 OSX. The fastboot client is
part of the Android SDK Platform-Tools and can be downloaded from:

https://developer.android.com/studio/releases/platform-tools

Board specific
==============

USB configuration
-----------------

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.

General configuration
---------------------

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``. These
may be overridden on the fastboot command line using ``-l`` and
``-s``.

Fastboot environment variables
==============================

Partition aliases
-----------------

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.

The current implementation 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>``

for example:

``fastboot_partition_alias_boot=LNX``

Variable overrides
------------------

Variables retrived through ``getvar`` can be overridden by defining
environment variables of the form ``fastboot.<variable>``. These are
looked up first so can be used to override values which would
otherwise be returned. Using this mechanism you can also return types
for NAND filesystems, as the fully parameterised variable is looked
up, e.g.

``fastboot.partition-type:boot=jffs2``

Boot command
------------

When executing the fastboot ``boot`` command, if ``fastboot_bootcmd`` is set then
that will be executed in place of ``bootm <CONFIG_FASTBOOT_BUF_ADDR>``.

Partition Names
===============

The Fastboot implementation in U-Boot allows to write images into disk
partitions. 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 for either USB:

::

   => fastboot usb 0

or UDP:

::

   => fastboot udp
   link up on port 0, speed 100, full duplex
   Using ethernet@4a100000 device
   Listening for fastboot command on 192.168.0.102

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 U-Boot 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_WDT and CONFIG_WDT_AT91 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.

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

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.

Android Verified Boot 2.0

This file contains information about the current support of Android Verified
Boot 2.0 in U-boot

1. OVERVIEW
---------------------------------
Verified Boot establishes a chain of trust from the bootloader to system images
* Provides integrity checking for:
  - Android Boot image: Linux kernel + ramdisk. RAW hashing of the whole
    partition is done and the hash is compared with the one stored in
    the VBMeta image
  - system/vendor partitions: verifying root hash of dm-verity hashtrees.
* Provides capabilities for rollback protection.

Integrity of the bootloader (U-boot BLOB and environment) is out of scope.

For additional details check:
https://android.googlesource.com/platform/external/avb/+/master/README.md

1.1. AVB using OP-TEE (optional)
---------------------------------
If AVB is configured to use OP-TEE (see 4. below) rollback indexes and
device lock state are stored in RPMB. The RPMB partition is managed by
OP-TEE (https://www.op-tee.org/) which is a secure OS leveraging ARM
TrustZone.


2. AVB 2.0 U-BOOT SHELL COMMANDS
-----------------------------------
Provides CLI interface to invoke AVB 2.0 verification + misc. commands for
different testing purposes:

avb init <dev> - initialize avb 2.0 for <dev>
avb verify - run verification process using hash data from vbmeta structure
avb read_rb <num> - read rollback index at location <num>
avb write_rb <num> <rb> - write rollback index <rb> to <num>
avb is_unlocked - returns unlock status of the device
avb get_uuid <partname> - read and print uuid of partition <partname>
avb read_part <partname> <offset> <num> <addr> - read <num> bytes from
partition <partname> to buffer <addr>
avb write_part <partname> <offset> <num> <addr> - write <num> bytes to
<partname> by <offset> using data from <addr>


3. PARTITIONS TAMPERING (EXAMPLE)
-----------------------------------
Boot or system/vendor (dm-verity metadata section) is tampered:
=> avb init 1
=> avb verify
avb_slot_verify.c:175: ERROR: boot: Hash of data does not match digest in
descriptor.
Slot verification result: ERROR_IO

Vbmeta partition is tampered:
=> avb init 1
=> avb verify
avb_vbmeta_image.c:206: ERROR: Hash does not match!
avb_slot_verify.c:388: ERROR: vbmeta: Error verifying vbmeta image:
HASH_MISMATCH
Slot verification result: ERROR_IO


4. ENABLE ON YOUR BOARD
-----------------------------------
The following options must be enabled:
CONFIG_LIBAVB=y
CONFIG_AVB_VERIFY=y
CONFIG_CMD_AVB=y

In addtion optionally if storing rollback indexes in RPMB with help of
OP-TEE:
CONFIG_TEE=y
CONFIG_OPTEE=y
CONFIG_OPTEE_TA_AVB=y
CONFIG_SUPPORT_EMMC_RPMB=y

Then add `avb verify` invocation to your android boot sequence of commands,
e.g.:

=> avb_verify=avb init $mmcdev; avb verify;
=> if run avb_verify; then                       \
        echo AVB verification OK. Continue boot; \
        set bootargs $bootargs $avb_bootargs;    \
   else                                          \
        echo AVB verification failed;            \
        exit;                                    \
   fi;                                           \

=> emmc_android_boot=                                   \
       echo Trying to boot Android from eMMC ...;       \
       ...                                              \
       run avb_verify;                                  \
       mmc read ${fdtaddr} ${fdt_start} ${fdt_size};    \
       mmc read ${loadaddr} ${boot_start} ${boot_size}; \
       bootm $loadaddr $loadaddr $fdtaddr;              \


To switch on automatic generation of vbmeta partition in AOSP build, add these
lines to device configuration mk file:

BOARD_AVB_ENABLE := true
BOARD_AVB_ALGORITHM := SHA512_RSA4096
BOARD_BOOTIMAGE_PARTITION_SIZE := <boot partition size>

After flashing U-boot don't forget to update environment and write new
partition table:
=> env default -f -a
=> setenv partitions $partitions_android
=> env save
=> gpt write mmc 1 $partitions_android

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

# SPDX-License-Identifier: GPL-2.0+

Blob Lists - bloblist
=====================

Introduction
------------

A bloblist provides a way to store collections of binary information (blobs) in
a central structure. Each record of information is assigned a tag so that its
owner can find it and update it. Each record is generally described by a C
structure defined by the code that owns it.


Passing state through the boot process
--------------------------------------

The bloblist is created when the first U-Boot component runs (often SPL,
sometimes TPL). It is passed through to each successive part of the boot and
can be accessed as needed. This provides a way to transfer state from one part
to the next. For example, TPL may determine that a watchdog reset occurred by
reading an SoC register. Reading the register may reset the value, so that it
cannot be read a second time. So TPL can store that in a bloblist record which
can be passed through to SPL and U-Boot proper, which can print a message
indicating that something went wrong and the watchdog fired.


Blobs
-----

While each blob in the bloblist can be of any length, bloblists are designed to
hold small amounts of data, typically a few KB at most. It is not possible to
change the length of a blob once it has been written. Each blob is normally
created from a C structure which can beused to access its fields.


Blob tags
---------

Each blob has a tag which is a 32-bit number. This uniquely identifies the
owner of the blob. Blob tags are listed in enum blob_tag_t and are named
with a BLOBT_ prefix.


Single structure
----------------

There is normally only one bloblist in U-Boot. Since a bloblist can store
multiple blobs it does not seem useful to allow multiple bloblists. Of course
there could be reasons for this, such as needing to spread the blobs around in
different memory areas due to fragmented memory, but it is simpler to just have
a single bloblist.


API
---

Bloblist provides a fairly simple API which allows blobs to be created  and
found. All access is via the blob's tag.


Finishing the bloblist
----------------------

When a part of U-Boot is about to jump to the next part, it can 'finish' the
bloblist in preparation for the next stage. This involves adding a checksum so
that the next stage can make sure that the data arrived safely. While the
bloblist is in use, changes can be made which will affect the checksum, so it
is easier to calculate the checksum at the end after all changes are made.


Future work
-----------

Bootstage has a mechanism to 'stash' its records for passing to the next part.
This should move to using bloblist, to avoid having its own mechanism for
passing information between U-Boot parts.


Simon Glass
sjg@chromium.org
12-Aug-2018

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

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

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

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. Build U-Boot

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


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


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


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


5. Write U-Boot to the SD card

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


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


7. 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 currently due to a lack of private libgcc
support.  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.

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 -target arm-linux-gnueabi" -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 "$@"

.. Copyright 2010 Nicolas Palix <npalix@diku.dk>
.. Copyright 2010 Julia Lawall <julia@diku.dk>
.. Copyright 2010 Gilles Muller <Gilles.Muller@lip6.fr>

.. highlight:: none

Coccinelle
==========

Coccinelle is a tool for pattern matching and text transformation that has
many uses in kernel development, including the application of complex,
tree-wide patches and detection of problematic programming patterns.

Getting Coccinelle
-------------------

The semantic patches included in the kernel use features and options
which are provided by Coccinelle version 1.0.0-rc11 and above.
Using earlier versions will fail as the option names used by
the Coccinelle files and coccicheck have been updated.

Coccinelle is available through the package manager
of many distributions, e.g. :

 - Debian
 - Fedora
 - Ubuntu
 - OpenSUSE
 - Arch Linux
 - NetBSD
 - FreeBSD

You can get the latest version released from the Coccinelle homepage at
http://coccinelle.lip6.fr/

Information and tips about Coccinelle are also provided on the wiki
pages at http://cocci.ekstranet.diku.dk/wiki/doku.php

Once you have it, run the following command::

     	./configure
        make

as a regular user, and install it with::

        sudo make install

Supplemental documentation
---------------------------

For supplemental documentation refer to the wiki:

https://bottest.wiki.kernel.org/coccicheck

The wiki documentation always refers to the linux-next version of the script.

Using Coccinelle on the Linux kernel
------------------------------------

A Coccinelle-specific target is defined in the top level
Makefile. This target is named ``coccicheck`` and calls the ``coccicheck``
front-end in the ``scripts`` directory.

Four basic modes are defined: ``patch``, ``report``, ``context``, and
``org``. The mode to use is specified by setting the MODE variable with
``MODE=<mode>``.

- ``patch`` proposes a fix, when possible.

- ``report`` generates a list in the following format:
  file:line:column-column: message

- ``context`` highlights lines of interest and their context in a
  diff-like style.Lines of interest are indicated with ``-``.

- ``org`` generates a report in the Org mode format of Emacs.

Note that not all semantic patches implement all modes. For easy use
of Coccinelle, the default mode is "report".

Two other modes provide some common combinations of these modes.

- ``chain`` tries the previous modes in the order above until one succeeds.

- ``rep+ctxt`` runs successively the report mode and the context mode.
  It should be used with the C option (described later)
  which checks the code on a file basis.

Examples
~~~~~~~~

To make a report for every semantic patch, run the following command::

		make coccicheck MODE=report

To produce patches, run::

		make coccicheck MODE=patch


The coccicheck target applies every semantic patch available in the
sub-directories of ``scripts/coccinelle`` to the entire Linux kernel.

For each semantic patch, a commit message is proposed.  It gives a
description of the problem being checked by the semantic patch, and
includes a reference to Coccinelle.

As any static code analyzer, Coccinelle produces false
positives. Thus, reports must be carefully checked, and patches
reviewed.

To enable verbose messages set the V= variable, for example::

   make coccicheck MODE=report V=1

Coccinelle parallelization
---------------------------

By default, coccicheck tries to run as parallel as possible. To change
the parallelism, set the J= variable. For example, to run across 4 CPUs::

   make coccicheck MODE=report J=4

As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization,
if support for this is detected you will benefit from parmap parallelization.

When parmap is enabled coccicheck will enable dynamic load balancing by using
``--chunksize 1`` argument, this ensures we keep feeding threads with work
one by one, so that we avoid the situation where most work gets done by only
a few threads. With dynamic load balancing, if a thread finishes early we keep
feeding it more work.

When parmap is enabled, if an error occurs in Coccinelle, this error
value is propagated back, the return value of the ``make coccicheck``
captures this return value.

Using Coccinelle with a single semantic patch
---------------------------------------------

The optional make variable COCCI can be used to check a single
semantic patch. In that case, the variable must be initialized with
the name of the semantic patch to apply.

For instance::

	make coccicheck COCCI=<my_SP.cocci> MODE=patch

or::

	make coccicheck COCCI=<my_SP.cocci> MODE=report


Controlling Which Files are Processed by Coccinelle
---------------------------------------------------

By default the entire kernel source tree is checked.

To apply Coccinelle to a specific directory, ``M=`` can be used.
For example, to check drivers/net/wireless/ one may write::

    make coccicheck M=drivers/net/wireless/

To apply Coccinelle on a file basis, instead of a directory basis, the
following command may be used::

    make C=1 CHECK="scripts/coccicheck"

To check only newly edited code, use the value 2 for the C flag, i.e.::

    make C=2 CHECK="scripts/coccicheck"

In these modes, which works on a file basis, there is no information
about semantic patches displayed, and no commit message proposed.

This runs every semantic patch in scripts/coccinelle by default. The
COCCI variable may additionally be used to only apply a single
semantic patch as shown in the previous section.

The "report" mode is the default. You can select another one with the
MODE variable explained above.

Debugging Coccinelle SmPL patches
---------------------------------

Using coccicheck is best as it provides in the spatch command line
include options matching the options used when we compile the kernel.
You can learn what these options are by using V=1, you could then
manually run Coccinelle with debug options added.

Alternatively you can debug running Coccinelle against SmPL patches
by asking for stderr to be redirected to stderr, by default stderr
is redirected to /dev/null, if you'd like to capture stderr you
can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For
instance::

    rm -f cocci.err
    make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err
    cat cocci.err

You can use SPFLAGS to add debugging flags, for instance you may want to
add both --profile --show-trying to SPFLAGS when debugging. For instance
you may want to use::

    rm -f err.log
    export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci
    make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd/arizona-irq.c

err.log will now have the profiling information, while stdout will
provide some progress information as Coccinelle moves forward with
work.

DEBUG_FILE support is only supported when using coccinelle >= 1.2.

.cocciconfig support
--------------------

Coccinelle supports reading .cocciconfig for default Coccinelle options that
should be used every time spatch is spawned, the order of precedence for
variables for .cocciconfig is as follows:

- Your current user's home directory is processed first
- Your directory from which spatch is called is processed next
- The directory provided with the --dir option is processed last, if used

Since coccicheck runs through make, it naturally runs from the kernel
proper dir, as such the second rule above would be implied for picking up a
.cocciconfig when using ``make coccicheck``.

``make coccicheck`` also supports using M= targets.If you do not supply
any M= target, it is assumed you want to target the entire kernel.
The kernel coccicheck script has::

    if [ "$KBUILD_EXTMOD" = "" ] ; then
        OPTIONS="--dir $srctree $COCCIINCLUDE"
    else
        OPTIONS="--dir $KBUILD_EXTMOD $COCCIINCLUDE"
    fi

KBUILD_EXTMOD is set when an explicit target with M= is used. For both cases
the spatch --dir argument is used, as such third rule applies when whether M=
is used or not, and when M= is used the target directory can have its own
.cocciconfig file. When M= is not passed as an argument to coccicheck the
target directory is the same as the directory from where spatch was called.

If not using the kernel's coccicheck target, keep the above precedence
order logic of .cocciconfig reading. If using the kernel's coccicheck target,
override any of the kernel's .coccicheck's settings using SPFLAGS.

We help Coccinelle when used against Linux with a set of sensible defaults
options for Linux with our own Linux .cocciconfig. This hints to coccinelle
git can be used for ``git grep`` queries over coccigrep. A timeout of 200
seconds should suffice for now.

The options picked up by coccinelle when reading a .cocciconfig do not appear
as arguments to spatch processes running on your system, to confirm what
options will be used by Coccinelle run::

      spatch --print-options-only

You can override with your own preferred index option by using SPFLAGS. Take
note that when there are conflicting options Coccinelle takes precedence for
the last options passed. Using .cocciconfig is possible to use idutils, however
given the order of precedence followed by Coccinelle, since the kernel now
carries its own .cocciconfig, you will need to use SPFLAGS to use idutils if
desired. See below section "Additional flags" for more details on how to use
idutils.

Additional flags
----------------

Additional flags can be passed to spatch through the SPFLAGS
variable. This works as Coccinelle respects the last flags
given to it when options are in conflict. ::

    make SPFLAGS=--use-glimpse coccicheck

Coccinelle supports idutils as well but requires coccinelle >= 1.0.6.
When no ID file is specified coccinelle assumes your ID database file
is in the file .id-utils.index on the top level of the kernel, coccinelle
carries a script scripts/idutils_index.sh which creates the database with::

    mkid -i C --output .id-utils.index

If you have another database filename you can also just symlink with this
name. ::

    make SPFLAGS=--use-idutils coccicheck

Alternatively you can specify the database filename explicitly, for
instance::

    make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck

See ``spatch --help`` to learn more about spatch options.

Note that the ``--use-glimpse`` and ``--use-idutils`` options
require external tools for indexing the code. None of them is
thus active by default. However, by indexing the code with
one of these tools, and according to the cocci file used,
spatch could proceed the entire code base more quickly.

SmPL patch specific options
---------------------------

SmPL patches can have their own requirements for options passed
to Coccinelle. SmPL patch specific options can be provided by
providing them at the top of the SmPL patch, for instance::

	// Options: --no-includes --include-headers

SmPL patch Coccinelle requirements
----------------------------------

As Coccinelle features get added some more advanced SmPL patches
may require newer versions of Coccinelle. If an SmPL patch requires
at least a version of Coccinelle, this can be specified as follows,
as an example if requiring at least Coccinelle >= 1.0.5::

	// Requires: 1.0.5

Proposing new semantic patches
-------------------------------

New semantic patches can be proposed and submitted by kernel
developers. For sake of clarity, they should be organized in the
sub-directories of ``scripts/coccinelle/``.


Detailed description of the ``report`` mode
-------------------------------------------

``report`` generates a list in the following format::

  file:line:column-column: message

Example
~~~~~~~

Running::

	make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci

will execute the following part of the SmPL script::

   <smpl>
   @r depends on !context && !patch && (org || report)@
   expression x;
   position p;
   @@

     ERR_PTR@p(PTR_ERR(x))

   @script:python depends on report@
   p << r.p;
   x << r.x;
   @@

   msg="ERR_CAST can be used with %s" % (x)
   coccilib.report.print_report(p[0], msg)
   </smpl>

This SmPL excerpt generates entries on the standard output, as
illustrated below::

    /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg
    /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth
    /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg


Detailed description of the ``patch`` mode
------------------------------------------

When the ``patch`` mode is available, it proposes a fix for each problem
identified.

Example
~~~~~~~

Running::

	make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci

will execute the following part of the SmPL script::

    <smpl>
    @ depends on !context && patch && !org && !report @
    expression x;
    @@

    - ERR_PTR(PTR_ERR(x))
    + ERR_CAST(x)
    </smpl>

This SmPL excerpt generates patch hunks on the standard output, as
illustrated below::

    diff -u -p a/crypto/ctr.c b/crypto/ctr.c
    --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200
    +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200
    @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct
 	alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
 				  CRYPTO_ALG_TYPE_MASK);
 	if (IS_ERR(alg))
    -		return ERR_PTR(PTR_ERR(alg));
    +		return ERR_CAST(alg);

 	/* Block size must be >= 4 bytes. */
 	err = -EINVAL;

Detailed description of the ``context`` mode
--------------------------------------------

``context`` highlights lines of interest and their context
in a diff-like style.

      **NOTE**: The diff-like output generated is NOT an applicable patch. The
      intent of the ``context`` mode is to highlight the important lines
      (annotated with minus, ``-``) and gives some surrounding context
      lines around. This output can be used with the diff mode of
      Emacs to review the code.

Example
~~~~~~~

Running::

	make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci

will execute the following part of the SmPL script::

    <smpl>
    @ depends on context && !patch && !org && !report@
    expression x;
    @@

    * ERR_PTR(PTR_ERR(x))
    </smpl>

This SmPL excerpt generates diff hunks on the standard output, as
illustrated below::

    diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing
    --- /home/user/linux/crypto/ctr.c	2010-05-26 10:49:38.000000000 +0200
    +++ /tmp/nothing
    @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct
 	alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
 				  CRYPTO_ALG_TYPE_MASK);
 	if (IS_ERR(alg))
    -		return ERR_PTR(PTR_ERR(alg));

 	/* Block size must be >= 4 bytes. */
 	err = -EINVAL;

Detailed description of the ``org`` mode
----------------------------------------

``org`` generates a report in the Org mode format of Emacs.

Example
~~~~~~~

Running::

	make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci

will execute the following part of the SmPL script::

    <smpl>
    @r depends on !context && !patch && (org || report)@
    expression x;
    position p;
    @@

      ERR_PTR@p(PTR_ERR(x))

    @script:python depends on org@
    p << r.p;
    x << r.x;
    @@

    msg="ERR_CAST can be used with %s" % (x)
    msg_safe=msg.replace("[","@(").replace("]",")")
    coccilib.org.print_todo(p[0], msg_safe)
    </smpl>

This SmPL excerpt generates Org entries on the standard output, as
illustrated below::

    * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]]
    * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]]
    * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]]