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>

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

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(struct bd_info *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)(struct bd_info *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(struct bd_info *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 (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)

Device tree
-----------
The U-Boot device tree is filtered by the fdtgrep tools during the build
process to generate a much smaller device tree used in SPL (spl/u-boot-spl.dtb)
with:
- the mandatory nodes (/alias, /chosen, /config)
- the nodes with one pre-relocation property:
  'u-boot,dm-pre-reloc' or 'u-boot,dm-spl'

fdtgrep is also used to remove:
- the properties defined in CONFIG_OF_SPL_REMOVE_PROPS
- all the pre-relocation properties
  ('u-boot,dm-pre-reloc', 'u-boot,dm-spl' and 'u-boot,dm-tpl')

All the nodes remaining in the SPL devicetree are bound
(see doc/driver-model/design.rst).

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 chosen in the
board config file.

TPL use a small device tree (u-boot-tpl.dtb), containing only the nodes with
the pre-relocation properties: 'u-boot,dm-pre-reloc' and 'u-boot,dm-tpl'
(see README.SPL for details).

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.

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 bd_info 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 struct bd_info 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 :-)

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>

ASN1
====

Abstract Syntax Notation One (or ASN1) is a standard by ITU-T and ISO/IEC
and used as a description language for defining data structure in
an independent manner.
Any data described in ASN1 notation can be serialized (or encoded) and
de-serialized (or decoded) with well-defined encoding rules.

A combination of ASN1 compiler and ASN1 decoder library function will
provide a function interface for parsing encoded binary into specific
data structure:
1) define data structure in a text file (*.asn1)
2) define "action" routines for specific "tags" defined in (1)
3) generate bytecode as a C file (*.asn1.[ch]) from *.asn1 file
   with ASN1 compiler (tools/asn1_compiler)
4) call a ASN1 decoder (asn1_ber_decoder()) with bytecode and data

Usage of ASN1 compiler
----------------------
  asn1_compiler [-v] [-d] <grammar-file> <c-file> <hdr-file>

  <grammar-file>:	ASN1 input file
  <c-file>:		generated C file
  <hdr-file>:		generated include file

Usage of ASN1 decoder
---------------------
  int asn1_ber_decoder(const struct asn1_decoder *decoder, void *context,
		       const unsigned char *data, size_t datalen);

  @decoder:		bytecode binary
  @context:		context for decoder
  @data:		data to be parsed
  @datalen:		size of data


As of writing this, ASN1 compiler and decoder are used to implement
X509 certificate parser, pcks7 message parser and RSA public key parser
for UEFI secure boot.

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(struct bd_info *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_AUTOBOOT_ENCRYPTION

  "bootstopkeysha256"	environment variable

	- Hash value of the input which unlocks the device and
	  stops autoboot.

	This option allows a string to be entered into U-Boot to stop the
	autoboot. The string itself is hashed and compared against the hash
	in the environment variable 'bootstopkeysha256'. If it matches then
	boot stops and a command-line prompt is presented.

	This provides a way to ship a secure production device which can also
	be accessed at the U-Boot command line.

  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.

  CONFIG_AUTOBOOT_USE_MENUKEY
  CONFIG_AUTOBOOT_MENUKEY

	If this key is pressed to stop autoboot, then the commands in the
	environment variable 'menucmd' will be executed before boot starts.
	For example, 33 means "!" in ASCII, so pressing ! at boot would take
	this action.

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";
		};
	};
};

BCMNS3 QSPI memory layout
=========================

BCMNS3 has total 8MB non-volatile SPI flash memory. It is used to store
different images like fip.bin, nitro firmware, DDR shmo value and other backup
images.

Following is the QSPI flash memory layout.

/*         QSPI layout
 * |---------------------------|->0x000000
 * |                           |
 * |                           |
 * |        fip.bin            |
 * |         2MB               |
 * |                           |
 * ~                           ~
 * ~                           ~
 * |                           |
 * |                           |
 * |                           |
 * |---------------------------|->0x200000
 * |                           |
 * |                           |
 * |                           |
 * |       fip.bin (Mirror)    |
 * |        2MB                |
 * ~                           ~
 * ~                           ~
 * |                           |
 * |                           |
 * |                           |
 * |---------------------------|->0x400000
 * |                           |
 * |      Nitro NS3 Config     |
 * |          1.5M             |
 * |                           |
 * ~                           ~
 * ~                           ~
 * |                           |
 * |---------------------------|->0x580000
 * |      Nitro NS3 Config     |
 * |          1.5M             |
 * |        (Mirror)           |
 * ~                           ~
 * ~                           ~
 * |                           |
 * |---------------------------|->0x700000
 * |   Nitro NS3 bspd Config   |
 * |        64KB               |
 * ~                           ~
 * ~                           ~
 * |                           |
 * |---------------------------|->0x710000
 * |   Nitro NS3 bspd Config   |
 * |        64KB               |
 * ~       (Mirror)            ~
 * ~                           ~
 * |                           |
 * |---------------------------|->0x720000
 * |        SHMOO              |
 * |        64KB               |
 * |                           |
 * ~                           ~
 * ~                           ~
 * |---------------------------|->0x730000
 * |        Meta Data          |
 * |        832KB              |
 * |                           |
 * ~                           ~
 * ~                           ~
 * |                           |
 * |---------------------------|
 */

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>

# 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. Blob records are zeroed when added.


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+

Boot Count Limit
================

This allows to detect multiple failed attempts to boot Linux.

After a power-on reset, "bootcount" variable will be initialized with 1, and
each reboot will increment the value by 1.

If, after a reboot, the new value of "bootcount" exceeds the value of
"bootlimit", then instead of the standard boot action (executing the contents of
"bootcmd") an alternate boot action will be performed, and the contents of
"altbootcmd" will be executed.

If the variable "bootlimit" is not defined in the environment, the Boot Count
Limit feature is disabled. If it is enabled, but "altbootcmd" is not defined,
then U-Boot will drop into interactive mode and remain there.

It is the responsibility of some application code (typically a Linux
application) to reset the variable "bootcount", thus allowing for more boot
cycles.

BOOTCOUNT_EXT
-------------

This adds support for maintaining boot count in a file on an EXT filesystem.
The file to use is define by:

SYS_BOOTCOUNT_EXT_INTERFACE
SYS_BOOTCOUNT_EXT_DEVPART
SYS_BOOTCOUNT_EXT_NAME

The format of the file is:

==== =================
type entry
==== =================
u8   magic
u8   version
u8   bootcount
u8   upgrade_available
==== =================

To prevent unattended usage of "altbootcmd" the "upgrade_available" variable is
used.
If "upgrade_available" is 0, "bootcount" is not saved, if "upgrade_available" is
1 "bootcount" is save.
So the Userspace Application must set the "upgrade_available" and "bootcount"
variables to 0, if a boot was successfully.
This also prevents writes on all reboots.

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

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

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

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

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

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

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

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

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


TYPICAL CALL

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

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

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

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

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

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

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

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

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

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

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

You can use the following functions to access the console:

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

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

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

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

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

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

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

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

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

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

Working drivers:

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

Work in progress:

    wl_kbd	(Wireless 4PPM keyboard)

Waiting for volounteers:

    lcd	(mpc8xx lcd controller; to )

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

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

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

Summary
=======

Note: this document used to be about the entire family of DaVinci SOCs but the
support for the DM* family and DA830 has since been dropped.

This README is about U-Boot support for TI's DA850 SoC. This SOC has an OMAP
part number but is very similar to the DaVinci series.

Currently the following boards are supported:

* TI DA850 EVM

* TI OMAP-L138 LCDK

* Lego EV3

Build
=====

* TI DA850 EVM:

make da850evm_config
make

* TI OMAP-L138 LCDK

make omapl138_lcdk_defconfig
make

* Lego EV3

make legoev3_defconfig
make

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

For DA850 an SPL (secondary program loader, see doc/README.SPL) is provided
to load U-Boot from SPI flash, MMC or NAND. The SPL takes care of the low level
initialization.

The SPL is built as u-boot.ais for all DA850 defconfigs except those booting
from NOR flash. The resulting image file can be programmed to the SPI flash
of the DA850 EVM/LCDK.

Devices that support booting from NOR utilize execute in place (XIP) and do
not require SPL to perform low level initialization.

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

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

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

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

Links
=====

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

2) TI OMAP-L138 LCDK
http://focus.ti.com/docs/prod/folders/print/omap-l138.html
http://www.ti.com/tool/TMDXLCDK138

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

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

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


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

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


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

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

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

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

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

The spl code starts in the second "page" of the image, with a size
defined by:

#define CONFIG_SYS_NROF_PAGES_NAND_SPL	6

After the spl code, there comes the "real" u-boot code
@ (6 + 1) * pagesize = 0x3800

------------------------------------------------------------------------
Setting up spl code:

/*
 * RBL searches from Block n (n = 1..24)
 * so we can define, how many UBL Headers
 * we write before the real spl code
 */
#define CONFIG_SYS_NROF_UBL_HEADER	5
#define CONFIG_SYS_NROF_PAGES_NAND_SPL	6

#define CONFIG_SYS_NAND_U_BOOT_OFFS	((CONFIG_SYS_NROF_UBL_HEADER * \
					CONFIG_SYS_NAND_BLOCK_SIZE) + \
					(CONFIG_SYS_NROF_PAGES_NAND_SPL) * \
					CONFIG_SYS_NAND_PAGE_SIZE)
------------------------------------------------------------------------

Burning into NAND:

step 1:
The RBL searches from Block n ( n = 1..24) on page 0 for valid UBL
Headers, so you have to burn the UBL header page from the u-boot.ubl
image to the blocks, you want to have the UBL header.
!! Don;t forget to switch to rbl nand read/write functions with
   "nandrbl rbl"

step 2:
You need to setup in the ublimage.cfg, where the RBL can find the spl
code, and how big it is.

!! RBL always starts reading from page 0 !!

For the AIT board, we have:
PAGES		6
START_BLOCK	5

So we need to copy the spl code to block 5 page 0
!! Don;t forget to switch to rbl nand read/write functions with
   "nandrbl rbl"

step 3:
You need to copy the u-boot image to the block/page
where the spl code reads it (CONFIG_SYS_NAND_U_BOOT_OFFS)
!! Don;t forget to switch to rbl nand read/write functions with
   "nandrbl uboot", which is default.

On the cam_enc_4xx board it is:
#define CONFIG_SYS_NAND_U_BOOT_OFFS	(0xc0000)

-> this results in following NAND usage on the cam_enc_4xx board:

addr

20000		possible UBL Header
40000		possible UBL Header
60000		possible UBL Header
80000		possilbe UBL Header
a0000		spl code
c0000		u-boot code

The above steps are executeed through the following environment vars:
(using 80000 as address for the UBL header)

pagesz=800
uboot=/tftpboot/cam_enc_4xx/u-boot.ubl
load=tftp 80000000 ${uboot}
writeheader nandrbl rbl;nand erase 80000 ${pagesz};nand write 80000000 80000 ${pagesz};nandrbl uboot
writenand_spl nandrbl rbl;nand erase a0000 3000;nand write 80000800 a0000 3000;nandrbl uboot
writeuboot nandrbl uboot;nand erase c0000 5d000;nand write 80003800 c0000 5d000
update=run load writeheader writenand_spl writeuboot

If you do a "run load update" u-boot, spl + ubl header
are magically updated ;-)

Note:
- There seem to be a bug in the RBL code (at least on my HW),
  In the UBL block, I can set the page to values != 0, so it
  is possible to burn step 1 and step 2 in one step into the
  flash, but the RBL ignores the page settings, so I have to
  burn the UBL Header to a page 0 and the spl code to
  a page 0 ... :-(
- If we make the nand read/write functions in the RBL equal to
  the functions in u-boot (as I have no RBL code, it is only
  possible in u-boot), we could burn the complete image in
  one step ... that would be nice ...

# SPDX-License-Identifier: GPL-2.0+
#
#  Copyright (C) 2015
#
#  Lukasz Majewski <l.majewski@majess.pl>

Device Firmware Upgrade (DFU) - extension to use TFTP
=====================================================

Why?
----

* Update TFTP (CONFIG_UPDATE_TFTP) only supports writing
code to NAND memory via TFTP.
* DFU supports writing data to the variety of mediums (NAND,
eMMC, SD, partitions, RAM, etc) via USB.

Combination of both solves their shortcomings!


Overview
--------

This document briefly describes how to use DFU for
upgrading firmware (e.g. kernel, u-boot, rootfs, etc.)
via TFTP protocol.

By using Ethernet (TFTP protocol to be precise) it is
possible to overcome the major problem of USB based DFU -
the relatively low transfer speed for large files.
This was caused by DFU standard, which imposed utilization
of only EP0 for transfer. By using Ethernet we can circumvent
this shortcoming.

Beagle Bone Black rev. C (BBB) powered by TI's am335x CPU has
been used as a demo board.

To utilize this feature, one needs to first enable support
for USB based DFU (CONFIG_DFU_*) and DFU TFTP update
(CONFIG_DFU_TFTP) described in ./doc/README.update.

The "dfu" command has been extended to support transfer via TFTP - one
needs to type for example "dfu tftp 0 mmc 0"

As of this writing (SHA1:8d77576371381ade83de475bb639949b44941e8c v2015.10-rc2)
the update.c code is not enabled (CONFIG_UPDATE_TFTP) by any board in the
contemporary u-boot tree.


Environment variables
---------------------

The "dfu tftp" command can be used in the "preboot" environment variable
(when it is enabled by defining CONFIG_PREBOOT).
This is the preferable way of using this command in the early boot stage
as opposed to legacy update_tftp() function invocation.


Beagle Bone Black (BBB) setup
-----------------------------

1. Setup tftp env variables:
   *  select desired eth device - 'ethact' variable ["ethact=cpsw"]
      (use "bdinfo" to check current setting)
   *  setup "serverip" and "ipaddr" variables
   *  set "loadaddr" as a fixed buffer where incoming data is placed
      ["loadaddr=0x81000000"]

#########
# BONUS #
#########
It is possible to use USB interface to emulate ETH connection by setting
"ethact=usb_ether". In this way one can have very fast DFU transfer via USB.

For 33MiB test image the transfer rate was 1MiB/s for ETH over USB and 200KiB/s
for pure DFU USB transfer.

2. Setup update_tftp variables:
   *  set "updatefile" - the file name to be downloaded via TFTP (stored on
      the HOST at e.g. /srv/tftp)

3. If required, to update firmware on boot, put the "dfu tftp 0 mmc 0" in the
    "preboot" env variable. Otherwise use this command from u-boot prompt.

4. Inspect "dfu" specific variables:
   * "dfu_alt_info" - information about available DFU entities
   * "dfu_bufsiz"   - variable to set buffer size [in bytes] - when it is not
		    possible to set large enough default buffer (8 MiB @ BBB)



FIT image format for download
-----------------------------

To create FIT image for download one should follow the update tftp README file
(./doc/README.update) with one notable difference:

The original snippet of ./doc/uImage.FIT/update_uboot.its

	images {
		update@1 {
			description = "U-Boot binary";

should look like

	images {
		u-boot.bin@1 {
			description = "U-Boot binary";

where "u-boot.bin" is the DFU entity name to be stored.



To do
-----

* Extend dfu-util command to support TFTP based transfers
* Upload support (via TFTP)

If you are experiencing hangups/data-aborts when trying to display a BMP image,
the following might be relevant to your situation...

Some architectures cannot handle unaligned memory accesses, and an attempt to
perform one will lead to a data abort. On such architectures it is necessary to
make sure all data is properly aligned, and in many situations simply choosing
a 32 bit aligned address is enough to ensure proper alignment. This is not
always the case when dealing with data that has an internal layout such as a
BMP image:

BMP images have a header that starts with 2 byte-size fields followed by mostly
32 bit fields. The packed struct that represents this header can be seen below:

typedef struct bmp_header {
	/* Header */
	char signature[2];
	__u32	file_size;
	__u32	reserved;
	__u32	data_offset;
	... etc
} __attribute__ ((packed)) bmp_header_t;

When placed in an aligned address such as 0x80a00000, char signature offsets
the __u32 fields into unaligned addresses (in our example 0x80a00002,
0x80a00006, and so on...). When these fields are accessed by U-Boot, a 32 bit
access is generated at a non-32-bit-aligned address, causing a data abort.
The proper alignment for BMP images is therefore: 32-bit-aligned-address + 2.

SPDX-License-Identifier: GPL-2.0+
/*
 * (C) Copyright 2014 Red Hat Inc.
 * Copyright (c) 2014-2015, NVIDIA CORPORATION.  All rights reserved.
 * Copyright (C) 2015 K. Merker <merker@debian.org>
 */

Generic Distro Configuration Concept
====================================

Linux distributions are faced with supporting a variety of boot mechanisms,
environments or bootloaders (PC BIOS, EFI, U-Boot, Barebox, ...). This makes
life complicated. Worse, bootloaders such as U-Boot have a configurable set
of features, and each board chooses to enable a different set of features.
Hence, distros typically need to have board-specific knowledge in order to
set up a bootable system.

This document defines a common set of U-Boot features that are required for
a distro to support the board in a generic fashion. Any board wishing to
allow distros to install and boot in an out-of-the-box fashion should enable
all these features. Linux distros can then create a single set of boot
support/install logic that targets these features. This will allow distros
to install on many boards without the need for board-specific logic.

In fact, some of these features can be implemented by any bootloader, thus
decoupling distro install/boot logic from any knowledge of the bootloader.

This model assumes that boards will load boot configuration files from a
regular storage mechanism (eMMC, SD card, USB Disk, SATA disk, etc.) with
a standard partitioning scheme (MBR, GPT). Boards that cannot support this
storage model are outside the scope of this document, and may still need
board-specific installer/boot-configuration support in a distro.

To some extent, this model assumes that a board has a separate boot flash
that contains U-Boot, and that the user has somehow installed U-Boot to this
flash before running the distro installer. Even on boards that do not conform
to this aspect of the model, the extent of the board-specific support in the
distro installer logic would be to install a board-specific U-Boot package to
the boot partition during installation. This distro-supplied U-Boot can still
implement the same features as on any other board, and hence the distro's boot
configuration file generation logic can still be board-agnostic.

Locating Bootable Disks
-----------------------

Typical desktop/server PCs search all (or a user-defined subset of) attached
storage devices for a bootable partition, then load the bootloader or boot
configuration files from there. A U-Boot board port that enables the features
mentioned in this document will search for boot configuration files in the
same way.

Thus, distros do not need to manipulate any kind of bootloader-specific
configuration data to indicate which storage device the system should boot
from.

Distros simply need to install the boot configuration files (see next
section) in an ext2/3/4 or FAT partition, mark the partition bootable (via
the MBR bootable flag, or GPT legacy_bios_bootable attribute), and U-Boot (or
any other bootloader) will find those boot files and execute them. This is
conceptually identical to creating a grub2 configuration file on a desktop
PC.

Note that in the absence of any partition that is explicitly marked bootable,
U-Boot falls back to searching the first valid partition of a disk for boot
configuration files. Other bootloaders are recommended to do the same, since
I believe that partition table bootable flags aren't so commonly used outside
the realm of x86 PCs.

U-Boot can also search for boot configuration files from a TFTP server.

Boot Configuration Files
------------------------

The standard format for boot configuration files is that of extlinux.conf, as
handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly
as specified at:

http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/

... with the exceptions that the BootLoaderSpec document:

* Prescribes a separate configuration per boot menu option, whereas U-Boot
  lumps all options into a single extlinux.conf file. Hence, U-Boot searches
  for /extlinux/extlinux.conf then /boot/extlinux/extlinux.conf on disk, or
  pxelinux.cfg/default over the network.

* Does not document the fdtdir option, which automatically selects the DTB to
  pass to the kernel.

One example extlinux.conf generated by the Fedora installer is:

------------------------------------------------------------
# extlinux.conf generated by anaconda

ui menu.c32

menu autoboot Welcome to Fedora. Automatic boot in # second{,s}. Press a key for options.
menu title Fedora Boot Options.
menu hidden

timeout 50
#totaltimeout 9000

default Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)

label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl) 22 (Rawhide)
	kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl
	append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf
	fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl
	initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl.img

label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)
	kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
	append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf
	fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
	initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae.img

label Fedora-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc (0-rescue-8f6ba7b039524e0eb957d2c9203f04bc)
	kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc
	initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img
	append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8
	fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae
------------------------------------------------------------

Another hand-crafted network boot configuration file is:

------------------------------------------------------------
TIMEOUT 100

MENU TITLE TFTP boot options

LABEL jetson-tk1-emmc
        MENU LABEL ../zImage root on Jetson TK1 eMMC
        LINUX ../zImage
        FDTDIR ../
        APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=80a5a8e9-c744-491a-93c1-4f4194fd690b

LABEL venice2-emmc
        MENU LABEL ../zImage root on Venice2 eMMC
        LINUX ../zImage
        FDTDIR ../
        APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=5f71e06f-be08-48ed-b1ef-ee4800cc860f

LABEL sdcard
        MENU LABEL ../zImage, root on 2GB sdcard
        LINUX ../zImage
        FDTDIR ../
        APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=b2f82cda-2535-4779-b467-094a210fbae7

LABEL fedora-installer-fk
        MENU LABEL Fedora installer w/ Fedora kernel
        LINUX fedora-installer/vmlinuz
        INITRD fedora-installer/initrd.img.orig
        FDTDIR fedora-installer/dtb
        APPEND loglevel=8 ip=dhcp inst.repo=http://10.0.0.2/mirrors/fedora/linux/development/rawhide/armhfp/os/ rd.shell cma=64M
------------------------------------------------------------

U-Boot Implementation
=====================

Enabling the distro options
---------------------------

In your board's defconfig, enable the DISTRO_DEFAULTS option by adding
a line with "CONFIG_DISTRO_DEFAULTS=y". If you want to enable this
from Kconfig itself, for e.g. all boards using a specific SoC then
add a "imply DISTRO_DEFAULTS" to your SoC CONFIG option.

In your board configuration file, include the following:

------------------------------------------------------------
#ifndef CONFIG_SPL_BUILD
#include <config_distro_bootcmd.h>
#endif
------------------------------------------------------------

The first of those headers primarily enables a core set of U-Boot features,
such as support for MBR and GPT partitions, ext* and FAT filesystems, booting
raw zImage and initrd (rather than FIT- or uImage-wrapped files), etc. Network
boot support is also enabled here, which is useful in order to boot distro
installers given that distros do not commonly distribute bootable install
media for non-PC targets at present.

Finally, a few options that are mostly relevant only when using U-Boot-
specific boot.scr scripts are enabled. This enables distros to generate a
U-Boot-specific boot.scr script rather than extlinux.conf as the boot
configuration file. While doing so is fully supported, and
CONFIG_DISTRO_DEFAULTS exposes enough parameterization to boot.scr to
allow for board-agnostic boot.scr content, this document recommends that
distros generate extlinux.conf rather than boot.scr. extlinux.conf is intended
to work across multiple bootloaders, whereas boot.scr will only work with
U-Boot. TODO: document the contract between U-Boot and boot.scr re: which
environment variables a generic boot.scr may rely upon.

The second of those headers sets up the default environment so that $bootcmd
is defined in a way that searches attached disks for boot configuration files,
and executes them if found.

Required Environment Variables
------------------------------

The U-Boot "syslinux" and "pxe boot" commands require a number of environment
variables be set. Default values for these variables are often hard-coded into
CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that
the user doesn't have to configure them.

fdt_addr:

  Mandatory for any system that provides the DTB in HW (e.g. ROM) and wishes
  to pass that DTB to Linux, rather than loading a DTB from the boot
  filesystem. Prohibited for any other system.

  If specified a DTB to boot the system must be available at the given
  address.

fdt_addr_r:

  Mandatory. The location in RAM where the DTB will be loaded or copied to when
  processing the fdtdir/devicetreedir or fdt/devicetree options in
  extlinux.conf.

  This is mandatory even when fdt_addr is provided, since extlinux.conf must
  always be able to provide a DTB which overrides any copy provided by the HW.

  A size of 1MB for the FDT/DTB seems reasonable.

fdtfile:

  Mandatory. the name of the DTB file for the specific board for instance
  the espressobin v5 board the value is "marvell/armada-3720-espressobin.dtb"
  while on a clearfog pro it is "armada-388-clearfog-pro.dtb" in the case of
  a board providing its firmware based DTB this value can be used to override
  the DTB with a different DTB. fdtfile will automatically be set for you if
  it matches the format ${soc}-${board}.dtb which covers most 32 bit use cases.
  AArch64 generally does not match as the Linux kernel put the dtb files under
  SoC vendor directories.

ramdisk_addr_r:

  Mandatory. The location in RAM where the initial ramdisk will be loaded to
  when processing the initrd option in extlinux.conf.

  It is recommended that this location be highest in RAM out of fdt_addr_,
  kernel_addr_r, and ramdisk_addr_r, so that the RAM disk can vary in size
  and use any available RAM.

kernel_addr_r:

  Mandatory. The location in RAM where the kernel will be loaded to when
  processing the kernel option in the extlinux.conf.

  The kernel should be located within the first 128M of RAM in order for the
  kernel CONFIG_AUTO_ZRELADDR option to work, which is likely enabled on any
  distro kernel. Since the kernel will decompress itself to 0x8000 after the
  start of RAM, kernel_addr_r should not overlap that area, or the kernel will
  have to copy itself somewhere else first before decompression.

  A size of 16MB for the kernel is likely adequate.

kernel_comp_addr_r:
  Optional. This is only required if user wants to boot Linux from a compressed
  Image(.gz, .bz2, .lzma, .lzo) using the booti command. It represents the
  location in RAM where the compressed Image will be decompressed temporarily.
  Once the decompression is complete, the decompressed data will be moved to
  kernel_addr_r for booting.

kernel_comp_size:
  Optional. This is only required if user wants to boot Linux from a compressed
  Image using booti command. It represents the size of the compressed file. The
  size has to at least the size of loaded image for decompression to succeed.

pxefile_addr_r:

  Mandatory. The location in RAM where extlinux.conf will be loaded to prior
  to processing.

  A size of 1MB for extlinux.conf is more than adequate.

scriptaddr:

  Mandatory, if the boot script is boot.scr rather than extlinux.conf. The
  location in RAM where boot.scr will be loaded to prior to execution.

  A size of 1MB for extlinux.conf is more than adequate.

For suggestions on memory locations for ARM systems, you must follow the
guidelines specified in Documentation/arm/Booting in the Linux kernel tree.

For a commented example of setting these values, please see the definition of
MEM_LAYOUT_ENV_SETTINGS in include/configs/tegra124-common.h.

Boot Target Configuration
-------------------------

<config_distro_bootcmd.h> defines $bootcmd and many helper command variables
that automatically search attached disks for boot configuration files and
execute them. Boards must provide configure <config_distro_bootcmd.h> so that
it supports the correct set of possible boot device types. To provide this
configuration, simply define macro BOOT_TARGET_DEVICES prior to including
<config_distro_bootcmd.h>. For example:

------------------------------------------------------------
#ifndef CONFIG_SPL_BUILD
#define BOOT_TARGET_DEVICES(func) \
        func(MMC, mmc, 1) \
        func(MMC, mmc, 0) \
        func(USB, usb, 0) \
        func(PXE, pxe, na) \
        func(DHCP, dhcp, na)
#include <config_distro_bootcmd.h>
#endif
------------------------------------------------------------

Each entry in the macro defines a single boot device (e.g. a specific eMMC
device or SD card) or type of boot device (e.g. USB disk). The parameters to
the func macro (passed in by the internal implementation of the header) are:

- Upper-case disk type (MMC, SATA, SCSI, IDE, USB, DHCP, PXE, VIRTIO).
- Lower-case disk type (same options as above).
- ID of the specific disk (MMC only) or ignored for other types.

User Configuration
==================

Once the user has installed U-Boot, it is expected that the environment will
be reset to the default values in order to enable $bootcmd and friends, as set
up by <config_distro_bootcmd.h>. After this, various environment variables may
be altered to influence the boot process:

boot_targets:

  The list of boot locations searched.

  Example: mmc0, mmc1, usb, pxe

  Entries may be removed or re-ordered in this list to affect the boot order.

boot_prefixes:

  For disk-based booting, the list of directories within a partition that are
  searched for boot configuration files (extlinux.conf, boot.scr).

  Example: / /boot/

  Entries may be removed or re-ordered in this list to affect the set of
  directories which are searched.

boot_scripts:

  The name of U-Boot style boot.scr files that $bootcmd searches for.

  Example: boot.scr.uimg boot.scr

  (Typically we expect extlinux.conf to be used, but execution of boot.scr is
  maintained for backwards-compatibility.)

  Entries may be removed or re-ordered in this list to affect the set of
  filenames which are supported.

scan_dev_for_extlinux:

  If you want to disable extlinux.conf on all disks, set the value to something
  innocuous, e.g. setenv scan_dev_for_extlinux true.

scan_dev_for_scripts:

  If you want to disable boot.scr on all disks, set the value to something
  innocuous, e.g. setenv scan_dev_for_scripts true.

boot_net_usb_start:

  If you want to prevent USB enumeration by distro boot commands which execute
  network operations, set the value to something innocuous, e.g. setenv
  boot_net_usb_start true. This would be useful if you know your Ethernet
  device is not attached to USB, and you wish to increase boot speed by
  avoiding unnecessary actions.

boot_net_pci_enum:

  If you want to prevent PCI enumeration by distro boot commands which execute
  network operations, set the value to something innocuous, e.g. setenv
  boot_net_pci_enum true. This would be useful if you know your Ethernet
  device is not attached to PCI, and you wish to increase boot speed by
  avoiding unnecessary actions.

Interactively booting from a specific device at the u-boot prompt
=================================================================

For interactively booting from a user-selected device at the u-boot command
prompt, the environment provides predefined bootcmd_<target> variables for
every target defined in boot_targets, which can be run be the user.

If the target is a storage device, the format of the target is always
<device type><device number>, e.g. mmc0.  Specifying the device number is
mandatory for storage devices, even if only support for a single instance
of the storage device is actually implemented.

For network targets (dhcp, pxe), only the device type gets specified;
they do not have a device number.

Examples:

 - run bootcmd_usb0
   boots from the first USB mass storage device

 - run bootcmd_mmc1
   boots from the second MMC device

 - run bootcmd_pxe
   boots by tftp using a pxelinux.cfg

The list of possible targets consists of:

- network targets
  * dhcp
  * pxe

- storage targets (to which a device number must be appended)
  * mmc
  * sata
  * scsi
  * ide
  * usb
  * virtio

Other *boot* variables than the ones defined above are only for internal use
of the boot environment and are not guaranteed to exist or work in the same
way in future u-boot versions.  In particular the <device type>_boot
variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation
detail and must not be used as a public interface.

Domain Name System
-------------------------------------------

The Domain Name System (DNS) is a hierarchical naming system for computers,
services, or any resource participating in the Internet. It associates various
information with domain names assigned to each of the participants. Most
importantly, it translates domain names meaningful to humans into the numerical
(binary) identifiers associated with networking equipment for the purpose of
locating and addressing these devices world-wide. An often used analogy to
explain the Domain Name System is that it serves as the "phone book" for the
Internet by translating human-friendly computer hostnames into IP addresses.
For example, www.example.com translates to 208.77.188.166.

For more information on DNS - http://en.wikipedia.org/wiki/Domain_Name_System

U-Boot and DNS
------------------------------------------

CONFIG_CMD_DNS - controls if the 'dns' command is compiled in. If it is, it
		 will send name lookups to the dns server (env var 'dnsip')
		 Turning this option on will about abou 1k to U-Boot's size.

		 Example:

bfin> print dnsip
dnsip=192.168.0.1

bfin> dns www.google.com
66.102.1.104

		 By default, dns does nothing except print the IP number on
		 the default console - which by itself, would be pretty
		 useless. Adding a third argument to the dns command will
		 use that as the environment variable to be set.

		 Example:

bfin> print googleip
## Error: "googleip" not defined
bfin> dns www.google.com googleip
64.233.161.104
bfin> print googleip
googleip=64.233.161.104
bfin> ping ${googleip}
Using Blackfin EMAC device
host 64.233.161.104 is alive

		 In this way, you can lookup, and set many more meaningful
		 things.

bfin> sntp
ntpserverip not set
bfin> dns pool.ntp.org ntpserverip
72.18.205.156
bfin> sntp
Date: 2009-07-18 Time:	4:06:57

		 For some helpful things that can be related to DNS in U-Boot,
		 look at the top level README for these config options:
		    CONFIG_CMD_DHCP
		    CONFIG_BOOTP_DNS
		    CONFIG_BOOTP_DNS2

---------------------------------
 Ethernet Address (MAC) Handling
---------------------------------

There are a variety of places in U-Boot where the MAC address is used, parsed,
and stored.  This document covers proper usage of each location and the moving
of data between them.

-----------
 Locations
-----------

Here are the places where MAC addresses might be stored:

 - board-specific location (eeprom, dedicated flash, ...)
	Note: only used when mandatory due to hardware design etc...

 - environment ("ethaddr", "eth1addr", ...)
	Note: this is the preferred way to permanently store MAC addresses

 - ethernet data (struct eth_device -> enetaddr)
	Note: these are temporary copies of the MAC address which exist only
	      after the respective init steps have run and only to make usage
	      in other places easier (to avoid constant env lookup/parsing)

 - struct bd_info and/or device tree
	Note: these are temporary copies of the MAC address only for the
	      purpose of passing this information to an OS kernel we are about
	      to boot

Correct flow of setting up the MAC address (summarized):

1. Read from hardware in initialize() function
2. Read from environment in net/eth.c after initialize()
3. The environment variable will be compared to the driver initialized
   struct eth_device->enetaddr. If they differ, a warning is printed, and the
   environment variable will be used unchanged.
   If the environment variable is not set, it will be initialized from
   eth_device->enetaddr, and a warning will be printed.
   If both are invalid and CONFIG_NET_RANDOM_ETHADDR is defined, a random,
   locally-assigned MAC is written to eth_device->enetaddr.
4. Program the address into hardware if the following conditions are met:
	a) The relevant driver has a 'write_addr' function
	b) The user hasn't set an 'ethmacskip' environment variable
	c) The address is valid (unicast, not all-zeros)

Previous behavior had the MAC address always being programmed into hardware
in the device's init() function.

-------
 Usage
-------

If the hardware design mandates that the MAC address is stored in some special
place (like EEPROM etc...), then the board specific init code (such as the
board-specific misc_init_r() function) is responsible for locating the MAC
address(es) and initializing the respective environment variable(s) from it.
Note that this shall be done if, and only if, the environment does not already
contain these environment variables, i.e. existing variable definitions must
not be overwritten.

During runtime, the ethernet layer will use the environment variables to sync
the MAC addresses to the ethernet structures.  All ethernet driver code should
then only use the enetaddr member of the eth_device structure.  This is done
on every network command, so the ethernet copies will stay in sync.

Any other code that wishes to access the MAC address should query the
environment directly.  The helper functions documented below should make
working with this storage much smoother.

---------
 Helpers
---------

To assist in the management of these layers, a few helper functions exist.  You
should use these rather than attempt to do any kind of parsing/manipulation
yourself as many common errors have arisen in the past.

	* void string_to_enetaddr(const char *addr, uchar *enetaddr);

Convert a string representation of a MAC address to the binary version.
char *addr = "00:11:22:33:44:55";
uchar enetaddr[6];
string_to_enetaddr(addr, enetaddr);
/* enetaddr now equals { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 } */

	* int eth_env_get_enetaddr(char *name, uchar *enetaddr);

Look up an environment variable and convert the stored address.  If the address
is valid, then the function returns 1.  Otherwise, the function returns 0.  In
all cases, the enetaddr memory is initialized.  If the env var is not found,
then it is set to all zeros.  The common function is_valid_ethaddr() is used
to determine address validity.
uchar enetaddr[6];
if (!eth_env_get_enetaddr("ethaddr", enetaddr)) {
	/* "ethaddr" is not set in the environment */
	... try and setup "ethaddr" in the env ...
}
/* enetaddr is now set to the value stored in the ethaddr env var */

	* int eth_env_set_enetaddr(char *name, const uchar *enetaddr);

Store the MAC address into the named environment variable.  The return value is
the same as the env_set() function.
uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 };
eth_env_set_enetaddr("ethaddr", enetaddr);
/* the "ethaddr" env var should now be set to "00:11:22:33:44:55" */

	* the %pM format modifier

The %pM format modifier can be used with any standard printf function to format
the binary 6 byte array representation of a MAC address.
uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 };
printf("The MAC is %pM\n", enetaddr);

char buf[20];
sprintf(buf, "%pM", enetaddr);
/* the buf variable is now set to "00:11:22:33:44:55" */

SPDX-License-Identifier: GPL-2.0+
/*
 * (C) Copyright 2015
 */

esbc_validate command
========================================

1. esbc_validate command is meant for validating header and
    signature of images (Boot Script and ESBC uboot client).
    SHA-256 and RSA operations are performed using SEC block in HW.
    This command works on both PBL based and Non PBL based Freescale
    platforms.
   Command usage:
    esbc_validate img_hdr_addr [pub_key_hash]
    esbc_validate hdr_addr <hash_val>
     Validates signature using RSA verification.
     $hdr_addr Address of header of the image to be validated.
     $hash_val -Optional. It provides Hash of public/srk key to be
       used to verify signature.

2. ESBC uboot client can be linux. Additionally, rootfs and device
    tree blob can also be signed.
3. In the event of header or signature failure in validation,
    ITS and ITF bits determine further course of action.
4. In case of soft failure, appropriate error is dumped on console.
5. In case of hard failure, SoC is issued RESET REQUEST after
    dumping error on the console.
6. KEY REVOCATION Feature:
    QorIQ platforms like B4/T4 have support of srk key table and key
    revocation in ISBC code in Silicon.
    The srk key table allows the user to have a key table with multiple
    keys and revoke any key in case of particular key gets compromised.
    In case the ISBC code uses the key revocation and srk key table to
    verify the u-boot code, the subsequent chain of trust should also
    use the same.
6. ISBC KEY EXTENSION Feature:
    This feature allows large number of keys to be used for esbc validation
    of images. A set of public keys is being signed and validated by ISBC
    which can be further used for esbc validation of images.

U-Boot supports access of both ext2 and ext4 filesystems, either in read-only
mode or in read-write mode.

First, to enable support for both ext4 (and, automatically, ext2 as well),
but without selecting the corresponding commands, enable one of the following:

  CONFIG_FS_EXT4	(for read-only)
  CONFIG_EXT4_WRITE	(for read-write)

Next, to select the ext2-related commands:

  * ext2ls
  * ext2load

or ext4-related commands:

  * ext4size
  * ext4ls
  * ext4load

use one or both of:

  CONFIG_CMD_EXT2
  CONFIG_CMD_EXT4

Selecting either of the above automatically selects CONFIG_FS_EXT4 if it
wasn't enabled already.

In addition, to get the write access command "ext4write", enable:

  CONFIG_CMD_EXT4_WRITE

which automatically selects CONFIG_EXT4_WRITE if it wasn't defined
already.

Also relevant are the generic filesystem commands, selected by:

  CONFIG_CMD_FS_GENERIC

This does not automatically enable EXT4 support for you, you still need
to do that yourself.

Some sample commands to test ext4 support:

1. Check that the commands can be seen in the output of U-Boot help:

	UBOOT #help
	...
	ext4load- load binary file from a Ext4 file system
	ext4ls  - list files in a directory (default /)
	ext4size - determine a file's size
	ext4write- create a file in ext4 formatted partition
	...

2. To list the files in an ext4-formatted partition, run:

	ext4ls <interface> <dev[:part]> [directory]

	For example:
	UBOOT #ext4ls mmc 0:5 /usr/lib

3. To read and load a file from an ext4-formatted partition to RAM, run:

	ext4load <interface> <dev[:part]> [addr] [filename] [bytes]

	For example:
	UBOOT #ext4load mmc 2:2 0x30007fc0 uImage

4. To write a file to an ext4-formatted partition.

	a) First load a file to RAM at a particular address for example 0x30007fc0.
	Now execute ext4write command:
	ext4write <interface> <dev[:part]> [filename] [Address] [sizebytes]

	For example:
	UBOOT #ext4write mmc 2:2 /boot/uImage 0x30007fc0 6183120
	(here 6183120 is the size of the file to be written)
	Note: Absolute path is required for the file to be written

References :
	-- ext4 implementation in Linux Kernel
	-- Uboot existing ext2 load and ls implementation
	-- Journaling block device JBD2 implementation in linux Kernel

U-Boot Falcon Mode
====================

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

This document provides an overview of how to add support for Falcon Mode
to a board.

Falcon Mode is introduced to speed up the booting process, allowing
to boot a Linux kernel (or whatever image) without a full blown U-Boot.

Falcon Mode relies on the SPL framework. In fact, to make booting faster,
U-Boot is split into two parts: the SPL (Secondary Program Loader) and U-Boot
image. In most implementations, SPL is used to start U-Boot when booting from
a mass storage, such as NAND or SD-Card. SPL has now support for other media,
and can generally be seen as a way to start an image performing the minimum
required initialization. SPL mainly initializes the RAM controller, and then
copies U-Boot image into the memory.

The Falcon Mode extends this way allowing to start the Linux kernel directly
from SPL. A new command is added to U-Boot to prepare the parameters that SPL
must pass to the kernel, using ATAGS or Device Tree.

In normal mode, these parameters are generated each time before
loading the kernel, passing to Linux the address in memory where
the parameters can be read.
With Falcon Mode, this snapshot can be saved into persistent storage and SPL is
informed to load it before running the kernel.

To boot the kernel, these steps under a Falcon-aware U-Boot are required:

1. Boot the board into U-Boot.
After loading the desired legacy-format kernel image into memory (and DT as
well, if used), use the "spl export" command to generate the kernel parameters
area or the DT.  U-Boot runs as when it boots the kernel, but stops before
passing the control to the kernel.

2. Save the prepared snapshot into persistent media.
The address where to save it must be configured into board configuration
file (CONFIG_CMD_SPL_NAND_OFS for NAND).

3. Boot the board into Falcon Mode. SPL will load the kernel and copy
the parameters which are saved in the persistent area to the required address.
If a valid uImage is not found at the defined location, U-Boot will be
booted instead.

It is required to implement a custom mechanism to select if SPL loads U-Boot
or another image.

The value of a GPIO is a simple way to operate the selection, as well as
reading a character from the SPL console if CONFIG_SPL_CONSOLE is set.

Falcon Mode is generally activated by setting CONFIG_SPL_OS_BOOT. This tells
SPL that U-Boot is not the only available image that SPL is able to start.

Configuration
----------------------------
CONFIG_CMD_SPL		Enable the "spl export" command.
			The command "spl export" is then available in U-Boot
			mode
CONFIG_SYS_SPL_ARGS_ADDR	Address in RAM where the parameters must be
				copied by SPL.
				In most cases, it is <start_of_ram> + 0x100

CONFIG_SYS_NAND_SPL_KERNEL_OFFS	Offset in NAND where the kernel is stored

CONFIG_CMD_SPL_NAND_OFS	Offset in NAND where the parameters area was saved.

CONFIG_CMD_SPL_NOR_OFS	Offset in NOR where the parameters area was saved.

CONFIG_CMD_SPL_WRITE_SIZE 	Size of the parameters area to be copied

CONFIG_SPL_OS_BOOT	Activate Falcon Mode.

Function that a board must implement
------------------------------------

void spl_board_prepare_for_linux(void) : optional
	Called from SPL before starting the kernel

spl_start_uboot() : required
		Returns "0" if SPL should start the kernel, "1" if U-Boot
		must be started.

Environment variables
---------------------

A board may chose to look at the environment for decisions about falcon
mode.  In this case the following variables may be supported:

boot_os : 		Set to yes/Yes/true/True/1 to enable booting to OS,
			any other value to fall back to U-Boot (including
			unset)
falcon_args_file :	Filename to load as the 'args' portion of falcon mode
			rather than the hard-coded value.
falcon_image_file :	Filename to load as the OS image portion of falcon
			mode rather than the hard-coded value.

Using spl command
-----------------

spl - SPL configuration

Usage:

spl export <img=atags|fdt> [kernel_addr] [initrd_addr] [fdt_addr ]

img		: "atags" or "fdt"
kernel_addr	: kernel is loaded as part of the boot process, but it is not started.
		  This is the address where a kernel image is stored.
initrd_addr	: Address of initial ramdisk
		  can be set to "-" if fdt_addr without initrd_addr is used
fdt_addr	: in case of fdt, the address of the device tree.

The spl export command does not write to a storage media. The user is
responsible to transfer the gathered information (assembled ATAGS list
or prepared FDT) from temporary storage in RAM into persistant storage
after each run of 'spl export'. Unfortunately the position of temporary
storage can not be predicted nor provided at commandline, it depends
highly on your system setup and your provided data (ATAGS or FDT).
However at the end of an succesful 'spl export' run it will print the
RAM address of temporary storage. The RAM address of FDT will also be
set in the environment variable 'fdtargsaddr', the new length of the
prepared FDT will be set in the environment variable 'fdtargslen'.
These environment variables can be used in scripts for writing updated
FDT to persistent storage.

Now the user have to save the generated BLOB from that printed address
to the pre-defined address in persistent storage
(CONFIG_CMD_SPL_NAND_OFS in case of NAND).
The following example shows how to prepare the data for Falcon Mode on
twister board with ATAGS BLOB.

The "spl export" command is prepared to work with ATAGS and FDT. However,
using FDT is at the moment untested. The ppc port (see a3m071 example
later) prepares the fdt blob with the fdt command instead.


Usage on the twister board:
--------------------------------

Using mtd names with the following (default) configuration
for mtdparts:

device nand0 <omap2-nand.0>, # parts = 9
 #: name		size		offset		mask_flags
 0: MLO                 0x00080000      0x00000000      0
 1: u-boot              0x00100000      0x00080000      0
 2: env1                0x00040000      0x00180000      0
 3: env2                0x00040000      0x001c0000      0
 4: kernel              0x00600000      0x00200000      0
 5: bootparms           0x00040000      0x00800000      0
 6: splashimg           0x00200000      0x00840000      0
 7: mini                0x02800000      0x00a40000      0
 8: rootfs              0x1cdc0000      0x03240000      0


twister => nand read 82000000 kernel

NAND read: device 0 offset 0x200000, size 0x600000
 6291456 bytes read: OK

Now the kernel is in RAM at address 0x82000000

twister => spl export atags 0x82000000
## Booting kernel from Legacy Image at 82000000 ...
   Image Name:   Linux-3.5.0-rc4-14089-gda0b7f4
   Image Type:   ARM Linux Kernel Image (uncompressed)
   Data Size:    3654808 Bytes = 3.5 MiB
   Load Address: 80008000
   Entry Point:  80008000
   Verifying Checksum ... OK
   Loading Kernel Image ... OK
OK
cmdline subcommand not supported
bdt subcommand not supported
Argument image is now in RAM at: 0x80000100

The result can be checked at address 0x80000100:

twister => md 0x80000100
80000100: 00000005 54410001 00000000 00000000    ......AT........
80000110: 00000000 00000067 54410009 746f6f72    ....g.....ATroot
80000120: 65642f3d 666e2f76 77722073 73666e20    =/dev/nfs rw nfs

The parameters generated with this step can be saved into NAND at the offset
0x800000 (value for twister for CONFIG_CMD_SPL_NAND_OFS)

nand erase.part bootparms
nand write 0x80000100 bootparms 0x4000

Now the parameters are stored into the NAND flash at the address
CONFIG_CMD_SPL_NAND_OFS (=0x800000).

Next time, the board can be started into Falcon Mode moving the
setting the gpio (on twister gpio 55 is used) to kernel mode.

The kernel is loaded directly by the SPL without passing through U-Boot.

Example with FDT: a3m071 board
-------------------------------

To boot the Linux kernel from the SPL, the DT blob (fdt) needs to get
prepard/patched first. U-Boot usually inserts some dynamic values into
the DT binary (blob), e.g. autodetected memory size, MAC addresses,
clocks speeds etc. To generate this patched DT blob, you can use
the following command:

1. Load fdt blob to SDRAM:
=> tftp 1800000 a3m071/a3m071.dtb

2. Set bootargs as desired for Linux booting (e.g. flash_mtd):
=> run mtdargs addip2 addtty

3. Use "fdt" commands to patch the DT blob:
=> fdt addr 1800000
=> fdt boardsetup
=> fdt chosen

4. Display patched DT blob (optional):
=> fdt print

5. Save fdt to NOR flash:
=> erase fc060000 fc07ffff
=> cp.b 1800000 fc060000 10000
...


Falcon Mode was presented at the RMLL 2012. Slides are available at:

http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf

# SPDX-License-Identifier: GPL-2.0+
#
# Copyright (c) 2011 The Chromium OS Authors.

Device Tree Control in U-Boot
=============================

This feature provides for run-time configuration of U-Boot via a flat
device tree (fdt). U-Boot configuration has traditionally been done
using CONFIG options in the board config file. This feature aims to
make it possible for a single U-Boot binary to support multiple boards,
with the exact configuration of each board controlled by a flat device
tree (fdt). This is the approach recently taken by the ARM Linux kernel
and has been used by PowerPC for some time.

The fdt is a convenient vehicle for implementing run-time configuration
for three reasons. Firstly it is easy to use, being a simple text file.
It is extensible since it consists of nodes and properties in a nice
hierarchical format.

Finally, there is already excellent infrastructure for the fdt: a
compiler checks the text file and converts it to a compact binary
format, and a library is already available in U-Boot (libfdt) for
handling this format.

The dts directory contains a Makefile for building the device tree blob
and embedding it in your U-Boot image. This is useful since it allows
U-Boot to configure itself according to what it finds there. If you have
a number of similar boards with different peripherals, you can describe
the features of each board in the device tree file, and have a single
generic source base.

To enable this feature, add CONFIG_OF_CONTROL to your board config file.


What is a Flat Device Tree?
---------------------------

An fdt can be specified in source format as a text file. To read about
the fdt syntax, take a look at the specification here:

https://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf

You also might find this section of the Linux kernel documentation
useful: (access this in the Linux kernel source code)

	Documentation/devicetree/booting-without-of.txt

There is also a mailing list:

	http://lists.ozlabs.org/listinfo/devicetree-discuss

In case you are wondering, OF stands for Open Firmware.


Tools
-----

To use this feature you will need to get the device tree compiler. This is
provided by U-Boot automatically. If you have a system version of dtc
(typically in the 'device-tree-compiler' package), it is currently not used.

If you want to build your own dtc, it is kept here:

	git://git.kernel.org/pub/scm/utils/dtc/dtc.git

For example:

	$ git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git
	$ cd dtc
	$ make
	$ sudo make install

Then run the compiler (your version will vary):

	$ dtc -v
	Version: DTC 1.2.0-g2cb4b51f
	$ make tests
	$ cd tests
	$ ./run_tests.sh
	********** TEST SUMMARY
	*     Total testcases:	1371
	*                PASS:	1371
	*                FAIL:	0
	*   Bad configuration:	0
	* Strange test result:	0

You will also find a useful fdtdump utility for decoding a binary file, as
well as fdtget/fdtput for reading and writing properties in a binary file.


Where do I get an fdt file for my board?
----------------------------------------

You may find that the Linux kernel has a suitable file. Look in the
kernel source in arch/<arch>/boot/dts.

If not you might find other boards with suitable files that you can
modify to your needs. Look in the board directories for files with a
.dts extension.

Failing that, you could write one from scratch yourself!


Configuration
-------------

Use:

#define CONFIG_DEFAULT_DEVICE_TREE	"<name>"

to set the filename of the device tree source. Then put your device tree
file into

	board/<vendor>/dts/<name>.dts

This should include your CPU or SOC's device tree file, placed in
arch/<arch>/dts, and then make any adjustments required.

If CONFIG_OF_EMBED is defined, then it will be picked up and built into
the U-Boot image (including u-boot.bin). This is suitable for debugging
and development only and is not recommended for production devices.

If CONFIG_OF_SEPARATE is defined, then it will be built and placed in
a u-boot.dtb file alongside u-boot-nodtb.bin. A common approach is then to
join the two:

	cat u-boot-nodtb.bin u-boot.dtb >image.bin

and then flash image.bin onto your board. Note that U-Boot creates
u-boot-dtb.bin which does the above step for you also. Resulting
u-boot.bin is a copy of u-boot-dtb.bin in this case. If you are using
CONFIG_SPL_FRAMEWORK, then u-boot.img will be built to include the device
tree binary.

If CONFIG_OF_BOARD is defined, a board-specific routine will provide the
device tree at runtime, for example if an earlier bootloader stage creates
it and passes it to U-Boot.

If CONFIG_OF_HOSTFILE is defined, then it will be read from a file on
startup. This is only useful for sandbox. Use the -d flag to U-Boot to
specify the file to read.

You cannot use more than one of these options at the same time.

To use a device tree file that you have compiled yourself, pass
EXT_DTB=<filename> to 'make', as in:

	make EXT_DTB=boot/am335x-boneblack-pubkey.dtb

Then U-Boot will copy that file to u-boot.dtb, put it in the .img file
if used, and u-boot-dtb.bin.

If you wish to put the fdt at a different address in memory, you can
define the "fdtcontroladdr" environment variable. This is the hex
address of the fdt binary blob, and will override either of the options.
Be aware that this environment variable is checked prior to relocation,
when only the compiled-in environment is available. Therefore it is not
possible to define this variable in the saved SPI/NAND flash
environment, for example (it will be ignored). After relocation, this
variable will be set to the address of the newly relocated fdt blob.
It is read-only and cannot be changed. It can optionally be used to
control the boot process of Linux with bootm/bootz commands.

To use this, put something like this in your board header file:

#define CONFIG_EXTRA_ENV_SETTINGS	"fdtcontroladdr=10000\0"

Build:

After board configuration is done, fdt supported u-boot can be build in two ways:
1)  build the default dts which is defined from CONFIG_DEFAULT_DEVICE_TREE
    $ make
2)  build the user specified dts file
    $ make DEVICE_TREE=<dts-file-name>


Relocation, SPL and TPL
-----------------------

U-Boot can be divided into three phases: TPL, SPL and U-Boot proper.

The full device tree is available to U-Boot proper, but normally only a subset
(or none at all) is available to TPL and SPL. See 'Pre-Relocation Support' and
'SPL Support' in doc/driver-model/design.rst for more details.


Using several DTBs in the SPL (CONFIG_SPL_MULTI_DTB)
----------------------------------------------------
In some rare cases it is desirable to let SPL be able to select one DTB among
many. This usually not very useful as the DTB for the SPL is small and usually
fits several platforms. However the DTB sometimes include information that do
work on several platforms (like IO tuning parameters).
In this case it is possible to use CONFIG_SPL_MULTI_DTB. This option appends to
the SPL a FIT image containing several DTBs listed in SPL_OF_LIST.
board_fit_config_name_match() is called to select the right DTB.

If board_fit_config_name_match() relies on DM (DM driver to access an EEPROM
containing the board ID for example), it possible to start with a generic DTB
and then switch over to the right DTB after the detection. For this purpose,
the platform code must call fdtdec_resetup(). Based on the returned flag, the
platform may have to re-initiliaze the DM subusystem using dm_uninit() and
dm_init_and_scan().


Limitations
-----------

U-Boot is designed to build with a single architecture type and CPU
type. So for example it is not possible to build a single ARM binary
which runs on your AT91 and OMAP boards, relying on an fdt to configure
the various features. This is because you must select one of
the CPU families within arch/arm/cpu/arm926ejs (omap or at91) at build
time. Similarly you cannot build for multiple cpu types or
architectures.

That said the complexity reduction by using fdt to support variants of
boards which use the same SOC / CPU can be substantial.

It is important to understand that the fdt only selects options
available in the platform / drivers. It cannot add new drivers (yet). So
you must still have the CONFIG option to enable the driver. For example,
you need to define CONFIG_SYS_NS16550 to bring in the NS16550 driver,
but can use the fdt to specific the UART clock, peripheral address, etc.
In very broad terms, the CONFIG options in general control *what* driver
files are pulled in, and the fdt controls *how* those files work.

--
Simon Glass <sjg@chromium.org>
1-Sep-11

U-Boot config options used in fec_mxc.c

CONFIG_FEC_MXC
	Selects fec_mxc.c to be compiled into u-boot. Can read out the
	ethaddr from the SoC eFuses (see below).

CONFIG_MII
	Must be defined if CONFIG_FEC_MXC is defined.

CONFIG_FEC_XCV_TYPE
	Defaults to MII100 for 100 Base-tx.
	RGMII selects 1000 Base-tx reduced pin count interface.
	RMII selects 100 Base-tx reduced pin count interface.

CONFIG_FEC_MXC_SWAP_PACKET
	Forced on iff MX28.
	Swaps the bytes order of all words(4 byte units) in the packet.
	This should not be specified by a board file. It is cpu specific.

CONFIG_PHYLIB
	fec_mxc supports PHYLIB and should be used for new boards.

CONFIG_FEC_MXC_NO_ANEG
	Relevant only if PHYLIB not used. Skips auto-negotiation restart.

CONFIG_FEC_MXC_PHYADDR
	Optional, selects the exact phy address that should be connected
	and function fecmxc_initialize will try to initialize it.

CONFIG_FEC_FIXED_SPEED
	Optional, selects a fixed speed on the MAC interface without asking some
	phy. This is usefull if there is a direct MAC <-> MAC connection, for
	example if the CPU is connected directly via the RGMII interface to a
	ethernet-switch.

Reading the ethaddr from the SoC eFuses:
if CONFIG_FEC_MXC is defined and the U-Boot environment does not contain the
ethaddr variable, then its value gets read from the corresponding eFuses in
the SoC. See the README files of the specific SoC for details.

Freescale system clock options

	- CONFIG_SYS_FSL_CLK
		Enable to call get_clocks() in board_init_f() for
		non-PPC platforms.

Table of interleaving 2-4 controllers
=====================================
  +--------------+-----------------------------------------------------------+
  |Configuration |                    Memory Controller                      |
  |              |       1              2              3             4       |
  |--------------+--------------+--------------+-----------------------------+
  | Two memory   | Not Intlv'ed | Not Intlv'ed |                             |
  | complexes    +--------------+--------------+                             |
  |              |      2-way Intlv'ed         |                             |
  |--------------+--------------+--------------+--------------+              |
  |              | Not Intlv'ed | Not Intlv'ed | Not Intlv'ed |              |
  | Three memory +--------------+--------------+--------------+              |
  | complexes    |         2-way Intlv'ed      | Not Intlv'ed |              |
  |              +-----------------------------+--------------+              |
  |              |                  3-way Intlv'ed            |              |
  +--------------+--------------+--------------+--------------+--------------+
  |              | Not Intlv'ed | Not Intlv'ed | Not Intlv'ed | Not Intlv'ed |
  | Four memory  +--------------+--------------+--------------+--------------+
  | complexes    |       2-way Intlv'ed        |       2-way Intlv'ed        |
  |              +-----------------------------+-----------------------------+
  |              |                      4-way Intlv'ed                       |
  +--------------+-----------------------------------------------------------+


Table of 2-way interleaving modes supported in cpu/8xxx/ddr/
======================================================
  +-------------+---------------------------------------------------------+
  |		|		    Rank Interleaving			  |
  |		+--------+-----------+-----------+------------+-----------+
  |Memory	|	 |	     |		 |    2x2     |    4x1	  |
  |Controller	|  None  | 2x1 lower | 2x1 upper | {CS0+CS1}, | {CS0+CS1+ |
  |Interleaving |	 | {CS0+CS1} | {CS2+CS3} | {CS2+CS3}  |  CS2+CS3} |
  +-------------+--------+-----------+-----------+------------+-----------+
  |None		|  Yes	 | Yes	     | Yes	 | Yes	      | Yes	  |
  +-------------+--------+-----------+-----------+------------+-----------+
  |Cacheline	|  Yes	 | Yes	     | No	 | No, Only(*)| Yes	  |
  |		|CS0 Only|	     |		 | {CS0+CS1}  |		  |
  +-------------+--------+-----------+-----------+------------+-----------+
  |Page		|  Yes	 | Yes	     | No	 | No, Only(*)| Yes	  |
  |		|CS0 Only|	     |		 | {CS0+CS1}  |		  |
  +-------------+--------+-----------+-----------+------------+-----------+
  |Bank		|  Yes	 | Yes	     | No	 | No, Only(*)| Yes	  |
  |		|CS0 Only|	     |		 | {CS0+CS1}  |		  |
  +-------------+--------+-----------+-----------+------------+-----------+
  |Superbank	|  No	 | Yes	     | No	 | No, Only(*)| Yes	  |
  |		|	 |	     |		 | {CS0+CS1}  |		  |
  +-------------+--------+-----------+-----------+------------+-----------+
 (*) Although the hardware can be configured with memory controller
 interleaving using "2x2" rank interleaving, it only interleaves {CS0+CS1}
 from each controller. {CS2+CS3} on each controller are only rank
 interleaved on that controller.

 For memory controller interleaving, identical DIMMs are suggested. Software
 doesn't check the size or organization of interleaved DIMMs.

The ways to configure the ddr interleaving mode
==============================================
1. In board header file(e.g.MPC8572DS.h), add default interleaving setting
   under "CONFIG_EXTRA_ENV_SETTINGS", like:
	#define CONFIG_EXTRA_ENV_SETTINGS				\
	 "hwconfig=fsl_ddr:ctlr_intlv=bank"			\
	 ......

2. Run U-Boot "setenv" command to configure the memory interleaving mode.
   Either numerical or string value is accepted.

  # disable memory controller interleaving
  setenv hwconfig "fsl_ddr:ctlr_intlv=null"

  # cacheline interleaving
  setenv hwconfig "fsl_ddr:ctlr_intlv=cacheline"

  # page interleaving
  setenv hwconfig "fsl_ddr:ctlr_intlv=page"

  # bank interleaving
  setenv hwconfig "fsl_ddr:ctlr_intlv=bank"

  # superbank
  setenv hwconfig "fsl_ddr:ctlr_intlv=superbank"

  # 1KB 3-way interleaving
  setenv hwconfig "fsl_ddr:ctlr_intlv=3way_1KB"

  # 4KB 3-way interleaving
  setenv hwconfig "fsl_ddr:ctlr_intlv=3way_4KB"

  # 8KB 3-way interleaving
  setenv hwconfig "fsl_ddr:ctlr_intlv=3way_8KB"

  # disable bank (chip-select) interleaving
  setenv hwconfig "fsl_ddr:bank_intlv=null"

  # bank(chip-select) interleaving cs0+cs1
  setenv hwconfig "fsl_ddr:bank_intlv=cs0_cs1"

  # bank(chip-select) interleaving cs2+cs3
  setenv hwconfig "fsl_ddr:bank_intlv=cs2_cs3"

  # bank(chip-select) interleaving (cs0+cs1) and (cs2+cs3)  (2x2)
  setenv hwconfig "fsl_ddr:bank_intlv=cs0_cs1_and_cs2_cs3"

  # bank(chip-select) interleaving (cs0+cs1+cs2+cs3) (4x1)
  setenv hwconfig "fsl_ddr:bank_intlv=cs0_cs1_cs2_cs3"

  # bank(chip-select) interleaving (auto)
  setenv hwconfig "fsl_ddr:bank_intlv=auto"
  This auto mode only select from cs0_cs1_cs2_cs3, cs0_cs1, null dependings
  on DIMMs.

Memory controller address hashing
==================================
If the DDR controller supports address hashing, it can be enabled by hwconfig.

Syntax is:
hwconfig=fsl_ddr:addr_hash=true

Memory controller ECC on/off
============================
If ECC is enabled in board configuratoin file, i.e. #define CONFIG_DDR_ECC,
ECC can be turned on/off by hwconfig.

Syntax is
hwconfig=fsl_ddr:ecc=off


Memory address parity on/off
============================
address parity can be turned on/off by hwconfig.
Syntax is:
hwconfig=fsl_ddr:parity=on


Memory testing options for mpc85xx
==================================
1. Memory test can be done once U-Boot prompt comes up using mtest, or
2. Memory test can be done with Power-On-Self-Test function, activated at
   compile time.

   In order to enable the POST memory test, CONFIG_POST needs to be
   defined in board configuraiton header file. By default, POST memory test
   performs a fast test. A slow test can be enabled by changing the flag at
   compiling time. To test memory bigger than 2GB, 36BIT support is needed.
   Memory is tested within a 2GB window. TLBs are used to map the virtual 2GB
   window to physical address so that all physical memory can be tested.

Combination of hwconfig
=======================
Hwconfig can be combined with multiple parameters, for example, on a supported
platform

hwconfig=fsl_ddr:addr_hash=true,ctlr_intlv=cacheline,bank_intlv=cs0_cs1_cs2_cs3,ecc=on


Table for dynamic ODT for DDR3
==============================
For single-slot system with quad-rank DIMM and dual-slot system, dynamic ODT may
be needed, depending on the configuration. The numbers in the following tables are
in Ohms.

* denotes dynamic ODT

Two slots system
+-----------------------+----------+---------------+-----------------------------+-----------------------------+
|     Configuration	|	   |DRAM controller|	       Slot 1		 |	      Slot 2	       |
+-----------+-----------+----------+-------+-------+--------------+--------------+--------------+--------------+
|	    |		|	   |	   |	   |	 Rank 1   |	Rank 2	 |   Rank 1	|    Rank 2    |
+  Slot 1   |	Slot 2	|Write/Read| Write | Read  |-------+------+-------+------+-------+------+-------+------+
|	    |		|	   |	   |	   | Write | Read | Write | Read | Write | Read | Write | Read |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	    |		|  Slot 1  |  off  | 75    | 120   | off  | off   | off  | off	 | off	| 30	| 30   |
| Dual Rank | Dual Rank |----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	    |		|  Slot 2  |  off  | 75    | off   | off  | 30	  | 30	 | 120	 | off	| off	| off  |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	    |		|  Slot 1  |  off  | 75    | 120   | off  | off   | off  | 20	 | 20	|	|      |
| Dual Rank |Single Rank|----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	    |		|  Slot 2  |  off  | 75    | off   | off  | 20	  | 20	 | 120	*| off	|	|      |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	    |		|  Slot 1  |  off  | 75    | 120  *| off  |	  |	 | off	 | off	| 20	| 20   |
|Single Rank| Dual Rank |----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	    |		|  Slot 2  |  off  | 75    | 20    | 20   |	  |	 | 120	 | off	| off	| off  |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	    |		|  Slot 1  |  off  | 75    | 120  *| off  |	  |	 | 30	 | 30	|	|      |
|Single Rank|Single Rank|----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	    |		|  Slot 2  |  off  | 75    | 30    | 30   |	  |	 | 120	*| off	|	|      |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
| Dual Rank |	Empty	|  Slot 1  |  off  | 75    | 40    | off  | off   | off  |	 |	|	|      |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|   Empty   | Dual Rank |  Slot 2  |  off  | 75    |	   |	  |	  |	 | 40	 | off	| off	| off  |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|Single Rank|	Empty	|  Slot 1  |  off  | 75    | 40    | off  |	  |	 |	 |	|	|      |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|   Empty   |Single Rank|  Slot 2  |  off  | 75    |	   |	  |	  |	 | 40	 | off	|	|      |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+

Single slot system
+-------------+------------+---------------+-----------------------------+-----------------------------+
|	      |		   |DRAM controller|	 Rank 1   |    Rank 2	 |    Rank 3	|    Rank 4    |
|Configuration| Write/Read |-------+-------+-------+------+-------+------+-------+------+-------+------+
|	      |		   | Write | Read  | Write | Read | Write | Read | Write | Read | Write | Read |
+-------------+------------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	      |   R1	   | off   | 75    | 120  *| off  | off   | off  | 20	 | 20	| off	| off  |
|	      |------------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	      |   R2	   | off   | 75    | off   | 20   | 120   | off  | 20	 | 20	| off	| off  |
|  Quad Rank  |------------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	      |   R3	   | off   | 75    | 20    | 20   | off   | off  | 120	*| off	| off	| off  |
|	      |------------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	      |   R4	   | off   | 75    | 20    | 20   | off   | off  | off	 | 20	| 120	| off  |
+-------------+------------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|	      |   R1	   | off   | 75    | 40    | off  | off   | off  |
|  Dual Rank  |------------+-------+-------+-------+------+-------+------+
|	      |   R2	   | off   | 75    | 40    | off  | off   | off  |
+-------------+------------+-------+-------+-------+------+-------+------+
| Single Rank |   R1	   | off   | 75    | 40    | off  |
+-------------+------------+-------+-------+-------+------+

Reference http://www.xrosstalkmag.com/mag_issues/xrosstalk_oct08_final.pdf
	  http://download.micron.com/pdf/technotes/ddr3/tn4108_ddr3_design_guide.pdf


Table for ODT for DDR2
======================
Two slots system
+-----------------------+----------+---------------+-----------------------------+-----------------------------+
|     Configuration     |          |DRAM controller|           Slot 1            |            Slot 2           |
+-----------+-----------+----------+-------+-------+--------------+--------------+--------------+--------------+
|           |           |          |       |       |     Rank 1   |     Rank 2   |   Rank 1     |    Rank 2    |
+  Slot 1   |   Slot 2  |Write/Read| Write | Read  |-------+------+-------+------+-------+------+-------+------+
|           |           |          |       |       | Write | Read | Write | Read | Write | Read | Write | Read |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|           |           |  Slot 1  |  off  | 150   | off   | off  | off   | off  | 75    | 75   | off   | off  |
| Dual Rank | Dual Rank |----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|           |           |  Slot 2  |  off  | 150   | 75    | 75   | off   | off  | off   | off  | off   | off  |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|           |           |  Slot 1  |  off  | 150   | off   | off  | off   | off  | 75    | 75   |       |      |
| Dual Rank |Single Rank|----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|           |           |  Slot 2  |  off  | 150   | 75    | 75   | off   | off  | off   | off  |       |      |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|           |           |  Slot 1  |  off  | 150   | off   | off  |       |      | 75    | 75   | off   | off  |
|Single Rank| Dual Rank |----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|           |           |  Slot 2  |  off  | 150   | 75    | 75   |       |      | off   | off  | off   | off  |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|           |           |  Slot 1  |  off  | 150   | off   | off  |       |      | 75    | 75   |       |      |
|Single Rank|Single Rank|----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|           |           |  Slot 2  |  off  | 150   | 75    | 75   |       |      | off   | off  |       |      |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
| Dual Rank |   Empty   |  Slot 1  |  off  | 75    | 150   | off  | off   | off  |       |      |       |      |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|   Empty   | Dual Rank |  Slot 2  |  off  | 75    |       |      |       |      | 150   | off  | off   | off  |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|Single Rank|   Empty   |  Slot 1  |  off  | 75    | 150   | off  |       |      |       |      |       |      |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+
|   Empty   |Single Rank|  Slot 2  |  off  | 75    |       |      |       |      | 150   | off  |       |      |
+-----------+-----------+----------+-------+-------+-------+------+-------+------+-------+------+-------+------+

Single slot system
+-------------+------------+---------------+-----------------------------+
|             |            |DRAM controller|     Rank 1   |    Rank 2    |
|Configuration| Write/Read |-------+-------+-------+------+-------+------+
|             |            | Write | Read  | Write | Read | Write | Read |
+-------------+------------+-------+-------+-------+------+-------+------+
|             |   R1       | off   | 75    | 150   | off  | off   | off  |
|  Dual Rank  |------------+-------+-------+-------+------+-------+------+
|             |   R2       | off   | 75    | 150   | off  | off   | off  |
+-------------+------------+-------+-------+-------+------+-------+------+
| Single Rank |   R1       | off   | 75    | 150   | off  |
+-------------+------------+-------+-------+-------+------+

Reference http://www.samsung.com/global/business/semiconductor/products/dram/downloads/applicationnote/ddr2_odt_control_200603.pdf


Interactive DDR debugging
===========================

For DDR parameter tuning up and debugging, the interactive DDR debugger can
be activated by setting the environment variable "ddr_interactive" to any
value.  (The value of ddr_interactive may have a meaning in the future, but,
for now, the presence of the variable will cause the debugger to run.)  Once
activated, U-Boot will show the prompt "FSL DDR>" before enabling the DDR
controller.  The available commands are printed by typing "help".

Another way to enter the interactive DDR debugger without setting the
environment variable is to send the 'd' character early during the boot
process.  To save booting time, no additional delay is added, so the window
to send the key press is very short -- basically, it is the time before the
memory controller code starts to run.  For example, when rebooting from
within U-Boot, the user must press 'd' IMMEDIATELY after hitting enter to
initiate a 'reset' command.  In case of power on/reset, the user can hold
down the 'd' key while applying power or hitting the board's reset button.

The example flow of using interactive debugging is
type command "compute" to calculate the parameters from the default
type command "print" with arguments to show SPD, options, registers
type command "edit" with arguments to change any if desired
type command "copy" with arguments to copy controller/dimm settings
type command "go" to continue calculation and enable DDR controller

Additional commands to restart the debugging are:
type command "reset" to reset the board
type command "recompute" to reload SPD and start over

Note, check "next_step" to show the flow. For example, after edit opts, the
next_step is STEP_ASSIGN_ADDRESSES. After editing registers, the next_step is
STEP_PROGRAM_REGS.  Upon issuing command "go", the debugger will program the
DDR controller with the current setting without further calculation and then
exit to resume the booting of the machine.

The detail syntax for each commands are

print [c<n>] [d<n>] [spd] [dimmparms] [commonparms] [opts] [addresses] [regs]
	c<n>		- the controller number, eg. c0, c1
	d<n>		- the DIMM number, eg. d0, d1
	spd		- print SPD data
	dimmparms	- DIMM parameters, calculated from SPD
	commonparms	- lowest common parameters for all DIMMs
	opts		- options
	addresses	- address assignment (not implemented yet)
	regs		- controller registers

edit <c#> <d#> <spd|dimmparms|commonparms|opts|addresses|regs> <element> <value>
	c<n>		- the controller number, eg. c0, c1
	d<n>		- the DIMM number, eg. d0, d1
	spd		- print SPD data
	dimmparms	- DIMM parameters, calculated from SPD
	commonparms	- lowest common parameters for all DIMMs
	opts		- options
	addresses	- address assignment (not implemented yet)
	regs		- controller registers
	<element>	- name of the modified element
			  byte number if the object is SPD
	<value>		- decimal or heximal (prefixed with 0x) numbers

copy <src c#> <src d#> <spd|dimmparms|commonparms|opts|addresses|regs> <dst c#> <dst d#>
	same as for "edit" command
	DIMM numbers ignored for commonparms, opts, and regs

reset
	no arguement	- reset the board

recompute
	no argument	- reload SPD and start over

compute
	no argument	- recompute from current next_step

next_step
	no argument	- show current next_step

help
	no argument	- print a list of all commands

go
	no argument	- program memory controller(s) and continue with U-Boot

Examples of debugging flow

	FSL DDR>compute
	Detected UDIMM UG51U6400N8SU-ACF
	FSL DDR>print
	print [c<n>] [d<n>] [spd] [dimmparms] [commonparms] [opts] [addresses] [regs]
	FSL DDR>print dimmparms
	DIMM parameters:  Controller=0 DIMM=0
	DIMM organization parameters:
	module part name = UG51U6400N8SU-ACF
	rank_density = 2147483648 bytes (2048 megabytes)
	capacity = 4294967296 bytes (4096 megabytes)
	burst_lengths_bitmask = 0C
	base_addresss = 0 (00000000 00000000)
	n_ranks = 2
	data_width = 64
	primary_sdram_width = 64
	ec_sdram_width = 0
	registered_dimm = 0
	n_row_addr = 15
	n_col_addr = 10
	edc_config = 0
	n_banks_per_sdram_device = 8
	tCKmin_X_ps = 1500
	tCKmin_X_minus_1_ps = 0
	tCKmin_X_minus_2_ps = 0
	tCKmax_ps = 0
	caslat_X = 960
	tAA_ps = 13125
	caslat_X_minus_1 = 0
	caslat_X_minus_2 = 0
	caslat_lowest_derated = 0
	tRCD_ps = 13125
	tRP_ps = 13125
	tRAS_ps = 36000
	tWR_ps = 15000
	tWTR_ps = 7500
	tRFC_ps = 160000
	tRRD_ps = 6000
	tRC_ps = 49125
	refresh_rate_ps = 7800000
	tIS_ps = 0
	tIH_ps = 0
	tDS_ps = 0
	tDH_ps = 0
	tRTP_ps = 7500
	tDQSQ_max_ps = 0
	tQHS_ps = 0
	FSL DDR>edit c0 opts ECC_mode 0
	FSL DDR>edit c0 regs cs0_bnds 0x000000FF
	FSL DDR>go
	2 GiB left unmapped
	4 GiB (DDR3, 64-bit, CL=9, ECC off)
	       DDR Chip-Select Interleaving Mode: CS0+CS1
	Testing 0x00000000 - 0x7fffffff
	Testing 0x80000000 - 0xffffffff
	Remap DDR 2 GiB left unmapped

	POST memory PASSED
	Flash: 128 MiB
	L2:    128 KB enabled
	Corenet Platform Cache: 1024 KB enabled
	SERDES: timeout resetting bank 3
	SRIO1: disabled
	SRIO2: disabled
	MMC:  FSL_ESDHC: 0
	EEPROM: Invalid ID (ff ff ff ff)
	PCIe1: disabled
	PCIe2: Root Complex, x1, regs @ 0xfe201000
	  01:00.0     - 8086:10d3 - Network controller
	PCIe2: Bus 00 - 01
	PCIe3: disabled
	In:    serial
	Out:   serial
	Err:   serial
	Net:   Initializing Fman
	Fman1: Uploading microcode version 101.8.0
	e1000: 00:1b:21:81:d2:e0
	FM1@DTSEC1, FM1@DTSEC2, FM1@DTSEC3, FM1@DTSEC4, FM1@DTSEC5, e1000#0 [PRIME]
	Warning: e1000#0 MAC addresses don't match:
	Address in SROM is         00:1b:21:81:d2:e0
	Address in environment is  00:e0:0c:00:ea:05

	Hit any key to stop autoboot:  0
	=>

This file documents Freescale DPAA-specific options.

FMan (Frame Manager)
  - CONFIG_FSL_FM_10GEC_REGULAR_NOTATION
	on SoCs T4240, T2080, LS1043A, etc, the notation between 10GEC and MAC as below:
		10GEC1->MAC9, 10GEC2->MAC10, 10GEC3->MAC1, 10GEC4->MAC2
	on SoCs T1024, etc, the notation between 10GEC and MAC as below:
		10GEC1->MAC1, 10GEC2->MAC2
	so we introduce CONFIG_FSL_FM_10GEC_REGULAR_NOTATION to identify the new SoCs on
	which 10GEC enumeration is consistent with MAC enumeration.

Freescale esdhc-specific options

	- CONFIG_SYS_FSL_ESDHC_LE
		ESDHC IP is in little-endian mode. Accessing ESDHC registers can be
		determined by ESDHC IP's endian mode or processor's endian mode.
	- CONFIG_SYS_FSL_ESDHC_BE
		ESDHC IP is in big-endian mode. Accessing ESDHC registers can be determined
		by ESDHC IP's endian mode or processor's endian mode.

Freescale-specific 'hwconfig' options.

This file documents Freescale-specific key:value pairs for the 'hwconfig'
option.  See README.hwconfig for general information about 'hwconfig'.

audclk
	Specific to the P1022DS reference board.

	This option specifies which of the two oscillator frequencies should be
	routed to the Wolfson WM8776 codec.  The ngPIXIS can be programmed to
	route either a 11.2896MHz or a 12.288MHz clock.  The default is
	12.288MHz.  This option has two effects.  First, the MUX on the board
	will be programmed accordingly.  Second, the clock-frequency property
	in the codec node in the device tree will be updated to the correct
	value.

	'audclk:11'
		Select the 11.2896MHz clock

	'audclk:12'
		Select the 12.288MHz clock

usb
	Specific to boards have USB controller

	This option specifies the following for a USB controller:

		- which controller mode to use
		- which USB PHY to use

	This is used by generic USB device-tree fixup function to update
	modified values of phy type and controller mode.

	Also used for configuring multiple USB controllers such that
	'usbN' (where N is 1, 2, etc. refers to controller no.)

	'phy_type'
		Select USB phy type: 'utmi' OR 'ulpi'

	'dr_mode'
		Select USB controller mode: 'host', 'peripheral' OR 'otg'

	Examples:
		usb1:dr_mode=host;usb2:dr_mode=peripheral'

		usb1:dr_mode=host,phy_type=utmi;usb2:dr_mode=host'

Freescale ARM64 SoCs like LS2080A have ARM TrustZone components like
TZPC-BP147 (TrustZone Protection Controller) and TZASC-400 (TrustZone
Address Space Controller).

While most of the configuration related programming of these peripherals
is left to a root-of-trust security software layer (running in EL3
privilege mode), but still some configurations of these peripherals
might be required while the bootloader is executing in EL3 privilege
mode. The following sections define how to turn on these features for
LS2080A like SoCs.

TZPC-BP147 (TrustZone Protection Controller)
============================================
- Depends on CONFIG_FSL_TZPC_BP147 configuration flag.
- Separates Secure World and Normal World on-chip RAM (OCRAM) spaces.
- Provides a programming model to set access control policy via the TZPC
  TZDECPROT Registers.

TZASC-400 (TrustZone Address Space Controller)
==============================================
- Depends on CONFIG_FSL_TZASC_400 configuration flag.
- Separates Secure World and Normal World external memory spaces for bus masters
  such as processors and DMA-equipped peripherals.
- Supports 8 fully programmable address regions, initially inactive at reset,
  and one base region, always active, that covers the remaining address space.

Driver implementing the fuse API for Freescale's IC Identification Module (IIM)

This IP can be found on the following SoCs:
 - MPC512x,
 - i.MX25,
 - i.MX27,
 - i.MX31,
 - i.MX35,
 - i.MX51,
 - i.MX53.

The section numbers in this file refer to the i.MX25 Reference Manual.

A fuse word contains 8 fuse bit slots, as explained in 30.4.2.2.1.

A bank contains 256 fuse word slots, as shown by the memory map in 30.3.1.

Some fuse bit or word slots may not have the corresponding fuses actually
implemented in the fusebox.

See the README files of the SoCs using this driver in order to know the
conventions used by U-Boot to store some specific data in the fuses, e.g. MAC
addresses.

Fuse operations:

   Read
      Read operations are implemented as read accesses to the shadow registers,
      using "Word y of Bank x" from the register summary in 30.3.2. This is
      explained in detail in 30.4.5.1.

   Sense
      Sense operations are implemented as explained in 30.4.5.2.

   Program
      Program operations are implemented as explained in 30.4.5.3. Following
      this operation, the shadow registers are reloaded by the hardware (not
      immediately, but this does not make any difference for a user reading
      these registers).

   Override
      Override operations are implemented as write accesses to the shadow
      registers, as explained in 30.4.5.4.

Configuration:

   CONFIG_FSL_IIM
      Define this to enable the fsl_iim driver.

Fuse API functions and commands

The fuse API allows to control a fusebox and how it is used by the upper
hardware layers.

A fuse corresponds to a single non-volatile memory bit that can be programmed
(i.e. blown, set to 1) only once. The programming operation is irreversible. A
fuse that has not been programmed reads 0.

Fuses can be used by SoCs to store various permanent configuration and data,
e.g. boot configuration, security configuration, MAC addresses, etc.

A fuse word is the smallest group of fuses that can be read at once from the
fusebox control IP registers. This is limited to 32 bits with the current API.

A fuse bank is the smallest group of fuse words having a common ID, as defined
by each SoC.

Upon startup, the fusebox control IP reads the fuse values and stores them to a
volatile shadow cache.

See the README files of the drivers implementing this API in order to know the
SoC- and implementation-specific details.

Functions / commands:

   int fuse_read(u32 bank, u32 word, u32 *val);
   fuse read <bank> <word> [<cnt>]
      Read fuse words from the shadow cache.

   int fuse_sense(u32 bank, u32 word, u32 *val);
   fuse sense <bank> <word> [<cnt>]
      Sense - i.e. read directly from the fusebox, skipping the shadow cache -
      fuse words. This operation does not update the shadow cache.

      This is useful to know the true value of fuses if an override has been
      performed (see below).

   int fuse_prog(u32 bank, u32 word, u32 val);
   fuse prog [-y] <bank> <word> <hexval> [<hexval>...]
      Program fuse words. This operation directly affects the fusebox and is
      irreversible. The shadow cache is updated accordingly or not, depending on
      each IP.

      Only the bits to be programmed should be set in the input value (i.e. for
      fuse bits that have already been programmed and hence should be left
      unchanged by a further programming, it is preferable to clear the
      corresponding bits in the input value in order not to perform a new
      hardware programming operation on these fuse bits).

   int fuse_override(u32 bank, u32 word, u32 val);
   fuse override <bank> <word> <hexval> [<hexval>...]
      Override fuse words in the shadow cache.

      The fusebox is unaffected, so following this operation, the shadow cache
      may differ from the fusebox values. Read or sense operations can then be
      used to get the values from the shadow cache or from the fusebox.

      This is useful to change the behaviors linked to some cached fuse values,
      either because this is needed only temporarily, or because some of the
      fuses have already been programmed or are locked (if the SoC allows to
      override a locked fuse).

Configuration:

   CONFIG_CMD_FUSE
      Define this to enable the fuse commands.

# SPDX-License-Identifier: GPL-2.0+
#
# (C) Copyright 2014 Google, Inc
# Simon Glass <sjg@chromium.org>

Background
----------

U-Boot traditionally had a board.c file for each architecture. This introduced
quite a lot of duplication, with each architecture tending to do
initialisation slightly differently. To address this, a new 'generic board
init' feature was introduced in March 2013 (further motivation is
provided in the cover letter below).

All boards and architectures have moved to this as of mid 2016.


What has changed?
-----------------

The main change is that the arch/<arch>/lib/board.c file is removed in
favour of common/board_f.c (for pre-relocation init) and common/board_r.c
(for post-relocation init).

Related to this, the global_data and bd_info structures now have a core set of
fields which are common to all architectures. Architecture-specific fields
have been moved to separate structures.


Further Background
------------------

The full text of the original generic board series is reproduced below.

--8<-------------

This series creates a generic board.c implementation which contains
the essential functions of the major arch/xxx/lib/board.c files.

What is the motivation for this change?

1. There is a lot of repeated code in the board.c files. Any change to
things like setting up the baud rate requires a change in 10 separate
places.

2. Since there are 10 separate files, adding a new feature which requires
initialisation is painful since it must be independently added in 10
places.

3. As time goes by the architectures naturally diverge since there is limited
pressure to compare features or even CONFIG options against similar things
in other board.c files.

4. New architectures must implement all the features all over again, and
sometimes in subtle different ways. This places an unfair burden on getting
a new architecture fully functional and running with U-Boot.

5. While it is a bit of a tricky change, I believe it is worthwhile and
achievable. There is no requirement that all code be common, only that
the code that is common should be located in common/board.c rather than
arch/xxx/lib/board.c.

All the functions of board_init_f() and board_init_r() are broken into
separate function calls so that they can easily be included or excluded
for a particular architecture. It also makes it easier to adopt Graeme's
initcall proposal when it is ready.

http://lists.denx.de/pipermail/u-boot/2012-January/114499.html

This series removes the dependency on generic relocation. So relocation
happens as one big chunk and is still completely arch-specific. See the
relocation series for a proposed solution to this for ARM:

http://lists.denx.de/pipermail/u-boot/2011-December/112928.html

or Graeme's recent x86 series v2:

http://lists.denx.de/pipermail/u-boot/2012-January/114467.html

Instead of moving over a whole architecture, this series takes the approach
of simply enabling generic board support for an architecture. It is then up
to each board to opt in by defining CONFIG_SYS_GENERIC_BOARD in the board
config file. If this is not done, then the code will be generated as
before. This allows both sets of code to co-exist until we are comfortable
with the generic approach, and enough boards run.

ARM is a relatively large board.c file and one which I can test, therefore
I think it is a good target for this series. On the other hand, x86 is
relatively small and simple, but different enough that it introduces a
few issues to be solved. So I have chosen both ARM and x86 for this series.
After a suggestion from Wolfgang I have added PPC also. This is the
largest and most feature-full board, so hopefully we have all bases
covered in this RFC.

A generic global_data structure is also required. This might upset a few
people. Here is my basic reasoning: most fields are the same, all
architectures include and need it, most global_data.h files already have
#ifdefs to select fields for a particular SOC, so it is hard to
see why architecures are different in this area. We can perhaps add a
way to put architecture-specific fields into a separate header file, but
for now I have judged that to be counter-productive.

Similarly we need a generic bd_info structure, since generic code will
be accessing it. I have done this in the same way as global_data and the
same comments apply.

There was dicussion on the list about passing gd_t around as a parameter
to pre-relocation init functions. I think this makes sense, but it can
be done as a separate change, and this series does not require it.

While this series needs to stand on its own (as with the link script
cleanup series and the generic relocation series) the goal is the
unification of the board init code. So I hope we can address issues with
this in mind, rather than focusing too narrowly on particular ARM, x86 or
PPC issues.

I have run-tested ARM on Tegra Seaboard only. To try it out, define
CONFIG_SYS_GENERIC_BOARD in your board file and rebuild. Most likely on
x86 and PPC at least it will hang, but if you are lucky it will print
something first :-)

I have run this though MAKEALL with CONFIG_SYS_GENERIC_BOARD on for all
ARM, PPC and x86 boards. There are a few failures due to errors in
the board config, which I have sent patches for. The main issue is
just the difference between __bss_end and __bss_end__.

Note: the first group of commits are required for this series to build,
but could be separated out if required. I have included them here for
convenience.

------------->8--

Simon Glass, sjg@chromium.org
March 2014
Updated after final removal, May 2016