Angstrom Linux for EM-X270

Introduction

The run-time Linux image for EM-X270 is based on Angstrom Linux 2007.1. The CompuLab Linux package for EM-X270 includes ready to run NAND flash image, Linux kernel configuration and source code patches, and OpenEmbedded configuration files used to build the Angstrom Linux image. The package also features LiveDisk image for easy installation of the run-time Angstrom Linux on EM-X270. The default Angstrom Linux image takes less than 50Mbyte of flash space, and includes above 300 software packages. Among them:

Core system
X11 Windowing System
Matchbox desktop manager
Minimo web browser
PIM suite
Phone dialer

The Image installation section gives brief introduction on how to setup and start using the run-time Linux image. Further we describe in more detail package structure and give guidelines for image modification and software development for EM-X270 platform.

Image installation

Installation with LiveDisk

Extract the contents of LiveDisk.zip from this package onto USB flash drive.
Insert the flash drive into "USB-A to mini-USB" adaptor supplied with EvalKit, and connect the other side of the adaptor to EM-X270.
Power up the EM-X270 while holding the "suspend/resume" button. You may release the button as soon as you see CompuLab logo on the LCD screen.
Wait until systems starts. You will be asked to calibrate the touchscreen and create a user to log in to the system
Click on the Updater icon. EM-X270 updater application will start.
Click Forward to continue, or Cancel if you decided to abandon the installation
By default, updater application will search for /media/usb/em_x270.img image file. Press Open or fill the filename entry to choose another image.
After you've chosen the image, press Forward.
Press Start! button to update EM-X270.
After restart the system will boot Angstrom Linux from the internal NAND flash. Note, that the first boot takes relatively much time because Angstrom Linux performs a lot of one-time initialization tasks.

Make sure you do not interrupt the updater application after pressing Start!, keep the USB flash drive inserted and the device powered up during the update process.

Any time you would like to boot clean system from the USB flash drive, you can unpack the original LiveDisk.zip to the USB flash drive and start over.

Package contents

images

LiveDisk.zip - archive contains files for USB LiveDisk.
em_x270.img.bz2 - ready to run image for EM-X270 NAND flash.
angstrom-em-x270.tar.bz2 - archive of root file system

kernel

uImage-2.6.23-em-x270 - ready to run Linux kernel image for EM-X270
linux-2.6.23-em-x270.config - Linux kernel configuration file
linux-2.6.23-em-x270.pacth - patch vs. Linux kernel 2.6.23 with support for EM-X270 peripherals

oe

The oe directory contains configuration files and EM-X270 specific package definition for OpenEmbedded. These files should reside under the OpenEmbedded root on your host system. Please consult OpenEmbedded reference manual for further details.

build/conf/local.conf - configuration file used to build Angstrom Linux image for EM-X270
org.openembedded.dev/conf/machine/em-x270.conf - machine definition file
org.openembedded.dev/packages/linux/em-x270_2.6.23.bb - recipe to build Linux kernel for EM-X270
org.openembedded.dev/packages/linux/em-x270-2.6.23/ - files needed to build Linux kernel for EM-X270

utilities

utilities directory contains miscellaneous utilities useful for development

create_image.sh - the script creates an image compatible with EM-X270 updater application
fixup-angstrom.sh - the script used to update several configuration files in the Angstrom Linux image before deploying the image to the device
patches/ - patches used by the fixup-angstrom.sh
updater/ - sources of EM-X270 updater application

EM-X270 specific device options

Certain on-board devices may be of particular interest for EM-X270 application developers. We provide here details of their operation in Angstrom Linux for EM-X270.

GSM/GPRS modem

GSM/GPRS modem is connected to BTUART of PXA270 processor and can be accessed through /dev/ttyS1 device node. In Angstrom Linux for EM-X270 it can operated either by GSMD daemon and a Dialer front end for voice calls, or PPPD daemon for data connection. At the system startup GSMD is enabled and it it possible to issue voice phone calls using Dialer application. If you'd like to switch to data communications using GPRS, you shoud tap "Other" -> "GPRS". To switch back to voice calls mode tap "Other" -> "GSM".

The data connection with GPRS modem may require update of provider-specific details in /etc/ppp/gprs-connect, /etc/ppp/gprs-options and /etc/ppp/pap-secrets files.

Example: /etc/ppp/gprs-connect

TIMEOUT         60
ABORT           'BUSY'
ABORT           'ERROR'
ABORT           'NO CARRIER'
''              'AT'
OK              AT+CGDCONT=1,"IP","internet","0.0.0.0",0,0
OK              ATD*99***1#
CONNECT         ''

The string "internet" in this example containts the APN (Access Point Name ) address of your GPRS provider. Contact your provider to know what is the right address and username/password to use. The username and password should reside in /etc/ppp/pap-secrets (both are a in the below example):

Example: /etc/ppp/pap-secrets

# Secrets for authentication using PAP
# client        server  secret                  IP addresses
  'a'            *       'a'                    *

It is important to set the user field of /etc/ppp/gprs-options to the same username.

GPS reciever

GPS reciever is connected to STUART of PXA270 processor and can be accessed through /dev/ttyS2 device node.

Wireless LAN

Wireless LAN on EM-X270 supports 802.11b. Currently Angstrom Linux for EM-X270 does not enable this interface automaticaly. The driver for wireless LAN chip present on EM-X270 is provided by the chip manufacturer and therefore redistributed by CompuLab in binary form. The driver is called bgw200 and can be enabled using

echo 1 > /sys/devices/platform/wlan/pwr_on
modprobe bgw200
iwconfig eth1 essid <your_ESSID>

You can use Linux standard iwconfig, iwscan, iwevent, iwgetid, iwlist, iwpriv, iwspy utilities.

VGA display

EM-X270 with EB-X270 extender board supports connection of standard VGA display. To direct graphics output to VGA append "display=vga" to kernel command line. Tap keyboard icon on the panel, tap "Other" -> "Terminal", and in the terminal window do

su
cmd_line=`fw_printenv boot_angstrom | cut -d= -f2- | \
          sed 's/setenv bootargs/setenv bootargs display=vga/'`
fw_setenv boot_angstrom $cmd_line

If you would like to use mouse rather than touchscreen, you should edit the /etc/matchbox/session file and change "-use_cursor no" to "-use_cursor yes"

Power management

Angstrom Linux for EM-X270 allows user to take full advantage of EM-X270 flexible power management capabilities. It supports very low power sleep mode, provides abitity to swtich on and off certain units power and implements charging supervision mechanism for battery powered operation mode.

Battery Charger Management

When EM-X270 operates as a battery powered device, battery monitoring and charging is supervised by the Linux kernel. It detects insertion and removal of USB OTG connector and performs operations necessary to ensure safe battery charging.

On-board Devices Power Control

The on-board WiFi interface, GPS reciever and cellular voice and GSM/GPRS modem can be switched on and off on the fly. Linux kernel for EM-X270 defines pwr_on attribute for these devices. The attributes can be accessed via sysfs:

/sys/devices/platform/wlan/pwr_on
/sys/devices/platform/gps/pwr_on
/sys/devices/platform/gprs/pwr_on

Writing 1 to appropriate attribute file will enable the device power and writng 0 will disable it. For instance, to enable the GSM/GPRS unit:

echo 1 > /sys/devices/platform/gprs/pwr_on

Software development

Cross-Compilation

In the embedded world, software development is almost always done on a system other than the one on which the software will eventually run. It is common nowadays to use x86 desktop workstations to develop software for ARM-based embedded products. Such an approach requires cross-compilation tools and environment.

Building a cross compiler became recently relatively simple thanks to such tools as crosstool. But working cross-compiler is not enough. Modern applications rely on variety of libraries, frameworks and utilities. All these has to be cross-compiled also. Most Linux and Open Source software projects use a configure script to configure their software for compilation. Configure is meant to ease configuring the software for compilation and its default assumption is that the software will be run in the same environment and processor in which it was compiled and run from the place in which it was installed. The second problem of many configure scripts, is that most application developers don't take cross-compilation into account, so configure ends up cross-compiling test code and trying to run it on the build host, which breaks the configuration. Thus, cross compilation tools are not enough for embedded application development and complete cross-development environment is required.

Nowadays, there are several popular cross-development environments: Scratchbox, OpenEmbedded, it's spin-off Poky Linux, and Embedded Linux Development Kit.

Scratchbox

Scratchbox is a chrooted cross-compilation environment. This means one has to log into the Scratchbox like one would log into a real machine. Once you logged in, you develop your application as if you were developing it on native ARM machine, but with computational power of modern x86 workstation.

OpenEmbedded

OpenEmbedded is a development environment allowing users to target a wide variety of devices and configurations. OpenEmbedded enables you to build an entire Linux distribution optimized for specific device needs. Additionally, it includes devshell addon that provides you with an interactive shell with all the appropriate variables set for cross-compiling.

Poky Linux

Poky is an embedded Linux build system, distribution and developer environment which builds upon OpenEmbedded technologies. It is less generic than OpenEmbedded, but on the other side, you may find it more tuned and optimized for such devices as PDAs and smartphones.

ELDK

Embedded Linux Development Kit (ELDK) is a collection of GNU cross development tools, such as compilers, binutils, gdb, etc., and a number of pre-built target tools and libraries necessary to provide some functionality on the target system. It is not full-featured cross-development environment like Scratchbox, OpenEmbedded, or Poky, but it is known to have stable and reliable cross compilation tools.

Networked Root Filesystem

It is convenient to use the same filesystem on host workstation and target device. Because the filesystem exists on the workstation, it is easy to use it for cross-development. And because the workspace is mounted on the target device also, we can test code developed on the host by running it on the target device.

The host workstation need to have NFS server packages installed. The package name depends on the distribution you use.

Example: Gentoo

emerge -av nfs-utils

Example: Ubuntu/Debian

apt-get install nfs-kernel-server nfs-common portmap

Example: Fedora Core

yum install nfs-utils

After the NFS tools are installed on the host workstation, you can use images/angstrom-em-x270.tar.bz2 for networked root filesystem. Just extract the archive to some directory:

mkdir /home/development/em-x270/rootfs
cd /home/development/em-x270/rootfs
tar xjf /path/to/em-x270-package/images/angstrom-em-x270.tar.bz2

add this directory to /etc/exports:

/home/development/em-x270/rootfs \
        192.168.0.0/255.255.255.0(no_root_squash,sync,rw)

and make the NFS server export this directory:

/usr/sbin/exportfs -a

Linux kernel has Root on NFS feature, allowing mounting root filesystem form a server rather than from local storage device. Default kernels shipped by CompuLab have this feature built in. If you are planing to use custom kernel you can enable Root on NFS as follows: in the kernel configuration choose "Networking -> Networking Options" menu and enable "IP: kernel level autoconfiguration"

  +-------------------------- Networking options ---------------------------+
  |  Arrow keys navigate the menu.  <Enter> selects submenus --->.          |
  |  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes, |
  |  <M> modularizes features.  Press <Esc><Esc> to exit, <|> for Help, </> |
  |  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < >       |
  | +---------------------------------------------------------------------+ |
  | |    [ ] Network packet debugging                                     | |
  | |    <*> Packet socket                                                | |
  | |    [ ]   Packet socket: mmapped IO                                  | |
  | |    <*> Unix domain sockets                                          | |
  | |    < > Transformation user configuration interface                  | |
  | |    [ ] Transformation sub policy support (EXPERIMENTAL)             | |
  | |    < > PF_KEY sockets                                               | |
  | |    [*] TCP/IP networking                                            | |
  | |    [ ]   IP: multicasting                                           | |
  | |    [ ]   IP: advanced router                                        | |
  | |    [*]   IP: kernel level autoconfiguration                         | |
  | |    [*]     IP: DHCP support (NEW)                                   | |
  | |    [*]     IP: BOOTP support (NEW)                                  | |
  | |    [ ]     IP: RARP support (NEW)                                   | |
  | |    < >   IP: tunneling                                              | |
  | |    < >   IP: GRE tunnels over IP                                    | |
  | |    [ ]   IP: ARP daemon support (EXPERIMENTAL)                      | |
  | |    [ ]   IP: TCP syncookie support (disabled per default)           | |
  | +----v(+)-------------------------------------------------------------+ |
  +-------------------------------------------------------------------------+
  |                    <Select>    < Exit >    < Help >                     |
  +-------------------------------------------------------------------------+

Afterwards choose "File Systems -> Network File Systems" menu and enable NFS options:

  +------------------------- Network File Systems --------------------------+
  |  Arrow keys navigate the menu.  <Enter> selects submenus --->.          |
  |  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes, |
  |  <M> modularizes features.  Press <Esc><Esc> to exit, <|> for Help, </> |
  |  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < >       |
  | +---------------------------------------------------------------------+ |
  | |    <*> NFS file system support                                      | |
  | |    [*]   Provide NFSv3 client support                               | |
  | |    [ ]     Provide client support for the NFSv3 ACL protocol extensi| |
  | |    [ ]   Provide NFSv4 client support (EXPERIMENTAL)                | |
  | |    [*]   Allow direct I/O on NFS files                              | |
  | |    <M> NFS server support                                           | |
  | |    [*]   Provide NFSv3 server support                               | |
  | |    [ ]     Provide server support for the NFSv3 ACL protocol extensi| |
  | |    [ ]     Provide NFSv4 server support (EXPERIMENTAL)              | |
  | |    [*]   Provide NFS server over TCP support                        | |
  | +----v(+)-------------------------------------------------------------+ |
  +-------------------------------------------------------------------------+
  |                    <Select>    < Exit >    < Help >                     |
  +-------------------------------------------------------------------------+

After the kernel is built it can be loaded with

root=/dev/nfs nfsroot=<serverip>:/path/to/nfsroot

options and access the filesystem on the host workstation and used for software development. More information about how to use NFS root can be found in Documentation/nfsroot.txt in the Linux kernel source tree (and also here)

Building the Linux kernel for EM-X270

There may be cases when default kernel for device does not fit your system requirements and you would like to build your own kernel. EM-X270 platform is supported by vanilla kernel starting from version 2.6.23. Yet, the support present there is incomplete and does not include several important features. This features can be enabled if you apply EM-X270 patchset to vanilla kernel and make proper kernel configuration. Keep in mind that to build Linux kernel for EM-X270 you need cross-compilation toolchain and mkimage utility from U-Boot.

Below is a brief description of Linux kernel build process for EM-X270 along with an example commands sequence.

Download Linux kernel source from preferred mirror
Unpack it to some directory
Apply EM-X270 patchset
Set environment variables ARCH, and CROSS_COMPILE so that kernel build system cross compile the kernel
Build the kernel, and modules
Install the modules

mkdir /home/development/em-x270/kernel
cd /home/development/em-x270/kernel
wget http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.23.tar.bz2
tar xjf linux-2.6.23.tar.bz2
cd linux-2.6.23
cat /path/to/x270em-linux-img/kernel/linux-2.6.23-em-x270.patch | patch -p1
export ARCH=arm
export CROSS_COMPILE=arm-linux-
make em_x270_defconfig
make menuconfig
make && make uImage && \
     INSTALL_MOD_PATH=/home/development/em-x270/rootfs make modules_install

In the above example, the Linux kernel image (uImage) will be created in /home/development/em-x270/kernel/linux-2.6.23/arch/arm/boot, and the loadable kernel modules will be installed into the /home/development/em-x270/rootfs/lib/modules directory.

Now, if you boot EM-X270 with newly created kernel image and with networked root filesysem at /home/development/em-x270/rootfs/ the system will be able to properly load kernel modules and you avoid modules versioning problems.

OE installation

Angstrom Linux images for EM-X270 are built with OpenEmbedded development environment. If you would like to build custom image you need to install the OpenEmbedded environment. Getting Started page of OpenEmbedded documentation describes the installation process.

Here we assume that you followed the Getting Started instructions and you have the same directory structure.

After you completed the installation of OpenEmbedded, you need to configure it to be able to build images for EM-X270. Recent versions of OpenEmbedded support EM-X270 and the only thing you need is to place local.conf from CompuLab package to /stuff/build/conf/local.conf:

cp -r /path/to/x270-em-linux/oe/build/conf/local.conf /stuff/build/conf

Another possibility is to use all OpenEmbedded related files from CompuLab Linux package for EM-X270:

cp -r /path/to/x270-em-linux/oe/* /stuff/

Now you are ready to build Linux images for EM-X270:

cd /stuff/build
bitbake angstrom-x11-image

After some time the image will be created and put into /stuff/build/tmp/deploy/glibc/images/em-x270 directory. Default configuration creates two types of images: tar, and jffs2. The jffs2 image can be transfered to the EM-X270 on-board NAND flash. The tar archive can be extracted to some directory on the host workstation, and this directory can be used as networked root filesystem for the device.