3 Introducing QNX RTP

This chapter covers the following topics:

• What is QNX RTP?
• What is QNX 6?
• What is Photon?
• What is a Resource Manager?
• What is the Package installer?
• How to make a package
• Setting up a package repository
• Migrating from QNX4 to QNX6
• Migrating from another OS to QNX 6

What is QNX RTP?

Read all about it on the QNX Realtime Platform product page at our web site.

[Author's Comments: add what is QNX6?]

How to get RTP

Download RTP or order the CD online from our RTP download web site.

What is QNX 6?

Get some background information on QNX 6 from our QNX product web site. For a more technical description of the QNX 6 OS, see System Architecture

QNX 6 core components:

• Neutrino microkernel
• Resource Manager architecture
• Standard device drivers
• Standard POSIX libraries & utilities
• Standard file systems
• Package Management File System

What is Photon?

[Author's Comments: incorporate description from 1.14 user's guide]

For more background information on the Photon microGUI, go to our QNX Realtime Platform web site.

Photon core components:

• Photon graphical microkernel
• Multimedia architecture
• Truetype font renderer
• Photon's Graphical Widget Libraries
• Package Installer
• Voyager Web Browser & HTML Renderer
• Additional free packages

What is a Resource Manager?

QNX 6 resource managers are responsible for presenting an interface to various types of devices. This may involve managing actual hardware devices (like serial ports, parallel ports, network cards, and disk drives) or virtual devices (like /dev/null, a network filesystem, and pseudo-ttys).

A resource manager is a user-level server program that accepts messages from other programs and, optionally, communicates with hardware.

The binding between the resource manager and the client programs that use the associated resource is done through a flexible mechanism called pathname space mapping. In pathname space mapping, an association is made between a pathname and a resource manager. The resource manager sets up this pathname space mapping by informing the QNX 6 Process Manager that it is the one responsible for handling requests at (or below, in the case of filesystems), a certain mountpoint. This allows the Process Manager to associate services (i.e. functions provided by resource managers) with pathnames.

Once the resource manager has established its pathname prefix, it will receive messages whenever any client program tries to do an open(), read(), write(), etc. on that pathname.

[Author's Comments: give a list of the main resource managers & what they do]

A resource manager

Here is an example of the heart of a resource manager

initialize the dispatch interface
register the pathname with the Process Manager
DO forever
   receive a message
   SWITCH on the type of message
       CASE io_open:
           perform io_open processing
           ENDCASE
       CASE io_read:
           perform io_read processing
           ENDCASE
       CASE io_write:
           perform io_write processing
           ENDCASE
       .   // etc. handle all other messages
       .   // that may occur, performing
       .   // processing as appropriate
   ENDSWITCH
ENDDO 

The architecture contains three parts:

• A channel is created to allow client programs to send messages to the resource manager.
• The pathname (or pathnames) that the resource manager is going to be responsible for is registered with the Process Manager, so that it can resolve open requests for that particular pathname to this resource manager.
• Messages are received and processed.

This message-processing structure (the switch/case, above) is required for every resource manager. However, we provide a set of convenient library functions to handle this functionality (and other key functionality as well).

For more detailed information on the resource manager concept, see System Architecture

What is the Package installer?

The Package Installer is the user interface for the QNX 6 package file system. This file system gives users a customized view of their files and directories; for an overview of this file system, see System Architecture; for more technical detail, see "Package filesystem".

The Package Installer is a resource manager (see "What is a Resource Manager?"). Once the Package Installer has established its pathname prefixes, it will receive messages whenever any client program tries to do an open(), read(), or write() on those pathnames.

You can use the following set of utilities to create, manage, and install packages. These utilities are described in the Utilities Reference.

To find out how to:	Look up:
Create packages for use with the package installer	packager
Extract information about a file from the package file system	pkgctl
Install software packages from a repository on CD-ROM or the Internet	pkg-installer

Installing a package from QNX

You can download and install a package from the QNX WWW website or CD_ROM repositories from Photon or from the command line.

Installing a package from Photon

To start the installation process from within Photon, do this:

• Click Package Installer on the Photon shelf.
• The resulting Package Installer dialog box shows a list of repositories. There are two lists of repositories: one for new software, the other for software already installed on your system. You may add or delete any of the repositories shown on either list. The new software repositories are shown by default (to view the repositories containing software already installed, click the View My Software button).
• Double click on a repository icon to expand the icon and show the available packages.

  The package installer retrieves all your local package descriptions from the installed manifest files. Manifest files are used by developers to put together a package for distribution: each installed package has a manifest file located at its root. This description includes the name and location of the script together with information on how and when it is to be run.

  Manifest files are XML-based text files. As long as you have permission, you may edit these files just as you edit other text files. In extreme circumstances, when there is no other option, being able to edit manifest files can be a life-saver, but be very careful if you do edit them. Manifest files are created by the developers of the software and contain only the information needed to install packages: you should never have to read them, let alone edit them.

• Decide where to store the package.

  The package installer will use a directory on your local filesystem to store the downloaded repository. Unless you select a different directory, the package installer will automatically create and use a default directory. If you don't want to use the default directory, do this:

  • Create a new storage directory for the local repository.
  • From the top-level dialog box window, click View My Software, then Add Repository buttons.
  • The Add new local repository dialog box appears: enter the details of your local repository and then click Done.
• Click Install Software, then select the QNX WWW or CD-ROM repository, and then click View Repository.

  The Package Installer connects to the repository and then retrieves all the remote package descriptions. A box tells you that the repository information is being downloaded.

• Select the packages you wish to see from the Show drop down box (e.g. new products, all products, or software patches).
• Select the package you wish to install.

  If you've got the right-hand pane showing, you may see a description of the package and vendor details in that pane.

• Choose a full or minimal install.

  A minimal install installs the core components plus any required components plus any recommended components; it does not install any optional components.

• Click Install

  You see a list of the files which will be installed.

• Select a local repository directory from the drop-down list and then click Continue.
• If you are asked, enter the license keys (you can choose to skip any package for which you do not have a license key).
• Click Continue.
• Read and agree to the licensing terms shown.

[Author's Comments: Add something about the find button. Explaing this: the package install does resolve dependencies with a third screen. This screen has a "find" button which goes out to each repository in your hotlist and looks for packages which satisfy your installation requirements]

Installing a package from the command line

To start the installation process from the command line, you can use the package installer utility in either of two ways:

• List the packages you want, e.g.

  pkg-installer -U url -p package -U url -p package 
  

• Or use an index file containing the packages to be installed, e.g.

  pkg-installer -i Index_file 
  

The index file contains the list of packages to be installed (must be the full path). As an example, your index file might look like this:

http://blah/package.qpm 
file:///blah/package.qpm 

[Author's Comments: this needs fleshing out to cover installs from the CD-ROM Repository and to emulate all of the steps in the Photon section)]

The package installer installs the specified packages automatically, as it does when you install from Photon.

What the package installer does

After you have started the process, the packages will be downloaded from the web site and expanded into the local repository you selected (if you needed to enter a license key, it will be used now for on-the-fly decrypting of the package). This is what the package installer does next:

• Check dependencies.

  A package may have dependencies listed in its manifest; these dependencies contain instructions on what to do if certain conditions apply. The package installer first checks for any relevant dependencies in the packages already installed, then checks for dependencies in the packages to be installed now.

  These dependencies may dictate some extra installation work. The package installer may have to disable some packages and install others; it does this work automatically after summarizing the work for you and asking for your confirmation.

• Download the packages and transfer them.
• Decompress the packages and store them in the selected local repository.
• Check for spill files.

  The package filesystem's contents are read-only; if you want to modify a file that's in the client-view of a package, the package filesystem makes a copy of the file and that is the file you modify and use from then on. The resulting modified file is called a spill file.

  If you have changed any previously installed package files, the package installer will ask whether you wish to continue to use the spill file or to replace it with a new package file.

• Run any required pre-install scripts.

  Package installation scripts are described in the package manifest file. The package manifest contains instructions detailing which scripts are to be run before and after the package installation. These are not the only scripts which may be required to install a package; library scripts, scripts that have been previously installed by other packages, may be needed as well. Library scripts may be called automatically whenever a certain package is installed and the installation meets pre-defined conditions.

• Run any required pre-use scripts.
• Modify the information in the /etc/system/package/packages file; this file determines the packages that will be activated or deactivated for the package filesystem manager.
• Restart the package filesystem (for more information on the package filesystem, see fs-pkg in the Utilities Reference.
• Run any required post-use scripts.
• Run any required post-install scripts.
• Remove redundant packages.

The package installer may carry out other actions during this sequence. For example, a package may have dependencies listed in its manifest; dependencies contain instructions on what to do if certain conditions apply. The package installer may install or remove packages according to these dependency instructions. Some instructions recommend rather than demand a certain action and in those cases you may be asked for your preferences.

For more information on the package installer, see pkg-installer in the Utilities Reference. Also, search on "package" in the Helpviewer.

[Author's Comments: can the package installer log its actions to a file? The package installer doesn't log its actions at the moment; this facility is planned.]

After the install

After you have successfully installed a package and as long as you have permission, you will be able to access the executable file in the directory specified in the MANIFEST file (the mapping of the installed files into the union filesystem).

Usually, scripts add icons pointing to the file on the Photon shelf, but this is not always the case, e.g. compiler tools don't do this. The executable should be placed in the path: this is not the responsibility of the package installer; the file is stored where packager is told to store it.

For more information about an executable you have installed, do one of the following:

• If the file is stored in a directory that is included in the PATH environment variable, you can access it from the command prompt.
• If you don't know where the file is, look for it using the find utility.
• If you know where the file is and are logged in as root, you can use the -i option of pkgctrl to get information about the file that was installed by a package.

[Author's Comments: what does the user have to do to install the software and start using it? Once the package is installed, it is up to the package to make sure it is available to the user. The user should be able to run the required commands right away.]

How to make a package

You use an interactive session with the packager utility to create a set of QPR packages for use with the package installer. The packager utility prompts you for information about the package.

If you specify an existing QPM file with the -m option, packager uses the information from the file as the default answers to its questions. If you also specify the -u option, packager uses the default answers to the questions without prompting you.

The -v option controls the amount of detail in the questions; if you specify a value of 2 (expert), packager displays only the questions without the explanations.

Example packager session

First, you have to create a base directory containing all the files and symbolic links that need be installed on your target system. Assuming you created a directory called test_packager, here's an example of an interactive session with packager:

[Author's Comments: show the session and check it out with packager. There will be a packager session article available soon -- this will include some in-depth discussion about what the "right" values are for the questions it asks.]

Setting up a package repository

[Author's Comments: add information here, refer to where? This is about setting up a package repository. I believe that all you have to do is use the packager and it will take care of everything for you. Then all you need to do is tell people where this information is stored. Check out later. The new packager adds support for creating a repository - even interactively!]

Migrating from QNX4 to QNX6

If you are migrating from QNX4 to QNX 6, you will need to install the migration package from the RTP CD-ROM repository (to find out how to do this, take a look at "Installing new software"). Or download the software you need from our migration kit website.

Similarities between QNX4 and QNX 6

QNX 4 and QNX 6 are similar in several respects including the following:

• architecture

  Architecturally, QNX 6 is the same as QNX 4. It provides an open-systems POSIX API in a robust scalable form suitable for a wide range of solutions from tiny resource-constrained systems to high-end distributed computing environments.

• filesystem
• Migrating files from a QNX 4 system to a QNX 6 system isn't complicated for this simple reason: they use the same filesystem. If you're going to run QNX 6 on a PC with a QNX 4 filesystem, then all the files in the QNX 4 partition or disk are accessed exactly the same as they were before.
• I/O management

  Where QNX 4 has I/O managers, QNX 6 has resource managers, a similar concept. In QNX 6, a resource manager library is provided for you as part of the regular libraries. This library hides a lot of the gory details, allowing you to concentrate on code that's specific to your application while still presenting a POSIX front end to the client. Even so, migrating I/O managers will likely be the one set of code that involves the most work, because this is where there are the most differences. The work will be minimized if you used the I/O manager framework that's available for QNX 4 as free software, since your process will be similar architecturally.

  For more information on QNX 6 resource managers, see the Programmer's Guide.

• functions

  Many QNX4 C library functions have equivalent functions in QNX 6; where there is no direct replacement, the migration guide gives you a cover function or a suggests a workaround. QNX 6 also contains many functions that were not available in QNX 4. See the migration kit web site for details.

Differences between QNX4 and QNX 6

QNX 4 and QNX 6 are different in several respects including the following:

• scheduling

  The main difference in scheduling is that in QNX 6, scheduling is done by thread, not by process. The highest-priority thread is chosen to run, regardless of what process it's in.

• processors

  QNX 6 runs on a number of different processors including x86, MIPS, and PowerPC (see the current list of supported platforms and processors on our web site). Assuming that you didn't use any processor-specific tricks, a program written for QNX 6 on an x86 could be recompiled and relinked so that it will also run on a Power PC machine.

• SMP support

  QNX 6 supports symmetric multiprocessing, so it can run on a multi-processor machine.

• POSIX

  QNX 6 contains newer POSIX components (e.g. POSIX threads). New functions from the Unix 98 standard and from other sources have been added. Some functions from the QNX 4 C library are present in QNX 6, but behave differently or have a slightly different set of arguments to meet the POSIX 1003.1 specification.

Planning the migration

When you migrate from QNX 4 to QNX 6, you will want a migration plan; here are some suggestions:

• Get some hands-on QNX 6 experience.
• Move your usual comfortable QNX environment to QNX 6.
• Move your utilities. Keep records on the effort required to migrate each utility; this will give you an estimating base when you come to plan the migration of your major applications.
• If you can, install QNX 6 on a separate machine and access it over your network using NFS or CIFS; this enables you to produce an executable program under QNX 4 and then switch over to your QNX 6 computer to run the executable.
• Make an inventory of the third-party software needed for your applications and verify when that software (or equivalent) will be available under QNX 6.
• Establish which applications will migrate to the new OS. It may be that some applications are due for major rewrite and/or upgrade and it may make sense to start with a new design in some of these cases.
• Establish the order in which applications will migrate. If there are inter-application dependencies, identify them and decide how to deal with them, bearing in mind that applications can communicate between QNX 4 and QNX 6 either by moving data from one environment to the other or by IPC over serial links or TCP/IP (but not through native QNX message passing).
• Develop good estimates of the time required to migrate each application. If you have already converted your utility programs, you'll have a yardstick to help in your estimation of the migration effort.

Migrating a program

Migrating a program involves these three steps:

• Analyze the work to be done.

  The mig4nto utility supplied with the migration kit identifies the major areas in a program that need attention. This utility copies source files, then inserts comments above each source line that contains a function name or C preprocessor manifest name requiring attention. These comments include brief suggestions regarding a course of action. Both QNX 4 and QNX 6 versions of the utility are available.

• Develop a strategy to handle architectural problems.

  You may prefer to redesign a program that contains obsolete functions or that is too tightly bound to QNX 4 facilities.

• Convert the files

  Start with the header files, then change any hard-coded pathnames where needed (e.g. to cater for the different nodename syntax), and then tackle the functions.

Detailed information

For detailed information on migrating from QNX 4 to QNX 6, install the migration package from the RTP CD-ROM repository (to find out how to do this, take a look at "Installing new software". Or download the software you need from our migration kit website.

Migrating from another OS to QNX 6

[Author's Comments: This section should provide answers to these questions from users: I am new to this UNIX- type world: should I start by getting to know UNIX (etc.) info from the many UNIX books out there? What are differences between QNX, UNIX, Linux,MS? What is the equivalent of the Windows registry? Are there DLLs? I am coming from Linux/Sun/MS what do I need to know?) How do I migrate from Amiga to RTP?)]

Where to start learning about RTP

RTP is similar to other UNIX-type operating systems. If you know nothing about UNIX, it's probably best to dive in and start learning about RTP from the start, because there are some differences among UNIX-type operating systems. A good book to start would be Rob Krten's book "Getting Started with Neutrino".

To learn about writing programs to run under UNIX, try Advanced Programming in the UNIX Environment by W. Richard Stevens, Addison Wesley. This book is the definitive guide to POSIX routines.

RTP, like Linux, uses POSIX threads, commonly known as Pthreads. A good book for learning about Pthreads is Programming with POSIX Threads, David R. Butenhof, Addison Wesley.

Differences between RTP and other OS

RTP-specific directories include /usr/photon, /$processor, /pkgs and /etc/system. Almost all other directories attempt to match the Filesystem Hierarchy Standard (FHS). This is a reference specification for UNIX distribution developers, package developers, and system implementers. For more inormation, see the FHS web site at http://www.pathname.com/fhs