17 Building a Custom OS Image

This chapter covers the following topics:

• Introduction
• Constructing a buildfile
• Where to find modules
• Selecting processes for an image

Information to be added

[Author's Comments: (@@What are the differences between disk, network, and embedded images?)]

[Author's Comments: (@@how do the config files get written?)--buildfile does it? how? where is .ifs file (for dumpifs)--It only exists on a Windows-based install, look at the file /fs/hd0-dos/config.sys (in my install it's in /fs/hd0-dos/Program Files/qnx/boot/fs/qnxbase.ifs and .../qnxbasedma.ifs). (add in building OS chapter)]

[Author's Comments: (@@add a section on using Photon and Nto on an embedded device? (checkout http://staff.qnx.com/~cforan/embed.html)]

Introduction

Building a custom OS image is a large subject covered in detail in a separate book (see Building Embedded Systems). In this chapter, we will take a brief look at making a QNX 6 image. In the embedded QNX 6 world, an image can mean a QNX 6 image or a flash filesystem image.

What is a QNX 6 image?

A QNX 6 image is simply a bootable or nonbootable directory structure that contains files. The files include the OS, your executables, and any data files that might be related to your programs. The bootable QNX 6 image is created by a program called mkifs (make image file system), which accepts information from two main sources: its command line and a buildfile.

What is a flash filesystem image?

A flash filesystem image is a structure that can be used in a read-only, read/write, or read/write/reclaim flash filesystem created by the mkefs utility.

Constructing a buildfile

A buildfile is the file that contains instructions for making an image.

The mkifs utility

The mkifs utility is used to create a QNX 6 image filesystem from a buildfile specification.

Currently, you can use mkifs to create only bootable images

The syntax is:

mkifs [-l inputline] [-v] [buildfile [imagefile]] 

where:

This component:	Does this:
-l inputline	Makes mkifs process the inputline before it starts interpreting the buildfile. Input lines given to mkifs must be quoted to prevent interpretation by the shell (especially since mkifs input lines often contain spaces). Multiple -l options are processed in the order specified.
-v	Requires mkifs to operate verbosely. Specifying additional -v options increases verbosity
buildfile	Specifies the input buildfile that mkifs should use to construct the image; use - to specify standard input (the default).
imagefile	Specifies the file to contain the image that mkifs builds; use - to specify standard output (the default). Note that imagefile can be specified only if buildfile has been specified.

The dumpifs utility

The dumpifs utility dumps the contents of an image filesystem. It can also be used to extract files from the image filesystem.

Buildfile format

Let's look at a very simple buildfile called shell.bld:

#   A simple "ls", "cat", and shell.
#   This file is "shell.bld"

[virtual=mipsle,srec] .bootstrap = {
   startup-vr41xx
   PATH=/proc/boot procnto
}
[+script] .script = {
   devc-ser8250 -e -b38400 0x1600ffc0^1,0x80010007 &
   reopen
   [+session] PATH=:/proc/boot esh 
}

[type=link] /dev/console=/dev/ser1
[type=link] /usr/lib/ldqnx.so.1=/proc/boot/libc.so

libc.so 

[data=copy]
devc-ser8250
esh
ls
cat
data1
data2 

In a buildfile, a pound sign (#) indicates a comment; anything between it and the end of the line is ignored. Make sure there's a space between a buildfile command and the pound sign. Although the three sections in the buildfile above seem to be distinct, in reality all three are similar in that they're lists of files.

Notice also how the buildfile itself is structured:

optional_attributes filename optional_contents

For example, this bit of code:

[virtual=mipsle,srec] .bootstrap = {
   startup-vr41xx
   PATH=/proc/boot procnto
}
 

Specifies these elements:

· optional_attribute is [virtual=mipsle,srec]
· filename is .bootstrap
· optional_contents start at = { and end at the corresponding closing brace three lines down.

Let's examine the three parts of the buildfile in some detail (see Building Embedded Systems for more information on mkifs, the utility used to build a QNX 6 image filesystem).

In the first part of the buildfile:

[virtual=mipsle,srec] .bootstrap = {
   startup-vr41xx
   PATH=/proc/boot procnto
}
 

The optional attributes specify that we are building a virtual address system using a little-endian MIPS CPU, with srec.boot as the name of the boot prefix, a small piece of code that is executed after the IPL and before the startup program. The attributes refer to an inline file to be included in the image, named .bootstrap. This file will contain the startup utility responsible for initializing NEC Vr41 type evaluation boards and procnto, the Neutrino microkernel and process manager. The IPL will transfer control to the startup program and process manager when the system starts up.

The second part:

[+script] .script = {
   devc-ser8250 -e -b38400 0x1600ffc0^1,0x80010007 &
   reopen
   [+session] PATH=:/proc/boot esh 
}
 

Specifies another inline file to be included in the image, this time a script file named .script to be run after the process manager has started. This script will contain the following specified command lines which will set up several options to be used by the serial driver for an 8250-compatible UART, then redirect standard input, output, and error to the console; and finally make the embedded shell program a session leader.

These script files stored on the target are not like regular QNX 6 script files, they have been parsed before they are included in the image. This is to make start up quicker by running them as stand alone programs, avoiding the need to run a shell interpreter first.

The last part of the buildfile:

[type=link] /dev/console=/dev/ser1
[type=link] /usr/lib/ldqnx.so.1=/proc/boot/libc.so

libc.so 

[data=copy]
devc-ser8250
esh
ls
cat
data1
data2 

Creates two symbolic links, specifies an external shared library object to include in the image, and causes data for the executable programs to be copied to RAM before use. The last six lines include six external files to be included in the image. The mkifs utility will find the external files on the host in a path specified by the MKIFS_PATH environment variable. By default, the utility places all files to be included in the image in the /proc/boot/ directory in the image.

In effect, then, our buildfile simply specifies nine files - two inline files and seven external.

Now we have the buildfile, we can make the image file by typing this:

mkifs shell.bld shell.ifs 

Setting heap sizes

[Author's Comments: (@@Do I need to set heap sizes and priorities? Why? (see /usr/help/product/neutrino_qrp_en/buil\dling/building_nto.html) or http://support.qnx.com/support/docs/neutrino_qrp/technotes/hat.html )]

Setting priorities

Where to find modules

Let's assume that one of the files you want to include in your image is actually stored on your development system as /release/data1. If you simply put /release/data1 in the buildfile, mkifs would include the file in the image, but would call it /proc/boot/data1 on the target system, instead of /release/data1.

Sometimes this is exactly what you want. But at other times you may want to specify the exact pathname on the target (i.e. you may wish to override the prefix of /proc/boot). For example, specifying /etc/passwd would place the host filesystem's /etc/passwd file in the target's pathname space as /proc/boot/passwd: probably not what you intended.

To get around this, if you include the line:

/etc/passwd = /etc/passwd 

in your buildfile, this would tell mkifs that the file /etc/passwd on the host should be stored as /etc/passwd on the target.

If you wanted a different source file (let's say /home/joe/embedded/passwd) to be the password file for the embedded system, you would include the buildfile code:

/etc/passwd = /home/joe/embedded/passwd 

Selecting processes for an image

[Author's Comments: (@@What does it mean to select processes for an image? How do I do it?)]

Mandatory processes

[Author's Comments: (@@What are the mandatory processes?)]

Disk, network, and embedded images