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

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

CONFIG_NETCONSOLE_BUFFER_SIZE - Override the default buffer size

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

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

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


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

	tools/netconsole <ip> [port]

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

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

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

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

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

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

where

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

Examples:

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

or

  netconsole=@/,@192.168.3.1/

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

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

	nc -u -l -p 6666

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

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

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

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

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

The generated tree is part static and part dynamic.

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

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

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

The xxd binary dumper is needed too which I got from

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


Pantelis Antoniou, 13 Oct 2005

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

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

1. High-level requirements

The key requirements for this project are as follows:

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

   o) Extensibility

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

   o) Configurability

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

   o) Controllability

      The framework shall support manual running of the POST tests.

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

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

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

4) The LWMON board shall be used for reference.

2. Design

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

2.1. Hardware-independent POST layer

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

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

  1) Tests running on power-on booting only

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

  2) Tests running on normal booting only

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

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

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

  4) Manually executed tests

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

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

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

  1) Tests running before relocating to RAM

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

  2) Tests running after relocating to RAM

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

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

2.1.1. POST layer interfaces

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

The following flags will be defined:

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

The POST layer will export the following interface routines:

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

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

  o) void post_reloc(ulong offset);

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

  o) int post_info(char *name);

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

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

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

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

  o) int post_hotkeys_pressed(gd_t *gd)

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

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

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

  o) name

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

  o) cmd

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

  o) desc

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

  o) flags

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

  o) test

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

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

2.1.2. Test results

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

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

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

2.1.3. Integration issues

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

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

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

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

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

2.1.4. Standalone tests

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

2.1.5. Command line interface

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

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

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

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

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

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

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

2.1.6. Power failure handling

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

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

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

2.1.7. Hazardous tests

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

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

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

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

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

2.2. Hardware-specific details

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

2.2.1. Generic PPC tests

The following generic POST tests will be developed:

  o) CPU test

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

  o) Cache test

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

  o) Memory test

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

2.2.1.1. CPU test

This test will verify the following ALU instructions:

  o) Condition register istructions

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

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

  o) Integer compare instructions

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

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

  o) Arithmetic instructions

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

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

  o) Logic instructions

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

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

  o) Shift instructions

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

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

  o) Branch instructions

     This group will contain: b, bl, bc.

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

  o) Load/store instructions

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

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

  o) Load/store multiple/string instructions


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

2.2.1.2 Special-Purpose Registers Tests

TBD.

2.2.1.3. Cache test

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

  1) Basic test #1

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

    The negative pattern must be read at the last step

  2) Basic test #2

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

    The negative pattern must be read at the last step

  3) Write-through mode test

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

    The negative pattern must be read at the last step

  4) Write-back mode test

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

    The negative pattern must be read at the last step

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

  1) Basic test #1

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

  2) Basic test #2

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

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

2.2.1.4. Memory test

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

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

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

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

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

2.2.2. Common tests

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

2.2.2.1. I2C test

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

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

2.2.2.2. Watchdog timer test

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

2.2.2.3. RTC test

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

  o) Time uniformity

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

  o) Passing month boundaries

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

2.2.3. MPC8xx peripherals tests

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

  o) Serial Management Controllers (SMC)

  o) Serial Communication Controllers (SCC)

2.2.3.1. Ethernet tests (SCC)

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

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

2.2.3.2. UART tests (SMC/SCC)

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

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

2.2.3.3. USB test

TBD

2.2.3.4. SPI test

TBD

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

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

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

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

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

Overview
--------

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


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

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

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

For example:

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

obj-$(CONFIG_SPL_BUILD) += foo.o

#ifdef CONFIG_SPL_BUILD
	foo();
#endif


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

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

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

CONFIG_SPL_LIBCOMMON_SUPPORT (common/libcommon.o)
CONFIG_SPL_LIBDISK_SUPPORT (disk/libdisk.o)
CONFIG_SPL_I2C_SUPPORT (drivers/i2c/libi2c.o)
CONFIG_SPL_GPIO_SUPPORT (drivers/gpio/libgpio.o)
CONFIG_SPL_MMC_SUPPORT (drivers/mmc/libmmc.o)
CONFIG_SPL_SERIAL_SUPPORT (drivers/serial/libserial.o)
CONFIG_SPL_SPI_FLASH_SUPPORT (drivers/mtd/spi/libspi_flash.o)
CONFIG_SPL_SPI_SUPPORT (drivers/spi/libspi.o)
CONFIG_SPL_FS_FAT (fs/fat/libfat.o)
CONFIG_SPL_FS_EXT4
CONFIG_SPL_LIBGENERIC_SUPPORT (lib/libgeneric.o)
CONFIG_SPL_POWER_SUPPORT (drivers/power/libpower.o)
CONFIG_SPL_NAND_SUPPORT (drivers/mtd/nand/raw/libnand.o)
CONFIG_SPL_DRIVERS_MISC_SUPPORT (drivers/misc)
CONFIG_SPL_DMA (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 the bd_t dram bank info is done in the new function
	dram_init_banksize() called after bd is accessible.

At lib level:

	Board.c code is adapted from ppc code

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

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

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

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

example for the tx25 board booting from NAND Flash:

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

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

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

TODO

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

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

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

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

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

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

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

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

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

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

How ELF relocations 23 and 2 work.

TBC

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

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

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

a) start debugger

arm-linux-gdb u-boot

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

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

b) connect to target

target remote bdi10:2001

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

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

c) discard symbol-file

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

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

d) load new symbol table:

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

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

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

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

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

Now you can use gdb as usual :-)

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(bd_t *bd)
{
	/* Enable clock */
	at91_sys_write(AT91_PMC_PCER, 1 << AT91SAM9260_ID_MCI);
	at91_mci_hw_init();

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

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

#endif

and the board definition files needs:

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

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

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

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

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

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

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

	CONFIG_PMECC_CAP=2
	CONFIG_PMECC_SECTOR_SIZE=512
	CONFIG_SPL_GENERATE_ATMEL_PMECC_HEADER=y

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

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

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

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

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

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

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

  bootdelay
  bootcmd
  CONFIG_BOOTDELAY
  CONFIG_BOOTCOMMAND

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

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

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

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

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

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

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

  CONFIG_BOOT_RETRY_TIME
  CONFIG_BOOT_RETRY_MIN

  "bootretry" environment variable

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

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

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

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

  CONFIG_AUTOBOOT_KEYED
  CONFIG_AUTOBOOT_KEYED_CTRLC
  CONFIG_AUTOBOOT_PROMPT
  CONFIG_AUTOBOOT_DELAY_STR
  CONFIG_AUTOBOOT_STOP_STR

  "bootdelaykey"  environment variable
  "bootstopkey"	  environment variable

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

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

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

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

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

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

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

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

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

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

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.

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

ANSI terminal bootmenu command

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

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

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

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

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

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

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

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

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

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

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

Example environment:

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


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

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

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

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

  #define CONFIG_CMD_BOOTMENU
  #define CONFIG_MENU

To run the bootmenu at startup add these additional definitions:

  #define CONFIG_AUTOBOOT_KEYED
  #define CONFIG_BOOTDELAY 30
  #define CONFIG_AUTOBOOT_MENU_SHOW

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

MIPS Boston Development Board

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The driver needs some defines to describe the target hardware:

CONFIG_SYS_VCXK_BASE

	base address of VCxK hardware memory

CONFIG_SYS_VCXK_DEFAULT_LINEALIGN

	defines the physical alignment of a pixel row

CONFIG_SYS_VCXK_DOUBLEBUFFERED

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

CONFIG_SYS_VCXK_<xxxx>_PIN

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

		ACKNOWLEDGE
			describes the acknowledge line from vcxk hardware

		ENABLE
			describes the enable line to vcxk hardware

		INVERT
			describes the invert line to vcxk hardware

		RESET
			describes the reset line to vcxk hardware

		REQUEST
			describes the request line to vcxk hardware

CONFIG_SYS_VCXK_<xxxx>_PORT

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

CONFIG_SYS_VCXK_<xxxx>_DDR

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

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

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

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

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

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

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

In addition, the t3corp board defines the routine thusly:

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

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


Config Option

  CONFIG_SYS_MAX_FLASH_SECT: Number of sectors available on Flash device

  CONFIG_SYS_FLASH_CFI_WIDTH: Data-width of the flash device

  CONFIG_CMD_FLASH: Enables Flash command library

  CONFIG_FLASH_CFI_DRIVER: Enables CFI Flash driver

  CONFIG_FLASH_CFI_MTD: Enables MTD frame work for NOR Flash devices

Chromium OS Support in U-Boot
=============================

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

This describes how to use U-Boot with Chromium OS. Several options are
available:

   - Running U-Boot from the 'altfw' feature, which is available on selected
        Chromebooks from 2019 onwards (initially Grunt). Press '1' from the
        developer-mode screen to get into U-Boot. See here for details:
        https://sites.google.com/a/chromium.org/dev/chromium-os/poking-around-your-chrome-os-device?pli=1

   - Running U-Boot from the disk partition. This involves signing U-Boot and
        placing it on the disk, for booting as a 'kernel'. See
        README.chromium-chainload for information on this. This is the only
        option on non-U-Boot Chromebooks from 2013 to 2018 and is somewhat
        more involved.

   - Running U-Boot with Chromium OS verified boot. This allows U-Boot to be
        used instead of either or both of depthcharge (a bootloader which forked
        from U-Boot in 2013) and coreboot. See below for more information on
        this.


U-Boot with Chromium OS verified boot
-------------------------------------

To obtain:

   git clone https://github.com/sglass68/u-boot.git
   cd u-boot
   git checkout cros-master

   cd ..
   git clone https://chromium.googlesource.com/chromiumos/platform/vboot_reference
   cd vboot_reference
   git checkout 45964294
   #  futility: updater: Correct output version for Snow

To build for sandbox:

   UB=/tmp/b/chromeos_sandbox    # U-Boot build directory
   cd u-boot
   make O=$UB chromeos_sandbox_defconfig
   make O=$UB -j20 -s VBOOT_SOURCE=/path/to/vboot_reference \
	MAKEFLAGS_VBOOT=DEBUG=1 QUIET=1

Replace sandbox with another supported target.

This produces $UB/image.bin which contains the firmware binaries in a SPI
flash image.

To run on sandbox:

   $UB/tpl/u-boot-tpl -d $UB/u-boot.dtb.out \
	-L6 -c "host bind 0 $CROS/src/build/images/cheza/latest/chromiumos_image.bin; vboot go auto" \
	-l -w -s state.dtb -r

To run on other boards:
   Install image.bin in the SPI flash of your device
   Boot your system


Sandbox
-------

Most Chromium OS development with U-Boot is undertaken using sandbox. There is
a sandbox target available (chromeos_sandbox) which allows running U-Boot on
a Linux machine completion with emulations of the display, TPM, disk, etc.

Running sandbox starts TPL, which contains the first phase of vboot, providing
a device tree and binding a Chromium OS disk image for use to find kernels
(any Chromium OS image will do). It also saves driver state between U-Boot
phases into state.dtb and will automatically ensure that memory is shared
between all phases. TPL will jump to SPL and then on to U-Boot proper.

It is possible to run with debugging on, e.g.

   gdb --args $UB/tpl/u-boot-tpl -d ....

Breakpoints can be set in any U-Boot phase. Overall this is a good debugging
environment for new verified-boot features.


Samus
-----

Basic support is available for samus, using the chromeos_samus target. If you
have an em100, use:

   sudo em100 -s -c W25Q128FW -d $UB/image.bin -t -r

to write the image and then boot samus (Power-Refresh).


Boot flow
---------

Verified boot starts in TPL, which selects the A or B SPL, which in turn selects
the A or B U-Boot. Then this jumps to the selected kernel. If anything goes
wrong, the device reboots and the recovery SPL and U-Boot are used instead.

More details are available here:

   https://www.chromium.org/chromium-os/chromiumos-design-docs/firmware-boot-and-recovery


New uclasses
------------

Several uclasses are provided in cros/:

	UCLASS_CROS_AUX_FW		Chrome OS auxiliary firmware
	UCLASS_CROS_FWSTORE		Chrome OS firmware storage
	UCLASS_CROS_NVDATA		Chrome OS non-volatile data device
	UCLASS_CROS_VBOOT_EC		Chrome OS vboot EC operations
	UCLASS_CROS_VBOOT_FLAG		Chrome OS verified boot flag

The existing UCLASS_CROS_EC is also used.


Commands
--------

A new 'vboot' command is provided to run particular vboot stages. The most
useful command is 'vboot go auto', which continues where the last stage left
off.

Note that TPL and SPL do not supports commands as yet, so the vboot code is
called directly from the SPL boot devices (BOOT_DEVICE_CROS_VBOOT). See
cros_load_image_tpl() and cros_load_image_spl() which both call
vboot_run_auto().


Config options
--------------

The main option is CONFIG_CHROMEOS, which enables a wide array of other options
so that the required features are present.


Device-tree config
------------------

Various options are available which control the operation of verified boot.
See cros/dts/bindings/config.txt for details. Most config is handled at run-
time, although build-time config (with Kconfig) could also be added fairly
easily.


Porting to other hardware
-------------------------

A basic port to samus (Chromebook Pixel 2015) is in a basic working state,
using the chromeos_samus target. Patches will likely be forthcoming in early
2019. Ports to an ARM board and coreboot (for x86 Chromebooks) are in the
dreaming state.


Tests
-----

Chromium OS firmware has a very limited set of tests. The tests that originally
existed in U-Boot were not brought over to coreboot or depthcharge.

The U-Boot tests ('make check') do operate, but at present there are no
Chromium OS tests available. These will hopefully come together over time. Of
course the above sandbox feature provides a sort of functional test and can
detecte problems that affect the flow or particular vboot features.


TO DO
-----

- Support for booting from coreboot (patches expected March 2019)
- Support for booting from an ARM board, e.g. bob


Simon Glass
sjg@chromium.org
7 October 2018

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

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

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

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


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

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

You can obtain the vbutil_kernel utility here:

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


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

See here:

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


Nyan-big
--------

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

1. Build U-Boot

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


2. Select a .its file

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

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


3. Build and sign an image

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


4. Prepare an SD card

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


5. Write U-Boot to the SD card

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


6. Start it up

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

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

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

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

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


7. Known problems

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

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

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


9. Notes

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

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

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


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


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

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

1. Patch U-Boot

Open include/configs/rk3288_common.h

Change:

#define CONFIG_SYS_TEXT_BASE		0x00100000

to:

#define CONFIG_SYS_TEXT_BASE		0x02000100



2. Build U-Boot

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


3. See above

4. Build and sign an image

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


5. See above

6. See above

7. Start it up

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

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

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

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


8. Known problems

None as yet.


9. Notes

None as yet.


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

flashrom
--------

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

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


coreboot
--------

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

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

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

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

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

NOTE: target compilation only work for _some_ ARM boards at the moment.
Also AArch64 is not supported currently due to a lack of private libgcc
support.  Boards which reassign gd in c will also fail to compile, but there is
in no strict reason to do so in the ARM world, since crt0.S takes care of this.
These assignments can be avoided by changing the init calls but this is not in
mainline yet.

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

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

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

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

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

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

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

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

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

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

.. highlight:: none

Coccinelle
==========

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

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

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

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

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

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

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

Once you have it, run the following command::

     	./configure
        make

as a regular user, and install it with::

        sudo make install

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

For supplemental documentation refer to the wiki:

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

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

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

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

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

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

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

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

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

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

Two other modes provide some common combinations of these modes.

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

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

Examples
~~~~~~~~

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

		make coccicheck MODE=report

To produce patches, run::

		make coccicheck MODE=patch


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

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

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

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

   make coccicheck MODE=report V=1

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

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

   make coccicheck MODE=report J=4

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

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

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

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

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

For instance::

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

or::

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


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

By default the entire kernel source tree is checked.

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

    make coccicheck M=drivers/net/wireless/

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

    make C=1 CHECK="scripts/coccicheck"

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

    make C=2 CHECK="scripts/coccicheck"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      spatch --print-options-only

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

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

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

    make SPFLAGS=--use-glimpse coccicheck

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

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

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

    make SPFLAGS=--use-idutils coccicheck

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

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

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

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

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

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

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

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

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

	// Requires: 1.0.5

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

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


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

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

  file:line:column-column: message

Example
~~~~~~~

Running::

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

will execute the following part of the SmPL script::

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

     ERR_PTR@p(PTR_ERR(x))

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

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

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

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


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

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

Example
~~~~~~~

Running::

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

will execute the following part of the SmPL script::

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

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

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

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

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

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

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

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

Example
~~~~~~~

Running::

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

will execute the following part of the SmPL script::

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

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

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

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

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

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

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

Example
~~~~~~~

Running::

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

will execute the following part of the SmPL script::

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

      ERR_PTR@p(PTR_ERR(x))

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

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

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

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

Command definition
------------------

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

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

name:		The name of the command. THIS IS NOT a string.

maxargs:	The maximum number of arguments this function takes including
		the command itself.

repeatable:	Either 0 or 1 to indicate if autorepeat is allowed.

command:	Pointer to the command function. This is the function that is
		called when the command is issued.

usage:		Short description. This is a string.

help:		Long description. This is a string. The long description is
		only available if CONFIG_SYS_LONGHELP is defined.

comp:		Pointer to the completion function. May be NULL.
		This function is called if the user hits the TAB key while
		entering the command arguments to complete the entry. Command
		completion is only available if CONFIG_AUTO_COMPLETE is defined.

Sub-command definition
----------------------

Likewise an array of struct cmd_tbl holding sub-commands can be created using either
of the following macros:

* U_BOOT_CMD_MKENT(name, maxargs, repeatable, command, "usage", "help")
* U_BOOT_CMD_MKENTCOMPLETE(name, maxargs, repeatable, command, "usage, "help",
  comp)

This table has to be evaluated in the command function of the main command, e.g.

    static struct cmd_tbl cmd_sub[] = {
        U_BOOT_CMD_MKENT(foo, CONFIG_SYS_MAXARGS, 1, do_foo, "", ""),
        U_BOOT_CMD_MKENT(bar, CONFIG_SYS_MAXARGS, 1, do_bar, "", ""),
    };

    static int do_cmd(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])
    {
        struct cmd_tbl *cp;

        if (argc < 2)
                return CMD_RET_USAGE;

        /* drop sub-command argument */
        argc--;
        argv++;

        cp = find_cmd_tbl(argv[0], cmd_ut_sub, ARRAY_SIZE(cmd_sub));

        if (cp)
            return cp->cmd(cmdtp, flag, argc, argv);

        return CMD_RET_USAGE;
    }

Command function
----------------

The command function pointer has to be of type
int (*cmd)(struct cmd_tbl *cmdtp, int flag, int argc, const char *argv[]);

cmdtp:		Table entry describing the command (see above).

flag:		A bitmap which may contain the following bit:
		CMD_FLAG_REPEAT - The last command is repeated.
		CMD_FLAG_BOOTD  - The command is called by the bootd command.
		CMD_FLAG_ENV    - The command is called by the run command.

argc:		Number of arguments including the command.

argv:		Arguments.

Allowable return value are:

CMD_RET_SUCCESS	The command was successfully executed.

CMD_RET_FAILURE	The command failed.

CMD_RET_USAGE	The command was called with invalid parameters. This value
		leads to the display of the usage string.

Completion function
-------------------

The completion function pointer has to be of type
int (*complete)(int argc, char *const argv[], char last_char,
		int maxv, char *cmdv[]);

argc:		Number of arguments including the command.

argv:		Arguments.

last_char:	The last character in the command line buffer.

maxv:		Maximum number of possible completions that may be returned by
		the function.

cmdv:		Used to return possible values for the last argument. The last
		possible completion must be followed by NULL.

The function returns the number of possible completions (without the terminating
NULL value).

Behind the scene
----------------

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

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

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

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

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

Writing tests
-------------

All new commands should have tests. Tests for existing commands are very
welcome.

It is fairly easy to write a test for a command. Enable it in sandbox, and
then add code that runs the command and checks the output.

Here is an example:

/* Test 'acpi items' command */
static int dm_test_acpi_cmd_items(struct unit_test_state *uts)
{
	struct acpi_ctx ctx;
	void *buf;

	buf = malloc(BUF_SIZE);
	ut_assertnonnull(buf);

	ctx.current = buf;
	ut_assertok(acpi_fill_ssdt(&ctx));
	console_record_reset();
	run_command("acpi items", 0);
	ut_assert_nextline("dev 'acpi-test', type 1, size 2");
	ut_assert_nextline("dev 'acpi-test2', type 1, size 2");
	ut_assert_console_end();

	ctx.current = buf;
	ut_assertok(acpi_inject_dsdt(&ctx));
	console_record_reset();
	run_command("acpi items", 0);
	ut_assert_nextline("dev 'acpi-test', type 2, size 2");
	ut_assert_nextline("dev 'acpi-test2', type 2, size 2");
	ut_assert_console_end();

	console_record_reset();
	run_command("acpi items -d", 0);
	ut_assert_nextline("dev 'acpi-test', type 2, size 2");
	ut_assert_nextlines_are_dump(2);
	ut_assert_nextline("%s", "");
	ut_assert_nextline("dev 'acpi-test2', type 2, size 2");
	ut_assert_nextlines_are_dump(2);
	ut_assert_nextline("%s", "");
	ut_assert_console_end();

	return 0;
}
DM_TEST(dm_test_acpi_cmd_items, DM_TESTF_SCAN_PDATA | DM_TESTF_SCAN_FDT);

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_t structure passed to the
application to do everything you want with the console.

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

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

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

Working drivers:

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

Work in progress:

    wl_kbd	(Wireless 4PPM keyboard)

Waiting for volounteers:

    lcd	(mpc8xx lcd controller; to )

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

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

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

Summary
=======

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 directly from SPI flash. The SPL takes care of the low level
initialization.

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

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+

Device Firmware Upgrade (DFU)

Overview:

  The Device Firmware Upgrade (DFU) allows to download and upload firmware
  to/from U-Boot connected over USB.

  U-boot follows the Universal Serial Bus Device Class Specification for
  Device Firmware Upgrade Version 1.1 the USB forum (DFU v1.1 in www.usb.org).

  U-Boot implements this DFU capability (CONFIG_DFU) with the command dfu
  (cmd/dfu.c / CONFIG_CMD_DFU) based on:
  - the DFU stack (common/dfu.c and common/spl/spl_dfu.c), based on the
    USB DFU download gadget (drivers/usb/gadget/f_dfu.c)
  - The access to mediums is done in DFU backends (driver/dfu)

  Today the supported DFU backends are:
  - MMC (RAW or FAT / EXT2 / EXT3 / EXT4 file system)
  - NAND
  - RAM
  - SF (serial flash)
  - MTD (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
  - virtual

  These DFU backends are also used by
  - the dfutftp (see README.dfutftp)
  - the thordown command (cmd/thordown.c and gadget/f_thor.c)

  The "virtual" backend is a generic DFU backend to support a board specific
  target (for example OTP), only based on the weak functions:
  - dfu_write_medium_virt
  - dfu_get_medium_size_virt
  - dfu_read_medium_virt

Configuration Options:
  CONFIG_DFU
  CONFIG_DFU_OVER_USB
  CONFIG_DFU_MMC
  CONFIG_DFU_MTD
  CONFIG_DFU_NAND
  CONFIG_DFU_RAM
  CONFIG_DFU_SF
  CONFIG_DFU_SF_PART
  CONFIG_DFU_TIMEOUT
  CONFIG_DFU_VIRTUAL
  CONFIG_CMD_DFU

Environment variables:
  the dfu command uses 3 environments variables:
  "dfu_alt_info" : the DFU setting for the USB download gadget with a semicolon
                   separated string of information on each alternate:
                   dfu_alt_info="<alt1>;<alt2>;....;<altN>"

                   when several devices are used, the format is:
                   - <interface> <dev>'='alternate list (';' separated)
                   - each interface is separated by '&'
                dfu_alt_info=\
                   "<interface1> <dev1>=<alt1>;....;<altN>&"\
                   "<interface2> <dev2>=<altN+1>;....;<altM>&"\
                   ...\
                   "<interfaceI> <devI>=<altY+1>;....;<altZ>&"

  "dfu_bufsiz" : size of the DFU buffer, when absent, use
                 CONFIG_SYS_DFU_DATA_BUF_SIZE (8 MiB by default)

  "dfu_hash_algo" : name of the hash algorithm to use

Commands:
  dfu <USB_controller> [<interface> <dev>] list
    list the alternate device defined in "dfu_alt_info"

  dfu <USB_controller> [<interface> <dev>] [<timeout>]
    start the dfu stack on the USB instance with the selected medium
    backend and use the "dfu_alt_info" variable to configure the
    alternate setting and link each one with the medium
    The dfu command continue until receive a ^C in console or
    a DFU detach transaction from HOST. If CONFIG_DFU_TIMEOUT option
    is enabled and <timeout> parameter is present in the command line,
    the DFU operation will be aborted automatically after <timeout>
    seconds of waiting remote to initiate DFU session.

  The possible values of <interface> are :
  (with <USB controller> = 0 in the dfu command example)

  "mmc" (for eMMC and SD card)
    cmd: dfu 0 mmc <dev>
    each element in "dfu_alt_info" =
      <name> raw <offset> <size> [mmcpart <num>]   raw access to mmc device
      <name> part <dev> <part_id> [mmcpart <num>]  raw access to partition
      <name> fat <dev> <part_id> [mmcpart <num>]   file in FAT partition
      <name> ext4 <dev> <part_id> [mmcpart <num>]  file in EXT4 partition

      with <partid> being the GPT or DOS partition index,
      with <num> being the eMMC hardware partition number.

    A value of environment variable dfu_alt_info for eMMC could be:

      "u-boot raw 0x3e 0x800 mmcpart 1;bl2 raw 0x1e 0x1d mmcpart 1"

    A value of environment variable dfu_alt_info for SD card could be:

      "u-boot raw 0x80 0x800;uImage ext4 0 2"

  "nand" (raw slc nand device)
    cmd: dfu 0 nand <dev>
    each element in "dfu_alt_info" =
      <name> raw <offset> <size>   raw access to mmc device
      <name> part <dev> <part_id>  raw acces to partition
      <name> partubi <dev> <part_id>  raw acces to ubi partition

      with <partid> is the MTD partition index

  "ram"
    cmd: dfu 0 ram <dev>
    (<dev> is not used for RAM target)
    each element in "dfu_alt_info" =
      <name> ram <offset> <size>  raw access to ram

  "sf" (serial flash : NOR)
    cmd: dfu 0 sf <dev>
    each element in "dfu_alt_info" =
      <name> ram <offset> <size>  raw access to sf device
      <name> part <dev> <part_id>  raw acces to partition
      <name> partubi <dev> <part_id>  raw acces to ubi partition

      with <partid> is the MTD partition index

  "mtd" (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
    cmd: dfu 0 mtd <dev>
      with <dev> the mtd identifier as defined in mtd command
      (nand0, nor0, spi-nand0,...)
    each element in "dfu_alt_info" =
      <name> raw <offset> <size>  raw access to mtd device
      <name> part <dev> <part_id>  raw acces to partition
      <name> partubi <dev> <part_id>  raw acces to ubi partition

      with <partid> is the MTD partition index

  "virt"
    cmd: dfu 0 virt <dev>
    each element in "dfu_alt_info" =
      <name>

  <interface> and <dev> are absent:
    the dfu command to use multiple devices
    cmd: dfu 0 list
    cmd: dfu 0
   "dfu_alt_info" variable provides the list of <interface> <dev> with
   alternate list separated by '&' with the same format for each <alt>
       mmc <dev>=<alt1>;....;<altN>
       nand <dev>=<alt1>;....;<altN>
       ram <dev>=<alt1>;....;<altN>
       sf <dev>=<alt1>;....;<altN>
       mtd <dev>=<alt1>;....;<altN>
       virt <dev>=<alt1>;....;<altN>

Callbacks:
  The weak callback functions can be implemented to manage specific behavior
  - dfu_initiated_callback  : called when the DFU transaction is started,
                              used to initiase the device
  - dfu_flush_callback      : called at the end of the DFU write after DFU
                              manifestation, used to manage the device when
                              DFU transaction is closed

Host tools:
  When U-Boot runs the dfu stack, the DFU host tools can be used
  to send/receive firmwares on each configurated alternate.

  For example dfu-util is a host side implementation of the DFU 1.1
  specifications(http://dfu-util.sourceforge.net/) which works with U-Boot.

Usage:
  Example 1: firmware located in eMMC or SD card, with:
  - alternate 1 (alt=1) for SPL partition (GPT partition 1)
  - alternate 2 (alt=2) for U-Boot partition (GPT partition 2)

  The U-Boot configuration is:

  U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2"

  U-Boot> dfu 0 mmc 0 list
  DFU alt settings list:
  dev: eMMC alt: 0 name: spl layout: RAW_ADDR
  dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR

  Boot> dfu 0 mmc 0

  On the Host side:

  list the available alternate setting:

  $> dfu-util -l
  dfu-util 0.9

  Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
  Copyright 2010-2016 Tormod Volden and Stefan Schmidt
  This program is Free Software and has ABSOLUTELY NO WARRANTY
  Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

  Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
     alt=1, name="u-boot", serial="003A00203438510D36383238"
  Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
     alt=0, name="spl", serial="003A00203438510D36383238"

  To download to U-Boot, use -D option

  $> dfu-util -a 0 -D u-boot-spl.bin
  $> dfu-util -a 1 -D u-boot.bin

  To upload from U-Boot, use -U option

  $> dfu-util -a 0 -U u-boot-spl.bin
  $> dfu-util -a 1 -U u-boot.bin

  To request a DFU detach and reset the USB connection:
  $> dfu-util -a 0 -e  -R


  Example 2: firmware located in NOR (sf) and NAND, with:
  - alternate 1 (alt=1) for SPL partition (NOR GPT partition 1)
  - alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2)
  - alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3)
  - alternate 4 (alt=4) for UBI partition (NAND GPT partition 1)

  U-Boot> env set dfu_alt_info \
  "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \
  u-boot-env part 0 3&nand 0=UBI partubi 0,1"

  U-Boot> dfu 0 list

  DFU alt settings list:
  dev: SF alt: 0 name: spl layout: RAW_ADDR
  dev: SF alt: 1 name: ssbl layout: RAW_ADDR
  dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR
  dev: NAND alt: 3 name: UBI layout: RAW_ADDR

  U-Boot> dfu 0

  $> dfu-util -l
  Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
     intf=0, alt=3, name="UBI", serial="002700333338511934383330"
  Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
     intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330"
  Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
     intf=0, alt=1, name="u-boot", serial="002700333338511934383330"
  Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
     intf=0, alt=0, name="spl", serial="002700333338511934383330"

  Same example with MTD backend

   U-Boot> env set dfu_alt_info \
      "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\
      "mtd nand0=UBI partubi 1"

  U-Boot> dfu 0 list
  using id 'nor0,0'
  using id 'nor0,1'
  using id 'nor0,2'
  using id 'nand0,0'
  DFU alt settings list:
  dev: MTD alt: 0 name: spl layout: RAW_ADDR
  dev: MTD alt: 1 name: u-boot layout: RAW_ADDR
  dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR
  dev: MTD alt: 3 name: UBI layout: RAW_ADDR

  Example 3: firmware located in SD Card (mmc) and virtual partition on
             OTP and PMIC not volatile memory
  - alternate 1 (alt=1) for scard
  - alternate 2 (alt=2) for OTP (virtual)
  - alternate 3 (alt=3) for PMIC NVM (virtual)

   U-Boot> env set dfu_alt_info \
      "mmc 0=sdcard raw 0 0x100000&"\
      "virt 0=otp" \
      "virt 1=pmic"

   U-Boot> dfu 0 list
   DFU alt settings list:
   dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR
   dev: VIRT alt: 1 name: otp layout: RAW_ADDR
   dev: VIRT alt: 2 name: pmic layout: RAW_ADDR

# 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"

This feature does not depend on "fitupd" command enabled.

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


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

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


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

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

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

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

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

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

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



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

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

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

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

should look like

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

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



To do
-----

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

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

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

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

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

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

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.

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 booti command. It represents the location
  in RAM where the compressed Image will be decompressed temporarily. Once the
  decompression is complete, decompressed data will be moved 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.