View source for CM-X300: U-Boot: Firmware Development

== Overview ==

Compulab CM-X300 is shipped with built-in firmware, which deals with initial module power-up and initialization procedures.
The firmware also provides a command line interface for Operating System or user program installation and loading.

This article describes the CM-X300 firmware structure, firmware assembly process and provides recommendations for testing U-Boot customization.
{{Note|The target audience of this article are developers, who need to alter the CM-X300 U-Boot behavior}}

== CM-X300 firmware structure ==
CM-X300 firmware consists of three main parts:
* [[CM-X300: U-Boot: Firmware Development#Marvell_Non_Trusted_Image_Module_(NTIM)|Marvell Non Trusted Image Module (NTIM)]]
* [[CM-X300: U-Boot: Firmware Development#Marvell_Non_Trusted_OEM_Boot_Module_(OBM)|Marvell Non Trusted OEM Boot Module (OBM)]]
* [[CM-X300: U-Boot: Firmware Development#U-Boot_for_CM-X300_module|U-Boot for CM-X300 module]]
In the default CM-X300 firmware image, all three binaries are built, assembled and tested at CompuLab.
Latest versions of ready to run CM-X300 firmware images are available at [http://www.compulab.co.il/x300/html/x300-developer.py Developer Resources for CM-X300 & SB-X300] web page.

=== Marvell Non Trusted Image Module (NTIM) ===
NTIM is a packed structure (table), which describes the images involved in the PXA3XX boot process.
NTIM must be created each time {{filename|cm-x300-firmware}} is built.<br>
In order to build the NTIM binary image it is necessary to have the OBM and U-Boot binaries and a Key file with NTIM description.
Building of the NTIM binary image is done by the {{cmd|ntbb}} (non-trusted boot builder) utility.<br>
The default command line for {{cmd|ntbb}} utility is:
<pre>
$ ./ntbb -v -m 1 -r <Key file name>
</pre>
Both {{cmd|ntbb}} utility and Key file can be obtained from CompuLab.

=== Marvell Non Trusted OEM Boot Module (OBM) ===
OBM is the first boot loader software that runs on the PXA3XX cpu after power on and the internal PXA3XX Boot ROM initializations. It performs low level hardware initialization and copies U-Boot from NAND flash to CM-X300 RAM.<br>
OBM is a proprietary software and can be distributed in binary form only.

=== U-Boot for CM-X300 module ===

U-Boot for CM-X300 is the last part of the CM-X300 firmware and it is the only part of CM-X300 firmware that could be altered by a user.
Upon its start, U-Boot assumes that it is already in the system's RAM and does not relocate itself. U-Boot initializes CM-X300 peripheral devices, such as PMIC, serial port, network and USB.<br>
U-Boot source code used for building CM-X300 firmware can be obtained from CompuLab on request.

== CM-X300 firmware assembly ==

All three binary images described above are assembled into one file ({{filename|cm-x300-firmware}}), to avoid errors during firmware update process.
The following command sequence is used:
* Prepare the NTIM table:
<pre>
$ ./ntbb -v -m 1 -r CM-X300L-image.txt
</pre>
* Create empty {{filename|cm-x300-firmware}} file and fill it with ''0xff'':
<pre>
$ cat > ff.pl <<EOF
> open(OUT, ">", "cm-x300-firmware");
> \$data = 0xff;
> binmode(OUT);
> for (\$i = 0; \$i < 0x80000; \$i++) {
>         print OUT pack('c', \$data);
> }
> EOF
$ perl ff.pl
</pre>

* Copy all the binary images with offsets defined in {{filename|CM-X300L-image.txt}}:
<pre>
$ dd if=NTIM_X300L.bin of=cm-x300-firmware conv=notrunc
$ dd if=MHL_wince_NTOBM.bin of=cm-x300-firmware conv=notrunc bs=128k seek=1
$ dd if=u-boot.bin of=cm-x300-firmware conv=notrunc bs=128k seek=2
</pre>

After completion of the above process {{filename|cm-x300-firmware}} file contains ready CM-X300 firmware image, that can be flashed into NAND as described in [[CM-X300: U-Boot: Firmware Update|Firmware Update]] article.<br>
The above sequence is available in a sample [[media:build-firmware-sample.sh|script]].

== Testing U-Boot customizations ==
During normal operation U-Boot is stored in the CM-X300 NAND flash as a part of the CM-X300 firmware. U-Boot development and testing requires frequent updates of the U-Boot bootloader and therefore of the entire CM-X300 firmware. This approach has two significant drawbacks:
* Multiple erases significantly shorten lifetime of vital blocks in the CM-X300 NAND flash.
* Buggy U-Boot build or badly formed firmware can result in disabled CM-X300 module.

=== Recommended testing solution ===

The recommended way to test U-Boot customizations is to load U-Boot into CM-X300 RAM and test it thoroughly before overwriting the working version.<br>
Use the following steps:
* In the file {{filename|/path/to/u-boot/board/cmx300/config.mk}} change the value of {{parameter|TEXT_BASE}} variable to {{parameter|0x80200000}}. This is the new memory location of your U-Boot under test.
* Compile U-Boot and put the {{filename|u-boot.bin}} file to TFTP root directory, MMC/SD card or USB thumb drive.
* Power up CM-X300 and wait until the working U-Boot version has started.
* For network {{cmd|tftp}} download:
<pre>
> setenv ipaddr <ip address for CM-X300>
> setenv serverip <TFTP server ip address>
> tftp 0x80200000 u-boot.bin
</pre>
* For MMC/SD card:
<pre>
> mmc init
> fatload mmc 1 0x80200000 u-boot.bin
</pre>
* Or for USB thumb drive:
<pre>
> usb start
> fatload usb 0 0x80200000 u-boot.bin
</pre>
* Start the test U-Boot version:
<pre>
> go 0x80200000
</pre>
* If U-Boot has started normally, continue with the testing, else fix the problem and start over.
{{Warning|After finishing all the tests, and before assembling the CM-X300 firmware, switch back the {{parameter|TEXT_BASE}} value to its default: {{parameter|0x83900000}}, otherwise firmware update will result in disabled CM-X300 module.}}

== Known issues ==
=== Cross-Compiler issues ===
U-Boot compilation process is very sensitive and highly dependent on cross-compiler. It is possible that certain cross-compilers fail to generate bootable code out of U-Boot sources.<br>
CompuLab recommended cross-compiler and build tool chain is [http://www.codesourcery.com/sgpp/lite/arm/portal/release324 Sourcery G++ Lite 2008q1-126 for ARM GNU/Linux].

== See Also ==

* [[U-Boot quick reference]]
* [[U-Boot images]]
* [[CM-X300: U-Boot: Firmware Update]]
* [[CM-X300: U-Boot: Disabled Module Recovery]]
* [http://www.denx.de/wiki/U-Boot/Documentation U-Boot documentation]


[[Category:U-Boot|Firmware Development]]
[[Category:CM-X300|U-Boot: Firmware Development]]