GNUDD Logo

Olet 1.10


Node: Top, Next: , Previous: (dir), Up: (dir)

This document is a collection of notes about porting the EtLinux embedded system onto a specific x86 single-board computer. Specifically, it refers to the Olympus device by Arcom, whence the name, equipped with an additional 4-port serial device and a disk-on-module IDE storage device.


Node: Setting up the Hardware, Next: , Previous: Top, Up: Top

Setting up the Hardware


Node: Turning the Olympus On, Next: , Previous: Setting up the Hardware, Up: Setting up the Hardware

Turning the Olympus On

You are assumed to have the SBC documentation handy and be familiar with it. This section only lists the most important issues.


Node: Power Supply, Next: , Previous: Turning the Olympus On, Up: Turning the Olympus On

Power Supply

The Olympus device has an 8-pin power connector, but it can be turned on by just using three such pins: GND, 5V, 12V. The -12V is only used to power the PC104 devices, and can be left open if not needed on the bus.

The following is an updated pin-out:


1: 5V
2: GND
3: 12V
These lines are mandatory
4: +5V Standby
5: PSON
These lines must be left open, unless you connect them to the ATX lines of the same name. Connecting pin 4 to 5V prevents the device from booting. You'd better leave them open.
6: -12V
Optional, only for PC104.
7: GND
8: 5V
Optional, as they are in short with pin 1 and 2.


Node: Jumpers, Previous: Power Supply, Up: Turning the Olympus On

Jumpers

The following jumpers are critical to system operation:


LK1
This must be in position 2-3 (battery enabled). Otherwise the device won't boot at all.
LK8
The jumper must be either in position 1-2 or 2-3. Pulling it off prevents the device from proceeding after the memory test.


Node: BIOS Setup, Next: , Previous: Turning the Olympus On, Up: Setting up the Hardware

BIOS Setup

This is a detailed list of what I've done with the BIOS settings in order to setup my specimen, keeping in mind the specific run-time requirements (mostly, getting 4 ISA IRQ lines available for the serial port).

I'd love to be able to save this setup to a file, but the x86 platform is as braindead now as it has always been.


Node: Serial Device Setup, Next: , Previous: BIOS Setup, Up: Setting up the Hardware

Serial Device Setup

The CPU board hosts 4 serial ports, configured as:


ttyS0
I/O Port: 0x3F8, IRQ: 4
ttyS1
I/O Port: 0x2F8, IRQ: 3
ttyS2
I/O Port: 0x3E8, IRQ: 11
ttyS3
I/O Port: 0x2E8, IRQ: 10

The 4 ports in the add-on device can thus be configured in the following way, to avoid sharing interrupt lines:


ttyS4
I/O Port: 0x240, IRQ: 7
ttyS5
I/O Port: 0x248, IRQ: 5
ttyS6
I/O Port: 0x260, IRQ: 9 (marked as "2/9" on the PCB)
ttyS7
I/O Port: 0x268, IRQ: 15

The I/O port selection is performed by setting the three jumpers marked as A, B, C to the positions out, out, in (i.e., only jumper C must be plugged).


Node: IRQ Assignment, Previous: Serial Device Setup, Up: Setting up the Hardware

IRQ Assignment

With the configuration chosen above, this is the global IRQ assignment on the target computer:


IRQ0
System timer (hardwired)
IRQ1
Keyboard (hardwired)
IRQ2
Same as IRQ9
IRQ3
ttyS1 (on board)
IRQ4
ttyS0 (on board)
IRQ5
ttyS5 (add-on serial)
IRQ6
Unused (and unusable)
IRQ7
ttyS4 (add-on serial)
IRQ8
Unused (and unusable)
IRQ9
ttyS6 (add-on serial)
IRQ10
ttyS3 (on board)
IRQ11
ttyS2 (on board)
IRQ12
Ethernet controller (on board, auto-assigned)
IRQ13
Unused (and unusable)
IRQ14
IDE controller (on board, auto-assigned)
IRQ15
ttyS7 (add-on serial)


Node: Setting up the Software, Next: , Previous: Setting up the Hardware, Up: Top

Setting up the Software


Node: Getting EtLinux, Next: , Previous: Setting up the Software, Up: Setting up the Software

Getting EtLinux

First of all, I suggest you get EtLinux-1,1 in some recent incantation. Since some of the material discussed here has been included in the CVS tree for EtLinux-1.1 during the port to the Olympus, I suggest you use the following command to retrieve the code as of Apr 11th 2003. The password for anonymous CVS login is "cvs".

         cvs -d :pserver:cvs@ar.linux.it:/data/cvs login
         cvs -d :pserver:cvs@ar.linux.it:/data/cvs \
                       co -D 2003-04-10 etlinux-1.1
     

The previous step will create a directory called "etlinux-1.1" under your current working directory. I'll assume later in this document you downloaded EtLinux inside /opt/olet; please note that the download directory should not be the one that exists within the olympus-etlinux package.

Later on we'll compile EtLinux packages from source and will add configuration files and packages to the etlinux-1.1 tree. To prevent accidental modification of the downloaded files, I suggest you write-protect all of them or change their ownership.


Node: Booting a Diskless Target, Next: , Previous: Getting EtLinux, Up: Setting up the Software

Booting a Diskless Target

In order to boot a GNU/Linux system on your target, you need to run a boot loader in order to load a kernel to the target. For filesystem access, the best solution for the initial boot (and for the whole of the development cycle) is running the system as a diskless host based on one of your local workstations or servers.

The requirements to satisfy in order to run a diskless system are the following ones:

The following subsections describe how to set up your system in practice in order to boot a diskless target, assuming that at least the local DNS is already set up and configured.


Node: Running a Boot Loader, Next: , Previous: Booting a Diskless Target, Up: Booting a Diskless Target

Running a boot loader

To boot your target for the first time, the best choice is to use a floppy disk with grub. To this aim, you can simply compile grub from the source code included in EtLinux, and then paste its two stages to the floppy with the following commands:

        make grub-0.5.96.1.bin
        cd grub-0.5.96.1
        cat stage1/stage1 stage2/stage2 > /dev/fd0
     

The floppy is now bootable and it will show a "grub>" prompt when used as boot device. The default compilation for grub in EtLinux already includes support for the RTL8139 network interface, so nothing more is needed.

If your server is already setup, you can now boot your target system by typing commands similar to the following ones:

         grub> bootp
         grub> root (bd)
         grub> kernel /tftpboot/bzImage root=/dev/nfs ip=auto rw
         grub> boot
     


Node: Configuring the DHCP Server, Next: , Previous: Running a Boot Loader, Up: Booting a Diskless Target

Configuring the DHCP Server

In order to reply to the boot network packets sent by grub, you'll need either a bootpd or dhcpd package installed. This section refers to dhcpd-2.2.

This is an example dhcpd configuration that offers a static address to a client computer. The target is called olet and it is given 192.168.16.44 as IP address. The server is 192.168.16.14 (ostro) and the LAN is a class-C network wit 192.168.16.254 (router) as default gateway.

     option domain-name "localnet.net";
     option domain-name-servers ostro.localnet.net;
     option subnet-mask 255.255.255.0;
     
     subnet 192.168.16.0 netmask 255.255.255.0 {
       option broadcast-address 192.168.16.255;
       option routers router.localnet.net;
     }
     
     host olet {
       hardware ethernet 00:60:e0:80:53:04;
       fixed-address olet.localnet.net;
       server-name "ostro.localnet.net";
     }
     

Please note that you'll need to stop and restart the dhcpd process every time the configuration file is changed.


Node: Configuring the TFTP Server, Next: , Previous: Configuring the DHCP Server, Up: Booting a Diskless Target

Configuring the TFTP Server

Once the network is configured vi DHCP, the target system needs to retrieve a kernel, and this is made available via TFTP. To enable tftpd in your server system you'll have to install the associated package and enable it in /etc/inetd.conf or equivalent file.

Please ensure that it allows access to the /tftpboot directory. This an example line for /etc/inetd.conf:

     #port type proto mode user   command and args....
     tftp  dgram udp  wait nobody /usr/sbin/tcpd /usr/sbin/in.tftpd /tftpboot
     

Please note that tftpd allows the "-s" parameter, that forces it to use all requested pathnames as if they start from the chosen public directory. This allows for shorter pathnames on the Grub configuration files.

If you changed the configuration file, sending SIGHUP to inetd is all that's needed to make it re-read its configuration: "killall -HUP inetd", but if you use tcpd as shown you'll also need to ensure access to the tftp service is allowed for your target. If you use xinetd instead of inetd, please check its documentation.


Node: Configuring the NFS Server, Next: , Previous: Configuring the TFTP Server, Up: Booting a Diskless Target

Configuring the NFS Server

When the kernel mounts the root filesystem via NFS by virtue of the "root=/dev/nfs" command line argument, the default directory being mounted is /tftpboot/192.168.16.44, where the IP used in the name is the one associated to the target machine. You can force a different pathname using the nfsroot= argument, for example "root=/dev/nfs nfsroot=/opt/root/olet". Whatever the directory name being used, it can be a symbolic link if you so prefer, and the real directory name must be exported by a line like the following one, in /etc/exports:

        /opt/root/olet olet(rw,no_root_squash)
     

The content of /opt/root/olet cam either be a complete filesystem image (for example, the same as your target filesystem that will be used in production) or just a root "partition" of a more complex system.


Node: Preparing the Target Tree, Next: , Previous: Configuring the NFS Server, Up: Booting a Diskless Target

Preparing the Target Tree

During the first development stages I recommend running a complete GNU/Linux tree on the target, setting it up as a copy of the server installation.

To this aim, the following steps should be performed:

The typical /opt/root/olet/etc/fstab will look like:

         ostro:/opt/root/olet  /       nfs defaults   0   0
         ostro:/usr            /usr    nfs ro         0   0
         ostro:/home           /home   nfs defaults   0   0
     

The file /etc/export on the server will be like this:

        /opt/root/olet olet(rw,no_root_squash)
        /usr           olet(ro)
        /home          olet(rw)
     

Please note that you need to stop and restart the NFS servers every time you change /etc/exports.

With a setup like the one described, you can expect to see the following kernel messages at boot time:

     Kernel command line: root=/dev/nfs ip=bootp
     [...]
     Detected 864.488 MHz processor.
     Console: colour VGA+ 80x25
     Calibrating delay loop... 1723.59 BogoMIPS
     [...]
     CPU: Intel Pentium III (Coppermine) stepping 0a
     [...]
     8139too Fast Ethernet driver 0.9.25
     PCI: Found IRQ 15 for device 00:0b.0
     8139too: 00:0b.0: unknown chip version, assuming RTL-8139
     8139too: 00:0b.0: TxConfig = 0x77000400
     eth0: RTL8139 Fast Ethernet at 0xc8000000, 00:60:e0:80:53:04, IRQ 15
     eth0:  Identified 8139 chip type 'RTL-8139'
     [...]
     eth0: Setting 100mbps full-duplex [...]
     Sending BOOTP requests . OK
     IP-Config: BOOTP answer from 192.168.16.14, my address is 192.168.16.44
     IP-Config: Complete:
     device=eth0, addr=192.168.16.44, mask=255.255.255.0, gw=192.168.16.14,
     host=192.168.16.44, domain=localnet.net, nis-domain=(none),
     bootserver=192.168.16.14, rootserver=192.168.16.14, rootpath=
     NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
     Looking up port of RPC 100003/2 on 192.168.16.14
     Looking up port of RPC 100005/1 on 192.168.16.14
     VFS: Mounted root (nfs filesystem).
     [...]
     

The messages printed by init will most likely include the following lines (although the details will depend on the distribution you are using):

     Checking all file systems...
     Mounting local filesystems...
     nothing was mounted
     Configuring network interfaces: done.
     Starting portmapper... Mounting remote filesystems...
     Setting the hostname to olet, resolved from DNS.
     


Node: Preparing a Kernel, Previous: Preparing the Target Tree, Up: Booting a Diskless Target

Preparing a Kernel

You should feel already confident with configuring and compiling a kernel. If not, please refer one of the several documents about the topic available on the Net. One, for example, is <http://www.linux.it/kerneldocs/kconf/>, and although it states to be about version 2.2 it applies unchanged to version 2.4 of the kernel.

A good kernel configuration for the Olympus is available as config0 within the package hosting this document. To compile your own kernel, you may thus follow the following steps:

        tar xvjf linux-2.4.19.tar.bz2
        cd linux-2.4.19
        cp $(HOME)/olet/config0 .config
        make oldconfig depend bzImage modules
     

The file arch/i386/boot/bzImage must then be made available to your boot loader, most likely by copying it over to /tftpboot. It is wise to save the configuration and the map file too.

        cp arch/i386/boot/bzImage  /tftpboot/bzImage.olet
        cp .config                 /tftpboot/bzImage.olet.cfg
        cp System.map              /tftpboot/bzImage.olet.map
     

If you want to install kernel modules for your target to you, you'll need to install them into the target tree (not the host tree):

        make module_install INSTALL_MOD_PATH=/opt/root/olet
     


Node: Partitioning the Target, Next: , Previous: Booting a Diskless Target, Up: Setting up the Software

Partitioning the Target

Once the target is booted, you can run fdisk to partition the disk-on-module device. My personal choice is 4MB for /dev/hda1, a single partition for the runtime environment and a small partition to store configuration files that will be used at runtime. Using the (fake) CHS geometry of my device, I get this partitioning when using "+4M" as size for the first partition, and reserving a pair of megs for the third partition.

     Disk /dev/hda: 32 heads, 63 sectors, 31 cylinders
     Units = cylinders of 2016 * 512 bytes
     
        Device Boot    Start       End    Blocks   Id  System
     /dev/hda1   *         1         5      5008+  83  Linux
     /dev/hda2             6        29     24192   83  Linux
     /dev/hda3            30        31      2016   83  Linux
     

4MB in the first partition are more than enough for the boot loader and at least two kernel images. Keeping a second kernel image around is usually needed to allow a recovery path when testing new images, but is barely needed when you can boot diskless for recovery.

After partitioning, mke2fs can be invoked all of the devices, without changing the default settings.

        mke2fs /dev/hda1
        mke2fs /dev/hda2
        mke2fs /dev/hda3
     


Node: Setting up Grub, Previous: Partitioning the Target, Up: Setting up the Software

Setting up Grub

Assuming you already booted your target system as a diskless host using a floppy disk, you may now need to install grub on the DOM (disk on module) device.

Since the kernel already identified the DOM as the first (and only) disk on the system, and since you already partitioned it, you only need to copy the boot loader to the target.

After mounting /dev/hda1 on the /mnt directory, you need to copy the following files into /mnt, after creating the directory boot/grub:

        boot/grub/stage2
        boot/grub/stage1
        boot/grub/menu.lst
     

The two stage files are the same two you already copied to a floppy disk (see Running a Boot Loader).

A simple menu.list can simply run the commands we saw in Running a Boot Loader, organized in a menu:

        timeout 2
     
        title diskless
          bootp
          root (nd)
          kernel /tftpboot/bzImage root=/dev/nfs ip=auto rw
     

A more flexible approach is re-loading the configuration file from the server, thus allowing a complete overhaul in the boot options without changing anything on the target:

        bootp
        timeout 1
     
        title reload configuration from server
          root (nd)
          configfile /tftpboot/menu.olet
     

With all the files in place, you should now invoke a grub shell and run the command "install (hd0,0)/boot/grub/stage1 (hd0) (hd0,0)/boot/grub/stage2 (hd0,0)/boot/grub/menu.lst". The GRUB shell can be either the grub executable or the grub prompt that welcomes you when booting from a floppy. The executable is found as grub/grub in the directory where you compiled the package

The culprit of the installation is therefore the command (typed on a single line):

        install (hd0,0)/boot/grub/stage1 (hd0) (hd0,0)/boot/grub/stage2
                (hd0,0)/boot/grub/menu.lst
     

It means: "install stage1 on hd0 with a block list for stage2 and the name of menu.lst.

To get detailed information about GRUB device naming, please refer to the GRUB manual.


Node: Design Choices, Next: , Previous: Setting up the Software, Up: Top

Design Choices

This chapter collects the discussion of a few design choices about the production environment where the system is meant to be run. The resulting material (code, binaries, configuration files) is then included in either Device-Specific Tweaks or Customizing EtLinux.


Node: Choosing the Filesystem Layout, Next: , Previous: Design Choices, Up: Design Choices

Choosing the Filesystem Layout

To avoid any delay in application execution during filesystem access, and to avoid data duplication in memory when executing your programs, the best option is using the tmpfs engine. However, tmpfs cannot be used as a root filesystem, because it must be filled by creating all the files one at a time before you can access its contents. In other words, you can't hand a tmpfs-image to the kernel to be mounted at boot time.

The suggested solution, therefore, is the following:

The name of the tar file to be used in filling tmpfs can be passed to the first init as an environment variable, by placing it on the kernel command-line.

The partition on the DOM device is big enough to host two copies of the tar file. Thus, the boot loader configuration can account for two different choices for the run-time filesystem, thus allowing an easy recovery route if any problem is found during an update.


Node: Display Configuration, Previous: Choosing the Filesystem Layout, Up: Design Choices

Display Configuration

In order to access the graphic display of the target, there are basically two choices: you can either use the kernel frame buffer and select the right VESA mode, or you can leave the display setup step to an X server. In the former case, you can either access the graphic display via mmap from an user application or use X and its interface anyways.

The kernel configuration suggested in Preparing a Kernel already includes support for the frame buffer device, and you can enable it by using one of the following kernel command-line options:


vga=0
Use text mode, 80x25. This is the default
vga=1
Use text mode, 80x50.
vga=0x301
This selects a frame buffer mode of 640x480 pixels, with 8 bits per pixel. It makes an 80x60 text mode when using an 8x8 font.
vga=0x303
This selects a frame buffer mode of 800x600 pixels, with 8 bits per pixel. It makes an 100x75 text mode when using an 8x8 font.
vga=0x305
This selects a frame buffer mode of 1024x768 pixels, with 8 bits per pixel. It makes an 128x96 text mode when using an 8x8 font.

See Documentation/fb/vesafb.txt in the kernel sources for more information.


Node: Device-Specific Tweaks, Next: , Previous: Design Choices, Up: Top

Device-Specific Tweaks

This chapter includes modifications to the base software tools that are needed to run the selected target platform with all needed features.


Node: Detecting the Serial Ports, Previous: Device-Specific Tweaks, Up: Device-Specific Tweaks

Detecting the Serial Ports

If you want the eight serial ports to be detected upright at system boot, you need to change the serial_table. You can't use setserial at run time, since ports 4-7 won't be available at all on the system, and you won't be able to reconfigure them to use the chosen I/O-port and IRQ number.

The patch file patches/serial.patch fixes the default serial_table to detect all the eight serial ports. To apply the patch, use "patch -p1 < path-to-patch-file" from within the top-level kernel source directory. You'll then need to recompile the kernel. The IRQ numbers that appear in the patch are not really meaningful, since autodetection is performed at boot time (so you can shuffle the IRQs of ttyS4-ttyS7 as you like, using the jumpers on the serial card).

The kernel boot messages will now include the following lines:

     Serial driver version 5.05c (2001-07-08)
            with MANY_PORTS MULTIPORT SHARE_IRQ DETECT_IRQ SERIAL_PCI enabled
     ttyS00 at 0x03f8 (irq = 4) is a 16550A
     ttyS01 at 0x02f8 (irq = 3) is a 16550A
     ttyS02 at 0x03e8 (irq = 11) is a 16550A
     ttyS03 at 0x02e8 (irq = 10) is a 16550A
     ttyS04 at 0x0240 (irq = 7) is a 16550A
     ttyS05 at 0x0248 (irq = 5) is a 16550A
     ttyS06 at 0x0260 (irq = 9) is a 16550A
     ttyS07 at 0x0268 (irq = 15) is a 16550A
     


Node: Customizing EtLinux, Next: , Previous: Device-Specific Tweaks, Up: Top

Customizing EtLinux

This chapter describes the steps that have been performed to customize EtLinux for the specific target and configuration.


Node: Creating a Local Copy of the Source Tree, Next: , Previous: Customizing EtLinux, Up: Customizing EtLinux

Creating a Local Copy of the Source Tree

The EtLinux distribution is built from sources, so it's wouldn't be wise to include it all in this olet package. Therefore, I chose to distribute only files you'll need to add to EtLinux, and the tools to make and remote symbolic links to the EtLinux source distribution.

This brings in another advantage: the original source tree is not modified at all and you keep complete control of what you have modified even without live access to the EtLinux CVS tree.

To create the tree of symbolic links to the sources, you should enter the etlinux-1.1 directory of this package (where you find custom configuration files and directories) and run ../tools/makelinks, after pointing the ETLINUX environment variable to your EtLinux source tree.

With bash or another sh-compatible shell, you can for example use:

        $ export ETLINUX=/opt/olet/etlinux-1.1
        $ cd etlinux-1.1
        $ ../tools/makelinks
     

Or, in a more expert fashion (and this time with a relative pathname for ETLINUX):

        $ (cd etlinux-1.1 && ETLINUX=../../etlinux-1.1 ../tools/makelinks)
     

If you ever need to remove the tree of symbolic links, keeping only the customization files, you can use tools/rmlinks:

       $ (cd etlinux-1.1 && ../tools/rmlinks)
     

Caution: please note that you ought to remove the links before updating this package from CVS, because a newer version of olet might replace an EtLinux file, and CVS will complain if it finds a symbolic link where it wants to create a file.


Node: Building a Tree, Next: , Previous: Creating a Local Copy of the Source Tree, Up: Customizing EtLinux

Building a Tree

To build a target tree, you should refer to the EtLinux manual (included in the distribution tree). This is just a quick summary on how to build a tree in a different directory than the source one.

Let's assume you are building your target tree in the directory etlinux-build within this directory. The sequence of actions will look like the following:

        $ export SOURCEDIR=$(/bin/pwd)
        $ mkdir etlinux-build
        $ cd etlinux-build
        $ ln -s $SOURCEDIR/Makefile .
        $ sudo make PLATFORM=host-native CONFIG=olet
     

As an alternative, you might prefer to set PLATFORM and CONFIG in your environment, to avoid retyping them over and over if you need to change the configuration and rebuild the system:

        $ mkdir etlinux-build
        $ cd etlinux-build
        $ ln -s $SOURCEDIR/Makefile .
        $ export PLATFORM=host-native CONFIG=olet
        $ sudo make
     

Please note, in both cases shown above, that SOURCEDIR is an absolute pathname. If it is relative you'll experience an error in some situations (although not in the straight compilation path shown here).

At the end of the compilation (which takes more or less 300 kilo-bogoMIPS-second) you'll find a complete target tree in the Trees subdirectory, named after your configuration of choice: Trees/olet. You can point your NFS-Root system directly to this directory, or move it over to a proper place.


Node: Fixing the Tree, Next: , Previous: Building a Tree, Up: Customizing EtLinux

Fixing the Tree

The default configuration for EtLinux needs some tailoring to the target device it will be hosted in. For example, you most likely miss a few device special files. You can proceed in two ways: either by creating a different _base file, after the name of your configuration file, or by creating a platform-specific customization rule-set.

Creating a different _base is pretty straightforward, as it amounts to just creating _base-olet.tar.gz if you configuration is called olet, and is documented in the EtLinux manual.

Creating a customization, on the other hand, means specifying what to remove from, what to add to and what to run on the target tree just installed. Here, we'll go with this option, the customization.

So, let's create a directory Customizations/olet in the source directory of EtLinux (there's already is one in the etlinux-1.1 directory distributed with this package). In the directory you can create a file called RUN, one called DEL and a tree of files called ADD/. When the customization is run, the build process first copies over the ADD/ tree, then removes unwanted files and finally executes RUN. Again, this is documented in more detail in the EtLinux manual.

Since our main concern at this point is creating device files, the RUN command will be used to run mknod. This has been preferred over creating the special files into ADD/ because CVS isn't designed to bring over special files and this package is hosted in a CVS tree.

The RUN file must be given execute permission and is run in the root directory of the target tree. Please refer to the EtLinux manual for more details.

Another thing you might want to customize is the /etc/init.d/options file. To this aim, the copy that gets into the target tree is copied over from Customizations/olet/ADD. The released copy is identical to the default, but removes the memory hack that only worked on Linux-2.0 (and is still the default in EtLinux).

To specify a list of customizations to the build command, you must pass them in the CUSTOM variable of make. Therefore the suggested compilation command line is now:

        $ sudo make PLATFORM=host-native CONFIG=olet CUSTOM=olet
     


Node: Adding the Application, Next: , Previous: Fixing the Tree, Up: Customizing EtLinux

Adding the Application

To add your custom application, the easiest way is creating a customization called, for example, application. You then just need to create a directory ADD where you can copy all the files you need to add to the target system. In order to fire specific processes at boot time, you can add them to either /etc/init.d/respawn or /etc/init.d/applications.

Using respawn/ to host the application may be safer if the application may die and must be silently restarted. If it's never expected to die, on the other hand, you might want to use applications/ instead.

This package includes a trivial example, called sample-application, that places a file in /etc/init.d/respawn that prints an alive message once every ten seconds. To include it in the target tree, you can for example use:

        $ export PLATFORM=host-native CONFIG=olet
        $ sudo make CUSTOM="olet sample-application"
     

or, alternatively:

        $ export PLATFORM=host-native CONFIG=olet
        $ export CUSTOM="olet sample-application"
        $ sudo make
     


Node: Adding X11, Next: , Previous: Adding the Application, Up: Customizing EtLinux

Adding X11

The system we are concerned with must run an X application drawing polygons at 1024x768, and nothing more. Therefore, we need to add an X server and configure it for this hardware and the requested resolution.

In order to add X11 to your system you first need to identify the binaries or compile them from source. If you want to compile them, please see Compiling X11.

One possible way to add X11-related files is creating another EtLinux customization, that we'll call x11. This step is documented in Customizations/x11. Other details you may want to consider are discussed in Other X11 Issues.


Node: Compiling X11, Next: , Previous: Adding X11, Up: Adding X11

Compiling X11

To compile XFree86 version 4.3.0, you'll need to get the source files X430src-1.tgz, X430src-2.tgz and so on through X40src-7.tgz (65MB overall). The files live in mirrors of ftp.xfree86.org, in the directory XFree86/4.3.0/source. The disk usage of the source tree after archive are uncompressed is around 320MB.

After extracting the packages, you need to issue "make World", possibly after changing the macro ProjectRoot in xc/config/cf/site.def, at line 87. Please read below before firing the compilation, though.

On an x86 host with a good amount of RAM "make World" takes more or less 6000 kilo-bogoMIPS-second (this means, for example, it takes 3000 seconds if you CPU is rated 2000 bogoMIPS).

Unfortunately, the X makefiles do not propagate errors, so if by chance you miss some header files, the compiler will complain but make will go on, and will finally emit the mild message "Full build of Release 6.6 of the X Window System complete.".

In this case, you won't be able to run the compiled tree. To look for errors, you should fire less over your compilation log and look for the regexp "^make.*Error [0-9]*$". This is an example:

        make 2>&1 > ../make.log
        [... wait one hour or so ...]
        grep '^make.*Error [0-9]*$' ../make.log
     

If there are errors, you should fix them (for example by installing the zlib1g-dev package), and recompile. To save time, this time do not issue "make World", as it would make clean and then recompile it all from scratch. Use instead "make -f xmakefile all". For example:

        make -f xmakefile all 2>&1 > ../make.log2
        grep '^make.*Error [0-9]*$' ../make.log2
     

If by chanche, you missed zlib the first time over, you'll get wrong font files, that won't be recreated by the second run of the compilation (they will be all files 20-bytes long, consising of the gzip version of empty files). In this case, you might prefer to "make World" again, or remove those files before making all.

A copiled X11 tree will take more or less 650MB of disk space.

After compilation is over with no errors, you may want to run "make install", but this means everything in /usr/X11R6 will be overwritten with your new version, if you have permission to overwrite it (you should not, as you should not be compiling as superuser).

If you want to try to install X to a different directory tree on your host system, you should change ProjectRoot in xc/config/cf/site.def, to point to some directory other than /usr/X11R6.

As alternative, if you want to install your tree to a subdirectory of your filesystem (for example, the root filesystem of your diskless client), you can issue a command like:

        make -f xmakefile install DESTDIR=/opt/olet/build/Trees/olet
     

The variable DESTDIR is used as prefix before ProjectRoot, so files will be installed under $DESTDIR/usr/X11R6 if you use the default value for ProjectRoot.


Node: Customizations/x11, Next: , Previous: Compiling X11, Up: Adding X11

Customizations/x11

The suggested implementation of Customizations/x11 includes the following steps

The last step is performed by accessing the X11COMPILED environment variable. If it is set, then it is assumed to refer to the xc/ directory of a source XFree86 tree where you compiled it.

If the variable is not set, then the files are copied over from your host system.

The following files are copied over, in addition to libz.

     usr/X11R6/lib/modules/fonts/libbitmap.a
      [exports/lib/modules/fonts/libbitmap.a]
     usr/X11R6/lib/modules/libpcidata.a
      [exports/lib/modules/libpcidata.a]
     usr/X11R6/lib/modules/libscanpci.a
      [exports/lib/modules/libscanpci.a]
     usr/X11R6/lib/modules/libvgahw.a
      [exports/lib/modules/libvgahw.a]
     usr/X11R6/lib/modules/input/mouse_drv.o
      [exports/lib/modules/input/mouse_drv.o]
     usr/X11R6/lib/modules/drivers/mga_drv.o
      [exports/lib/modules/drivers/mga_drv.o]
     usr/X11R6/lib/modules/libint10.a
      [exports/lib/modules/libint10.a]
     usr/X11R6/lib/modules/libfb.a
      [exports/lib/modules/libfb.a]
     usr/X11R6/lib/modules/libvbe.a
      [exports/lib/modules/libvbe.a]
     usr/X11R6/lib/modules/libxaa.a
      [exports/lib/modules/libxaa.a]
     usr/X11R6/lib/modules/libramdac.a
      [exports/lib/modules/libramdac.a]
     usr/X11R6/lib/X11/fonts/misc/cursor.pcf.gz
      [fonts/bdf/misc/cursor.pcf.gz]
     usr/X11R6/lib/X11/fonts/misc/6x13-ISO8859-1.pcf.gz
      [fonts/bdf/misc/6x13-ISO8859-1.pcf.gz]
     

Moreover, the files fonts/misc/fonts.alias and fonts/misc/fonts.dir are created (and filled with the few mandatory lines), and /var/log is created as the X server wants to write its log file in there.

To create the filesystem with this customization in place, you should compile in the following way:

        $ export PLATFORM=host-native CONFIG=olet
        $ export CUSTOM="olet sample-application x11"
        $ export X11COMPILED=/opt/compiled/X-4.3.0/xc
        $ sudo make
     


Node: Other X11 Issues, Previous: Customizations/x11, Up: Adding X11

Other X11 Issues

You may want to address a few more points with X11 and your target system:

The log-file problem is solved by uncommenting one line in Customization/x11/RUN, the log file is created by default since it may help during development, and this memory leakage may even be acceptable in production.

The blanking problem is solved by including a line like the following one in your own application, after you opened your connection to the display:

       XSetScreenSaver(dpy, 0 /* timeout */, 0, 1, DefaultExposures);
     

The issue about X libraries is solved simply by linking the application statically with X libraries; this is definitely the best choice if you run a single application. If you run more applications, you should definitely use dynamic linking and add the needed libraries to your target tree.

Color names can be supported by simply copying over /usr/X11R6/lib/X11/rgb.txt to your target tree.


Node: Creating the Temporary Filesystem, Previous: Adding X11, Up: Customizing EtLinux

Creating the Temporary Filesystem

In order to run the target system with a tmpfs root filesystem, we need to first boot it into a temporary filesystem. Creating the temporary filesystem is just like creating the runtime filesystem, but with a different configuration file and a different set of customizations.

To this aim, this package includes a olet0 configuration file and an olet0 customization. The configuration file selects just the bare minimum needed to boot the system, without the standard selection for init, and the customization places a script in /sbin/init.

The script relies on the commands mount, tar, gzip and mini-pivot to perform the steps described in Choosing the Filesystem Layout. This tree is compiled by issuing the command "make CONFIG=olet0 CUSTOM=olet0" or by setting the variables in your own environment.

The provided /sbin/init checks whether its own environment includes TARFILE as a variable, and whether its value identifies a readable file. If the conditions are not met, then it runs an interactive ettcl session on the console as last resort.

The provided /sbin/init, moreover, copies all the contents of a /custom directory to the target tree, if such a directory is found within its filesystem (i.e, /dev/hda2 in this case).

Therefore, you might want to add your own application in this way, you could put the following files into your temporary root filesystem:

       /custom/etc/applications/myappscript
       /custom/bin/myapp
       /custom/etc/myapp.conf
     


Node: The Overall System Boot, Previous: Customizing EtLinux, Up: Top

The Overall System Boot

This chapter tries to summarize the final setup of the target system as far as boot time is concerned, as well as what are the files involved in the production environment.


Node: Booting Steps, Next: , Previous: The Overall System Boot, Up: The Overall System Boot

Booting Steps

We can identify the following booting steps:

The contents of /dev/hda2 are copied over from Trees/olet0, created as described in Creating the Temporary Filesystem. The tar file ($TARFILE) is the complete EtLinux filesystem to be used at run time.


Node: Grub Configuration, Next: , Previous: Booting Steps, Up: The Overall System Boot

Grub Configuration

The configuration file for Grub, /boot/grub/menu.lst, may be based on the following one:

     
     timeout 2
     default 0
     
     title production
       root (hd0,0)
       kernel /linux-olet vga=1 root=/dev/hda2 TARFILE=olet.tar.gz
     
     title prev-kernel
       root (hd0,0)
       kernel /linux-olet.old vga=1 root=/dev/hda2 TARFILE=olet.tar.gz
     
     title prev-tree
       root (hd0,0)
       kernel /linux-olet vga=1 root=/dev/hda2 TARFILE=olet.old.tar.gz
     
     # assume tftpd was called with the -s switch
     title development
       bootp
       root (nd)
       configfile /menu.generic
     
     

The configuration shown accounts for a recovery version of the tmpfs setup (useful when testing a new tree for an update) and a host-based diskless setup. Use of the configfile command allows to control every aspect of the boot process from the host system, thus limiting the number of reboots of the target system.


Node: DOM Contents, Next: , Previous: Grub Configuration, Up: The Overall System Boot

DOM Contents

The suggested production setup of the Disk On Module (DOM) is as follows:


/dev/hda1
A small partition (4MB or so) to host the boot loader and the kernel image. There's enough space for a second kernel image as a safe measure during updates.
/dev/hda2
The majority of the DOM, hosting the temporary boot filesystem and the tar file (or several of them). The filesystem is mounted read-only during the boot process and immediately unmounted.
/dev/hda3
A small partition to host configuration files or runtime defaults for the application. It should be mounted read-only by the application, remounting in read-write mode only during the unlikely update of these information.


Node: Compilation Summary, Next: , Previous: DOM Contents, Up: The Overall System Boot

Compilation Summary

In order to compile the whole trees, assuming you are running bash you'll need to perform the following steps, assuming your EtLinux source is in /opt/olet/etlinux-1-1, this package is in /opt/olet/olet and X11 has been compiled in /opt/olet/xc .

       cd /opt/olet/olet
     
       cd etlinux-1.1
       ETLINUX=/opt/olet/etlinux-1.1 ../tools/makelinks
       export SOURCEDIR=$(/bin/pwd)
       cd ..
     
       mkdir build
       cd build
       ln -s $SOURCEDIR/Makefile .
       export X11COMPILED=/opt/olet/xc
       export PLATFORM=host-native
       sudo make CONFIG=olet CUSTOM="olet x11"
       sudo make CONFIG=olet0 CUSTOM=olet0
     


Node: Installation Summary, Previous: Compilation Summary, Up: The Overall System Boot

Installation Summary

Table of Contents