Architech’s Tibidabo documentation¶

Version:	1.0.1A
Copyright:	Architech
Date:	28/01/2014

This documentation is old, you can find the last release: Here

Welcome to Tibidabo documentation!

Have you just received your Tibidabo board? Then you sure want to read the Unboxing Chapter first.

If you are a new user of the Yocto based SDK we suggest you to read the Quick start guide chapter, otherwise, if you want to have a better understanding of specific topics, just jump directly to the chapter that interests you the most.

Furthermore, we encourage you to read the official Yocto Project documentation.

Notations¶

Throughout this guide, there are commands, file system paths, etc., that can either refer to the machine (real or virtual) you use to run the SDK or to the board.

Host

This box will be used to refer to the machine running the SDK

Board

This box will be used to refer to Tibidabo board

However, the previous notations can make you struggle with long lines. In such a case, the following notation is used.

Host select

This Box will be used where long lines need to be displayed, as well as with system paths, commands, configuration files, etc.
All related to the host.
It will be used to display code example as well.

Board select

The same facility will be used, when needed, for the board.

If you click on select on the top right corner of these two last boxes, you will get the text inside the box selected. We have to warn you that your browser might select the line numbers as well, so, the first time you use such a feature, you are invited to check it.

Sometimes, when referring to file system paths, the path starts with /path/to. In such a case, the documentation is NOT referring to a physical file system path, it just means you need to read the path, understand what it means, and understand what is the proper path on your system. For example, when referring to the device file associated to your USB flash memory you could read something like this in the documentation:

Host select

/path/to/your/USB/device

Since things are different from one machine to another, you need to understand its meaning and corresponding value for your machine, like for example:

Host select

/dev/sdb

Chapters¶

Unboxing¶

This powerful board comes with this beautiful box

Tibidabo feeds its horses by means of an external power supply, which is included in the package and has several socket adapters.

The SPI NOR on the board has been programmed to let Tibidabo boot a core-image-minimal image generated with Yocto.

What are we waiting for? Lets boot the board!

First of all, make sure SW1 has this configuration

Connect the HDMI connector (CN8) to your monitor/television by means of an HDMI cable
Connect a USB keyboard to the board (connector CN18)
Take the socket adapter compatible with your country, plug it in the power adapter. When in position, you should hear a slight click
Power on the board connecting the external power adapter to Tibidabo connector CN19
The login is root

Enjoy!

Quick start guide¶

This document will guide you from importing the virtual machine to debugging an Hello World! example on a customized Linux distribution you will generate with OpenEmbedded/Yocto toolchain.

Install¶

The development environment is provided as a virtual disk (to be used by a VirtualBox virtual machine) which you can download from this page:

Important

http://downloads.architechboards.com/sdk/virtual_machine/download.html

Important

Compute the MD5SUM value of the zip file you downloaded and compare it to the golden one you find in the download page.

Uncompress the file, and you will get a .vdi file that is our virtual disk image. The environment contains the SDK for all the boards provided by Architech, Tibidabo included.

Download VirtualBox¶

For being able to use it, you first need to install VirtualBox (version 4.2.10 or higher). You can get VirtualBox installer from here:

https://www.virtualbox.org/wiki/Downloads

Download the version that suits your host operating system. You need to download and install the Extension Pack as well.

Important

Make sure that the extension pack has the same version of VirtualBox.

Install the software with all the default options.

Create a new Virtual Machine¶

Run VirtualBox

Click on New button

Select the name of the virtual machine and the operating system type

Select the amount of memory you want to give to your new virtual machine

Make the virtual machine use Architech’s virtual disk by pointing to the downloaded file. Than click on Create.

Setup the network¶

We need to setup a port forwarding rule to let you (later) use the virtual machine as a local repository of packages.

Note

The virtual machine must be off

Select Architech’s virtual machine from the list of virtual machines

Click on Settings

Select Network

Expand Advanced of Adapter 1

Click on Port Forwarding

_images/vdi_network_nat_port_forwarding.png

Add a new rule

_images/vdi_network_nat_port_forwarding_rule_add.png

Configure the rule

_images/vdi_network_nat_port_forwarding_rule_added.png

Click on Ok

Customize the number of processors¶

Building an entire system from the ground up is a business that can take up to several hours. To improve the performances of the overall build process, you can, if your computer has enough resources, assign more than one processor to the virtual machine.

Note

The virtual machine must be off

Select Architech’s virtual machine from the list of virtual machines

Click on Settings

Select System
Select Processor
Assign the number of processors you wish to assign to the virtual machine

_images/vdi_change_number_of_processors.png

Create a shared folder¶

A shared folder is way for host and guest operating systems to exchange files by means of the file system. You need to choose a directory on your host operating system to share with the guest operating system.

Note

The virtual machine must be off

Select Architech’s virtual machine from the list of virtual machines

Click on Settings

Select Shared Folders
Add a new shared folder

Choose a directory to share on your host machine. Make sure Auto-mount is selected.

Once the virtual machine has been booted, the shared folder will be mounted under /media/ directory inside the virtual machine.

Build¶

Important

A working internet connection, several GB of free disk space and several hours are required by the build process

Select Architech’s virtual machine from the list of virtual machines inside Virtual Box application

Click on the icon Start button in the toolbar and wait until the virtual machine is ready

Double click on Architech SDK icon you have on the virtual machine desktop.

The first screen gives you two choices: ArchiTech and 3rd Party. Choose ArchiTech.

Select Tibidabo as board you want develop on.

_images/splashscreen_board_selection.jpg

A new screen opens up from where you can perform a set of actions. Click on Run bitbake to obtain a terminal ready to start to build an image.

Open local.conf file:

Host select

gedit conf/local.conf

Go to the end of the file and add the following lines:

Host select

EXTRA_IMAGE_FEATURES_append = " tools-debug debug-tweaks"
IMAGE_INSTALL_append = " tcf-agent"

This will trigger the installation of a features set onto the final root file system, like tcf-agent and gdbserver.

Save the file and close gedit.
Build core-image-minimal-dev image by means of the following command:

Host select

bitbake core-image-minimal-dev

At the end of the build process, the image will be saved inside directory:

Host select

/home/architech/architech_sdk/architech/tibidabo/yocto/build/tmp/deploy/images/tibidabo

Setup sysroot directory on your host machine:

Host select

sudo tar -xjf /home/architech/architech_sdk/architech/tibidabo/yocto/build/tmp/deploy/images/tibidabo/core-image-minimal-dev-tibidabo.tar.bz2 -C /home/architech/architech_sdk/architech/tibidabo/sysroot/

Note

sudo password is: “architech“

Deploy¶

To deploy the root file system, you are going to need a micro SD card.

Copy the root file system to your SD card

Host select

sudo dd if=~/architech_sdk/architech/tibidabo/yocto/tmp/deploy/images/tibidabo/core-image-minimal-dev-tibidabo.sdcard of=/path/to/your/sd/card/device

Warning

Be very careful when you use dd to write to a device to pick up the right device, otherwise you can mess up another disk you have on your machine, destroying its content forever!

Warning

The content of the SD card will be lost forever!

Important

Be sure you unmount the device from the filesystem before using dd program, you sure don’t want to have the operating system interfere during the write process.

After dd completes, make sure everything has been really written to the SD card:

Host select

sync

Unmount the micro SD card from your computer
Plug the micro SD in the board socket.

Boot¶

First of all, make sure the board can boot entirely from the micro SD card by setting SW1 with this configuration

Take the power socket adapter compatible with your country, plug it in the power adapter. When in position, you should hear a slight click. Power on the board connecting the external power adapter to Tibidabo connector CN19.

Now it’s time to start the serial console.

On Tibidabo there is the dedicated serial console connector CN1

which you can connect, by means of a mini-USB cable, to your personal computer.

Note

Every operating system has its own killer application to give you a serial terminal interface. In this guide, we are assuming your host operating system is Ubuntu.

On a Linux (Ubuntu) host machine, the console is seen as a ttyUSBX device and you can access to it by means of an application like minicom.

Minicom needs to know the name of the serial device. The simplest way for you to discover the name of the device is by looking to the kernel messages, so:

clean the kernel messages

Host select

sudo dmesg -c

connect the mini-USB cable to the board already powered-on
display the kernel messages

Host select

dmesg

read the output

Host select

[ 2614.290675] usb 3-4: >new full-speed USB device number 4 using xhci_hcd
[ 2614.313854] usb 3-4: >New USB device found, idVendor=0403, idProduct=6015
[ 2614.313861] usb 3-4: >New USB device strings: Mfr=1, Product=2, SerialNumber=3
[ 2614.313865] usb 3-4: >Product: FT230X Basic UART
[ 2614.313868] usb 3-4: >Manufacturer: FTDI
[ 2614.313870] usb 3-4: >SerialNumber: DN002OZI
[ 2614.379284] usbcore: registered new interface driver usbserial
[ 2614.379298] usbcore: registered new interface driver usbserial_generic
[ 2614.379306] USB Serial support registered for generic
[ 2614.379310] usbserial: USB Serial Driver core
[ 2614.387899] usbcore: registered new interface driver ftdi_sio
[ 2614.387914] USB Serial support registered for FTDI USB Serial Device
[ 2614.387997] ftdi_sio 3-4:1.0: >FTDI USB Serial Device converter detected
[ 2614.388029] usb 3-4: >Detected FT-X
[ 2614.388031] usb 3-4: >Number of endpoints 2
[ 2614.388034] usb 3-4: >Endpoint 1 MaxPacketSize 64
[ 2614.388035] usb 3-4: >Endpoint 2 MaxPacketSize 64
[ 2614.388037] usb 3-4: >Setting MaxPacketSize 64
[ 2614.388260] usb 3-4: >FTDI USB Serial Device converter now attached to /dev/ttyUSB0
[ 2614.388288] ftdi_sio: v1.6.0:USB FTDI Serial Converters Driver

As you can see, here the device has been recognized as /dev/ttyUSB0.

Now that you know the device name, run minicom:

Host select

sudo minicom -ws

If minicom is not installed, you can install it with:

Host select

sudo apt-get install minicom

then you can setup your port with these parameters:

Host select

+-----------------------------------------------------------------------+
| A -    Serial Device      : /dev/ttyUSB0                              |
| B - Lockfile Location     : /var/lock                                 |
| C -   Callin Program      :                                           |
| D -  Callout Program      :                                           |
| E -    Bps/Par/Bits       : 115200 8N1                                |
| F - Hardware Flow Control : No                                        |
| G - Software Flow Control : No                                        |
|                                                                       |
|    Change which setting?                                              |
+-----------------------------------------------------------------------+
        | Screen and keyboard      |
        | Save setup as dfl        |
        | Save setup as..          |
        | Exit                     |
        | Exit from Minicom        |
        +--------------------------+

If on your system the device has not been recognized as /dev/ttyUSB0, just replace /dev/ttyUSB0 with the proper device.

Once you are done configuring the serial port, you are back to minicom main menu and you can select exit.

Give root to the login prompt:

Board

tibidabo login: root

and press Enter.

Note

Sometimes, the time you spend setting up minicom makes you miss all the output that leads to the login and you see just a black screen, press Enter then to get the login prompt.

Code¶

The time to create a simple HelloWorld! application using Eclipse has come.

Return to the Splashscreen, which we left on Tibidabo board screen, and click on Develop with Eclipse.

Go to File→ New→ Project, select C/C++→ C Project and press next button.

Insert HelloWorld as project name, select Hello World ANSI C Autotools Project and press next button.

Insert Author field and click on Finish button. Select Yes on the Open Associated Perspective? question.
Build the project by selecting Project→ Build All.

Debug¶

Use an ethernet cable to connect the board (connector CN16 Port P0) to your PC. Configure your workstation ip address as 192.168.0.100. Make sure the board can be seen by your host machine:

Board select

ifconfig pt0 192.168.0.10

Host select

ping 192.168.0.10

If the output is similar to this one:

Host select

64 bytes from 192.168.0.100: icmp_req=1 ttl=64 time=0.946 ms
64 bytes from 192.168.0.100: icmp_req=2 ttl=64 time=0.763 ms
64 bytes from 192.168.0.100: icmp_req=3 ttl=64 time=0.671 ms
64 bytes from 192.168.0.100: icmp_req=4 ttl=64 time=0.793 ms

then the ethernet connection is ok. Enable the remote debug with Yocto by typing this command on Tibidabo console:

Board select

/etc/init.d/tcf-agent restart

On the Host machine, follow these steps to let Eclipse deploy and debug your application:

Select Run→ Debug Configurations...
In the left area, expand C/C++Remote Application.
Locate your project and select it to bring up a new tabbed view in the Debug Configurations Dialog.

Insert in C/C++ Application the filepath (on your host machine) of the compiled binary.
Click on New button near the drop-down menu in the Connection field.
Select TCF icon.

Insert in Host Name and Connection Name fields the IP address of the target board. (e.g. 192.168.0.10)

Then press Finish.
Use the drop-down menu now in the Connection field and pick up the IP Address you entered earlier.
Enter the absolute path on the target into which you want to deploy the cross-compiled application. Use the Browse button near Remote Absolute File Path for C/C++Application: field. No password is needed.

Enter also in the path the name of the application you want to debug. (e.g. Hello)

Select Debugger tab

In GDB Debugger field, insert the filepath of gdb for your toolchain

Host select

/home/architech/architech_sdk/architech/tibidabo/toolchain/sysroots/i686-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb

In Debugger window there is a tab named Shared Library, click on it.
Add the libraries paths lib and usr/lib of the rootfs (which must be the same used in the target board)

Host select

/home/architech/architech_sdk/architech/tibidabo/sysroot/lib
/home/architech/architech_sdk/architech/tibidabo/sysroot/usr/lib

Click Debug to login.
Accept the debug perspective.

Important

If debug does not work, check on the board if tcf-agent is running and gdbserver has been installed.

SDK Architecture¶

This chapter gives an overview on how the SDK has been composed and where to find the tools on the virtual machine.

SDK¶

The SDK provided by Architech to support Tibidabo is composed by several components, the most important of which are:

Yocto,
Eclipse, and
Qt Creator

Regarding the installation and configuration of these tools, you have many options:

get a virtual machine with everything already setup,
download a script to setup your Ubuntu machine, or
just get the meta-layer and compose your SDK by hand

The method you choose depends on your level of expertise and the results you want to achieve.

If you are new to Yocto and/or Linux, or simply you don’t want to read tons of documentation right now, we suggest you to download and install the virtual machine because it is the simplest solution (have a look at VM content), everything inside the virtual machine has been thought to work out of the box, plus you will get support.

If performances are your greatest concerns, consider reading Chapter Create SDK.

Virtual Machine¶

The development environment is provided as a virtual disk (to be used by a VirtualBox virtual machine) which you can download from this page:

Important

http://downloads.architechboards.com/sdk/virtual_machine/download.html

Important

Compute the MD5SUM value of the zip file you downloaded and compare it to the golden one you find in the download page.

Uncompress the file, and you will get a .vdi file that is our virtual disk image. The environment contains the SDK for all the boards provided by Architech, Tibidabo included.

Download VirtualBox¶

For being able to use it, you first need to install VirtualBox (version 4.2.10 or higher). You can get VirtualBox installer from here:

https://www.virtualbox.org/wiki/Downloads

Download the version that suits your host operating system. You need to download and install the Extension Pack as well.

Important

Make sure that the extension pack has the same version of VirtualBox.

Install the software with all the default options.

Create a new Virtual Machine¶

Run VirtualBox

Click on New button

Select the name of the virtual machine and the operating system type

Select the amount of memory you want to give to your new virtual machine

Make the virtual machine use Architech’s virtual disk by pointing to the downloaded file. Than click on Create.

Setup the network¶

We need to setup a port forwarding rule to let you (later) use the virtual machine as a local repository of packages.

Note

The virtual machine must be off

Select Architech’s virtual machine from the list of virtual machines

Click on Settings

Select Network

Expand Advanced of Adapter 1

Click on Port Forwarding

Add a new rule

Configure the rule

Click on Ok

Customize the number of processors¶

Note

The virtual machine must be off

Select Architech’s virtual machine from the list of virtual machines

Click on Settings

Select System
Select Processor
Assign the number of processors you wish to assign to the virtual machine

Create a shared folder¶

Note

The virtual machine must be off

Select Architech’s virtual machine from the list of virtual machines

Click on Settings

Select Shared Folders
Add a new shared folder

Choose a directory to share on your host machine. Make sure Auto-mount is selected.

Once the virtual machine has been booted, the shared folder will be mounted under /media/ directory inside the virtual machine.

VM content¶

The virtual machine provided by Architech contains:

A splash screen, used to easily interact with the boards tools
Yocto/OpenEmbedded toolchain to build BSPs and file systems
A cross-toolchain (derived from Yocto/OpenEmbedded) for all the boards
Eclipse, installed and configured
Qt creator, installed and configured

All the aforementioned tools are installed under directory /home/architech/architech_sdk, its sub-directories main layout is the following:

Host select

architech_sdk
    |
    |_ splashscreen
    |
    |_ spashscreen-interface
    |
    |_ architech-manifest
    |
    |_ architech
        |
        |_ ...
        |
        |_ tibidabo
            |
            |_ eclipse
            |
            |_ java
            |
            |_ qtcreator
            |
            |_ splashscreen
            |
            |_ sysroot
            |
            |_ toolchain
            |
            |_ workspace
            |   |
            |   |_ eclipse
            |   |
            |   |_ qt
            |
            |_ yocto
                |
                |_ build
                |
                |_ poky
                |
                |_ meta-tibidabo
                |
                |_ ...

tibidabo directory contains all the tools composing the ArchiTech SDK for Tibidabo board, along with all the information needed by the splash screen application. In particular:

eclipse directory is where Eclipse IDE has been installed
java directory is where the Java Virtual Machine has been installed (needed by Eclipse)
qtcreator contains the installation of Qt Creator IDE
splashscreen directory contains information and scripts used by the splash screen application,
sysroot is supposed to contain the file system you want to compile against,
toolchain is where the cross-toolchain has been installed installed
workspace contains the the workspaces for Eclipse and Qt Creator IDEs
yocto is where you find all the meta-layers Tibidabo requires, along with Poky and the build directory

Splash screen¶

The splash screen application has been designed to facilitate the access to the boards tools. It can be opened by clicking on its Desktop icon.

Once started, you can can choose if you want to work with Architech’s boards or with partners’ ones. For Tibidabo, choose ArchiTech.

A list of all available Architech’s boards will open, select Tibidabo.

A list of actions related to Tibidabo that can be activated will appear.

Create SDK¶

If you have speed in mind, it is possible to install the SDK on a native Ubuntu machine (other Linux distributions may support this SDK with minor changes but won’t be supported). This chapter will guide you on how to clone the entire SDK, to setup the SDK for one board or just OpenEmbedded/Yocto for Tibidabo board.

Installation¶

Architech’s Yocto based SDK is built on top of Ubuntu 12.04 32bit, hence all the scripts provided are proven to work on such a system.

If you wish to use another distribution/version you might need to change some script option and/or modify the scripts yourself, remember that you won’t get any support in doing so.

Install a clone of the virtual machine inside your native machine¶

To install the same tools you get inside the virtual machine on your native machine you need to download and run a system wide installation script:

Host select

git clone -b dora https://github.com/architech-boards/machine_installer.git
cd machine_installer
./machine_install -g -p

where -g option asks the script to install and configure a few graphic customization, while -p option asks the script to install the required packages on the machine. If you want to install the toolchain on a machine not equal to Ubuntu 12.04 32bit then you may want to read the script, install the required packages by hand, and run it without options. You might need to recompile the Qt application used to render the splashscreen.

At the end of the installation process, you will get the same tools installed within the virtual machine, that is, all the tools necessary to work with Architech’s boards.

Install just one board¶

If you don’t want to install the tools for all the boards, you can install just the subset of tools related to Tibidabo:

Host select

git clone -b dora https://github.com/architech-boards/tibidabo-splashscreen.git
cd tibidabo-splashscreen
./run_install

This script needs the same tools/packages required by machine_install

Yocto¶

The easiest way to setup and keep all the necessary meta-layers in sync with upstream repositories is achieved by means of Google’s repo tool. The following steps are necessary for a clean installation:

Install repo tool, if you already have it go to step 4

Host select

mkdir -p ~/bin
sudo apt-get install curl
curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo

Make sure directory ~/bin is included in your PATH variable by printing its content

Host select

echo $PATH

If ~/bin directory is not included, add this line to your ~/.bashrc

Host select

export PATH="$PATH:${HOME}/bin"

Open a new terminal
Change the current directory to the directory where you want all the meta-layers to be downloaded into
Download the manifest

Host select

repo init -u https://github.com/architech-boards/tibidabo-manifest.git -b dora -m manifest.xml

Download the repositories

Host select

repo sync

By the end of the last step, all the necessary meta-layers should be in place, anyway, you still need to edit your local.conf and bblayers.conf to compile for tibidabo machine and using all the downloaded meta-layers.

When you want your local repositories to be updated, just:

Open a terminal
Change the current directory to the directory where you ran repo init
Sync your repositories with upstream

Host select

repo sync

If you really want to download everything by hand, just clone branch dora of meta-tibidabo:

Host select

git clone -b dora https://github.com/architech-boards/meta-tibidabo.git

and have a look at the README file.

To install Eclipse, Qt Creator, cross-toolchain, NFS, TFTP, etc., read Yocto/OpenEmbedded documentation, along with the other tools one.

BSP¶

The Board Support Package is composed by a set files, patches, recipes, configuration files, etc. This chapter gives you the information you need when you want to customize something, fix a bug, or simply learn how the all thing has been assembled.

U-boot¶

The bootloader used by Tibidabo is u-boot. If you want to browse/modify the sources first you have to get them. There are two viable ways to do that:

if you already built Tibidabo’s bootloader with Bitbake, then you already have them on your (virtual) disk, otherwise
you can download and patch them.

Bitbake will place u-boot sources under:

Host select

/path/to/build/tmp/work/tibidabo-poky-linux-gnueabi/u-boot-fslc/v2013.10-r1/git

this means that within the virtual machine you will find them under:

Host select

/home/architech/architech_sdk/architech/tibidabo/yocto/build/tmp/work/tibidabo-poky-linux-gnueabi/u-boot-fslc/v2013.10-r1/git

We suggest you to don’t work under Bitbake build directory, you will pay a speed penalty and you can have troubles syncronizing the all thing. Just copy them some place else and do what you have to do.

If you didn’t build them already with Bitbake, or you just want to make every step by hand, you can always get them from the Internet by cloning the proper repository and checking out the proper commit:

Host select

cd ~/Documents
git clone git://github.com/Freescale/u-boot-imx.git
cd u-boot-imx
git checkout 079e214888279518ce061c71238a74a0c3db2c28

and by properly patching the sources:

Host select

cd ~/Documents
git clone -b dora https://github.com/architech-boards/meta-tibidabo.git
patch -p1 -d u-boot-imx/ < meta-tibidabo/recipes-bsp/u-boot/u-boot-fslc-v2013.10/0001-tibidabo.patch

Now that you have the sources, you can start browsing the code from the following files:

Host select

~/Documents/u-boot-imx/board/architech/tibidabo/*
~/Documents/u-boot-imx/include/configs/tibidabo.h

Suppose you modified something and you want to recompile the sources to test your patches, well, you need a cross-toolchain (see Cross compiler Section). If you are not working with the virtual machine, the most comfortable way to get the toolchain is to ask Bitbake for it:

Host select

bitbake meta-toolchain

When Bitbake finishes, you will find an install script under directory:

Host select

/path/to/build/tmp/deploy/sdk/

Install the script, and you will get under the installation directory a script to source to get your environment almost in place for compiling. The name of the script is:

Host select

environment-setup-cortexa9hf-vfp-neon-poky-linux-gnueabi

Anyway, the environment is not quite right for compiling the bootloader and the Linux kernel, you need to unset a few variables:

Host select

unset CFLAGS CPPFLAGS CXXFLAGS LDFLAGS

Ok, now you a working environment to compile u-boot, just do:

Host select

cd ~/Documents/u-boot-imx
make mrproper
make tibidabo_config
make -j <2 * number of processor's cores> all

If you omit -j parameter, make will run one task after the other, if you specify it make will parallelize the tasks execution while respecting the dependencies between them. Generally, you will place a value for -j parameter corresponding to the double of your processor’s cores number, for example, on a quad core machine you will place -j 8.

Under the virtual machine, the toolchain is already installed under:

Host select

/home/architech/architech_sdk/architech/tibidabo/toolchain

In the very same directory there is a file, environment-nofs, that you can source that takes care of the environment for you when you want to compile the bootloader or the kernel

Host select

source /home/architech/architech_sdk/architech/tibidabo/toolchain/environment-nofs

Once the build process is complete, you will find u-boot.imx file in your sources directory, that’s the file you need to boot the board.

Linux Kernel¶

Like we saw for the bootloader, the first thing you need is: sources. Get them from Bitbake build directory (if you built the kernel with it) or get them from the Internet.

Bitbake will place the sources under directory:

Host select

/path/to/build/tmp/work/tibidabo-poky-linux-gnueabi/linux-imx/3.0.35-r38.14/git

If you are working with the virtual machine, you will find them under directory:

Host select

/home/architech/architech_sdk/architech/tibidabo/yocto/build/tmp/work/tibidabo-poky-linux-gnueabi/linux-imx/3.0.35-r38.14/git

We suggest you to don’t work under Bitbake build directory, you will pay a speed penalty and you could have troubles syncronizing the all thing. Just copy them some place else and do what you have to do.

If you didn’t build them already with Bitbake or you just want to do make every step by hand, you can always get them from the Internet by cloning the proper repository and checking out the proper hash commit:

Host select

cd ~/Documents
git clone git://git.freescale.com/imx/linux-2.6-imx.git
cd linux-2.6-imx
git checkout bdde708ebfde4a8c1d3829578d3f6481a343533a

and by properly patching the sources:

Host select

cd ~/Documents
git clone -b dora https://github.com/architech-boards/meta-tibidabo.git
patch -p1 -d linux-2.6-imx/ < meta-tibidabo/recipes-kernel/linux/linux-imx-3.0.35/0001-tibidabo.patch
cp meta-tibidabo/recipes-kernel/linux/linux-imx-3.0.35/defconfig linux-2.6-imx/.config

Now that you have the sources, you can start browsing the code from the following files:

Host select

~/Documents/linux-2.6-imx/arch/arm/mach-mx6/board-tibidabo.c
~/Documents/linux-2.6-imx/drivers/mtd/devices/n25q.c

Source the script to load the proper evironment for the cross-toolchain (see Cross compiler Section) and you are ready to customize the kernel:

Host select

cd ~/Documents/linux-2.6-imx
make menuconfig

and to compile it:

Host select

make -j <2 * number of processor's cores> uImage

By the end of the build process you will get uImage under arch/arm/boot.

Host select

~/Documents/linux-2.6-imx/arch/arm/boot/uImage

Meta Layer¶

A Yocto/OpenEmbedded meta-layer is a directory that contains recipes, configuration files, patches, etc., all needed by Bitbake to properly “see” and build a BSP, a distrubution, a (set of) package(s), whatever. meta-tibidabo is a meta-layer which defines the customizations to make to Freescale’s i.MX6 BSP and Yocto/OpenEmbedded in order to get a working system, tailor made of Tibidabo.

You can get it with git:

Host select

git clone -b dora https://github.com/architech-boards/meta-tibidabo.git

The machine name for Tibidabo is tibidabo.

The strictly BSP related recipes are located under:

Host select

meta-tibidabo/recipes-bsp/u-boot/
meta-tibidabo/recipes-bsp/bootscript/
meta-tibidabo/recipes-kernel/linux/

The other recipes are there just to customize other aspects of the system or to offer some facility to help you easily manage some task, for example, working with flash memory or partitions.

Tibidabo is powered by a big serial NOR memory, big enough to place a full featured root file system inside of it. However, you might not be interested in how to place the file system inside of it from the beginning and how to mount and unmount it inside your file system. There is a recipe inside meta-tibidabo, tibidabo-flash-utils, that will install three scripts inside the target file system to make the aforementioned tasks easy:

tibidabo_fs2flash
tibidabo_mount_flash
tibidabo_umount_flash

tibidabo_fs2flash takes as input a .tar.bz2 file, cleans and formats the flash memory, and finally takes the file you gave him to setup the root file system. For more information just run:

Host select

tibidabo_fs2flash -h

from Tibidabo shell.

tibidabo_mount_flash lets you mount the flash memory partition inside your filesystem (under /mnt/flash) without any effort and, likewise, tibidabo_umount_flash helps you unmounting the partition.

Remember that to install those scripts inside the target, you need to add meta-openmbedded/meta-oe meta layer to your bblayers.conf file. If you are working with Architech virtual machine, you don’t have to worry about that, everything is already in place.

tibidabo-flash-utils won’t be placed by default inside your file system, if you want it you need to add a line like this one to your local.conf file

Host select

IMAGE_INSTALL_append = " tibidabo-flash-utils"

Probably the most comfortable way, at least at the beginning, to build a valid SD card or SATA disk is to use file .sdcard that Bitbake emits when builds an image. However, Bitbake prepares a final iso image to write to the medium without any knowledge of its size. If you write the image on an SD card, for example, the first thing you notice is that the file system does not fit the card. How do you resize partitions and file systems to get the best out of your device? You have two possibilities:

put your SD card into your computer and use some tool, however, this option is available only on a Linux machines, or
resize the file system directly on the target board.

meta-tibidabo has a recipe, tibidabo-resize-partition, that puts a script inside the target file system that does online resizing of the last partition on the medium (that must be a primary partition), which can be an SD card, an mSATA hard disk, or an USB memory stick. The script name is tibidabo_resize_partition, to see the help just type:

Host select

tibidabo_resize_partition -h

on Tibidabo’s console.

An example for resizing the SD card iso image generated by Bitbake, can be:

Host select

tibidabo_resize_partition -d /dev/mmcblk0 -p 2

then follow the instructions, if any.

Even tibidabo-resize-partition won’t be placed by default inside the final root file system, unless you asks Bitbake for it, by adding the following line to your build directory local.conf file:

Host select

IMAGE_INSTALL_append = " tibidabo-resize-partition"

Root FS¶

By default, Tibidabo’s Yocto/OpenEmbedded SDK will generate three different types of files when you build an image:

.ext3,
.tar.bz2, and
.sdcard.

.ext3 is meant to be used by QEMU and won’t be discussed here. The .tar.bz2 file can be flattened out in your final medium partition (on SD card, flash memory, mSATA disk or USB stick) or on your host development system and used for build purposes with the Yocto Project. File .sdcard can be written out “as is” on the final medium with, for example, dd program:

Host select

sudo dd if=/path/to/image.sdcard of=/path/to/your/final/media/device

Where, the path to the image .sdcard file inside the SDK virtual machine is:

Host select

/home/architech/architech_sdk/architech/tibidabo/yocto/build/tmp/deploy/images/tibidabo

Warning

Be very careful when you use dd to write to a device to pick up the right device, otherwise you can mess up another disk you have on your machine, destroying its content forever!

Warning

The content of the media will be lost forever!

Important

Be sure you unmount the device from the filesystem before using dd program, you sure don’t want to have the operating system interfere during the write process.

After dd completes, run:

Host select

sync

Generally, especially at the beginning, when you build an image for Tibidabo is more comfortable to create an SD card using the .sdcard file, because you need almost zero effort to get everything running. However, if you need to develop for a while on the board this solution turns out to be inefficient, and you will want a faster solution. Assuming you already built an SD card out of a .sdcard file, you have an SD card with two partitions on it. The first one is supposed to contain the kernel image (uImage file) and the bootscript file, the second partition is supposed to contain the root file system. When you build a new file system you can delete everything contained on the second partition and you can untar file .tar.bz2 to the second partition on the SD card. If you have built a new kernel just overwrite the old one on the first partition. In case you have built a new bootloader take a look at Bootloader deploy.

Toolchain¶

Once your (virtual/)machine has been set up you can compile, customize the BSP for your board, write and debug applications, change the file system on-the-fly directly on the board, etc. This chapter will guide you to the basic use of the most important tools you can use to build customize, develop and tune your board.

Bitbake¶

Bitbake is the most important and powerful tool available inside Yocto/OpenEmbedded. It takes as input configuration files and recipes and produces what it is asked for, that is, it can build a package, the Linux kernel, the bootloader, an entire operating system from scratch, etc.

A recipe (.bb file) is a collection of metadata used by BitBake to set variables or define additional build-time tasks. By means of variables, a recipe can specify, for example, where to get the sources, which build process to use, the license of the package, an so on. There is a set of predefined tasks (the fetch task for example fetches the sources from the network, from a repository or from the local machine, than the sources are cached for later reuses) that executed one after the other get the job done, but a recipe can always add custom ones or override/modify existing ones. The most fine-graned operation that Bitbake can execute is, in fact, a single task.

Environment¶

To properly run Bitbake, the first thing you need to do is setup the shell environment. Luckily, there is a script that takes care of it, all you need to do is:

Host select

source /path/to/oe-init-build-env /path/to/build/directory

Inside the virtual machine, you can find oe-init-build-env script inside:

Host select

/home/architech/architech_sdk/architech/tibidabo/yocto/poky

If you omit the build directory path, a directory named build will be created under your current working directory.

By default, with the SDK, the script is used like this:

Host select

source /home/architech/architech_sdk/architech/tibidabo/yocto/poky/oe-init-build-env

Your current working directory changes to such a directory and you can customize configurations files (that the environment script put in place for you when creating the directory), run Bitbake to build whatever pops to your mind as well run hob. If you specify a custom directory, the script will setup all you need inside that directory and will change your current working directory to that specific directory.

Important

The build directory contains all the caches, builds output, temporary files, log files, file system images... everything!

The default build directory for Tibidabo is located under:

Host select

/home/architech/architech_sdk/architech/tibidabo/yocto/build

and the splash screen has a facility (a button located under Tibidabo’s page) that can take you there with the right environment already in place so you are productive right away.

Configuration files¶

Configuration files are used by Bitbake to define variables value, preferences, etc..., there are a lot of them. At the beginning you should just worry about two of them, both located under conf directory inside your build directory, we are talking about local.conf and bblayers.conf.

local.conf contains your customizations for the build process, the most important variables you should be interested about are: MACHINE, DISTRO, BB_NUMBER_THREADS and PARALLEL_MAKE. MACHINE defines the target machine you want compile against. The proper value for Tibidabo is tibidabo:

Host select

MACHINE ??= "tibidabo"

DISTRO let you choose which distribution to use to build the root file systems for the board. The default distribution to use with the board is:

Host select

DISTRO ?= "poky"

BB_NUMBER_THREADS and PARALLEL_MAKE can help you speed up the build process. BB_NUMBER_THREADS is used to tell Bitbake how many tasks can be executed at the same time, while PARALLEL_MAKE contains the -j option to give to make program when issued. Both BB_NUMBER_THREADS and PARALLEL_MAKE are related to the number of processors of your (virtual) machine, and should be set with a number that is two times the number of processors on your (virtual) machine. If for example, your (virtual) machine has/sees four cores, then you should set those variables like this:

Host select

BB_NUMBER_THREADS ?= "8"
PARALLEL_MAKE ?= "-j 8"

bblayers.conf is used to tell Bitbake which meta-layers to take into account when parsing/looking for recipes, machine, distributions, configuration files, bbclasses, and so on. The most important variable contained inside bblayers.conf is BBLAYERS, it’s the variable where the actual meta-layers layout get specified.

All the variables value we just spoke about are taken care of by Architech installation scripts.

Command line¶

With your shell setup with the proper environment and your configuration files customized according to your board and your will, you are ready to use Bitbake. The first suggestion is to run:

Host select

bitbake -h

Bitbake will show you all the options it can be run with. During normal activity you will need to simply run a command like:

Host select

bitbake <recipe name>

for example:

Host select

bitbake core-image-minimal-dev

Such a comman will build bootloader, Linux kernel and a root file system. core-image-minimal-dev tells Bitbake to execute whatever recipe

Host select

/home/architech/architech_sdk/architech/tibidabo/yocto/poky/meta/recipes-extended/images/core-image-minimal-dev.bb

tells it to do, so, you just place the name of the recipe without the extension.

Of course, there are times when you want more control over Bitbake, for example, you want to execute just one task like recompiling the Linux kernel, no matter what. That action can be achieved with:

Host select

bitbake -c compile -f virtual/kernel

where -c compile states the you want to execute the do_compile task and -f forces Bitbake to execute the command even if it thinks that there are no modifications and hence there is no need to to execute the same command again.

Another useful option is -e which gets Bitbake to print the environment state for the command you ran.

The last option we want to introduce is -D, which can be in fact repeated more than once and asks Bitbake to emit debug print. The amount of debug output you get depend on many times you repeated the option.

Of course, there are other options, but the ones introduced here should give you an head start.

Hob¶

Hob is a graphical interface for Bitbake. It can be called once Bitbake environment has been setup (see Bitbake) like this:

Host

hob

once open, you are required to select the machine you want to compile against

after that, you can select the image you want to build and, of course, you can customize it.

Eclipse¶

Eclipse is an integrated development environment (IDE). It contains a base workspace and the Yocto plug-in system to compile and debug a program for Tibidabo. Hereafter, the operating system that runs the IDE/debugger will be named host machine, and the board being debugged will be named target machine. The host machine could be running as a virtual machine guest operating system, anyway, the documentation for the host machine running as a guest operating system and as host operating system is exactly the same.

To write your application you need:

a root file system filesystem (you can use bitbake/hob to build your preferred filesystem) with development support (that is, it must include all the necessary libraries, header files, the tcf-agent program and gdbserver) included
a media with the root filesystem installed and, if necessary, the bootloader
Tibidabo powered up with the aforementioned root file system
a working serial console terminal
a working network connection between your workstation and the board (connector CN16 Port P0), so, be sure that:

your board has ip address 192.168.0.10 on interface pt0, and

your PC has an ip address in the same family of addresses, e.g. 192.168.0.100.

Creating the Project¶

You can create two types of projects: Autotools-based, or Makefile-based. This section describes how to create Autotools-based projects from within the Eclipse IDE. Launch Eclipse using Architech Splashscreen just click on Develop with Eclipse.

To create a project based on a Yocto template and then display the source code, follow these steps:

Select File→New→Project...
Under C/C++, double click on C Project to create the project.
Click on “Next” button
Expand Yocto Project ADT Autotools Project.
Select Hello World ANSI C Autotools Project. This is an Autotools-based project based on a Yocto Project template.

Put a name in the Project name: field. Do not use hyphens as part of the name.
Click Next.
Add information in the Author and Copyright notice fields.
Be sure the License field is correct.
Click Finish.

Note

If the “open perspective” prompt appears, click Yes so that you enter in C/C++ perspective. The left-hand navigation panel shows your project. You can display your source by double clicking on the project source file.

Select Project→Properties→Yocto Project Settings and check Use project specific settings

Building the Project¶

To build the project, select Project→Build Project. The console should update with messages from the cross-compiler. To add more libraries to compile:

Click on Project→Properties.
Expand the box next to Autotools.
Select Configure Settings.
In CFLAGS field, you can add the path of includes with -Ipath_include
In LDFLAGS field, you can specify the libraries you use with -lname_library and you can also specify the path where to look for libraries with -Lpath_library
Click on Project→Build All to compile the project

Note

All libraries must be located in /home/architech/architech_sdk/architech/tibidabo/sysroot subdirectories.

Deploying and Debugging the Application¶

Connect Tibidabo console to your PC and power-on the board. Once you built the project and the board is running the image, use minicom to run tcf-agent program in target board:

Board select

tibidabo login: root
/etc/init.d/tcf-agent restart

On the Host machine, follow these steps to let Eclipse deploy and debug your application:

Select Run→Debug Configurations...
In the left area, expand C/C++ Remote Application.
Locate your project and select it to bring up a new tabbed view in the Debug Configurations Dialog.

Insert in C/C++ Application the filepath of your application binary on your host machine.
Click on “New” button near the drop-down menu in the Connection field.
Select TCF icon.

Insert in Host Name and Connection Name fields the IP address of the target board. (e.g. 192.168.0.10)

Press Finish.
Use the drop-down menu now in the Connection field and pick the IP Address you entered earlier.
Enter the absolute path on the target into which you want to deploy the application. Use Browse button near Remote Absolute File Path for C/C++Application: field. No password is needed.

Enter also in the path the name of the application you want to debug. (e.g. Hello)

Select Debugger tab

In GDB Debugger field, insert the filepath of gdb for your toolchain

Host select

/home/architech/architech_sdk/architech/tibidabo/toolchain/sysroots/i686-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb

In Debugger window there is a tab named Shared Library, click on it.
Add the libraries paths lib and usr/lib of the rootfs (which must be the same used in the target board)

Host select

/home/architech/architech_sdk/architech/tibidabo/sysroot/lib
/home/architech/architech_sdk/architech/tibidabo/sysroot/usr/lib

Click Debug to bring up a login screen and login.
Accept the debug perspective.

Important

If debug does not work, check on the board if tcf-agent is running and gdbserver has been installed.

Qt Framework¶

The Qt Framework used by this SDK is composed of libraries for your host machine and your target. To compile the libraries for x86 you only need your distribution toolchain, while to compile the libraries for Tibidabo board you need the proper cross-toolchain (see Chapter Cross compiler for further information on how to get it).

This section just wants to show you how the framework has been generated.

Before to begin, keep in mind you might need to install the following package to compile yourself the libraries under Ubuntu

Host select

sudo apt-get install libxrender-dev

So, to install qt-everywhere for x86 from sources, the usual drill of download, uncompress, configure, make and make install is required:

Host select

wget http://download.qt-project.org/official_releases/qt/4.8/4.8.5/qt-everywhere-opensource-src-4.8.5.zip
unzip qt-everywhere-opensource-src-4.8.5.zip
cd qt-everywhere-opensource-src-4.8.5
./configure /*Choose Open source Edition when asked, and accept the license*/
make
make install

The installation of the libraries for Tibidabo from sources is sligthly more complicated. Once you downloaded and uncompressed the sources

Host select

wget http://download.qt-project.org/official_releases/qt/4.8/4.8.5/qt-everywhere-opensource-src-4.8.5.zip
unzip qt-everywhere-opensource-src-4.8.5.zip
cd qt-everywhere-opensource-src-4.8.5
cp -r mkspecs/qws/linux-arm-g++/ mkspecs/qws/linux-tibidabo-g++
cd mkspecs/qws/linux-tibidabo-g++/
gedit qmake.conf

you need to customize qmake configuration

Host select

#
# qmake configuration for building with arm-linux-g++
#

include(../../common/linux.conf)
include(../../common/gcc-base-unix.conf)
include(../../common/g++-unix.conf)
include(../../common/qws.conf)

# modifications to g++.conf
QMAKE_CC                = arm-poky-linux-gnueabi-gcc --sysroot=/home/architech/architech_sdk/architech/tibidabo/toolchain/sysroots/cortexa9hf-vfp-neon-poky-linux-gnueabi
QMAKE_CXX               = arm-poky-linux-gnueabi-g++ --sysroot=/home/architech/architech_sdk/architech/tibidabo/toolchain/sysroots/cortexa9hf-vfp-neon-poky-linux-gnueabi
QMAKE_LINK              = arm-poky-linux-gnueabi-g++ --sysroot=/home/architech/architech_sdk/architech/tibidabo/toolchain/sysroots/cortexa9hf-vfp-neon-poky-linux-gnueabi
QMAKE_LINK_SHLIB        = arm-poky-linux-gnueabi-g++ --sysroot=/home/architech/architech_sdk/architech/tibidabo/toolchain/sysroots/cortexa9hf-vfp-neon-poky-linux-gnueabi

# modifications to linux.conf
QMAKE_AR                = arm-poky-linux-gnueabi-ar cqs
QMAKE_OBJCOPY           = arm-poky-linux-gnueabi-objcopy
QMAKE_STRIP             = arm-poky-linux-gnueabi-strip

load(qt_config)

save the file and exit from gedit, then configure, make and make install

Host select

cd ../../../
./configure -no-pch -opensource -confirm-license -prefix /usr/local/Trolltech/Tibidabo -no-qt3support -embedded arm -nomake examples -nomake demo -little-endian -xplatform qws/linux-tibidabo-g++ -qtlibinfix E
make
make install

A comfortable tool to get your job done with Qt is Qt Creator, which its use will be introduced in Section Qt Creator. You can download it from here:

Tip

http://sourceforge.net/projects/qtcreator.mirror/files/Qt%20Creator%202.8.1/qt-creator-linux-x86-opensource-2.8.1.run/download

Qt Creator¶

Qt is a cross-platform application framework that is used to build applications. One of the best features of Qt is its capability of generating Graphical User Interfaces (GUIs).
Qt Creator is a cross-platform C++ IDE which includes a visual debugger, an integrated GUI layout and form designer. It makes possible to compile and debug applications on both x86 (host) and ARM (target) machines.
This SDK relies on version 4.8.5 of Qt and version 2.8.1 of Qt Creator.

Before getting our hands dirty, make sure all these steps have been followed:

Use Hob or Bitbake to build an image which includes: openssh, support for C++, tcf-agent and gdbserver.

Note

You could build qt4e-demo-image if you want to see the demo of Qt. Just remember to complete its file system with tcf-agent, gdbserver and openssh.

Deploy the root file system just generated on the final media used to boot the board
Replicate the same root file system into directory

Host select

/home/architech/architech_sdk/architech/tibidabo/sysroot

Copy the Qt Libraries to the board media used to boot

Host select

sudo mkdir -p /path/to/board/sysroot/usr/local/Trolltech/
sudo cp -r /usr/local/Trolltech/Tibidabo/* /path/to/board/sysroot/usr/local/Trolltech/

Copy the Qt Libraries to your sdk sysroot directory

Host select

sudo mkdir -p ~/architech_sdk/architech/tibidabo/sysroot/usr/local/Trolltech/
sudo cp -r /usr/local/Trolltech/Tibidabo/* ~/architech_sdk/architech/tibidabo/sysroot/usr/local/Trolltech

Unmount the media used to boot the board from your computer and insert it into the board
Power-On the board
Open up the serial console.

If you based your root file system on qt4e-demo-image, be sure you execute this command

Board select

/etc/init.d/qtdemo stop

to stop the execution of the demo application.

Provide a working network connection between your workstation and the board (connector CN16 Port P0), so, be sure that:

your board has ip address 192.168.0.10 on interface pt0, and

your PC has an ip address in the same family of addresses, e.g. 192.168.0.100.

Hello World!¶

The purpose of this example project is to generate a form with an “Hello World” label in it, at the beginning on the x86 virtual machine and than on Tibidabo board.

To create the project follow these steps:

Use the Welcome Screen to run Qt Creator by selecting Architech→Tibidabo→Develop with Qt Creator

Go to File -> Open File or Project to open QtHelloWorld.pro file located in /home/architech/architech_sdk/architech/tibidabo/workspace/qt/QtHelloWorld/ directory.
Click on “QtHelloWorld” icon to open project menu.

Select the build configuration: Desktop - Debug.

To build the project, click on the bottom-left icon.

Once you built the project, click on the green triangle to run it.

Congratulations! You just built your first Qt application for x86.

In the next section we will debug our Hello World! application directly on Tibidabo.

Debug Hello World project¶

Select build configuration: tibidabo - Debug and build the project.

Copy the generated executable to the target board (e.g /home/root/).

Host select

scp /home/architech/architech_sdk/architech/tibidabo/workspace/qt/build-QtHelloWorld-Hachiko-Debug/QtHelloWorld root@192.168.0.10:/home/root

Use minicom to launch gdbserver application on the target board:

Board select

gdbserver :10000 QtHelloWorld -qws

In Qt Creator, open the source file main.cpp and set a breakpoint at line 6. | To do this go with the mouse at line 6 and click with the right button to open the menu, select Set brackpoint at line 6

Go to Debug→Start Debugging→Attach To Remote Debug Server, a form named “Start Debugger” will appear, insert the following data:

Kit: tibidabo
Local executable:

Host select

/home/architech/architech_sdk/architech/tibidabo/workspace/qt/build-QtHelloWorld-tibidabo-Debug/QtHelloWorld

Press OK button to start the debug.

The hotkeys to debug the application are:

F10: Step over
F11: Step into
Shift + F11: Step out
F5: Continue, or press this icon:

To successfully exit from the debug it is better to close the graphical application from the target board with the mouse by clicking on the ‘X’ symbol.

Cross compiler¶

Yocto/OpenEmbedded can be driven to generate the cross-toolchain for your platform. There are two common ways to get that:

Host select

bitbake meta-toolchain

Host select

bitbake <image recipe name> -c populate_sdk

The first method provides you the toolchain, you need to provide the file system to compile against, the second method provides both the toolchain and the file system along with -dev and -dbg packages installed.

Both ways you get an installation script.

The virtual machine has a cross-toolchain installed for each board, each generated with meta-toolchain. To use it just do:

Host select

source /home/architech/architech_sdk/architech/tibidabo/toolchain/environment

to compile Linux user-space stuff. If you want to compile kernel or bootloader then do:

Host select

source /home/architech/architech_sdk/architech/tibidabo/toolchain/environment-nofs

and you are ready to go.

Opkg¶

Opkg (Open PacKaGe Management) is a lightweight package management system. It is written in C and resembles apt/dpkg in operation. It is intended for use on embedded Linux devices and is used in this capacity in the OpenEmbedded and OpenWrt projects.

Useful commands:

update the list of available packages:

Board select

opkg update

list available packages:

Board select

opkg list

list installed packages:

Board select

opkg list-installed

install packages:

Board select

opkg install <package 1> <package 2> ... <package n>

list package providing <file>

Board select

opkg search <file>

Show package information

Board select

opkg info <package>

show package dependencies:

Board select

opkg whatdepends <package>

remove packages:

Board select

opkg remove <package 1> <package 2> ... <package n>

Force Bitbake to install Opkg in the final image¶

With some images, Bitbake (e.g. core-image-minimal) does not install the package management system in the final target. To force Bitbake to include it in the next build, edit your configuration file

Host select

/home/architech/architech_sdk/architech/tibidabo/yocto/build/conf/local.conf

and add this line to it:

Host select

IMAGE_FEATURES_append = " package-management"

Create a repository¶

opkg reads the list of packages repositories in configuration files located under /etc/opkg/. You can easily setup a new repository for your custom builds:

Install a web server on your machine, for example apache2:

Host select

sudo apt-get install apache2

Configure apache web server to “see” the packages you built, for example:

Host select

sudo ln -s /home/architech/architech_sdk/architech/tibidabo/yocto/build/tmp/deploy/ipk/ /var/www/tibidabo-ipk

Create a new configuration file on the target (for example /etc/opkg/my_packages.conf) containing lines like this one to index the packages related to a particular machine:

Board select

src/gz tibidabo http://192.168.0.100:8000/tibidabo-ipk/tibidabo

To actually reach the virtual machine we set up a port forwarding mechanism in Chapter Virtual Machine so that every time the board communicates with the workstation on port 8000, VirtualBox actually turns the communication directly to the virtual machine operating system on port 80 where it finds apache waiting for it.

Connect the board and the personal computer you are developing on by means of an ethernet cable
Update the list of available packages on the target

Board select

opkg update

Update repository index¶

Sometimes, you need to force bitbake to rebuild the index of packages by means of:

Host select

bitbake package-index

The board¶

This chapter introduces the board, its hardware and how to boot it.

Hardware¶

The hardware documentation of Tibidabo can be found here:

http://downloads.architechboards.com/doc/Tibidabo/download.html

Power-On¶

Tibidabo takes the power from connector CN19. The board is shipped with an external power adapter.

To assemble it, take the power socket adapter compatible with your country, plug it in the power adapter.

_images/board_poweron_power_supply_adapter_selection.jpg

When in position, you should hear a slight click.

_images/board_poweron_power_supply_install_adapter.jpg

To power-on the board, just connect the external power adapter to Tibidabo connector CN19.

Serial Console¶

On Tibidabo there is the dedicated serial console connector CN1

which you can connect, by means of a mini-USB cable, to your personal computer.

Note

Every operating system has its own killer application to give you a serial terminal interface. In this guide, we are assuming your host operating system is Ubuntu.

On a Linux (Ubuntu) host machine, the console is seen as a ttyUSBX device and you can access to it by means of an application like minicom.

Minicom needs to know the name of the serial device. The simplest way for you to discover the name of the device is by looking to the kernel messages, so:

clean the kernel messages

Host select

sudo dmesg -c

connect the mini-USB cable to the board already powered-on
display the kernel messages

Host select

dmesg

read the output

Host select

[ 2614.290675] usb 3-4: >new full-speed USB device number 4 using xhci_hcd
[ 2614.313854] usb 3-4: >New USB device found, idVendor=0403, idProduct=6015
[ 2614.313861] usb 3-4: >New USB device strings: Mfr=1, Product=2, SerialNumber=3
[ 2614.313865] usb 3-4: >Product: FT230X Basic UART
[ 2614.313868] usb 3-4: >Manufacturer: FTDI
[ 2614.313870] usb 3-4: >SerialNumber: DN002OZI
[ 2614.379284] usbcore: registered new interface driver usbserial
[ 2614.379298] usbcore: registered new interface driver usbserial_generic
[ 2614.379306] USB Serial support registered for generic
[ 2614.379310] usbserial: USB Serial Driver core
[ 2614.387899] usbcore: registered new interface driver ftdi_sio
[ 2614.387914] USB Serial support registered for FTDI USB Serial Device
[ 2614.387997] ftdi_sio 3-4:1.0: >FTDI USB Serial Device converter detected
[ 2614.388029] usb 3-4: >Detected FT-X
[ 2614.388031] usb 3-4: >Number of endpoints 2
[ 2614.388034] usb 3-4: >Endpoint 1 MaxPacketSize 64
[ 2614.388035] usb 3-4: >Endpoint 2 MaxPacketSize 64
[ 2614.388037] usb 3-4: >Setting MaxPacketSize 64
[ 2614.388260] usb 3-4: >FTDI USB Serial Device converter now attached to /dev/ttyUSB0
[ 2614.388288] ftdi_sio: v1.6.0:USB FTDI Serial Converters Driver

As you can see, here the device has been recognized as /dev/ttyUSB0.

Now that you know the device name, run minicom:

Host select

sudo minicom -ws

If minicom is not installed, you can install it with:

Host select

sudo apt-get install minicom

then you can setup your port with these parameters:

Host select

+-----------------------------------------------------------------------+
| A -    Serial Device      : /dev/ttyUSB0                              |
| B - Lockfile Location     : /var/lock                                 |
| C -   Callin Program      :                                           |
| D -  Callout Program      :                                           |
| E -    Bps/Par/Bits       : 115200 8N1                                |
| F - Hardware Flow Control : No                                        |
| G - Software Flow Control : No                                        |
|                                                                       |
|    Change which setting?                                              |
+-----------------------------------------------------------------------+
        | Screen and keyboard      |
        | Save setup as dfl        |
        | Save setup as..          |
        | Exit                     |
        | Exit from Minicom        |
        +--------------------------+

If on your system the device has not been recognized as /dev/ttyUSB0, just replace /dev/ttyUSB0 with the proper device.

Once you are done configuring the serial port, you are back to minicom main menu and you can select exit.

Let’s boot¶

The boot process of an i.MX6 processor is quite complex. After a Power On Reset (POR) the processor starts executing the internal ROM program. The boot mode is based on the binary value stored in the internal BOOT_MODE register:

BOOT_MODE[1:0]	Boot Type
00	Boot from fuses
01	Serial downloader
10	Internal boot
11	Reserved

BOOT_MODE[1] is read from SRC_BOOT_MODE1 pin (F12). BOOT_MODE[0] is read from SRC_BOOT_MODE0 pin (C12).

On Tibidabo, switches 1 and 2 of SW1 let you define the values for BOOT_MODE register:

SW1 switch 1 controls BOOT_MODE[0]
SW1 switch 2 controls BOOT_MODE[1]

in the image BOOT_MODE[1:0] = 10 (Internal boot).

The other switches of SW1 are used for Internal boot mode and will be explained later in this chapter.

eFUSEs¶

eFUSEs are One Time Programmable (OTP) devices. The On-Chip OTP Controller (OCOTP_CTRL) manages reads/writes from/to eFUSEs and memory mapping of the values by means of shadow registers. You can blow the fuses by means of u-boot fuse command, be very careful because fuses are one time programmable only, a mistake will last forever! However, even if you manage to brik the board, you can always use it with the Serial downloader boot mode.

Boot from FUSEs¶

In boot from fuses mode the boot ROM uses the fuses values to decide how to boot. The boot flow is controlled by BT_FUSE_SEL eFUSE:

if 1 the boot ROM will load the bootloader according to the state of eFUSEs,
if 0 (the device has not yet been programmed) the boot ROM will jump to serial downloader mode.

Tibidabo is shipped with no fuse blown so you can blow the fuses when you think you are ready.

For example, to instruct the processor to boot from SD card you can blow the following fuses with u-boot fuse command:

Board select

fuse prog 0 5 0x00001040
fuse prog 0 6 0x00000010

where, the first command setup the boot from sd card, while the second command sets BT_FUSE_SEL = 1.

Again, if you want to instruct the processor to boot from SPI NOR you can blow the following fuses:

Board select

fuse prog 0 5 0x18000030
fuse prog 0 6 0x00000010

where the first command setup the boot from serial ROM, and the second command sets BT_FUSE_SEL = 1.

Serial Downloader¶

Serial downloader boot mode tells the processor’s boot ROM to load registers configuration and bootloader from USB. To work with this boot mode you need a micro USB cable to connect the board (connector CN4) to your Personal Computer and a software installed on your PC, speaking of which, if you have a Microsoft Windows operating system you need Freescale’s i.MX6 Manufacturing Tool that can be downloaded from:

http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=IMX6_SW

If you have a Linux operating system instead, you need Boundary Devices imx_usb_loader tool that can be obtained from their git repository:

git://github.com/boundarydevices/imx_usb_loader

To compile imx_usb_loader project you need libusb installed on your distribution. This is the set of commands needed on an Ubuntu machine to setup the tool:

Host select

sudo apt-get install libusb-1.0 libusb-dev libusb-1.0-0-dev
git clone git://github.com/boundarydevices/imx_usb_loader
cd imx_usb_loader
make

Once the tool is ready, power up the board, then you can download your u-boot.imx on the board with this command:

Host select

./imx_usb /path/to/your/u-boot.imx

Internal Boot¶

If BT_FUSE_SEL = 1 then all boot options are controlled by the eFUSEs, otherwise, if BT_FUSE_SEL = 0 then specific boot configuration parameters may be set using GPIO pins rather than eFUSEs. The use of GPIOs is intended for development only. If an error occurs, the boot ROM jumps to serial downloader boot mode. On Tibidabo, SW1 switches 3, 4, 5, 6 (along with a set of jumpers available on the bottom side of the board) can define a custom boot mode so you can simulate your configuration before blowing fuses.

SW1[6:3] = BOOT_CFG[24]-BOOT_CFG1[6:4]	Boot Device
1100	SD regular boot
1101	SD fast boot
0011	Serial NOR
0010	SATA

For example, this is the selection of the boot from SD card (fast boot)

_images/boot_switches_device_selection.jpg

Bootloader deploy¶

When you boot with serial downloader, you just do:

Host select

cd /path/to/imx_usb
./imx_usb /path/to/your/u-boot.imx

but when you boot from fuses or you want to use the internal boot you need to understand where the processor looks for the bootloader binary. If you want to boot from SPI NOR, you need to write the bootloader binary (u-boot.imx) to the flash memory. You can do it with from u-boot or from Linux as well. To do it from u-boot, you first need to read into memory a valid bootloader binary (from ethernet, SD card, mSATA or USB), then:

Board select

sf probe
sf erase 0x64000
sf write $loadaddr 0x400 $filesize

where loadaddr is an environment variable where the memory load address is defined, and filesize is the size of file u-boot.imx that has been previously loaded to memory. Be careful, by default the bootloader is configured to save the environment inside the SD card, not in the flash itself. If you prefer to save the environment inside the SPI NOR, open u-boot file:

Host select

/path/to/u-boot/sources/include/configs/tibidabo.h

define macro CONFIG_ENV_IS_IN_SPI_FLASH by uncommenting it, comment CONFIG_ENV_IS_IN_MMC definition, and recompile the bootloader.

In case you want to boot from SD card, you need to write the bootloader starting at address 1024 on the medium, just inside the MBR gap. The first partition on the medium must start at an address that leaves enough room for then bootloader and its environment variables, block 8192 (with block size of 512) will be more then enough (the environment gets written/read on the SD card with an offset of 384KB and will be 8KB large). Good, but how do you write your u-boot binary on the SD card? If you do not care to customize the bootloader, and you built an image with Yocto/OpenEmbedded, you may have noticed that under the directory where Yocto/OpenEmbedded puts all the built images there is a file with extension .sdcard. Well, such a file is an iso and can be written as is to the SD card device, just:

Host select

sudo dd if=/path/to/image.sdcard of=/path/to/your/sd/card/device

Once the iso has been written, the SD card will have all you need to make it boot from it (it will have bootloader, kernel image, file system and kernel modules). Ok, but what if you want to rewrite just the bootload and not the all image? You can overwrite the bootloader on the SD card always with dd:

Host select

sudo dd if=/path/to/u-boot.imx of=/path/to/your/sd/card/device bs=1k seek=1

Bootscript¶

Once the bootloader has been properly deployed (see Bootloader deploy), you turn on the board, the bootloader gets loaded and starts running until it gets to the boot command. What happens next? Well, since the board have a lot of options from where to load the kernel and with which options run the kernel, where is the root file system, which video mode, etc..., you get the best result if you have a simple facility to customize the system boot process yourself instead of having a milion combinations script that doesn’t do exactly what you want it to do. The facility we are talking about is a simple u-boot script that the default boot command tries to load from, in order, mSATA, SD and tftp. When u-boot finds it, the script gets executed. That’s it. Here is an example of an u-boot script that tries to load the Linux kernel binary from the SD card first partition (the partition can be FAT, EXT2, EXT3 or EXT4), and tells the kernel to use the second partition of the SD card as root partition:

Host select

setenv bootargs ${bootargs} vmalloc=400M root=/dev/mmcblk0p2 rw,rootwait consoleblank=0 video=mxcfb0:dev=hdmi,1280x720M@60,if=RGB24 video=mxcfb1:dev=lcd,CLAA-WVGA,if=RGB666 fbmem=28M,10M
mmc dev 0
for file_system in fat ext2; do
    ${file_system}load mmc 0:1 ${loadaddr} /uImage && bootm ${loadaddr}
done
echo Impossible to boot from SD card partition 1

But that is an u-boot script, not the bootscript, to make it suitable as a bootscript you need to give it mkimage as input first. If you are not that comfortable with mkimage, you can have a simplified interface offered by create-bootscript.sh script. The usage is very simple, just run it like this:

Host select

./create-bootscript.sh -i /path/to/your/u-boot/script -o /path/to/where/to/emit/the/final/bootscript

where parameter -i stands for source file to take as input and -o stands for “binary” file to emit as output.

Copy the output file to where you want it to be found, that is:

SD card, first or second partition in the root director
mSATA, first or second partition in the root directory, or
TFTP directory on your computer.

Important

Name the script exactly bootscript

Video modes¶

Tibidabo has three possible video outputs:

HDMI via connector CN8
LVDS via connector CN3, thought for SAMSUNG’s MODEL LTI460HN08 (connector pad numeration is reversed with respect to SAMSUNG monitor datasheet to direct use of a flat ribbon lvds cable)
LVDS via display port connector CN22, meant for SILICA lvds display

Warning

Do not connect CN22 to DISPLAY PORT devices, CN22 uses just the connector of a DISPLAY PORT but the signals are meant to work just with Silica’s LCD (LVDS) displays.

If you want to boot using SILICA’s lcd as the only video output device you need to add to the kernel command line something like:

video=mxcfb0:dev=ldb,LDB-WVGA,if=RGB666 ldb=dul0

If you want to boot using SAMSUNG’s display as the only video output device you need to add to the kernel command line something like:

video=mxcfb0:dev=ldb,LDB-1080P60,if=RGB666 ldb=spl0

If you want to boot using a full HD HDMI display as the only video output device you need to add to the kernel command line something like:

video=mxcfb0:dev=hdmi,1920x1080M@60,if=RGB24

You can have a video output on more than one device and the resolutions stated before are not the only resolutions available. Keep also into account that the LVDS output has several working modes, like: spl, dul, sin, sep (please, have a look at /drivers/video/mxc/ldb.c).

Network¶

Tibidabo networking is powered by MARVELL Gigabit switch MV88E6123. On the board there is a dual ethernet connector, each connector has a name that is printed on the PCB (P0 and P1). The switch is supported both by u-boot and Linux kernel, however, u-boot support is limited so, if you need u-boot to load files from the network use just one of the two ports. Under Linux, instead, the default network configuration is:

Board select

root@tibidabo:~# ifconfig
eth0      Link encap:Ethernet  HWaddr 1E:ED:19:27:1A:B3
          UP BROADCAST RUNNING MULTICAST  MTU:1492  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:2 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:0 (0.0 B)  TX bytes:644 (644.0 B)

lo        Link encap:Local Loopback
          inet addr:127.0.0.1  Mask:255.0.0.0
          UP LOOPBACK RUNNING  MTU:16436  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)

but if you take a closer look, you discover that there are more interfaces available:

Board select

root@tibidabo:~# ifconfig -a
eth0      Link encap:Ethernet  HWaddr 1E:ED:19:27:1A:B3
          UP BROADCAST RUNNING MULTICAST  MTU:1492  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:2 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:0 (0.0 B)  TX bytes:644 (644.0 B)

lo        Link encap:Local Loopback
          inet addr:127.0.0.1  Mask:255.0.0.0
          UP LOOPBACK RUNNING  MTU:16436  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)

pt0       Link encap:Ethernet  HWaddr 1E:ED:19:27:1A:B3
          BROADCAST MULTICAST  MTU:1492  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)

pt1       Link encap:Ethernet  HWaddr 1E:ED:19:27:1A:B3
          BROADCAST MULTICAST  MTU:1492  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)

where pt0 is the network inteface corresponding to connector P0, while pt1 is the network interface corresponding to connector P1.

eth0 has a random MAC address assigned and, as you can see, pt0 and pt1 have the same address. To properly use the network you need to be sure that pt0 and pt1 have unique MAC addresses. You can change the MAC address of a specific network interface by means of this command:

Board select

ifconfig <port> hw ether <new mac address>

substitute <port> with pt0 or pt1, and <new mac address> with the MAC address you decided to assign.

If you want that configuration to be brought up at boot you can add a few line in file /etc/network/interfaces, for example, if you want pt0 to have a fixed ip address (say 192.168.0.10) and MAC address of value 1e:ed:19:27:1a:b6 you could add the following lines:

Board select

auto pt0
iface pt0 inet static
    address 192.168.0.10
    netmask 255.255.255.0
    hwaddress ether 1e:ed:19:27:1a:b6

You can, of course, define the default configuration for pt1 as well.

Add-ons¶

Huawei MU609¶

MU609 is high-quality designed HSPA module in small size and Huawei standard LGA form factor which is specially designed for industrial-grade M2M applications such as vehicle telematics, tracking, mobile payment, industrial router, safety monitor and industrial PDAs. Tibidabo sources can be easily updated to support MU609.

Download the kernel patch and the configuration fragment to ~/Documents. Be sure you followed the guide on Tibidabo linux kernel, and once you have prepared the kernel sources to be compiled by hand you can apply the patches:

Host select

patch -p1 -d ~/Documents/linux-2.6-imx/ < ~/Documents/0002-tibidabo-huawei.patch

To make the device work properly, make sure the Linux kernel is configured according to the configuration fragment file (~/Documents/huawei-mu609.cfg) you just downloaded.

Note

The patches have been tested with module MU609 programmed with firmware version 12.105.29.00.00

FAQ¶

Virtual Machine¶

What is the password for the default user of the virtual machine?¶

The password for the default user, that is architech, is:

Host

architech

What is sudo?¶

sudo is a program for Unix-like computer operating systems that allows users to run programs/commands with the security privileges of another user, normally the superuser or root. Not all the users can call sudo, only the sudoers, architech (the default user of the virtual machine) user is a sudoer. When you run a command preceeded by sudo Linux will ask you the user password, for architech user the password is architech.

What is the password for user root?¶

By default, Ubuntu 12.04 32bit comes with no password defined for roor user, to set it run the following command:

Host

sudo passwd root

Linux will ask you (twice, the second time is just for confirmation) to write the password for user root.

Table Of Contents

Architech’s Tibidabo documentation¶

Notations¶

Chapters¶

Unboxing¶

Quick start guide¶

Install¶

Download VirtualBox¶

Create a new Virtual Machine¶

Setup the network¶

Customize the number of processors¶

Create a shared folder¶

Build¶

Deploy¶

Boot¶

Code¶

Debug¶

SDK Architecture¶

SDK¶

Virtual Machine¶

Download VirtualBox¶

Create a new Virtual Machine¶

Setup the network¶

Customize the number of processors¶

Create a shared folder¶

VM content¶

Splash screen¶

Create SDK¶

Installation¶

Install a clone of the virtual machine inside your native machine¶

Install just one board¶

Yocto¶

BSP¶

U-boot¶

Linux Kernel¶

Meta Layer¶

Root FS¶

Toolchain¶

Bitbake¶

Environment¶

Configuration files¶

Command line¶

Hob¶

Eclipse¶

Creating the Project¶

Building the Project¶

Deploying and Debugging the Application¶

Qt Framework¶

Qt Creator¶

Hello World!¶

Debug Hello World project¶

Cross compiler¶

Opkg¶

Force Bitbake to install Opkg in the final image¶

Create a repository¶

Update repository index¶

The board¶

Hardware¶

Power-On¶

Serial Console¶

Let’s boot¶

eFUSEs¶

Boot from FUSEs¶

Serial Downloader¶

Internal Boot¶

Bootloader deploy¶

Bootscript¶

Video modes¶

Network¶

Add-ons¶

Huawei MU609¶

FAQ¶

Virtual Machine¶

What is the password for the default user of the virtual machine?¶

What is sudo?¶

What is the password for user root?¶

Tibidabo¶