Gentoo Linux for CM-iGLX

Introduction

Linux for CM-iGLX module is based on Gentoo Linux 2007.0. The CompuLab Linux package for CM-iGLX includes ready to run USB NAND flash image, Linux kernel configuration and source code patches, portage tree used to create the image, packages database archive, and graphics and touchscreen driver sources. The Getting started with Linux on CM-iGLX page gives brief introduction on how to setup and start using the run-time Linux image. Here we describe in more detail image structure, and also provide guidelines for image modification, and even creation of your own Gentoo Linux for CM-iGLX.

The Linux image we provide is made as generic as possible. It includes more then 200 packages, among them KDE, mplayer, thttpd web server, and Samba Windows connectivity suite. There is about 30 MB of free space available for user applications. The user can free additional space by removing unnecessary components from the above list.

Package contents

The CompuLab Linux package for CM-iGLX contains the following components:

gentoo.img.gz

gentoo.img.gz is ready-to-run disk image with Linux for CM-iGLX. It can be installed onto the on-board NAND flash as described at Getting started page. The gentoo.img is a complete disk image, containing partition table and two partitions: /boot and /. The /boot partition is ~10Mbytes and it is used to store bootloader and Linux kernel. The rest of the image is the / partition containing root filesystem. Each of the partitions can be loop-mounted and modified on the host workstation, e.g. using image_mount.sh utility.

kernel

kernel directory contains Linux kernel binary (vmlinux-2.6.24-cm-iglx), a copy of .config used to build the kernel (linux-2.6.24.config) and the modification of the kernel source made to support CM-iGLX devices. These modifications are available as patch vs. standard Linux kernel 2.6.24. (linux-2.6.24.pacth)

package_management

package_management directory contains information needed to use Portage installer to add/remove/update packages for CM-iGLX. The usr-portage.tar.gz is the Portage tree used to create the CM-iGLX run-time image. The var-db-pkg.tar.gz is the information about packages installed on CM-iGLX. Package management is described in more detail here

drivers

drivers directory contains user-space drivers that are not included in standard Gentoo packages:

• rt73 - Wireless LAN driver
• xf86-video-amd - accelerated video driver for X11 utilizing GeodeLX graphics accelerator.
• xf86-input-evtouch - X11 touchscreen driver

scripts

Miscellaneous useful scripts (currently only one)

• image_mount.sh - utility to mount partitions on run-time image

app_examples

Some usefull application examples

• geodelx-v4l2 - two simple examples for video capture and video overlay

Linux Kernel and Drivers

Kernel compilation

Linux kernel for CM-iGLX is based on version 2.6.24 with addition of GeodeLX frame buffer drivers from AMD, Video Input Port drivers and drivers for on-board WM9715 touchscreen controller. The changes and additions to the Linux kernel for CM-iGLX are available as patch generated versus Linux kernel 2.6.24.

The following example demonstrates how to compile Linux kernel for CM-iGLX:

mkdir /path/to/cm-iglx/kernel/
cd /path/to/cm-iglx/kernel/
wget http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.24.tar.bz2
tar xjf linux-2.6.24.tar.bz2
cd linux-2.6.24
patch -p1 < /path/to/compulab/package/linux-2.6.24.patch
cp /path/to/compulab/package/linux-2.6.24.config .config
make menuconfig
make && INSTALL_MOD_PATH=/path/to/target make modules_install

Note, that after the compilation is finished the drivers compiled as loadable kernel modules will be stored in /path/to/target/lib/modules/<kernel version>/ directory. This directory should be transfered to the CM-iGLX root file system.

Additional information about kernel build process can be found in README file in the kernel source tree.

Graphics support

Kernel

We added driver GeodeLX frame buffer device. It's implementation resides in drivers/video/geode and lib/cimmaron in the kernel source tree.

X11

X11-specific graphics driver included in CM-iGLX image was complied from source files located at drivers/xf86-video-amd.tar.bz2 in our Linux package.

Custom LCD configuration

You can adjust X server to support displays with non-standard resolution. To do so you need to edit /etc/X11/xorg.conf configuration file.

There are some fundamental things you need to know before hacking a xorg.conf. These are:

• Your monitor's horizontal and vertical sync frequency options
• Your video adapter's driving clock frequencies, or "dot clocks"

The horizontal sync frequency is just the number of times per second the monitor can write a horizontal scan line; it is the single most important statistic about your monitor. The vertical sync frequency is the number of times per second the monitor can traverse its beam vertically.

Sync frequencies are usually listed on the specifications page of your monitor manual. The vertical sync frequency number is typically calibrated in Hz (cycles per second), the horizontal one in KHz (kilocycles per second). The usual ranges are between 50 and 150Hz vertical, and between 31 and 135 KHz horizontal.

If you have a multisync monitor, these frequencies will be given as ranges. For AMD Geode LX800 video adapter's driving clock frequency range is 25.18 to 229.50 MHz.

Now read carefully the "Timing Chart" section in your display documentation. Find the typical values for "active time", "blanking time", "front porch", "sync time", "back porch" both for the horizontal and vertical timings. Your target is to create appropriate "modeline", for example:

#Modename 	clock   horizontal timing     vertical timing
"752x564"     40     752 784  944 1088     564 567 569 611

The horizontal section consists of four fields, which specify how each horizontal line on the display is to be generated.

The first field of the section (752) contains the number of dots per line which will be illuminated to form the picture - "active time". The second field of the section (784) indicates at which dot the horizontal sync pulse will begin. Difference between second and first fields called "front porch". The third field (944) indicates at which dot the horizontal sync pulse will end. Difference between third and second fields called "sync time". The fourth field (1088) specifies the total horizontal frame length. Difference between fourth and third fields called "back porch".

The vertical section also contains four fields. The first field (564) contains the number of visible lines, which will appear on the display. The second field (567) indicates the line number at which the vertical sync pulse will begin. The third field (569) specifies the line number at which the vertical sync pulse will end. The fourth field contains the total vertical frame length (611).

Note again that all of the horizontal numbers (752, 784, 944, and 1088) are divisible by eight!

Choose the desired refresh rate (for example 60 Hz) to obtain appropriate dot-clock frequency:

---

Dot-clock frequency = 1088*611*60 Hz = 40 MHz ("clock" field in "modeline").

---

Ensure that it in range of supported by CM-iGLX video adapter's frequencies. Ensure that horizontal and vertical sync frequencies are supported by your display.

Now it's time to edit your /etc/X11/xorg.conf.

Find section named "Monitor" and add lines:

UseModes 	"Custom"
HorizSync	30 - 50
VertRefresh	65 - 72

(Don't forget to specify values of your display!)

Find section named "Screen" and add lines:

SubSection "Display"
	Depth     16
	Viewport  0 0
	Modes     "752x564"
EndSubSection

Add section named "Modes" with the following content:

Section "Modes"
	Identifier "Custom"
	ModeLine   "752x564"	 40	752 784 944 1088	  564 567 569 611 				+hsync +vsync
EndSection

Save the file and restart X server.

For more information please visit these links:

• XFree86 Video Timings HOWTO
• xorg.conf manual page

Video Input Port

Package includes two simple examples for video capture and video overlay. This examples already exist on gentoo.img in /root/geodelx-v4l2-examples

Capture

The capture example accepts the following command line options:

-d | --device name   Video device name [/dev/v4l/video]
-h | --help          Print this message
-m | --mmap          Use memory mapped buffers
-r | --read          Use read() calls
-o | --output        Capture to file [file]

To view captured images install imagemagick:

USE="jpeg png gs fpx mpeg graphviz hdri jbig jpeg2k lcms perl zlib svg wmf" emerge -av  media-gfx/imagemagick

Use display utility:

display -size 720x480 -depth 16 uyvy:/path/to/captured/image

If you have troubles in viewing images try to capture with --read option.

Overlay

The overlay example accepts the following command line options:

-d | --device name   Video device name [/dev/v4l/video]
-w | --width value   Overlay window width [640]
-e | --height value  Overlay window height [480]
-l | --left value    Overlay window left coord [0]
-t | --top value     Overlay window top coord [0]
-s | --steps value   Steps for control adjustment []
-v | --verbose       Verbose output
-h | --help          Print this message

Touchscreen support

Kernel

The kernel driver for WM97xx touchscreen controller can be found in drivers/input/touchscreen/wm97xx. The driver has several parameters, that can be modified to adopt the driver behaviour to particular touchscreens and application needs:

• dejitter_history - touchscreen dejitter filter history length
• enable_btn - enable/disbale BUTTON_* events.
• abs_x - touchscreen absolute X min, max, fuzz
• abs_y - touchscreen absolute Y min, max, fuzz
• rpu - set internal pull up resitor for pen detect
• pil - set current used for pressure measurement
• pressure - set threshold for pressure measurement
• delay - set adc sample delay

X11

X11-specific touchscreen driver included in CM-iGLX image was complied from source files located at drivers/xf86-input-evtouch.tar.bz2 in our Linux package.

Calibration utility

The touchscreen calibration utility calibrate.sh is a part of the image. To enable this driver, add Option "Calibrate" "1" to xorg.conf:

Section "InputDevice"	
...
Option "Calibrate" "1"
EndSection

Copy empty_cursor.xbm file to the root folder:

cp /path/to/empty_cursor.xbm /

Then with X not running run:

calibrate.sh

White screen with 9 black crosses should appear.

The first calibration step consists of finding the maximum and minimum coordinates. To do this just touch the screen with the pen along all edges and corners. DO NOT CLICK -- Just move the pen accross the screen. After your first touch of the screen two text lines should appear somewhere in the upper left area of the screen. For you only the first line is interesting. This line shows the currently found minimum and maximum values of the X- and Y-coordinates.

Merge Max_X, Max_Y, Min_X, Min_Y found in there into the InputDevice section of /etc/X11/xorg.conf and remove the Calibrate line.

Remove temporary empty_cursor.xbm file from the root folder:

rm /empty_cursor.xbm

Your touch screen should work now.

Software management and development

The software packages for CM-iGLX were prepared in a way very similar to described below. If you setup your host workstation in the way we describe here, you'll be able to add/remove Gentoo packages for your target system using Portage environment, develop and test your application of the host workstation, and finally choose what packages, and files you want to deploy to your production target.

Host side workstation setup

Setup a Linux PC workstation. Any modern Linux distribution (such as Fedora Core, SuSe, Ubuntu) will work. We used Gentoo Linux on our host, but it's not mandatory. We recommend installing ssh, and nfs servers, so you can access the same files from both host workstation and CM-iGLX.

Development file system setup

Download Gentoo stage3 and Portage tree from preferred Gentoo mirrors. Download CompuLab Linux package to your Linux workstation and create a directory that you will be using for CM-iGLX development, say /mnt/gentoo:

mkdir /mnt/gentoo
wget http://distfiles.gentoo.org/releases/x86/2007.0/stages/stage3-i686-2007.0.tar.bz2
wget http://distfiles.gentoo.org/releases/snapshots/2007.0/portage-2007.0.tar.bz2
tar xjf stage3-i686-2007.0.tar.bz2 -C /mnt/gentoo
tar xjf portage-2007.0.tar.bz2 -C /mnt/gentoo/usr
cp /etc/resolv.conf /mnt/gentoo/etc/resolv.conf

Now you have basic Gentoo system on your host workstation that can be used for software development and management for CM-iGLX. To use this system you just need to chroot into the Gentoo environment:

mount -t proc proc /mnt/gentoo/proc
mount -o bind /dev/ /mnt/gentoo/dev
mount -t sysfs sys /mnt/gentoo/sys
chroot /mnt/gentoo /bin/bash
env-update

Target file system extraction

The CM-iGLX Gentoo image contains partition table, /boot and / partitions. Each of the partitions can be loop-mounted using image_mount.sh script, and it's contents can be copied to a directory on your host workstation.

cd /path/to/compulab/package
wget http://www.compulab.co.il/iglx/download/iglx-linux.zip
unzip iglx-linux.zip
gunzip gentoo.img
mkdir gentoo.img.mnt
./scripts/image_mount.sh gentoo.img root gentoo.img.mnt
mkdir /opt/glx
cp -a /path/to/compulab/gentoo.img.mnt /mnt/gentoo/opt/glx

At this point your host workstation has two Gentoo systems, one is fully functional, that can be used for development and testing, and the other one is exact copy of Gentoo Linux image on CM-iGLX. The directory tree on your host will resemble the following figure:

.
|-- bin
|-- boot
|-- dev
|-- etc
|-- home
|-- lib
|-- lost+found
|-- mnt
|   |-- gentoo
|   |	|-- bin
|   |	|-- boot
|   |	|-- dev
|   |	|-- etc
|   |	|-- home
|   |	|-- lib
|   |	|-- opt
|   |	|   |-- glx
|   |	|   |-- bin
|   |	|   |-- boot
|   |	|   |-- dev
|   |	|   |-- etc
|   |	|   |-- home
|   |	|   |-- lib
|   |	|   |-- opt
|   |	|   |-- proc
|   |	|   |-- tmp
|   |	|   |-- usr
|   |	|   `-- var
|   |	|-- proc
|   |	|-- tmp
|   |	|-- usr
|   |	`-- var
|-- opt
|-- proc
|-- tftproot
|-- tmp
|-- usr
`-- var

NFS setup

CM-iGLX can use networked file system as its root filing system. It allows faster turn-around for software updates, development and testing. Using the same files on both host and target computers, without need to reflash entire file system to the target greatly simplifies development for embedded systems. That's why we recommend setting up NFS server on your host workstation, and using NFS-exported files as root file system on CM-iGLX.

1. Set up the NFS server on your host Linux system. If you are using Gentoo Linux

   emerge nfs-utils
   rc-update add nfs default
   

   If you're using other Linux distribution, refer to its manuals to find out how to setup NFS server.

2. Export target file systems - add the following lines to your /etc/exports:

   /mnt/gentoo/ 192.168.1.0/255.255.255.0(sync,no_root_squash,rw)
   /mnt/gentoo/opt/glx 192.168.1.0/255.255.255.0(sync,no_root_squash,rw)
   

3. Start the NFS server

   /etc/init.d/nfs start
   

To setup CM-iGLX to boot with NFS-root you need to add the following entry into /boot/grub/grub.conf on the CM-iGLX USB NAND flash:

title Gentoo Linux (NFS root)
kernel /vmlinuz-2.6.24-cm-iglx root=/dev/nfs nfsroot=<server_ip>:/mnt/gentoo ip=::::cm-iglx:eth1:
boot

The /boot/grub/grub.conf file can be modified either on running Linux system on the CM-iGLX.

More information about using NFS root can be found in Linux kernel documentation in Documentation/nfsroot.txt in the kernel source tree.

Package management

Development Gentoo system

You can use Gentoo Portage installer to add, remove and modify packages on both development and target file systems. After you performed all the steps describe in the previous section, you can chroot to the development Gentoo system, and use emerge utility to manage software packages on it.

Here's the contents of make.conf we used to create the CM-iGLX image:

CFLAGS="-Os -mtune=k6-2 -pipe -fomit-frame-pointer"
CHOST="i686-pc-linux-gnu"
CXXFLAGS="${CFLAGS}"
FEATURES="noman nodoc noinfo buildpkg"
USE="-opengl bitmap-fonts truetype-fonts type1-fonts X alsa"

You can copy these settings to the /mnt/gentoo/etc/make.conf file and add or modify them, esspecially USE flags, to create packages that suit most your application needs.

Target System

The target system extracted from gentoo.img needs some additional information to allow proper usage of portage. Due to size limitations, the packages database of the target file system, is shipped in a separate archive: var-db-pkg.tar.gz. To make use of it you need to extract it into appropriate place:

tar -xvvzf /path/to/compulab/package/package_management/var-db-pkd.tar.gz -C /mnt/gentoo/opt/glx/var/db/pkg

Next, after chroot`ing into the development Gentoo system you can emerge packages into the target file system:

ROOT=/opt/glx emerge <package spec>

NAND flash image creation and deployment

Last step in embedded software development is deployment of the file system to the device. There several ways to do it.

First of all, you can loop-mount the gentoo.img file, copy the files from updated target file system back to the image, and use the way described in Getting started with Linux on CM-iGLX.

Another way is to use /mnt/gentoo as NFS-root, and than mount the NAND flash, and copy the files from /mnt/gentoo/opt/glx directly to the NAND flash.

Yet another way is to create bootable USB-stick, copy the target files to it and than transfer entire contents of the USB-stick onto the CM-iGLX on-board NAND flash.

Known problems and limitations

• Some USB mass storage devices cause incorrect mount of root file system. Instead of using on-board USB NAND flash as root, Linux kernel will try to mount an external USB storage device.
• ACPI state S3 (suspend to RAM) state is not supported

See also

• Getting started with Linux on CM-iGLX

Kenrel and Drivers

• The Linux Kernel Archives
• X11 video driver for GeodeLX display controller
• Xorg Touchscreen Driver

Gentoo Linux

• Gentoo Linux
• Portage manual
• HOWTO Gentoo LiveCD and LiveUSB
• HOWTO Small Footprint Gentoo on USB
• Gentoo Embedded x86 Guide