CM-i.MX31: Official documentation

Setting up an Environment using OpenSuSE 10.2

Hardware Requirements

For beginning you need the follow minimum Hardware:

• PC with x86 compatible CPU (32bit preferred)
• CPU ≥ 1 GHz
• ≥ RAM 1024 MB
• free USB port or free COM port

• 1 Dev-iMX31 Developement Board
• 1 CM-iMX31 Core Module
• 1 USB Client-To-Host Cable or a RS232 null modem cable
• 1 CAT5 cable

Software Requirements

During the development phase, the following tools were used

• Windows XP SP2
• VMWare 6.0
• OpenSuSE 10.2 (!!)
• LTIB Revision 5
• PuTTY for Terminal Access

Windows is used as a main operating system, OpenSuSE will be used to build the LTIB packages and the kernel. It will also offer a TFTP and a NFS service. To simplify access from Windows to the LTIB directory, SMB will be used.

Start VMware and create a new Typical Virtual machine configuration. Choose Linux as Guest Operating system and select "Other Linux 2.6.x kernel 32bit". Enter a descriptive name for the machine. Choose the network settings which are appropriate for your network. During the development phase, briged networking was used. The network was configured to use an automatically assigned IP adress for the Windows installation and a fixed IP adress for the Linux installation. Choose a disk size of about 30GB, depending on your available space and requirements. Remove the Sound Adapter and the floppy from the machine, they will most likely not be used. If possible allow the machine to use 512 MB RAM (or more).

Load either a real OpenSuSE 10.2 disk or use VMware's ISO feature to load a ISO image. When booting press ESC to select the CDROM as boot device. The OpenSuSE installation is started. During installation you will be asked for a selection of packages. Choose the following options:

• OpenSuSE Base System
• YaST System Administration
• KDE Desktop Environment
• KDE Base System
• X Window System
• Fonts
• File server
• Basis Development

If you need other packages check these as well. Make sure that all dependencies are solved. The installation will start and after a reboot you will be prompted for a root password, hostname and domain name. Disable the firewall and disable access for IPv6 (we will just use IPv4). Setup your network adapter(s) according to your network settings. After rebooting, you will be presented with your chosen desktop.

We will now define settings for the forthcoming setup.

• IP Adress for the Target: 192.168.0.51
• IP Adress for the Linux installation: 192.168.0.75
• Broadcast: 255.255.255.0
• Gateway: 192.168.0.1
• Nameserver: 192.168.0.1

Set the IP Adress of the Linux installation accordingly. This can be done via YaST2 which can be found in System Menu -> Computer -> Administrator Settings. You will need to provide your root password. Navigate to Network Devices -> Network Card. You should be able to change your IPAdress to the desired settings. You can check if your settings were successful by running ifconfig in a terminal. You should be able to see your interface with the entered IP. It is recommended to use a Static IP instead of a dynamically assigned IP.

Now make sure you can reach the Linux installation e.g. by establishing a SSH Session using !PuTTY. The SSH Server is enabled by default. If this does not work, check your firewall or network settings.

We will now proceed by installing LTIB, the Linux Target Image Builder.

Installing LTIB

Download the ISO Image of the LTIB rev.5 from the Freescale Website, if you have not already done so. In VMWare, insert the virtual disc into the cd drive. This can be done via the menu option VM -> Removable Devices -> CDROM -> Edit -> Use ISO Image -> Select Image. The Linux Installation should now show a dialog telling the user that a new disc was entered. If this does not happen, use the menu option: VM -> Removable Devices -> CDROM -> Disconnect and then VM -> Removable Devices -> CDROM -> Connect. The entered image will be mounted on /media/ltib.

Open a SSH Session (e.g. by using PuTTY) to your Linux VM (or use the terminal) in order to install ltib. Make sure you are logged in as a normal user and not as root. Change to /media/ltib and run ./ltib.

cd /media/ltib
./install

You will be asked to agree to the license agreement. Press Y to continue. A list of packages will be shown. You can either scroll to the end or press Ctrl-C to go on directly. Answer "yes" and you will be asked for the installation location. Simply enter "~" (without the ") to select your home directory. A subdirectory will automatically be created. The installation script will now copy various files to your selected location. After the installation is complete, navigate to your home directory. We will now create a symbolic link to the Ltib directory. Type

ln -s ltib-imx31ads-20071008 ltib5

to create that link. Now change to ~/ltib5 and run ./ltib.

cd ~/ltib5
./ltib

LTIB will warn that it requires root rights for some tasks and will also automatically provide a solution. Run the command

sudo /usr/sbin/visudo

and add the given line to the file. Save the file and run the ltib command again. The following process might take a while.

Connecting the Dev Board

In the meanwhile you might want to connect the Dev Board to your computer. You will now have to decide whether you will use a Windows Terminal program such as !PuTTY or a Linux terminal program such as Minicom. In this instruction all operations were performed by using !PuTTY in Windows. Minicom could be installed by using !YaSTs Software Management Feature. Use the search box to search for "minicom".

VMWare handles it's USB devices in such a way, that when you connect a USB device whilst the Virtual Machine has the focus, it will capture the device and only be usable in the virtual machine. If the virtual machine does not have the focus, the device will be accessible under Microsoft Windows only. We have used the USB Port on the board for this instructions.

If you connect the device while the virtual machine has the focus it will most likely be known as /dev/ttyUSB0. You can simply check with the command ls /dev/ttyU* If you connect it if the virtual machine does not have the focus, you can find it's assigned virtual COM port in the device manager which can be reached via Start->Run->compmgmt.msc. In this instructions we will assume, that COM5 was assigned.

Connect the USB cable to the plug labeled USB2UART and connect the network cable to the plug named ETH2. Windows (or Linux) will now detect a new device and will most likely install drivers for it if needed. Linux should already have the drivers built into the kernel and therefore should not need any. The link to the windows drivers can be found at the end of these instructions.

Setting up required services

Open YaST2 and navigate to Network Services. We will now setup the TFTP service. The device will retrieve its kernel via TFTP. Choose TFTP server and set it to "Enable". As boot Image Directory select home/dev/ltib5/rootfs/boot whereas dev is the username. Click Finish to save the settings and close the dialog. Now select the NFS server. Select "Start" and click Next. Add a new directory and enter /home/dev/ltib5/rootfs. As options, write: rw,no_root_squash,async and click ok. Save your settings and close the dialog by clicking "Finish". We will also need a link pointing to the rootfs. Fire up a terminal and run the following commands:

sudo mkdir /srv/nfs
sudo ln -s /home/dev/ltib5/rootfs /srv/nfs/rootfs

In case you are not using YaST or a graphical environment, the following configuration files might be of interest:

• /etc/xinetd.d/tftp (TFTP Service)

# default: off
# description: tftp service is provided primarily for booting or when a \
#       router need an upgrade. Most sites run this only on machines acting as
#       "boot servers".
service tftp
{
        socket_type     = dgram
        protocol        = udp
        wait            = yes
        user            = root
        server          = /usr/sbin/in.tftpd
        server_args     =  -s /home/dev/ltib5/rootfs/boot
        disable         = no
}

• /etc/exports (NFS Export)

/home/dev/ltib5/rootfs  *(rw,root_squash,sync)

You might want to restart the services after these changes.

/etc/init.d/xinetd restart
/etc/init.d/nfsserver restart

Creating Links to the Linux installation

If you are using Windows as development platform and if you are running the Linux installation in a virtual machine, you might want to create samba shares to have direct access to the files. If you do not need or want this, you can simply skip this chapter. Open !YaST2 and navigate to Network Services -> Samba Server. Enter a Workgroup name or use the default. Select "Not a domain controller" and set the Service Start to "During Boot". Open the Tab "Shares", click "Add". As Share Name, enter "ltib" and as share path, select the directory /home/dev/ltib5. Replace "dev" with your selected username. Click finish. We will now also have to add a smb user. You can either choose to have root or your user name to have access to the ltib installation directory. Open a terminal or !PuTTY session to the Linux installation and run the following command:

sudo smbpasswd -a root
or
sudo smbpasswd -a username

In addition we will now create a batch file which will we can run to access the smb share in Windows (also known as a network drive). Paste the following lines into a file named accessShare.bat.

@echo off
net use y: /delete
net use y: \\192.168.0.75\ltib password /USER:username /Persistent:No

Replace password and username with your selected username and password. Running this command will make sure the directory gets mounted when you run the file and unmounted when you exit Windows. The connection to the share will not be persistent throughout sessions. When running the script, you should get a drive named Y which contains the contents of your ltib installation.

Installing the BSP

We will now apply the BSP (Board Support Package) to our raw LTIB installation. The BSP provides various patches for this specific core module and dev board. The most current BSP can be downloaded from the Bluetechnix Website. Copy the most current revision to a location within your user directory, I will assume /home/dev/patchset. Navigate to the directory ./bsp-r5/mxc_patchset and run the command:

./install ~/ltib5

This will copy the files to the appropriate locations and will execute the patches. You should not see any error messages during this process (only informative messages). Answer the following questions with y. We will now configure the kernel for the first compilation run.

Configuring and Compiling the Kernel

At first, navigate to Package List and select the package mxc-misc if it is not already selected. Then, navigate to Target System Configuration and select Options -> Network Setup -> and change IP address, netmask, broadcast, gateway and nameserver IP address according to your network structure. In our example we would choose the following settings.

• IP address: 192.168.0.51 (Target's IP address)
• Netmask: 255.255.255.0
• Broadcast address: 192.168.0.255
• Gateway address: 192.168.0.1
• Nameserver address: 192.168.0.1

Go back until you are at the main screen and then select "Configure the kernel" if it is not already selected. Select Exit and when you are asked if you want to save the new configuration, select Yes. Make sure you have a valid internet connection, otherwise LTIb might fail if it tries to get missing packages from bitshrine.org. When reaching the kernel configuration screen, perform no changes, but simply click Exit. The following process might take a while. It should end without any errors and you should receive the message "Build Succeeded" at the very end.

The following directories will have been created:

• ltib5/rootfs - This directory contains the root file system for the target
• ltib5/rootfs/boot - This directory contains the kernel image in uImage format (filename: uImage)
• ltib5/rootfs/unit_tests - This directory contains unit tests for various processor features
• ltib5/rpm/BUILD/linux - This directory contains the kernel sources. If you are planning to change the kernel, this is the correct place to go
• ltib5/pkgs - This directory contains the different packages which can be selected when you run ./ltib --configure

In case you are using a BSP prior to revision 99, you will have to run the following command every time you make changes in the kernel configuration (as well as now). If you are using a revision past 99, you can skip this step.

Finally you will need to run the command:

/opt/freescale/ltib/usr/bin/mkimage -C none -A arm -O linux -T kernel -a 80300000 -e 80300000 -n imageName -d zImage uImage

in the ltib5/rootfs/boot directory as root to create a valid uImage file from the created zImage file.

Boot the target

The target already comes with a pre - flashed bootloader and is basically fully working (FIXME: The uboot setup_bootargs_net isn't correct, there is a colon too much before eth0 in ip=... With this mistake the target won't boot if two network cards are enabled). By following the previous chapters, you should now have a fully working development environment. Connect the target as explained, open a terminal session to the board (using 115200 8N1 as UART settings) and switch it on. you should see the following messages appear:

U-Boot 1.2.0 (Feb 11 2008 - 16:52:34)

DRAM:  64 MB
Flash: 40 MB
In:    serial
Out:   serial
Err:   serial
Hit any key to stop autoboot:  0
dm9000 i/o: 0xb4000000, id: 0x90000a46
MAC: a0:a5:e0:87:1c:da
operating at 100M full duplex mode
TFTP from server 192.168.0.75; our IP address is 192.168.0.51
Filename 'uImage'.
Load address: 0x80100000
...

When you see the message "Hit any key to stop autoboot" hit any key and you will be presented with the bootloader's command line. we will now tell the bootloader where it can find its bootfile and other settings:

setenv ipaddr 192.168.0.51 (Target's IP Address)
setenv netmask 255.255.255.0
setenv serverip 192.168.0.75 (IP of TFTP/NFS Server)
setenv bootfile uImage
setenv rootpath /srv/nfs/rootfs
run setup_bootargs_net
saveenv

Reboot the device and you should see the following output:

U-Boot 1.2.0 (Feb 11 2008 - 16:52:34)

DRAM:  64 MB
Flash: 40 MB
In:    serial
Out:   serial
Err:   serial
Hit any key to stop autoboot:  0
dm9000 i/o: 0xb4000000, id: 0x90000a46
MAC: a0:a5:e0:87:1c:da
operating at 100M full duplex mode
TFTP from server 192.168.0.75; our IP address is 192.168.0.51
Filename 'uImage'.
Load address: 0x80100000
Loading: #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################
done
Bytes transferred = 1579764 (181af4 hex)
## Booting image at 80100000 ...
   Image Name:   imageName
   Image Type:   ARM Linux Kernel Image (uncompressed)
   Data Size:    1579700 Bytes =  1.5 MB
   Load Address: 80300000
   Entry Point:  80300000
   Verifying Checksum ... OK
OK

Starting kernel ...

Uncompressing Linux.......................................................................................................... done, booting the kernel.

When the boot process has finished and no errors appeared, connect the Hitachi Display to the port labeled IPU interface. You will be presented with the Qtopia environment and will be able to use the board.

Possible Errors

You receive the following message during boot:

U-Boot 1.2.0 (Feb 11 2008 - 16:52:34)

DRAM:  64 MB
Flash: 40 MB
In:    serial
Out:   serial
Err:   serial
Hit any key to stop autoboot:  0
dm9000 i/o: 0xb4000000, id: 0x90000a46
MAC: a0:a5:e0:87:1c:da
operating at 100M full duplex mode
TFTP from server 192.168.0.75; our IP address is 192.168.0.51
Filename 'uImage'.
Load address: 0x80100000
Loading: *
TFTP error: 'File not found' (1)
Starting again

This means, that the target could not retrieve the file uImage via TFTP. The reasons for this could be:

• A not working lan connection between target and host
• The file uImage is missing (run the mkimage command)
• Wrong permissions on the uImage file
• A not running TFTP Server or a TFTP server sharing the wrong directory

You receive the following message during boot:

Root-NFS: Server returned error -13 while mounting /srv/nfs/rootfs
VFS: Unable to mount root fs via NFS, trying floppy.
VFS: Cannot open root device "nfs" or unknown-block(2,0)
Please append a correct "root=" boot option; here are the available partitions:
1f00        512 mtdblock0 (driver?)
1f01        512 mtdblock1 (driver?)
1f02       2048 mtdblock2 (driver?)
1f03      29696 mtdblock3 (driver?)
Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(2,0)

It is most likely you didn't set the right network settings. Run ltib --configure, navigate to Target Options -> Network and enter the correct network settings.

You receive an error message stating that problems with the NFS root file system occured: Try to mount the NFS file system on your local system:

sudo mkdir /mnt/rootfs-nfs
sudo mount -t nfs localhost:/srv/nfs/rootfs /mnt/rootfs-nfs
ls /mnt/rootfs-nfs

If this gives you an error you might want to check the permissions either on the nfs export or the mount point.

Setting up an Environment using Ubuntu 8.04

General Notes

This instruction was written for Ubuntu 8.04 Beta. It should work on 8.04 final as well, though this has not been tested yet, since the final wasn't available at the time of writing. Basically everything works according to the (more detailed) !OpenSuSE 10.2 setup description, except for a few changes at the beginning and when setting up the network services needed. These steps will be described in detail here. You might still want to read through the !OpenSuSE explanation since not Ubuntu specific details won't be discussed here. If you have a question, please check the !OpenSuSE instructions first.

Installation of Ubuntu

Perform a normal Ubuntu Installation. Leave all settings as default, only change the settings for time and keyboard layout as needed. you may also choose a different partitioning scheme. After the last reboot, login with your chosen username and passwort, open a terminal window and run the following commands (you will need an internet connection to do this):

sudo aptitude update
sudo aptitude install libc6-dev libgcc patch bison rpm zlib-bin zlib1g-dev ncurses-dev build-essential

Installing LTIB Revision 5

Now you may install ltib by inserting your cd or mounting your image and running /media/cdrom/install. You will be asked where you want to install ltib. Enter ~ as directory. This will install it into your home directory. After the installation is complete, change into your home directory by using cd ~ and enter the following command to create a link.

ln -s ltib-imx31ads-20071008 ltib5

Now change to the ltib installation directory using cd ~/ltib5. Run ltib for the first time with ./ltib. If it complains about missing packages you probably haven't run all the sudo commands above. If it complains about not having su rights for different operations, perform the steps given in the instructions (you can quit vi by using ESC :q). The following operation might take a while and should complete successfully.

Enabling network services

We will now enable SMB and NFS Support for the Target and the Host. Click System -> Shared Folders and check both checkboxes (SMB / NFS Support), then click "Install Services". Again, you will need an internet connection for this to work. After this is done, click unlock. Add a new SMB Share for your ltib installation directory. Uncheck Read Only. Now add another share. Select NFS as type and select the rootfs directory in the ltib installation directory as sharepoint. Add an allowed host and enter "*". Since the configuration tool does not provide all the features we need, we will edit the NFS export. Run sudo gedit /etc/exports and change the content to:

/home/user/ltib-imx31ads-20071008 *(rw,no_root_squash,async)

Additionally, restart the NFS server:

sudo /etc/init.d/nfs-common restart

Finally to make NFS work, we need to create the following symbolic link

sudo mkdir /srv/nfs
sudo ln -s /home/username/ltib5/rootfs rootfs

Ubuntu does not provide a graphical tool to configure TFTPD, so we will have to do this by hand. Run the following commands:

sudo apt-get install xinetd tftpd tftp

Create /etc/xinetd.d/tftp and put this entry:

service tftp
{
protocol        = udp
port            = 69
socket_type     = dgram
wait            = yes
user            = nobody
server          = /usr/sbin/in.tftpd
server_args     = /home/user/ltib-imx31ads-20071008/rootfs/boot
disable         = no
}

Restart the xinet daemon:

sudo /etc/init.d/xinetd restart

TFTP is now setup and we have everything we need.

Notes

• If you need SSH access (e.g. for a !PuTTY Session) you might want to install the ssh server. This can be done by running sudo apt-get install openssh-server.
• Ubuntu doesn't enable a root account by default. Should you need it, you can use sudo -s, and then run passwd to set a net password.
• Concerning the network setup, Ubuntu seems to have troubles with the virtual machine network interface. You might want to edit the file /etc/network/interfaces by hand with these settings and then restart networking

sudo /etc/init.d/networking restart

Where to go from here

To continue, the next steps can be found in the section above.