CM-X300: U-Boot: Firmware Development - Revision history

Grinberg: /* U-Boot for CM-X300 module */

2013-04-04T10:12:02Z

‎U-Boot for CM-X300 module

Grinberg: /* Recommended testing solution */

2012-03-05T10:54:19Z

‎Recommended testing solution

Mike: Reverted edits by Bettytaylor23 (Talk); changed back to last version by Grinberg

2010-10-19T16:01:50Z

Reverted edits by Bettytaylor23 (Talk); changed back to last version by Grinberg

Bettytaylor23 at 06:14, 16 October 2010

2010-10-16T06:14:11Z

Grinberg: /* Cross-Compiler issues */

2010-08-22T10:50:57Z

‎Cross-Compiler issues

Mike at 15:27, 22 December 2009

2009-12-22T15:27:48Z

New page

== 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. 
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. 
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. 
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. 
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 Update]] article. 
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. 
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 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>
* 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. 
It is recommended to prepare at least two different (version/vendor) cross-compilers, before starting the U-Boot customization and development process.

== See Also ==

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

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

@@ Line 13: / Line 13: @@
 * [[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.
+Latest versions of ready to run CM-X300 firmware images are available at [http://compulab.co.il/products/computer-on-modules/cm-x300/#devres 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.
+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:
@@ Line 34: / Line 34: @@
 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>
 == CM-X300 firmware assembly ==
@@ Line 64: / Line 63: @@
 </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>
+After completion of the above process the {{filename|cm-x300-firmware}} file will contain a ready to use CM-X300 firmware image, which 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]].

@@ Line 77: / Line 77: @@
 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 or USB thumb drive.
+* 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:
@@ Line 84: / Line 84: @@
 > setenv serverip <TFTP server ip address>
 > tftp 0x80200000 u-boot.bin
 </pre>
 * Or for USB thumb drive:

@@ Line 26: / Line 26: @@
 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>

@@ Line 64: / Line 64: @@
 </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 Update]] article.<br>
+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]].
@@ Line 99: / Line 99: @@
 == 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>
+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>
-It is recommended to prepare at least two different (version/vendor) cross-compilers, before starting the U-Boot customization and development process.
+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 ==
@@ Line 106: / Line 106: @@
 * [[U-Boot quick reference]]
 * [[U-Boot images]]
-* [[CM-X300 U-Boot Update]]
+* [[CM-X300: U-Boot: Firmware Update]]
 * [http://www.denx.de/wiki/U-Boot/Documentation U-Boot documentation]