[U-Boot] mx23: Add a README file

From: Fabio Estevam <fabio.estevam@freescale.com>

Provide instructions on how to build U-boot and flash the binary into an SD card
for a mx23 based platform.

Signed-off-by: Fabio Estevam <fabio.estevam@freescale.com>
---
 doc/README.mx23_common |  145 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 145 insertions(+)
 create mode 100644 doc/README.mx23_common

Dear Fabio Estevam,

> From: Fabio Estevam <fabio.estevam@freescale.com>
> 
> Provide instructions on how to build U-boot and flash the binary into an SD
> card for a mx23 based platform.

Can most of this not be shared with MX28 ?

> Signed-off-by: Fabio Estevam <fabio.estevam@freescale.com>
> ---
>  doc/README.mx23_common |  145
> ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145
> insertions(+)
>  create mode 100644 doc/README.mx23_common
> 
> diff --git a/doc/README.mx23_common b/doc/README.mx23_common
> new file mode 100644
> index 0000000..dcf0ba4
> --- /dev/null
> +++ b/doc/README.mx23_common
> @@ -0,0 +1,145 @@
> +Booting U-boot on a MX23 processor
> +==================================
> +
> +This document describes the MX23 U-Boot port. This document mostly
> +covers topics related to making the module/board bootable.
> +
> +Terminology
> +-----------
> +
> +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 MX23 based board
> +3) Installation of U-Boot for a MX23 based board to SD card
> +
> +1) Prerequisites
> +----------------
> +
> +To make a MX23 based board bootable, some tools are necessary. The first
> one +is the "elftosb" tool distributed by Freescale Semiconductor. The
> other one +is the "mxsboot" tool found in U-Boot source tree.
> +
> +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 MX23 based board
> +-------------------------------------------
> +
> +Compiling the U-Boot for a MX23 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 MX23 based board
> +
> +	$ make <mx23_based_board_name>_config
> +
> +Examples:
> +
> +1. For building U-boot for Freescale MX23EVK board:
> +
> +	$ make mx23evk_config
> +
> +2. 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 the i.MX23 CPU 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.
> +
> +3) Installation of U-Boot for a MX23 based board to SD card
> +-----------------------------------------------------------
> +
> +To boot a MX23 based board from a SD connected to SSP1 or SSP2, set the
> boot +mode DIP switches according to i.MX23 manual section 35.1.2 (Table
> 35-3). +
> +An SD card the i.MX23 CPU can use 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: +
> +	$ sudo dd if=u-boot.sd of=/dev/mmcblk0p1; sync
> +
> +Last step is to insert the card into MX23 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.

Best regards,
Marek Vasut

On Fri, May 3, 2013 at 12:55 PM, Marek Vasut <marex@denx.de> wrote:
> Dear Fabio Estevam,
>
>> From: Fabio Estevam <fabio.estevam@freescale.com>
>>
>> Provide instructions on how to build U-boot and flash the binary into an SD
>> card for a mx23 based platform.
>
> Can most of this not be shared with MX28 ?

Maybe to provide a README.mxs and reference it in the board specific docs.

--
Otavio Salvador                             O.S. Systems
E-mail: otavio@ossystems.com.br  http://www.ossystems.com.br
Mobile: +55 53 9981-7854              http://projetos.ossystems.com.br