doc: imx: reorganize i.MX documentation

Currently the U-Boot doc/ directory contains the following files
that are only relevant for i.MX devices:

- doc/README.imx25
- doc/README.imx27
- doc/README.imx5
- doc/README.imx6
- doc/README.imximage
- doc/README.mxc_hab
- doc/README.mxs
- doc/README.mxsimage
- doc/README.sdp

Move all content to a common i.MX folder for a better documentation
structure.

Signed-off-by: Breno Lima <breno.lima@nxp.com>

9 files changed, 1118 insertions, 0 deletions

diff --git a/doc/imx/README.imx25 b/doc/imx/README.imx25
new file mode 100644
index 0000000..0ca21b6
--- /dev/null
+++ b/doc/imx/README.imx25
@@ -0,0 +1,10 @@
+U-Boot for Freescale i.MX25
+
+This file contains information for the port of U-Boot to the Freescale i.MX25
+SoC.
+
+1. CONVENTIONS FOR FUSE ASSIGNMENTS
+-----------------------------------
+
+1.1 MAC Address: It is stored in the words 26 to 31 of fuse bank 0, using the
+    natural MAC byte order (i.e. MSB first).
diff --git a/doc/imx/README.imx27 b/doc/imx/README.imx27
new file mode 100644
index 0000000..6f92cb4
--- /dev/null
+++ b/doc/imx/README.imx27
@@ -0,0 +1,10 @@
+U-Boot for Freescale i.MX27
+
+This file contains information for the port of U-Boot to the Freescale i.MX27
+SoC.
+
+1. CONVENTIONS FOR FUSE ASSIGNMENTS
+-----------------------------------
+
+1.1 MAC Address: It is stored in the words 4 to 9 of fuse bank 0, using the
+    reversed MAC byte order (i.e. LSB first).
diff --git a/doc/imx/README.imx5 b/doc/imx/README.imx5
new file mode 100644
index 0000000..ea0e144
--- /dev/null
+++ b/doc/imx/README.imx5
@@ -0,0 +1,40 @@
+U-Boot for Freescale i.MX5x
+
+This file contains information for the port of U-Boot to the Freescale
+i.MX5x SoCs.
+
+1. CONFIGURATION OPTIONS/SETTINGS
+---------------------------------
+
+1.1 CONFIG_MX51_PLL_ERRATA: Workaround for i.MX51 PLL errata.
+    This option should be enabled by all boards using the i.MX51 silicon
+    version up until (including) 3.0 running at 800MHz.
+    The PLL's in the i.MX51 processor can go out of lock due to a metastable
+    condition in an analog flip-flop when used at high frequencies.
+    This workaround implements an undocumented feature in the PLL (dither
+    mode), which causes the effect of this failure to be much lower (in terms
+    of frequency deviation), avoiding system failure, or at least decreasing
+    the likelihood of system failure.
+
+1.2 CONFIG_SYS_MAIN_PWR_ON: Trigger MAIN_PWR_ON upon startup.
+    This option should be enabled for boards having a SYS_ON_OFF_CTL signal
+    connected to GPIO1[23] and triggering the MAIN_PWR_ON signal like in the
+    reference designs.
+
+2. CONVENTIONS FOR FUSE ASSIGNMENTS
+-----------------------------------
+
+2.1 MAC Address: It is stored in the words 9 to 14 of fuse bank 1, using the
+    natural MAC byte order (i.e. MSB first).
+
+    This is an example how to program an example MAC address 01:23:45:67:89:ab
+    into the eFuses. Assure that the programming voltage is available and then
+    execute:
+
+    => fuse prog -y 1 9 01 23 45 67 89 ab
+
+    After programming a MAC address, consider locking the MAC fuses. This is
+    done by programming the MAC_ADDR_LOCK fuse, which is bit 4 of word 0 in
+    bank 1:
+
+    => fuse prog -y 1 0 10
diff --git a/doc/imx/README.imx6 b/doc/imx/README.imx6
new file mode 100644
index 0000000..b0644f8
--- /dev/null
+++ b/doc/imx/README.imx6
@@ -0,0 +1,115 @@
+U-Boot for Freescale i.MX6
+
+This file contains information for the port of U-Boot to the Freescale i.MX6
+SoC.
+
+1. CONVENTIONS FOR FUSE ASSIGNMENTS
+-----------------------------------
+
+1.1 MAC Address: It is stored in fuse bank 4, with the 32 lsbs in word 2 and the
+    16 msbs in word 3[15:0].
+    For i.MX6SX and i.MX6UL, they have two MAC addresses. The second MAC address
+    is stored in fuse bank 4, with the 16 lsb in word 3[31:16] and the 32 msbs in 
+    word 4.
+
+Example:
+
+For reading the MAC address fuses on a MX6Q:
+
+- The MAC address is stored in two fuse addresses (the fuse addresses are
+described in the Fusemap Descriptions table from the mx6q Reference Manual):
+
+0x620[31:0] - MAC_ADDR[31:0]
+0x630[15:0] - MAC_ADDR[47:32]
+
+In order to use the fuse API, we need to pass the bank and word values, which
+are calculated as below:
+
+Fuse address for the lower MAC address: 0x620
+Base address for the fuses: 0x400
+
+(0x620 - 0x400)/0x10 = 0x22 = 34 decimal
+
+As the fuses are arranged in banks of 8 words:
+
+34 / 8 = 4 and the remainder is 2, so in this case:
+
+bank = 4
+word = 2
+
+And the U-Boot command would be:
+
+=> fuse read 4 2
+Reading bank 4:
+
+Word 0x00000002: 9f027772
+
+Doing the same for the upper MAC address:
+
+Fuse address for the upper MAC address: 0x630
+Base address for the fuses: 0x400
+
+(0x630 - 0x400)/0x10 = 0x23 = 35 decimal
+
+As the fuses are arranged in banks of 8 words:
+
+35 / 8 = 4 and the remainder is 3, so in this case:
+
+bank = 4
+word = 3
+
+And the U-Boot command would be:
+
+=> fuse read 4 3
+Reading bank 4:
+
+Word 0x00000003: 00000004
+
+,which matches the ethaddr value:
+=> echo ${ethaddr}
+00:04:9f:02:77:72
+
+Some other useful hints:
+
+- The 'bank' and 'word' numbers can be easily obtained from the mx6 Reference
+Manual. For the mx6quad case, please check the "46.5 OCOTP Memory Map/Register
+Definition" from the "i.MX 6Dual/6Quad Applications Processor Reference Manual,
+Rev. 1, 04/2013" document. For example, for the MAC fuses we have:
+
+Address:
+21B_C620	Value of OTP Bank4 Word2 (MAC Address)(OCOTP_MAC0)
+
+21B_C630	Value of OTP Bank4 Word3 (MAC Address)(OCOTP_MAC1)
+
+- The command '=> fuse read 4 2 2' reads the whole MAC addresses at once:
+
+=> fuse read 4 2 2
+Reading bank 4:
+
+Word 0x00000002: 9f027772 00000004
+
+2. Using imx_usb_loader for first install with SPL
+--------------------------------------------------
+
+imx_usb_loader is a very nice tool by Boundary Devices that
+allow to install U-Boot without a JTAG debugger, using
+the USB boot mode as described in the manual. It is
+a replacement for Freescale's MFGTOOLS.
+
+The sources can be found here:
+
+	https://github.com/boundarydevices/imx_usb_loader.git
+
+Booting in USB mode, the i.MX6 announces itself to the Linux Host as:
+
+Bus 001 Device 111: ID 15a2:0061 Freescale Semiconductor, Inc.
+
+imx_usb_loader is able to download a single file (u-boot.imx)
+to the board. For boards without SPL support, it is enough to
+issue the command:
+
+	sudo ../imx_usb_loader/imx_usb -v u-boot.imx
+
+In order to load SPL and u-boot.img via imx_usb_loader tool,
+please refer to doc/README.sdp.
+
diff --git a/doc/imx/README.imximage b/doc/imx/README.imximage
new file mode 100644
index 0000000..803682f
--- /dev/null
+++ b/doc/imx/README.imximage
@@ -0,0 +1,239 @@
+---------------------------------------------
+Imximage Boot Image generation using mkimage
+---------------------------------------------
+
+This document describes how to set up a U-Boot image that can be booted
+by Freescale MX25, MX35, MX51, MX53 and MX6 processors via internal boot
+mode.
+
+These processors can boot directly from NAND, SPI flash and SD card flash
+using its internal boot ROM support. MX6 processors additionally support
+boot from NOR flash and SATA disks. All processors can boot from an internal
+UART, if booting from device media fails.
+Booting from NOR flash does not require to use this image type.
+
+For more details refer Chapter 2 - System Boot and section 2.14
+(flash header description) of the processor's manual.
+
+Command syntax:
+--------------
+./tools/mkimage -l <mx u-boot_file>
+		to list the imx image file details
+
+./tools/mkimage -T imximage \
+		-n <board specific configuration file> \
+		-e <execution address> -d <u-boot binary>  <output image file>
+
+For example, for the mx51evk board:
+./tools/mkimage -n ./board/freescale/mx51evk/imximage.cfg \
+		-T imximage -e 0x97800000  \
+		-d u-boot.bin u-boot.imx
+
+You can generate directly the image when you compile u-boot with:
+
+$ make u-boot.imx
+
+The output image can be flashed on the board SPI flash or on a SD card.
+In both cases, you have to copy the image at the offset required for the
+chosen media devices (0x400 for both SPI flash or SD card).
+
+Please check Freescale documentation for further details.
+
+Board specific configuration file specifications:
+-------------------------------------------------
+1. This file must present in the $(BOARDDIR) and the name should be
+	imximage.cfg (since this is used in Makefile).
+2. This file can have empty lines and lines starting with "#" as first
+	character to put comments.
+3. This file can have configuration command lines as mentioned below,
+	any other information in this file is treated as invalid.
+
+Configuration command line syntax:
+---------------------------------
+1. Each command line is must have two strings, first one command or address
+	and second one data string
+2. Following are the valid command strings and associated data strings:-
+	Command string		data string
+	--------------		-----------
+	IMXIMAGE_VERSION        1/2
+				1 is for mx25/mx35/mx51 compatible,
+				2 is for mx53/mx6 compatible,
+				others is invalid and error is generated.
+				This command need appear the fist before
+				other valid commands in configuration file.
+
+	BOOT_OFFSET		value
+
+				This command is parallel to BOOT_FROM and
+				is preferred over BOOT_FROM.
+
+				value:  Offset of the image header, this
+					value shall be set to one of the
+					values found in the file:
+						arch/arm/include/asm/\
+						mach-imx/imximage.cfg
+				Example:
+				BOOT_OFFSET FLASH_OFFSET_STANDARD
+
+	BOOT_FROM		nand/spi/sd/onenand/nor/sata
+
+				This command is parallel to BOOT_OFFSET and
+				is to be deprecated in favor of BOOT_OFFSET.
+
+				Example:
+				BOOT_FROM spi
+
+	CSF			value
+
+				Total size of CSF (Command Sequence File)
+				used for Secure Boot/ High Assurance Boot
+				(HAB).
+
+				Using this command will populate the IVT
+				(Initial Vector Table) CSF pointer and adjust
+				the length fields only. The CSF itself needs
+				to be generated with Freescale tools and
+				'manually' appended to the u-boot.imx file.
+
+				The CSF is then simply concatenated
+				to the u-boot image, making a signed bootloader,
+				that the processor can verify
+				if the fuses for the keys are burned.
+
+				Further infos how to configure the SOC to verify
+				the bootloader can be found in the "High
+				Assurance Boot Version Application Programming
+				Interface Reference Manual" as part of the
+				Freescale Code Signing Tool, available on the
+				manufacturer's website.
+
+				Example:
+				CSF 0x2000
+
+	DATA			type address value
+
+				type: word=4, halfword=2, byte=1
+				address: physycal register address
+				value: value to be set in register
+				All values are in in hexadecimal.
+				Example (write to IOMUXC):
+				DATA 4 0x73FA88a0 0x200
+
+The processor support up to 60 register programming commands for IMXIMAGE_VERSION 1
+and 220 register programming commands for IMXIMAGE_VERSION 2.
+An error is generated if more commands are found in the configuration file.
+
+3. All commands are optional to program.
+
+Setup a SD Card for booting
+--------------------------------
+
+The following example prepare a SD card with u-boot and a FAT partition
+to be used to stored the kernel to be booted.
+I will set the SD in the most compatible mode, setting it with
+255 heads and 63 sectors, as suggested from several documentation and
+howto on line (I took as reference the preparation of a SD Card for the
+Beagleboard, running u-boot as bootloader).
+
+You should start clearing the partitions table on the SD card. Because
+the u-boot image must be stored at the offset 0x400, it must be assured
+that there is no partition at that address. A new SD card is already
+formatted with FAT filesystem and the partition starts from the first
+cylinder, so we need to change it.
+
+You can do all steps with fdisk. If the device for the SD card is
+/dev/mmcblk0, the following commands make the job:
+
+1. Start the fdisk utility (as superuser)
+	fdisk /dev/mmcblk0
+
+2. Clear the actual partition
+
+Command (m for help): o
+
+3. Print card info:
+
+Command (m for help): p
+Disk /dev/mmcblk0: 1981 MB, 1981284352 bytes
+
+In my case, I have a 2 GB card. I need the size to set later the correct value
+for the cylinders.
+
+4. Go to expert mode:
+
+Command (m for help): x
+
+5. Set card geometry
+
+Expert command (m for help): h
+Number of heads (1-256, default 4): 255
+
+Expert command (m for help): s
+Number of sectors (1-63, default 16): 63
+Warning: setting sector offset for DOS compatiblity
+
+We have set 255 heads, 63 sector. We have to set the cylinder.
+The value to be set can be calculated with:
+
+	cilynder = <total size> / <heads> / <sectors> / <blocksize>
+
+in this example,
+	1981284352 / 255 / 63 / 512 = 239.x = 239
+
+
+Expert command (m for help): c
+Number of cylinders (1-1048576, default 60032): 239
+
+6. Leave the expert mode
+Expert command (m for help): r
+
+7. Set up a partition
+
+Now set a partition table to store the kernel or whatever you want. Of course,
+you can set additional partitions to store rootfs, data, etc.
+In my example I want to set a single partition. I must take care
+to not overwrite the space where I will put u-boot.
+
+Command (m for help): n
+Command action
+   e   extended
+   p   primary partition (1-4)
+p
+Partition number (1-4): 1
+First cylinder (1-239, default 1): 3
+Last cylinder, +cylinders or +size{K,M,G} (3-239, default 239): +100M
+
+Command (m for help): p
+
+Disk /dev/mmcblk0: 1967 MB, 1967128576 bytes
+255 heads, 63 sectors/track, 239 cylinders
+Units = cylinders of 16065 * 512 = 8225280 bytes
+Disk identifier: 0xb712a870
+
+	Device Boot	 Start	       End	Blocks	 Id  System
+/dev/mmcblk0p1		     3		16	112455	 83  Linux
+
+I have set 100MB, leaving the first 2 sectors free. I will copy u-boot
+there.
+
+8. Write the partition table and exit.
+
+Command (m for help): w
+The partition table has been altered!
+
+Calling ioctl() to re-read partition table.
+
+9. Copy u-boot.imx on the SD card
+
+I use dd:
+
+dd if=u-boot.imx of=/dev/mmcblk0 bs=512 seek=2
+
+This command copies the u-boot image at the address 0x400, as required
+by the processor.
+
+Now remove your card from the PC and go to the target. If evrything went right,
+the u-boot prompt should come after power on.
+
+------------------------------------------------
+Author: Stefano babic <sbabic@denx.de>
diff --git a/doc/imx/README.mxc_hab b/doc/imx/README.mxc_hab
new file mode 100644
index 0000000..a40ebf3
--- /dev/null
+++ b/doc/imx/README.mxc_hab
@@ -0,0 +1,144 @@
+1. High Assurance Boot (HAB) for i.MX CPUs
+------------------------------------------
+
+To enable the authenticated or encrypted boot mode of U-Boot, it is
+required to set the proper configuration for the target board. This
+is done by adding the following configuration in the defconfig file:
+
+CONFIG_SECURE_BOOT=y
+
+In addition, the U-Boot image to be programmed into the
+boot media needs to be properly constructed, i.e. it must contain a
+proper Command Sequence File (CSF).
+
+The CSF itself is generated by the i.MX High Assurance Boot Reference
+Code Signing Tool.
+https://www.nxp.com/webapp/sps/download/license.jsp?colCode=IMX_CST_TOOL
+
+More information about the CSF and HAB can be found in the AN4581.
+https://www.nxp.com/docs/en/application-note/AN4581.pdf
+
+We don't want to explain how to create a PKI tree or SRK table as
+this is well explained in the Application Note.
+
+2. Secure Boot on non-SPL targets
+---------------------------------
+
+On non-SPL targets a singe U-Boot binary is generated, mkimage will
+output additional information about "HAB Blocks" which can be used
+in the CST to authenticate the U-Boot image (entries in the CSF file).
+
+Image Type:   Freescale IMX Boot Image
+Image Ver:    2 (i.MX53/6 compatible)
+Data Size:    327680 Bytes = 320.00 kB = 0.31 MB
+Load Address: 177ff420
+Entry Point:  17800000
+HAB Blocks:   0x177ff400 0x00000000 0x0004dc00
+	      ^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^
+		|	   |	      |
+		|	   |	      ----- (1)
+		|	   |
+		|	   ---------------- (2)
+		|
+		--------------------------- (3)
+
+(1)	Size of area in file u-boot-dtb.imx to sign
+	This area should include the IVT, the Boot Data the DCD
+	and U-Boot itself.
+(2)	Start of area in u-boot-dtb.imx to sign
+(3)	Start of area in RAM to authenticate
+
+CONFIG_SECURE_BOOT currently enables only an additional command
+'hab_status' in U-Boot to retrieve the HAB status and events. This
+can be useful while developing and testing HAB.
+
+Commands to generate a signed U-Boot using i.MX HAB CST tool:
+# Compile CSF and create signature
+cst --o csf-u-boot.bin --i command_sequence_uboot.csf
+# Append compiled CSF to Binary
+cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx
+
+3. Secure Boot on SPL targets
+-----------------------------
+
+This version of U-Boot is able to build a signable version of the SPL
+as well as a signable version of the U-Boot image. The signature can
+be verified through High Assurance Boot (HAB).
+
+After building, you need to create a command sequence file and use
+i.MX HAB Code Signing Tool to sign both binaries. After creation,
+the mkimage tool outputs the required information about the HAB Blocks
+parameter for the CSF. During the build, the information is preserved
+in log files named as the binaries. (SPL.log and u-boot-ivt.log).
+
+Example Output of the SPL (imximage) creation:
+ Image Type:   Freescale IMX Boot Image
+ Image Ver:    2 (i.MX53/6/7 compatible)
+ Mode:         DCD
+ Data Size:    61440 Bytes = 60.00 kB = 0.06 MB
+ Load Address: 00907420
+ Entry Point:  00908000
+ HAB Blocks:   0x00907400 0x00000000 0x0000cc00
+
+Example Output of the u-boot-ivt.img (firmware_ivt) creation:
+ Image Name:   U-Boot 2016.11-rc1-31589-g2a4411
+ Created:      Sat Nov  5 21:53:28 2016
+ Image Type:   ARM U-Boot Firmware with HABv4 IVT (uncompressed)
+ Data Size:    352192 Bytes = 343.94 kB = 0.34 MB
+ Load Address: 17800000
+ Entry Point:  00000000
+ HAB Blocks:   0x177fffc0   0x0000   0x00054020
+
+# Compile CSF and create signature
+cst --o csf-u-boot.bin --i command_sequence_uboot.csf
+cst --o csf-SPL.bin --i command_sequence_spl.csf
+# Append compiled CSF to Binary
+cat SPL csf-SPL.bin > SPL-signed
+cat u-boot-ivt.img csf-u-boot.bin > u-boot-signed.img
+
+These two signed binaries can be used on an i.MX in closed
+configuration when the according SRK Table Hash has been flashed.
+
+4. Setup U-Boot Image for Encrypted Boot
+----------------------------------------
+An authenticated U-Boot image is used as starting point for
+Encrypted Boot. The image is encrypted by i.MX Code Signing
+Tool (CST). The CST replaces only the image data of
+u-boot-dtb.imx with the encrypted data. The Initial Vector Table,
+DCD, and Boot data, remains in plaintext.
+
+The image data is encrypted with a Encryption Key (DEK).
+Therefore, this key is needed to decrypt the data during the
+booting process. The DEK is protected by wrapping it in a Blob,
+which needs to be appended to the U-Boot image and specified in
+the CSF file.
+
+The DEK blob is generated by an authenticated U-Boot image with
+the dek_blob cmd enabled. The image used for DEK blob generation
+needs to have the following configurations enabled in Kconfig:
+
+CONFIG_SECURE_BOOT=y
+CONFIG_CMD_DEKBLOB=y
+
+Note: The encrypted boot feature is only supported by HABv4 or
+greater.
+
+The dek_blob command then can be used to generate the DEK blob of
+a DEK previously loaded in memory. The command is used as follows:
+
+dek_blob <DEK address> <Output Address> <Key Size in Bits>
+example: dek_blob 0x10800000 0x10801000 192
+
+The resulting DEK blob then is used to construct the encrypted
+U-Boot image. Note that the blob needs to be transferred back
+to the host.Then the following commands are used to construct
+the final image.
+
+cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx
+objcopy -I binary -O binary --pad-to <blob_dst> --gap-fill=0x00 \
+    u-boot-signed.imx u-boot-signed-pad.bin
+cat u-boot-signed-pad.imx DEK_blob.bin > u-boot-encrypted.imx
+
+    NOTE: u-boot-signed.bin needs to be padded to the value
+    equivalent to the address in which the DEK blob is specified
+    in the CSF.
diff --git a/doc/imx/README.mxs b/doc/imx/README.mxs
new file mode 100644
index 0000000..e23ab9c
--- /dev/null
+++ b/doc/imx/README.mxs
@@ -0,0 +1,290 @@
+Booting U-Boot on a MXS processor
+=================================
+
+This document describes the MXS U-Boot port. This document mostly covers topics
+related to making the module/board bootable.
+
+Terminology
+-----------
+
+The term "MXS" refers to a family of Freescale SoCs that is composed by MX23
+and MX28.
+
+The dollar symbol ($) introduces a snipped of shell code. This shall be typed
+into the unix command prompt in U-Boot source code root directory.
+
+The (=>) introduces a snipped of code that should by typed into U-Boot command
+prompt
+
+Contents
+--------
+
+1) Prerequisites
+2) Compiling U-Boot for a MXS based board
+3) Installation of U-Boot for a MXS based board to SD card
+4) Installation of U-Boot into NAND flash on a MX28 based board
+5) Installation of U-Boot into SPI NOR flash on a MX28 based board
+
+1) Prerequisites
+----------------
+
+To make a MXS based board bootable, some tools are necessary. The only
+mandatory tool is the "mxsboot" tool found in U-Boot source tree. The
+tool is built automatically when compiling U-Boot for i.MX23 or i.MX28.
+
+The production of BootStream image is handled via "mkimage", which is
+also part of the U-Boot source tree. The "mkimage" requires OpenSSL
+development libraries to be installed. In case of Debian and derivates,
+this is installed by running:
+
+	$ sudo apt-get install libssl-dev
+
+NOTE: The "elftosb" tool distributed by Freescale Semiconductor is no
+      longer necessary for general use of U-Boot on i.MX23 and i.MX28.
+      The mkimage supports generation of BootStream images encrypted
+      with a zero key, which is the vast majority of use-cases. In
+      case you do need to produce image encrypted with non-zero key
+      or other special features, please use the "elftosb" tool,
+      otherwise continue to section 2). The installation procedure of
+      the "elftosb" is outlined below:
+
+Firstly, obtain the elftosb archive from the following location:
+
+	ftp://ftp.denx.de/pub/tools/elftosb-10.12.01.tar.gz
+
+We use a $VER variable here to denote the current version. At the time of
+writing of this document, that is "10.12.01". To obtain the file from command
+line, use:
+
+	$ VER="10.12.01"
+	$ wget ftp://ftp.denx.de/pub/tools/elftosb-${VER}.tar.gz
+
+Extract the file:
+
+	$ tar xzf elftosb-${VER}.tar.gz
+
+Compile the file. We need to manually tell the linker to use also libm:
+
+	$ cd elftosb-${VER}/
+	$ make LIBS="-lstdc++ -lm" elftosb
+
+Optionally, remove debugging symbols from elftosb:
+
+	$ strip bld/linux/elftosb
+
+Finally, install the "elftosb" binary. The "install" target is missing, so just
+copy the binary by hand:
+
+	$ sudo cp bld/linux/elftosb /usr/local/bin/
+
+Make sure the "elftosb" binary can be found in your $PATH, in this case this
+means "/usr/local/bin/" has to be in your $PATH.
+
+2) Compiling U-Boot for a MXS based board
+-------------------------------------------
+
+Compiling the U-Boot for a MXS board is straightforward and done as compiling
+U-Boot for any other ARM device. For cross-compiler setup, please refer to
+ELDK5.0 documentation. First, clean up the source code:
+
+	$ make mrproper
+
+Next, configure U-Boot for a MXS based board
+
+	$ make <mxs_based_board_name>_config
+
+Examples:
+
+1. For building U-Boot for Aries M28EVK board:
+
+	$ make m28evk_config
+
+2. For building U-Boot for Freescale MX28EVK board:
+
+	$ make mx28evk_config
+
+3. For building U-Boot for Freescale MX23EVK board:
+
+	$ make mx23evk_config
+
+4. For building U-Boot for Olimex MX23 Olinuxino board:
+
+	$ make mx23_olinuxino_config
+
+Lastly, compile U-Boot and prepare a "BootStream". The "BootStream" is a special
+type of file, which MXS CPUs can boot. This is handled by the following
+command:
+
+	$ make u-boot.sb
+
+HINT: To speed-up the build process, you can add -j<N>, where N is number of
+      compiler instances that'll run in parallel.
+
+The code produces "u-boot.sb" file. This file needs to be augmented with a
+proper header to allow successful boot from SD or NAND. Adding the header is
+discussed in the following chapters.
+
+NOTE: The process that produces u-boot.sb uses the mkimage to generate the
+      BootStream. The BootStream is encrypted with zero key. In case you need
+      some special features of the BootStream and plan on using the "elftosb"
+      tool instead, the invocation to produce a compatible BootStream with the
+      one produced by mkimage is outlined below. For further details, refer to
+      the documentation bundled with the "elftosb" package.
+
+	$ elftosb -zf imx23 -c arch/arm/cpu/arm926ejs/mxs/u-boot-imx23.bd \
+		-o u-boot.sb
+	$ elftosb -zf imx28 -c arch/arm/cpu/arm926ejs/mxs/u-boot-imx28.bd \
+		-o u-boot.sb
+
+3) Installation of U-Boot for a MXS based board to SD card
+----------------------------------------------------------
+
+To boot a MXS based board from SD, set the boot mode DIP switches according to
+to MX28 manual, section 12.2.1 (Table 12-2) or MX23 manual, section 35.1.2
+(Table 35-3).
+
+The SD card used to boot U-Boot must contain a DOS partition table, which in
+turn carries a partition of special type and which contains a special header.
+The rest of partitions in the DOS partition table can be used by the user.
+
+To prepare such partition, use your favourite partitioning tool. The partition
+must have the following parameters:
+
+	* Start sector .......... sector 2048
+	* Partition size ........ at least 1024 kb
+	* Partition type ........ 0x53 (sometimes "OnTrack DM6 Aux3")
+
+For example in Linux fdisk, the sequence for a clear card follows. Be sure to
+run fdisk with the option "-u=sectors" to set units to sectors:
+
+	* o ..................... create a clear partition table
+	* n ..................... create new partition
+		* p ............. primary partition
+		* 1 ............. first partition
+		* 2048 .......... first sector is 2048
+		* +1M ........... make the partition 1Mb big
+	* t 1 ................... change first partition ID
+		* 53 ............ change the ID to 0x53 (OnTrack DM6 Aux3)
+	* <create other partitions>
+	* w ..................... write partition table to disk
+
+The partition layout is ready, next the special partition must be filled with
+proper contents. The contents is generated by running the following command
+(see chapter 2)):
+
+	$ ./tools/mxsboot sd u-boot.sb u-boot.sd
+
+The resulting file, "u-boot.sd", shall then be written to the partition. In this
+case, we assume the first partition of the SD card is /dev/mmcblk0p1:
+
+	$ dd if=u-boot.sd of=/dev/mmcblk0p1
+
+Last step is to insert the card into the MXS based board and boot.
+
+NOTE: If the user needs to adjust the start sector, the "mxsboot" tool contains
+      a "-p" switch for that purpose. The "-p" switch takes the sector number as
+      an argument.
+
+4) Installation of U-Boot into NAND flash on a MX28 based board
+---------------------------------------------------------------
+
+To boot a MX28 based board from NAND, set the boot mode DIP switches according
+to MX28 manual section 12.2.1 (Table 12-2), PORT=GPMI, NAND 1.8 V.
+
+There are two possibilities when preparing an image writable to NAND flash.
+
+	I) The NAND wasn't written at all yet or the BCB is broken
+	----------------------------------------------------------
+	   In this case, both BCB (FCB and DBBT) and firmware needs to be
+	   written to NAND. To generate NAND image containing all these,
+	   there is a tool called "mxsboot" in the "tools/" directory. The tool
+	   is invoked on "u-boot.sb" file from chapter 2):
+
+		 $ ./tools/mxsboot nand u-boot.sb u-boot.nand
+
+	   NOTE: The above invokation works for NAND flash with geometry of
+		 2048b per page, 64b OOB data, 128kb erase size. If your chip
+		 has a different geometry, please use:
+
+		 -w <size>	change page size (default 2048 b)
+		 -o <size>	change oob size (default 64 b)
+		 -e <size>	change erase size (default 131072 b)
+
+		 The geometry information can be obtained from running U-Boot
+		 on the MX28 board by issuing the "nand info" command.
+
+	   The resulting file, "u-boot.nand" can be written directly to NAND
+	   from the U-Boot prompt. To simplify the process, the U-Boot default
+	   environment contains script "update_nand_full" to update the system.
+
+	   This script expects a working TFTP server containing the file
+	   "u-boot.nand" in it's root directory. This can be changed by
+	   adjusting the "update_nand_full_filename" variable.
+
+	   To update the system, run the following in U-Boot prompt:
+
+		 => run update_nand_full
+
+	   In case you would only need to update the bootloader in future,
+	   see II) below.
+
+	II) The NAND was already written with a good BCB
+	------------------------------------------------
+	   This part applies after the part I) above was done at least once.
+
+	   If part I) above was done correctly already, there is no need to
+	   write the FCB and DBBT parts of NAND again. It's possible to upgrade
+	   only the bootloader image.
+
+	   To simplify the process of firmware update, the U-Boot default
+	   environment contains script "update_nand_firmware" to update only
+	   the firmware, without rewriting FCB and DBBT.
+
+	   This script expects a working TFTP server containing the file
+	   "u-boot.sb" in it's root directory. This can be changed by
+	   adjusting the "update_nand_firmware_filename" variable.
+
+	   To update the system, run the following in U-Boot prompt:
+
+		 => run update_nand_firmware
+
+	III) Special settings for the update scripts
+	--------------------------------------------
+	   There is a slight possibility of the user wanting to adjust the
+	   STRIDE and COUNT options of the NAND boot. For description of these,
+	   see MX28 manual section 12.12.1.2 and 12.12.1.3.
+
+	   The update scripts take this possibility into account. In case the
+	   user changes STRIDE by blowing fuses, the user also has to change
+	   "update_nand_stride" variable. In case the user changes COUNT by
+	   blowing fuses, the user also has to change "update_nand_count"
+	   variable for the update scripts to work correctly.
+
+	   In case the user needs to boot a firmware image bigger than 1Mb, the
+	   user has to adjust the "update_nand_firmware_maxsz" variable for the
+	   update scripts to work properly.
+
+5) Installation of U-Boot into SPI NOR flash on a MX28 based board
+------------------------------------------------------------------
+
+The u-boot.sb file can be directly written to SPI NOR from U-Boot prompt.
+
+Load u-boot.sb into RAM, this can be done in several ways and one way is to use
+tftp:
+       => tftp u-boot.sb 0x42000000
+
+Probe the SPI NOR flash:
+       => sf probe
+
+(SPI NOR should be succesfully detected in this step)
+
+Erase the blocks where U-Boot binary will be written to:
+       => sf erase 0x0 0x80000
+
+Write u-boot.sb to SPI NOR:
+       => sf write 0x42000000 0 0x80000
+
+Power off the board and set the boot mode DIP switches to boot from the SPI NOR
+according to MX28 manual section 12.2.1 (Table 12-2)
+
+Last step is to power up the board and U-Boot should start from SPI NOR.
diff --git a/doc/imx/README.mxsimage b/doc/imx/README.mxsimage
new file mode 100644
index 0000000..c3975ee
--- /dev/null
+++ b/doc/imx/README.mxsimage
@@ -0,0 +1,170 @@
+Freescale i.MX233/i.MX28 SB image generator via mkimage
+=======================================================
+
+This tool allows user to produce SB BootStream encrypted with a zero key.
+Such a BootStream is then bootable on i.MX23/i.MX28.
+
+Usage -- producing image:
+=========================
+The mxsimage tool is targeted to be a simple replacement for the elftosb2 .
+To generate an image, write an image configuration file and run:
+
+ mkimage -A arm -O u-boot -T mxsimage -n <path to configuration file> \
+	 <output bootstream file>
+
+The output bootstream file is usually using the .sb file extension. Note
+that the example configuration files for producing bootable BootStream with
+the U-Boot bootloader can be found under arch/arm/boot/cpu/arm926ejs/mxs/
+directory. See the following files:
+
+ mxsimage.mx23.cfg -- This is an example configuration for i.MX23
+ mxsimage.mx28.cfg -- This is an example configuration for i.MX28
+
+Each configuration file uses very simple instruction semantics and a few
+additional rules have to be followed so that a useful image can be produced.
+These semantics and rules will be outlined now.
+
+- Each line of the configuration file contains exactly one instruction.
+- Every numeric value must be encoded in hexadecimal and in format 0xabcdef12 .
+- The configuration file is a concatenation of blocks called "sections" and
+  optionally "DCD blocks" (see below), and optional flags lines.
+  - Each "section" is started by the "SECTION" instruction.
+  - The "SECTION" instruction has the following semantics:
+
+      SECTION u32_section_number [BOOTABLE]
+      - u32_section_number :: User-selected ID of the section
+      - BOOTABLE           :: Sets the section as bootable
+
+  - A bootable section is one from which the BootROM starts executing
+    subsequent instructions or code. Exactly one section must be selected
+    as bootable, usually the one containing the instructions and data to
+    load the bootloader.
+
+  - A "SECTION" must be immediatelly followed by a "TAG" instruction.
+  - The "TAG" instruction has the following semantics:
+
+      TAG [LAST]
+      - LAST               :: Flag denoting the last section in the file
+
+  - After a "TAG" unstruction, any of the following instructions may follow
+    in any order and any quantity:
+
+      NOOP
+      - This instruction does nothing
+
+      LOAD     u32_address string_filename
+      - Instructs the BootROM to load file pointed by "string_filename" onto
+	address "u32_address".
+
+      LOAD IVT u32_address u32_IVT_entry_point
+      - Crafts and loads IVT onto address "u32_address" with the entry point
+	of u32_IVT_entry_point.
+      - i.MX28-specific instruction!
+
+      LOAD DCD u32_address u32_DCD_block_ID
+      - Loads the DCD block with ID "u32_DCD_block_ID" onto address
+	"u32_address" and executes the contents of this DCD block
+      - i.MX28-specific instruction!
+
+      FILL u32_address u32_pattern u32_length
+      - Starts to write memory from addres "u32_address" with a pattern
+	specified by "u32_pattern". Writes exactly "u32_length" bytes of the
+	pattern.
+
+      JUMP [HAB] u32_address [u32_r0_arg]
+      - Jumps onto memory address specified by "u32_address" by setting this
+	address in PT. The BootROM will pass the "u32_r0_arg" value in ARM
+	register "r0" to the executed code if this option is specified.
+	Otherwise, ARM register "r0" will default to value 0x00000000. The
+	optional "HAB" flag is i.MX28-specific flag turning on the HAB boot.
+
+      CALL [HAB] u32_address [u32_r0_arg]
+      - See JUMP instruction above, as the operation is exactly the same with
+	one difference. The CALL instruction does allow returning into the
+	BootROM from the executed code. U-Boot makes use of this in it's SPL
+	code.
+
+      MODE string_mode
+      - Restart the CPU and start booting from device specified by the
+	"string_mode" argument. The "string_mode" differs for each CPU
+	and can be:
+	 i.MX23, string_mode = USB/I2C/SPI1_FLASH/SPI2_FLASH/NAND_BCH
+			       JTAG/SPI3_EEPROM/SD_SSP0/SD_SSP1
+	 i.MX28, string_mode = USB/I2C/SPI2_FLASH/SPI3_FLASH/NAND_BCH
+			       JTAG/SPI2_EEPROM/SD_SSP0/SD_SSP1
+
+  - An optional "DCD" blocks can be added at the begining of the configuration
+    file. Note that the DCD is only supported on i.MX28.
+    - The DCD blocks must be inserted before the first "section" in the
+      configuration file.
+    - The DCD block has the following semantics:
+
+	DCD u32_DCD_block_ID
+	- u32_DCD_block_ID	:: The ID number of the DCD block, must match
+				   the ID number used by "LOAD DCD" instruction.
+
+    - The DCD block must be followed by one of the following instructions. All
+      of the instructions operate either on 1, 2 or 4 bytes. This is selected by
+      the 'n' suffix of the instruction:
+
+	WRITE.n u32_address u32_value
+	- Write the "u32_value" to the "u32_address" address.
+
+	ORR.n u32_address u32_value
+	- Read the "u32_address", perform a bitwise-OR with the "u32_value" and
+	  write the result back to "u32_address".
+
+	ANDC.n u32_address u32_value
+	- Read the "u32_address", perform a bitwise-AND with the complement of
+	  "u32_value" and write the result back to "u32_address".
+
+	EQZ.n u32_address u32_count
+	- Read the "u32_address" at most "u32_count" times and test if the value
+	  read is zero. If it is, break the loop earlier.
+
+	NEZ.n u32_address u32_count
+	- Read the "u32_address" at most "u32_count" times and test if the value
+	  read is non-zero. If it is, break the loop earlier.
+
+	EQ.n u32_address u32_mask
+	- Read the "u32_address" in a loop and test if the result masked with
+	  "u32_mask" equals the "u32_mask". If the values are equal, break the
+	  reading loop.
+
+	NEQ.n u32_address u32_mask
+	- Read the "u32_address" in a loop and test if the result masked with
+	  "u32_mask" does not equal the "u32_mask". If the values are not equal,
+	  break the reading loop.
+
+	NOOP
+	- This instruction does nothing.
+
+  - An optional flags lines can be one of the following:
+
+	DISPLAYPROGRESS
+	- Enable boot progress output form the BootROM.
+
+- If the boot progress output from the BootROM is enabled, the BootROM will
+  produce a letter on the Debug UART for each instruction it started processing.
+  Here is a mapping between the above instructions and the BootROM output:
+
+   H -- SB Image header loaded
+   T -- TAG instruction
+   N -- NOOP instruction
+   L -- LOAD instruction
+   F -- FILL instruction
+   J -- JUMP instruction
+   C -- CALL instruction
+   M -- MODE instruction
+
+Usage -- verifying image:
+=========================
+
+The mxsimage can also verify and dump contents of an image. Use the following
+syntax to verify and dump contents of an image:
+
+ mkimage -l <input bootstream file>
+
+This will output all the information from the SB image header and all the
+instructions contained in the SB image. It will also check if the various
+checksums in the SB image are correct.
diff --git a/doc/imx/README.sdp b/doc/imx/README.sdp
new file mode 100644
index 0000000..178ea68
--- /dev/null
+++ b/doc/imx/README.sdp
@@ -0,0 +1,100 @@
+-------------
+SDP in U-Boot
+-------------
+
+SDP stands for serial download protocol. It is the protocol used in NXP's
+i.MX SoCs ROM Serial Downloader and provides means to download a program
+image to the chip over USB and UART serial connection.
+
+The implementation in U-Boot uses the USB Downloader Gadget (g_dnl) to
+provide a SDP implementation over USB. This allows to download program
+images to the target in SPL/U-Boot using the same protocol/tooling the
+SoC's recovery mechanism is using.
+
+The SDP protocol over USB is a USB HID class protocol. USB HID class
+protocols allow to access a USB device without OS specific drivers. The
+U-Boot implementation has primarly been tested using the open source
+imx_loader utility (https://github.com/boundarydevices/imx_usb_loader).
+
+The host side utilities are typically capable to interpret the i.MX
+specific image header (see doc/README.imximage). There are extensions
+for imx_loader's imx_usb utility which allow to interpret the U-Boot
+specific legacy image format (see mkimage(1)). Also the U-Boot side
+support beside the i.MX specific header the U-Boot legacy header.
+
+Usage
+-----
+
+This implementation can be started in U-Boot using the sdp command
+(CONFIG_CMD_USB_SDP) or in SPL if Serial Downloader boot mode has been
+detected (CONFIG_SPL_USB_SDP_SUPPORT).
+
+A typical use case is downloading full U-Boot after SPL has been
+downloaded through the boot ROM's Serial Downloader. Using boot mode
+detection the SPL will run the SDP implementation automatically in
+this case:
+
+  # imx_usb SPL
+
+Targets Serial Console:
+
+  Trying to boot from USB SDP
+  SDP: initialize...
+  SDP: handle requests...
+
+At this point the SPL reenumerated as a new HID device and emulating
+the boot ROM's SDP protocol. The USB VID/PID will depend on standard
+U-Boot configurations CONFIG_G_DNL_(VENDOR|PRODUCT)_NUM. Make sure
+imx_usb is aware of the USB VID/PID for your device by adding a
+configuration entry in imx_usb.conf:
+
+  0x1b67:0x4fff, mx6_usb_sdp_spl.conf
+
+And the device specific configuration file mx6_usb_sdp_spl.conf:
+
+  mx6_spl_sdp
+  hid,uboot_header,1024,0x910000,0x10000000,1G,0x00900000,0x40000
+
+This allows to download the regular U-Boot with legacy image headers
+(u-boot.img) using a second invocation of imx_usb:
+
+  # imx_usb u-boot.img
+
+Furthermore, when U-Boot is running the sdp command can be used to
+download and run scripts:
+
+  # imx_usb script.scr
+
+imx_usb configuration files can be also used to download multiple
+files and of arbitrary types, e.g.
+
+  mx6_usb_sdp_uboot
+  hid,1024,0x10000000,1G,0x00907000,0x31000
+  full.itb:load 0x12100000
+  boot.scr:load 0x12000000,jump 0x12000000
+
+There is also a batch mode which allows imx_usb to handle multiple
+consecutive reenumerations by adding multiple VID/PID specifications
+in imx_usb.conf:
+
+  0x15a2:0x0061, mx6_usb_rom.conf, 0x1b67:0x4fff, mx6_usb_sdp_spl.conf
+
+In this mode the file to download (imx_usb job) needs to be specified
+in the configuration files.
+
+mx6_usb_rom.conf:
+
+  mx6_qsb
+  hid,1024,0x910000,0x10000000,1G,0x00900000,0x40000
+  SPL:jump header2
+
+mx6_usb_sdp_spl.conf:
+
+  mx6_spl_sdp
+  hid,uboot_header,1024,0x10000000,1G,0x00907000,0x31000
+  u-boot.img:jump header2
+
+With that SPL and U-Boot can be downloaded with a single invocation
+of imx_usb without arguments:
+
+  # imx_usb