CM-iGLX: Linux: Gentoo
Contents
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:
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.
- 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.
- 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)
-
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
