~~NOCACHE~~
===== Build System =====
====== PTXdist 2012.07 ======

===== 1. Preparing the development host =====

<WRAP round important>Please note:\\ The following was tested on Ubuntu 10.04 / 12.04. Older versions are not working.</WRAP>

To install PTXdist you need a Linux OS like Ubuntu. The BSP needs some additional packages which are normally not installed. These packages are:
  * gawk
  * dialog
  * ncurses-dev
  * bison
  * flex
  * quilt
  * texinfo
  * gettext
  * g++
  * libxml-parser-perl

For development it is recommended to have an [[en:tftp|tftp server]] for image download and update and an [[en:nfs|nfs server]] for network mounted rootfs configured and running.

===== Build system installation =====

After installing all packages download PTXdist source, configure, compile and install. See [[.:downloads| download page]] for links.

Extract the package ptxdist-2012.07.0.tar.bz2 to a temporary directory and call:
<code bash>
$ ./configure
$ make
$ sudo make install
</code>

This will install PTXdist to /usr/local. Afterwards please configure PTXdist with:

<code bash>
$ ptxdist setup 
</code>

You have to setup the following things:

  * ftp / http proxies
  * username and mail address
  * path for archive of downloaded source packages (aka local package pool)
  * and some more features ...

===== Toolchain installation =====

See [[.:downloads| download page]] for links to toolchain download. If using precompiled toolchain install to ///opt//. Otherwise following the documentation for building toolchains.

Normally the toolchain is alredy configured in the BSP. So nothing further to setup.

===== BSP installation =====

Extract the package OSELAS.BSP-TQ-TQMA53.<version>.tgz to any directory (e.g. ///opt// or ///home//):

<code bash>
$ cd /opt/projekte
$ tar -xvf OSELAS.BSP-TQ-TQMA53.0101.tgz
$ cd OSELAS.BSP-TQ-TQMA53
</code>

===== Using the build system =====

==== Getting help ====

<WRAP round tip>The manual is your friend. See [[en:arm:tqma53:linux:ptxdist:downloads|Downloads]] where to get it.</WRAP>

==== Configuration ====

To configure the system (e.g. add additional packages) you can start the PTXdist menu:
<code bash>
$ ptxdist menu
</code>

To add additional packages to your root filesystem simply use the ptxdist tool. The ncurses based UI is the same that is used by the linux kernel with "make menuconfig". It can be used the following way:

  * use the up / down arrow keys to navigate in the menu
  * use the left / right arrow keys to navigate between buttons
  * select / deselect packages and options using the SPACE key
  * enter submenus or press buttons using the ENTER key

Dependencies between packages should be “automagically” resolved. Software is organized in sections.

==== Compilation ====

Select the platform MBa53 and start building the images:

<code bash>
$ ptxdist platform configs/platform-tq-mba53/platformconfig
$ ptxdist go
$ ptxdist images
</code>

PTXdist downloads some packages. If it reports some errors please 

   * verify your internet connection or proxy settings.
   * make sure the package source is correct. Some packege source pages will change from time to time. (You can always try to download the source package manually and copy it to your package pool)
   * some packages like bootloaders and kernels where you can select versions need to know about there hash sums. You have to enter the correct hash in the PTXdist configuration.

==== Changing packages ====

PTXdist uses release tar balls for software it loads from the net. You have to work with patches, if you need to make changes of the source code. Follow the instructions of the developers section in the PTXdist manual.

<WRAP round alert>Changes that are made in the build directories only will be deleted, when PTXdist needs to redo a buildstep. </WRAP>



==== Adding own packages ====

PTXdist needs a package for every bit you need in your root FS. To add your software, files etc. you have to provide local packages. Follow the instructions of the developers section in the PTXdist manual. PTXdist provides templates as starting point for own packages. Type

<code bash>
$ ptxdist newpackage
</code>

to see what package templates exist.

==== Deployment ====

Finally, you will find the built images in //platform-MBa53/images//. 

   * hd.img is a bootable image for usage with an SD card
   * hd_emmc.img is a bootable image for usage with the eMMC an TQMa53.
   * barebox-image: bootloader for SD
   * barebox_emmc-image: bootloader for eMMC
   * linuximage: Kernel (zImage)
   * Root file system images

The SD-card and eMMC images are complete system images intended for
 		 	
  * development system initialisation 
  * deployment 

The barebox bootloader supports update of  

  * bootloader 
  * kernel 
  * devicetree 
  * root FS 
	 
To update bootloader / kernel / root FS in a running system you have to copy the images in your tftp directory and rename them to 
the names that the bootloader environment expects.  
 
<WRAP round tip> To see the names needed type  
<code bash> 
$ cat /env/config  
</code> 
at the bootloader prompt. 
</WRAP>  
	 
You can use the update scripts from the barebox environment for update:

  * update_kernel
  * update_barebox
  * update_rootfs

To update parts of the barebox environment or the device tree during development you can use also the barebox tftp command.	 	

==== Adapting BSP for an own product ====

The BSP was developed for the starterkit. To use it in a product with special needs or a different basebord we suggest to define an own platform. To start with it make a copy of the platform definition and select the new platform definition

<code bash> 
$ cd <BSPROOT>
$ cp -r <BSPROOT>/configs/platform-tq-mba53 to <BSPROOT>/configs/<your-cool-platform>
$ ptxdist platform <BSPROOT>/configs/<your-cool-platform>/platformconfig
</code> 

To start configuring your new platform type

<code bash> 
$ ptxdist platformconfig
</code> 

The first thing to change should be the platform name. Adapt things like kernel configuration, image creation etc. to your needs.

The new system will be built under <BSPROOT>/platform-<platformname_from_platformconfig>

<WRAP round important>Please read the build system documentation howto go further.</WRAP>

===== Using different boot media =====

==== NFS ====

To boot the MBa53 from network you need a working bootloader in SD-card or eMMC which is able to get the kernel image over tftp and to provide the kernel with commandline settigns for NFS. Depending on the bootloader location the board has to be configured to load the bootloader. See [[.build_system#sd-card|SD-card]] and [[.build_system#emmc|eMMC]]. You have to provide the images via tftp and nfs and to configure the bootloader to work with your tftp-server and your nfs-server 

The following example is given for the barebox loader used in the BSP:

<code sh>
barebox@TQ tqma53: edit /env/config
</code>

The following settings have to be configured in the script:

<code sh>
# or set your networking parameters here
eth0.ipaddr=<tqma53 IP> 
eth0.netmask=<tqma53 netmask>
eth0.serverip=<nfs / tftp server ip>
#eth0.gateway=a.b.c.d
#eth0.ethaddr=de:ad:be:ef:00:00

ip=$eth0.ipaddr:$eth0.serverip:$eth0.gateway:$eth0.netmask::eth0:off
</code>

Save environment and reset to make it active:

<code sh>
barebox@TQ tqma53: reset
</code>

Verify environment settings:

<code sh>
barebox@TQ tqma53: printenv
</code>

Verify eth0 configuration:

<code sh>
barebox@TQ tqma53: devinfo eth0
</code>


==== eMMC ====

To initialize the eMMC with an newly created image follow the instructions below:

  * Use [[.build_system#sd-card|SD-card]] boot
  * on your development host add an additional ext3 partition to the SD card
  * copy the hd_emmc.img file to this partition
  * insert the SD card in MBa53 and boot
  * copy the image to the eMMC using the following commands:    

  root@tqm:~ mount /dev/mmcblk0p4 /mnt
  root@tqm:~ cd /mnt
  root@tqm:/mnt dd if=hd_emmc.img of=/dev/mmcblk1 bs=1M conv=fsync
  root@tqm:/mnt poweroff

  * remove SD card
  * configure for eMMC boot (see table)

You can also establish an workflow using the Freescale Manufacturing tool.

To boot the MBa53 from an initialized eMMC you have to set the switches S1, S2 and S3.

^  Switch S1 settings ^^^
^ DIP ^  OFF  ^  ON  ^
| S2 1 |  X  |     |
| S2 2 |  X  |     |

^  Switch S2 settings ^^^
^ DIP ^  OFF  ^  ON  ^
| S2 1 |  X  |     |
| S2 2 |  X  |     |
| S2 3 |  X  |     |
| S2 4 |  X  |     |
| S2 5 |  X  |     |
| S2 6 |     |  X  |
| S2 7 |     |  X  |
| S2 8 |  X  |     |

^  Switch S3 settings ^^^
^ DIP ^  OFF  ^  ON  ^
| S3 1 |  X  |     |
| S3 2 |  X  |     |
| S3 3 |     |  X  |
| S3 4 |  X  |     |
| S3 5 |     |  X  |
| S3 6 |  X  |     |
| S3 7 |  X  |     |
| S3 8 |  X  |     |

Power up the MBa53. The login is root without any password.
If you connect a DVI monitor to X5 you can see the login prompt.

==== SD-Card ====

Copy the hd.img to an SD-card to boot the module via SD-card.

<code bash>
$ dd if=platform-MBa53/images/hd.img of=/dev/sd<n> bs=1M conv=fsync
</code>

<WRAP round tip>You have to use the raw device of the SD card not a partition!</WRAP>

To boot the MBa53 from a previously generated SD Card you have to set the switches S1, S2 and S3.

^  Switch S1 settings ^^^
^ DIP ^  OFF  ^  ON  ^
| S2 1 |  X  |     |
| S2 2 |  X  |     |

^  Switch S2 settings ^^^
^ DIP ^  OFF  ^  ON  ^
| S2 1 |  X  |     |
| S2 2 |  X  |     |
| S2 3 |  X  |     |
| S2 4 |  X  |     |
| S2 5 |  X  |     |
| S2 6 |     |  X  |
| S2 7 |  X  |     |
| S2 8 |  X  |     |

^  Switch S3 settings ^^^
^ DIP ^  OFF  ^  ON  ^
| S3 1 |  X  |     |
| S3 2 |  X  |     |
| S3 3 |  X  |     |
| S3 4 |     |  X  |
| S3 5 |  X  |     |
| S3 6 |     |  X  |
| S3 7 |  X  |     |
| S3 8 |  X  |     |

Insert the SDcard in X6 and power up the MBa53. The login is root without any password.
If you connect a DVI monitor to X5 you can see the login prompt.